Introduction

Welcome to the SatoshiPay API! You can use this API to make digital goods like articles, images, videos and downloadable files available for purchase using the SatoshiPay widget. This documentation covers:

SatoshiPay and You

You need to embed the digital goods and the SatoshiPay widget into your website

SatoshiPay handles the payments

You need to deliver the digital goods to your users via HTTP

The following diagram illustrates how your website and SatoshiPay interact with each other:

The SatoshiPay backend manages a registry of your digital goods. This registry contains pricing and some meta information, but not the content itself. You can register and manage these goods using the Digital Goods API.

The goods can be embedded on your web page using HTML Tags with special data attributes. The location of the HTML tag determines the position of the digital good on the page, or if the good hasn't been paid yet, the position of its placeholder.

The special HTML tags are recognised by the SatoshiPay widget, which needs to be included on every page that contains digital goods for sale. When a user buys a digital good, the widget handles the payment process by communicating to the SatoshiPay backend using a WebSocket connection. After successful payment the widget receives a payment receipt, which in turn is used to fetch the content of the good from a special HTTP Endpoint provided by you (see Retrieving Goods).

The SatoshiPay Widget

Include SatoshiPay Widget

<script src="https://wallet.satoshipay.io/satoshipay.js"></script>

The SatoshiPay website widget floats at the bottom right of the page and looks like this:

The widget displays a user's current balance in lumens and, when clicked, a menu where a user can top-up, manage their wallet, and learn more about the tool.

The SatoshiPay widget can be included anywhere on any web page and will automatically transform SatoshiPay HTML Tags into digital goods. See it in action at the SatoshiPay website.

The widget performs the following tasks:

Generate a Stellar wallet and keep it in the user's LocalStorage

Communicate with SatoshiPay servers

Control digital goods on the web page

Interact with the user via menus and messages

Digital Goods API

Digital Goods API Endpoint

https://api.satoshipay.io/v2/

The Digital Goods API allows developers to interact with SatoshiPay using HTTP REST calls and JSON. Digital goods merchants communicate with the API in order to register individual goods for sale – either directly or through plugins and libraries provided by SatoshiPay or 3rd parties. The digital goods merchant hosts complementary HTTP Endpoints that deliver the goods to the user.

Every request to the API must be authenticated with your API credentials. These credentials can be obtained in the SatoshiPay Dashboard after creating an account. Before you can access your credentials, you need to set a Stellar address for payouts. Your API key and secret can then be found at Settings > API Access.

The API uses Basic Authentication, where the user name is your API key, and the password is your API secret.

The example uses Basic Authentication to receive the list of your goods. The result will be an empty array [] if you didn't add any goods yet.

If authorization fails, a JSON object with an error message will be returned as a response (along with the HTTP status 401) .

Errors

If an error occurs while handling the request, a JSON error object will be returned along with a corresponding HTTP status code. The object contains status and error codes, the name of the error, as well as the error message.

Goods

The API resource goods allows a merchant to manage their digital goods. A good in the API represents a merchant's digital good (e.g. news article, image, audio/video or file download) and holds all information needed for SatoshiPay to handle payments. This includes pricing information and other metadata, but not the content itself.

Partially update a good, i.e. send only those properties that are to be updated.

Request

Insert the ID of the good that should be updated into the request URL and provide an 'update' object that has any subset of the following properties. The specified properties will then overwrite the properties of the good with the given id in the request URL.

Property

Type

Required

Description

price

integer

no

Good's price in stroops. One lumen is 10^7 (10,000,000) stroops.

asset

string

yes

Asset of good's price. Only "XLM" is currently supported.

sharedSecret

string

no

Shared secret information which will be used to create paymentReceipt used to authenticate user during digital goods retrieval.

url

string

no

URL of the web page which contains the good. Used as a reference in the Dashboard.

Request

Provide an array of 'request' objects in the body. Each request object has the following properties:

Property

Type

Required

Description

method

string

yes

The method of the query. Has to be one of POST, PUT, PATCH or DELETE.

path

string

yes

The path of the resource. For example: /goods/<id>

body

json value

depending on method

JSON value that represents the body of the request.

Response

Returns an array of 'response' objects that each correspond to the respective request from the request array. Each response object has the following properties:

Property

Type

Description

status

integer

HTTP status code of the respective request.

body

json value

JSON value that represents the response body from the respective request.

Payment Expiry

Digital goods can have a payment expiry. After a successful payment, a good will be in its paid state until the defined expiry time interval has passed, after which the payment will no longer be valid.

Setting Payment Expiry

During the registration of a good, the optional purchaseValidityPeriod property can be set with an arbitrary, positive time period. The time format is translated by the "ms" NPM package, which converts various time formats to milliseconds. See examples below.

Before purchase, a digital good is represented on the merchant's website by a placeholder. These placeholders are injected by the SatoshiPay widget, which scans the current page for placeholder tags on initialization. The placeholder tags are identified by a CSS class name starting with satoshipay-placeholder and contain details about the good they replace in their data attributes (see the text tag example).

