API docs by Redocly

Open Payments (1.3.0)

Download OpenAPI specification:

E-mail: tech@interledger.org License: Apache-2.0

An API for open access to financial accounts to send and receive payments.

The resource server manages the core transaction resources of the Open Payments protocol: incoming payments, outgoing payments, and quotes. All resources are scoped to a wallet address and require an access token issued by the authorization server.

Endpoints:

  • /incoming-payments — create and manage incoming payments
  • /outgoing-payments — create and manage outgoing payment instructions
  • /quotes — request a quote for a specific send or receive amount

For a full overview of these resources, see the Resources concepts page.

incoming-payment

incoming payment operations

Create an Incoming Payment

A client MUST create an incoming payment resource before it is possible to send any payments to the wallet address.

When a client creates an incoming payment the receiving Account Servicing Entity generates unique payment details that can be used to address payments to the account and returns these details to the client as properties of the new incoming payment. Any payments received using those details are then associated with the incoming payment.

All of the input parameters are optional.

For example, the client could use the metadata property to store an external reference on the incoming payment and this can be shared with the account holder to assist with reconciliation.

If incomingAmount is specified and the total received using the payment details equals or exceeds the specified incomingAmount, then the receiving Account Servicing Entity MUST reject any further payments and set completed to true.

If an expiresAt value is defined, and the current date and time on the receiving Account Servicing Entity's systems exceeds that value, the receiving Account Servicing Entity MUST reject any further payments.

Authorizations:
GNAP
header Parameters
Signature-Input
required
string
Examples: Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-length" "content-type");created=1618884473;keyid="gnap-rsa"

The Signature-Input field is a Dictionary structured field containing the metadata for one or more message signatures generated from components within the HTTP message. Each member describes a single message signature. The member's key is the label that uniquely identifies the message signature within the context of the HTTP message. The member's value is the serialization of the covered components Inner List plus all signature metadata parameters identified by the label. The following components MUST be included: - "@method" - "@target-uri" - "authorization". When the message contains a request body, the covered components MUST also include the following: - "content-digest" The keyid parameter of the signature MUST be set to the kid value of the JWK. See ietf-httpbis-message-signatures for more details.

Signature
required
string
Examples: Signature: sig1=:EWJgAONk3D6542Scj8g51rYeMHw96cH2XiCMxcyL511wyemGcw==:

The signature generated based on the Signature-Input, using the signing algorithm specified in the "alg" field of the JWK.

Request Body schema: application/json
required

A subset of the incoming payments schema is accepted as input to create a new incoming payment.

The incomingAmount must use the same assetCode and assetScale as the wallet address.

walletAddress
required
string <uri> (walletAddress)

The URL of an Open Payments wallet address

object (amount)

The maximum amount that should be paid into the wallet address under this incoming payment.

expiresAt
string <date-time>

The date and time when payments into the incoming payment must no longer be accepted.

object

Additional metadata associated with the incoming payment. (Optional)

Responses

Request samples

