Simple Payment Setup Protocol
Simple Payment Setup Protocol (SPSP)
This document describes the Simple Payment Setup Protocol (SPSP), a basic protocol for exchanging payment information between payee and payer to facilitate payment over Interledger. SPSP uses the STREAM transport protocol for condition generation and data encoding.
STREAM does not specify how payment details, such as the ILP address or shared secret, should be exchanged between the counterparties. SPSP is a minimal protocol that uses HTTPS for communicating these details.
SPSP provides for exchanging basic server details needed by a client to set up a STREAM connection. It is intended for use by end-user applications.
- SPSP Client - The application that uses SPSP to interact with the SPSP Server.
- SPSP Server - The application that handles incoming SPSP requests from the SPSP Client.
- SPSP Endpoint - The specific HTTPS endpoint on the SPSP Server used for setting up a payment.
- STREAM Module - Software included in the SPSP Client and Server that implements the STREAM protocol.
SPSP may be used by end-user applications, such as a digital wallet with a user interface to initiate payments. SPSP Clients and Servers use the STREAM Module to send and receive Interledger payments. Payment pointers can be used as a persistent identifier on Interledger. Payment pointers can also be used as a unique identifier for an invoice to be paid or for a pull payment agreement.
SPSP messages MUST be exchanged over HTTPS.
Any SPSP Server will expose an HTTPS endpoint called the SPSP Endpoint. The SPSP Client can query this endpoint to get information about the SPSP Server's connection details, namely the ILP address and a shared secret. The SPSP Client can apply this information to establish a STREAM connection using the STREAM Module.
Relation to Other Protocols
SPSP is used for exchanging connection information before an ILP payment or data transfer is initiated. The SPSP Client and Server use the STREAM transport protocol to generate the ILP packets. The SPSP Server generates the shared secret and ILP address to be used in STREAM and communicates it to the client over HTTPS.
The SPSP Endpoint is a URL the payment pointer resolves to, used by the SPSP Client to query information about the SPSP Server and set up payments. SPSP Clients SHOULD treat the URL as opaque and not depend on any information they derive from the URL. There are several supported ways to refer to an SPSP Endpoint:
- Payment pointer (Recommended)
$example.com/bob. This SHOULD be the only kind of SPSP identifier exposed to users.
- Raw endpoint URL (Not recommended)
https://example.com/spsp/alice. This SHOULD NOT be exposed to users, but SHOULD be supported by SPSP Clients.
The SPSP Endpoint MUST respond to HTTPS
GET requests in the following manner:
GET <SPSP Endpoint>)
The client queries the SPSP Endpoint to get information about the server:
(With the identifier
GET /.well-known/pay HTTP/1.1
Accept: application/spsp4+json, application/spsp+json
Request Headers to Support Web Monetization Polyfills
Web Monetization polyfills may query SPSP from a non-privileged context if they are implemented as a script rather than a browser extension. Sites may choose to use a script-based polyfill to enable Web Monetization for their visitors without requiring any browser extension or browser support.
In this situation, CORS headers are necessary to make the SPSP server reachable. If CORS headers are not included, the SPSP query will be rejected and Web Monetization will fail to initialize.
SPSP servers SHOULD expose the CORS headers listed below on
GET <SPSP Endpoint> and
OPTIONS <SPSP Endpoint>.
Request Headers to Support STREAM Receipts
|A base64-encoded Receipt Nonce.
|A base64-encoded Receipt Secret.
The SPSP Client MAY be provided with an SPSP Endpoint belonging to the receipt verifier, which would add the receipt headers and proxy the query to the SPSP Server.
HTTP/1.1 200 OK
More information about the parameters can be found in section Response Body.
The response MUST contain at least the following headers:
application/spsp4+json to indicate the response is encoded as JSON and that the ILP payment should be sent via STREAM.
|Indicates how long the SPSP Client should cache the response. See supported cache-control directives below.
To handle as many transactions per second as possible, the SPSP Client caches results from the SPSP Server. The information returned by the SPSP Server is not expected to change rapidly, so repeated requests for the same information are usually redundant. The SPSP Server communicates how long to cache results for using the HTTP-standard
Cache-Control header in the responses to RESTful API calls.
The SPSP Client understands the following Cache-Control directives:
|The SPSP Client should cache this response for
<i> MUST be a positive integer.
|The SPSP Client must not cache this response.
The response body is a JSON object that includes basic account details necessary for setting up payments. More fields can be added but implementations MUST ignore fields they do not understand.
|ILP Address of the SPSP Server. In case of push payments, this is the receiver. In case of pull payments, this is the sender.
|32 bytes, base64 (base64url) encoded (including padding)
|The shared secret to be used by this specific HTTP client in the STREAM. Should be shared only by the server and this specific HTTP client, and should therefore be different in each query response. Even though clients SHOULD accept base64url encoded secrets, base64 encoded secrets are recommended.
true, the SPSP server will issue STREAM Receipts in the STREAM connection. If
false or omitted, the server will not issue STREAM Receipts.
receiver Does Not Exist
HTTP/1.1 404 Not Found
"message": "Invalid receiver ID"
Model of Operation
Establishing a connection
We assume that the SPSP Client knows the SPSP Server's SPSP Endpoint (see Payment pointers).
The user's SPSP Client queries the SPSP Server's SPSP Endpoint.
The SPSP Endpoint responds with the SPSP Server's info, namely the ILP address (
destination_account) and the shared secret (
shared_secret) to be used in STREAM.
destination_accountMUST be used as the STREAM
shared_secretMUST be decoded from base64 and used as the STREAM
The SPSP Client establishes a STREAM connection to the SPSP Server using the SPSP Server's ILP address and shared secret.
Simple push payment
Given the open STREAM connection, the SPSP Client begins sending ILP packets of value.
- The SPSP Client will adjust their STREAM
sendMaxto reflect the amount they're willing to send.
- The SPSP Server will adjust their STREAM
receiveMaxto reflect the amount they're willing to receive.
- The SPSP Client's and Server's STREAM Modules will move as much value as possible while staying inside these bounds.
- If the SPSP Client reaches their
sendMax, they end the stream and the connection. If the SPSP Server reaches their
receiveMax, they will end the stream and the connection.
Simple data transmission
Given the open STREAM connection, either the SPSP Client or the Server begins sending ILP packets of data.
The size of the data SHOULD be defined by setting STREAM
maxOffset. Each application built on STREAM and using the principle of data transmission MAY define more restrictive requirements.
All STREAM parameters -
maxOffset - are defined in STREAM's frame encoding.
Note that the SPSP Client and Server can send as many STREAM payments and data as they want using the same query response. If the STREAM connection is closed the Client SHOULD attempt to reconnect with the same parameters or it SHOULD query the Server again for new connection parameters once the time indicated in the
Cache-Control header has passed.