Goods placeholder:

The data attributes specify where the good can be downloaded from by the SatoshiPay client once the payment has been successfully completed, which specific type of good is displayed, and other content type specific properties like length or size. See below for a detailed description of the data attributes for different content types.

During page load placeholders will appear in a simplified form (grey boxes) to make them recognizable while the SatoshiPay widget is being initialized. Placeholder styling can not be modified by the surrounding website.

Absolute or relative URL to placeholder/preview image. This will be displayed if the video has not been paid yet. E.g. /placeholders/4.png.

Download

Download Example

<divclass="satoshipay-placeholder-download"data-sp-type="application/pdf"data-sp-src="/paid-content/3.pdf"data-sp-id="558bcdbb1309c59725bdb561"data-sp-length="835669"data-sp-title="Book: What's the Deal with Bitcoins?"></div>

This tag type represents a secure download link that is displayed after successful payment.

Data Attributes

Data Attribute

Required

Description

data-sp-type

yes

Content type (MIME), must start with "application/" for this type of digital good, e.g. application/pdf. See supported types.

Data Attributes

Unique identifier for the good in SatoshiPay's registry. Consists of a hex string, e.g. 558bcdbb1309c59725bdb559.

data-sp-currency

no

The XLM price converted to US Dollars, Euro, or UK Pounds. Use currency symbols: 'USD', 'EUR', or 'GBP')

data-sp-placeholder

no

Absolute or relative URL to placeholder/preview image. This will be displayed if the image has not been paid yet. E.g. /placeholders/2.png.

data-sp-height

no

Height of placeholder/preview image in pixels, e.g. 360.

data-sp-width

no

Width of placeholder/preview image in pixels, e.g. 640.

Retrieving Goods

The merchant needs to provide public endpoints to allow the SatoshiPay widget to retrieve a good once it has successfully been paid for. The URL of an endpoint is defined as the data-sp-src attribute in the HTML tag.

In the example, assuming the special HTML tags are defined in https://example.org/index.html, the data-sp-src attribute has been set to /satoshipay-content/5 (another possibility would be the absolute URL https://example.org/satoshipay-content/5).

The endpoint will be called with a GET request that has the following query parameters:

Query Parameter

Description

paymentReceipt

Receipt for payment. This parameter should be used by the endpoint to authenticate the request (see authentication below).

Authentication

Authentication is implemented on the merchant's HTTP endpoint without connecting to the SatoshiPay API. It is done by verifying the value of the query parameter paymentReceipt, which consists of the Base64 encoded JSON payload and a signature split by a dot.

The correct signature for the above example payload and a sharedSecret value of "jsbicjttovhgtkdtsthduxg" is
text
"13c5d97f6ac3b0d2412962437066ca22ada3cafad1aefad85a2e261a98b2ee14e0ca8f3c7772c78fd8fed9cfb0b51b4b4c154c078a1a0b36a5c19185c84b6281"

Field

Name

Description

exp

Expiration time

Expiration time (UNIX time in seconds) after which the payment receipt MUST NOT be accepted for processing.

Validating paymentReceipt means verifying the signature and expiration time. The signature is the SHA-512 hash of the string resulting from concatenating payloadBase64 and the good's sharedSecret known only by merchant.

The merchant is responsible for generating a unique sharedSecret for every good and storing it in the merchant's own database.

If `sharedSecret` is not unique for every good, it would mean that any random valid `paymentReceipt` can be used to access all goods served by the merchant.
Because payment receipts can be used to access the content, it is advised to secure the HTTP endpoint using an SSL connection (HTTPS).

Response Format

The response needs to have HTTP status 200 set and contain the correct Content-Type header for the digital good. In most cases simply passing on the MIME media type returned by the file system should be sufficient, but make sure to check the list of content types that are supported.

The HTTP header is followed by the content of the digital good, for example HTML code.

Cross-Domain

Required Headers

Access-Control-Allow-Origin: *

If you are serving digital goods from a different hostname the website containing SatoshiPay widget is served from, you need to work around the same-origin policy by adding these headers to your response:

For goods with a larger file size it is recommended to process HTTP range requests and serve partial content. This will allow browsers and download managers to resume a transfer or to transfer file segments in parallel.

To make skipping to a certain position (seeking) in an audio file or video possible, support for range requests is required. Most browsers or players won't allow seeking if the HTTP source does not support partial content.

We will publish sample digital goods servers written in PHP and Node with support for range requests soon. Contact us if you would like to get early access.

Content Types

SatoshiPay uses the MIME media type standard to identify the content of digital goods. Media types (also "content types") influence the way digital goods are retrieved and displayed. Here is a complete list of supported types.

Testnet Sandbox

To faciliate easier development, the SatoshiPay client is available in a sandbox environment which connects to the Stellar testnet. Testnet funds are free. Please note that the testnet may arbitrarily reset.