Content type
application/json
{
  • "walletAddress": "https://openpayments.guide/alice/",
  • "incomingAmount": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{}

List Incoming Payments

List all incoming payments on the wallet address

Authorizations:
GNAP
query Parameters
wallet-address
required
string

URL of a wallet address hosted by a Rafiki instance.

cursor
string non-empty

The cursor key to list from.

first
integer [ 1 .. 100 ]

The number of items to return after the cursor.

last
integer [ 1 .. 100 ]

The number of items to return before the cursor.

header Parameters
Signature-Input
required
string
Examples: Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-length" "content-type");created=1618884473;keyid="gnap-rsa"

The Signature-Input field is a Dictionary structured field containing the metadata for one or more message signatures generated from components within the HTTP message. Each member describes a single message signature. The member's key is the label that uniquely identifies the message signature within the context of the HTTP message. The member's value is the serialization of the covered components Inner List plus all signature metadata parameters identified by the label. The following components MUST be included: - "@method" - "@target-uri" - "authorization". When the message contains a request body, the covered components MUST also include the following: - "content-digest" The keyid parameter of the signature MUST be set to the kid value of the JWK. See ietf-httpbis-message-signatures for more details.

Signature
required
string
Examples: Signature: sig1=:EWJgAONk3D6542Scj8g51rYeMHw96cH2XiCMxcyL511wyemGcw==:

The signature generated based on the Signature-Input, using the signing algorithm specified in the "alg" field of the JWK.

Responses

Response samples

Content type
application/json
Example
{}

Get an Incoming Payment

A client can fetch the latest state of an incoming payment to determine the amount received into the wallet address.

Authorizations:
GNAP
path Parameters
id
required
string

Sub-resource identifier

header Parameters
Signature-Input
string
Examples: Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-length" "content-type");created=1618884473;keyid="gnap-rsa"

The Signature-Input field is a Dictionary structured field containing the metadata for one or more message signatures generated from components within the HTTP message. Each member describes a single message signature. The member's key is the label that uniquely identifies the message signature within the context of the HTTP message. The member's value is the serialization of the covered components Inner List plus all signature metadata parameters identified by the label. The following components MUST be included: - "@method" - "@target-uri" - "authorization". When the message contains a request body, the covered components MUST also include the following: - "content-digest" The keyid parameter of the signature MUST be set to the kid value of the JWK. See ietf-httpbis-message-signatures for more details.

Signature
string
Examples: Signature: sig1=:EWJgAONk3D6542Scj8g51rYeMHw96cH2XiCMxcyL511wyemGcw==:

The signature generated based on the Signature-Input, using the signing algorithm specified in the "alg" field of the JWK.

Responses

Response samples

Content type
application/json
{}

Complete an Incoming Payment

A client with the appropriate permissions MAY mark a non-expired incoming payment as completed indicating that the client is not going to make any further payments toward this incoming payment, even though the full incomingAmount may not have been received.

This indicates to the receiving Account Servicing Entity that it can begin any post processing of the payment such as generating account statements or notifying the account holder of the completed payment.

Authorizations:
GNAP
path Parameters
id
required
string

Sub-resource identifier

header Parameters
Signature-Input
required
string
Examples: Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-length" "content-type");created=1618884473;keyid="gnap-rsa"

The Signature-Input field is a Dictionary structured field containing the metadata for one or more message signatures generated from components within the HTTP message. Each member describes a single message signature. The member's key is the label that uniquely identifies the message signature within the context of the HTTP message. The member's value is the serialization of the covered components Inner List plus all signature metadata parameters identified by the label. The following components MUST be included: - "@method" - "@target-uri" - "authorization". When the message contains a request body, the covered components MUST also include the following: - "content-digest" The keyid parameter of the signature MUST be set to the kid value of the JWK. See ietf-httpbis-message-signatures for more details.

Signature
required
string
Examples: Signature: sig1=:EWJgAONk3D6542Scj8g51rYeMHw96cH2XiCMxcyL511wyemGcw==:

The signature generated based on the Signature-Input, using the signing algorithm specified in the "alg" field of the JWK.

Responses

Response samples

Content type
application/json
{}

outgoing-payment

outgoing payment operations

Create an Outgoing Payment

An outgoing payment is a sub-resource of a wallet address. It represents a payment from the wallet address.

Once created, it is already authorized and SHOULD be processed immediately. If payment fails, the Account Servicing Entity must mark the outgoing payment as failed.

Authorizations:
GNAP
header Parameters
Signature-Input
required
string
Examples: Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-length" "content-type");created=1618884473;keyid="gnap-rsa"

The Signature-Input field is a Dictionary structured field containing the metadata for one or more message signatures generated from components within the HTTP message. Each member describes a single message signature. The member's key is the label that uniquely identifies the message signature within the context of the HTTP message. The member's value is the serialization of the covered components Inner List plus all signature metadata parameters identified by the label. The following components MUST be included: - "@method" - "@target-uri" - "authorization". When the message contains a request body, the covered components MUST also include the following: - "content-digest" The keyid parameter of the signature MUST be set to the kid value of the JWK. See ietf-httpbis-message-signatures for more details.

Signature
required
string
Examples: Signature: sig1=:EWJgAONk3D6542Scj8g51rYeMHw96cH2XiCMxcyL511wyemGcw==:

The signature generated based on the Signature-Input, using the signing algorithm specified in the "alg" field of the JWK.

Request Body schema: application/json
required

A subset of the outgoing payments schema is accepted as input to create a new outgoing payment.

The debitAmount must use the same assetCode and assetScale as the wallet address.

Either provide a quoteId to create an outgoing payment based on a quote or provide incomingPayment and debitAmount to create an outgoing payment directly from an incoming payment.

One of
walletAddress
required
string <uri> (walletAddress)

The URL of an Open Payments wallet address

quoteId
required
string <uri>

The URL of the quote defining this payment's amounts.

object

Additional metadata associated with the outgoing payment. (Optional)

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
{}

List Outgoing Payments

List all outgoing payments on the wallet address

Authorizations:
GNAP
query Parameters
wallet-address
required
string

URL of a wallet address hosted by a Rafiki instance.

cursor
string non-empty

The cursor key to list from.

first
integer [ 1 .. 100 ]

The number of items to return after the cursor.

last
integer [ 1 .. 100 ]

The number of items to return before the cursor.

header Parameters
Signature-Input
required
string
Examples: Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-length" "content-type");created=1618884473;keyid="gnap-rsa"

The Signature-Input field is a Dictionary structured field containing the metadata for one or more message signatures generated from components within the HTTP message. Each member describes a single message signature. The member's key is the label that uniquely identifies the message signature within the context of the HTTP message. The member's value is the serialization of the covered components Inner List plus all signature metadata parameters identified by the label. The following components MUST be included: - "@method" - "@target-uri" - "authorization". When the message contains a request body, the covered components MUST also include the following: - "content-digest" The keyid parameter of the signature MUST be set to the kid value of the JWK. See ietf-httpbis-message-signatures for more details.

Signature
required
string
Examples: Signature: sig1=:EWJgAONk3D6542Scj8g51rYeMHw96cH2XiCMxcyL511wyemGcw==:

The signature generated based on the Signature-Input, using the signing algorithm specified in the "alg" field of the JWK.

Responses

Response samples

Content type
application/json
Example
{}

Get an Outgoing Payment

A client can fetch the latest state of an outgoing payment.

Authorizations:
GNAP
path Parameters
id
required
string

Sub-resource identifier

header Parameters
Signature-Input
required
string
Examples: Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-length" "content-type");created=1618884473;keyid="gnap-rsa"

The Signature-Input field is a Dictionary structured field containing the metadata for one or more message signatures generated from components within the HTTP message. Each member describes a single message signature. The member's key is the label that uniquely identifies the message signature within the context of the HTTP message. The member's value is the serialization of the covered components Inner List plus all signature metadata parameters identified by the label. The following components MUST be included: - "@method" - "@target-uri" - "authorization". When the message contains a request body, the covered components MUST also include the following: - "content-digest" The keyid parameter of the signature MUST be set to the kid value of the JWK. See ietf-httpbis-message-signatures for more details.

Signature
required
string
Examples: Signature: sig1=:EWJgAONk3D6542Scj8g51rYeMHw96cH2XiCMxcyL511wyemGcw==:

The signature generated based on the Signature-Input, using the signing algorithm specified in the "alg" field of the JWK.

Responses

Response samples

Content type
application/json
{}

Get spent amounts for current outgoing payment grant

Returns the spent amounts for the current outgoing payment grant corresponding to the presented GNAP access token, if any. If a grant was created with an interval (recurring), the amounts returned are for the current interval.

Authorizations:
GNAP
header Parameters
Signature-Input
required
string
Examples: Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-length" "content-type");created=1618884473;keyid="gnap-rsa"

The Signature-Input field is a Dictionary structured field containing the metadata for one or more message signatures generated from components within the HTTP message. Each member describes a single message signature. The member's key is the label that uniquely identifies the message signature within the context of the HTTP message. The member's value is the serialization of the covered components Inner List plus all signature metadata parameters identified by the label. The following components MUST be included: - "@method" - "@target-uri" - "authorization". When the message contains a request body, the covered components MUST also include the following: - "content-digest" The keyid parameter of the signature MUST be set to the kid value of the JWK. See ietf-httpbis-message-signatures for more details.

Signature
required
string
Examples: Signature: sig1=:EWJgAONk3D6542Scj8g51rYeMHw96cH2XiCMxcyL511wyemGcw==:

The signature generated based on the Signature-Input, using the signing algorithm specified in the "alg" field of the JWK.

Responses

Response samples

Content type
application/json
Example
{
  • "spentReceiveAmount": {
    },
  • "spentDebitAmount": {
    }
}

quote

quote operations

Create a Quote

A quote is a sub-resource of a wallet address. It represents a quote for a payment from the wallet address.

Authorizations:
GNAP
header Parameters
Signature-Input
required
string
Examples: Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-length" "content-type");created=1618884473;keyid="gnap-rsa"

The Signature-Input field is a Dictionary structured field containing the metadata for one or more message signatures generated from components within the HTTP message. Each member describes a single message signature. The member's key is the label that uniquely identifies the message signature within the context of the HTTP message. The member's value is the serialization of the covered components Inner List plus all signature metadata parameters identified by the label. The following components MUST be included: - "@method" - "@target-uri" - "authorization". When the message contains a request body, the covered components MUST also include the following: - "content-digest" The keyid parameter of the signature MUST be set to the kid value of the JWK. See ietf-httpbis-message-signatures for more details.

Signature
required
string
Examples: Signature: sig1=:EWJgAONk3D6542Scj8g51rYeMHw96cH2XiCMxcyL511wyemGcw==:

The signature generated based on the Signature-Input, using the signing algorithm specified in the "alg" field of the JWK.

Request Body schema: application/json
required

A subset of the quotes schema is accepted as input to create a new quote.

The quote must be created with a (debitAmount xor receiveAmount) unless the receiver is an Incoming Payment which has an incomingAmount.

One of
walletAddress
required
string <uri> (walletAddress)

The URL of an Open Payments wallet address

receiver
required
string <uri> (receiver) ^(https|http)://(.+)/incoming-payments/(.+)$

The URL of the incoming payment that is being paid.

method
required
string (payment-method)
Value: "ilp"

Responses

Request samples

Content type
application/json
Example

Response samples

Content type
application/json
{}

Get a Quote

A client can fetch the latest state of a quote.

Authorizations:
GNAP
path Parameters
id
required
string

Sub-resource identifier

header Parameters
Signature-Input
required
string
Examples: Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-length" "content-type");created=1618884473;keyid="gnap-rsa"

The Signature-Input field is a Dictionary structured field containing the metadata for one or more message signatures generated from components within the HTTP message. Each member describes a single message signature. The member's key is the label that uniquely identifies the message signature within the context of the HTTP message. The member's value is the serialization of the covered components Inner List plus all signature metadata parameters identified by the label. The following components MUST be included: - "@method" - "@target-uri" - "authorization". When the message contains a request body, the covered components MUST also include the following: - "content-digest" The keyid parameter of the signature MUST be set to the kid value of the JWK. See ietf-httpbis-message-signatures for more details.

Signature
required
string
Examples: Signature: sig1=:EWJgAONk3D6542Scj8g51rYeMHw96cH2XiCMxcyL511wyemGcw==:

The signature generated based on the Signature-Input, using the signing algorithm specified in the "alg" field of the JWK.

Responses

Response samples

Content type
application/json
{}