As discussed on the call today we’re thinking about how to relate Payment Pointers, SPSP and Open Payments in a simple way that is easy to understand and work with.
This is the proposal, please share comments and suggestions below.
SPSP
SPSP defines the concept of an SPSP endpoint which locates a JSON document resource providing, at a minimum, STREAM credentials to use to open a new STREAM connection.
The expected behaviour of an SPSP client (which queries the endpoint) is to establish the STREAM connection and begin sending money to the entity that provided the SPSP endpoint URL.
SPSP only defines the expected behaviour of the service (an SPSP server) hosting the SPSP endpoint when queried via an HTTP GET request.
The use of SPSP is indicated by the SPSP client through the Accept
header which contains a value of application/spsp4+json
.
Therefore SPSP was designed to accommodate future versions that expand upon the functionality in the current version. It is possible for a future version of the protocol to extend the schema of the JSON document and define new behaviours for other HTTP verbs and still remain backwards compatible with SPSP.
Open Payments
We propose that Open Payments is the next version of SPSP.
It defines a super-set of behaviours of the systems that were previously called the SPSP client and SPSP server. All operations center around the Open Payments endpoint (the URL resolved from the user’s Payment Pointer)
Open Payments clients SHOULD still be able interact with a legacy SPSP server to send money via monetization (as currently supported by SPSP).
Open Payments expands the set of media types defined to include the following:
- Mandate:
application/mandate+json
- Invoice:
application/invoice+json
- Monetization:
application/monetization+json
For backwards compatibility, clients and servers SHOULD accept both application/monetization+json
and application/spsp4+json
media types and treat these as equivalent.
Operations
In Open Payments, a GET
request against the Open Payments endpoint returns either a monetization resource or the metadata for the account. The response differs depending on the content-type requested.
When performing a GET request against an Open Payments endpoint for monetization, Open Payments clients SHOULD send two Accept headers indicating support for Open Payments but also for SPSP (but indicating a preference for Open Payments via the order of the headers).
Example request for Payment Pointer $wallet.example/adrian :
GET /adrian HTTP/1.1
Host: wallet.example
Accept: application/monetization+json, application/spsp4+json
Example response
HTTP/1.1 200 OK
Content-Type: application/monetization+json
{
"ilpAddress": "example.ilpdemo.red.bob",
"sharedSecret": "6jR5iNIVRvqeasJeCty6C+YB5X9FhSOUPCL/5nha5Vs="
}
Example request 2:
GET /adrian HTTP/1.1
Host: wallet.example
Accept: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json
{
"issuer": "https://wallet.example",
"assets_supported": [
{"code": "USD", "scale": 2},
{"code": "EUR", "scale": 2}
]
}
To create invoices and mandates the client does a POST
request against the Open Payments endpoint and indicates the type of resource being created through the media type:
Verb | Content-Type or Accept header | Action |
---|---|---|
GET | application/monetization+json | Return STREAM credentials |
GET | application/json | Return account metadata |
POST | application/invoice+json | Create an invoice resource |
POST | application/mandate+json | Create a mandate resource |
Legacy SPSP servers will return an empty response or an error making it simple for clients to detect that the receiver only supports SPSP and not Open Payments and falling back to using Monetization if possible to complete the payment.