Create an Incoming Payment
POST /incoming-payments
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
Parameters
Header Parameters
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.
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.
The signature generated based on the Signature-Input, using the signing algorithm specified in the “alg” field of the JWK.
The signature generated based on the Signature-Input, using the signing algorithm specified in the “alg” field of the JWK.
Request Body 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.
object
URL of a wallet address hosted by a Rafiki instance.
The maximum amount that should be paid into the wallet address under this incoming payment.
object
The value is an unsigned 64-bit integer amount, represented as a string.
The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.
The scale of amounts denoted in the corresponding asset code.
The date and time when payments into the incoming payment must no longer be accepted.
Additional metadata associated with the incoming payment. (Optional)
object
Examples
{ "walletAddress": "https://openpayments.guide/alice/", "incomingAmount": { "value": "2500", "assetCode": "USD", "assetScale": 2 }, "metadata": { "externalRef": "INV2022-02-0137" }}Responses
201
Incoming Payment Created
An incoming payment resource with public details.
object
The URL identifying the incoming payment.
The URL of the wallet address this payment is being made into.
Describes whether the incoming payment has completed receiving fund.
The maximum amount that should be paid into the wallet address under this incoming payment.
object
The value is an unsigned 64-bit integer amount, represented as a string.
The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.
The scale of amounts denoted in the corresponding asset code.
The total amount that has been paid into the wallet address under this incoming payment.
object
The value is an unsigned 64-bit integer amount, represented as a string.
The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.
The scale of amounts denoted in the corresponding asset code.
The date and time when payments under this incoming payment will no longer be accepted.
Additional metadata associated with the incoming payment. (Optional)
object
The date and time when the incoming payment was created.
The date and time when the incoming payment was updated.
The list of payment methods supported by this incoming payment.
object
The ILP address to use when establishing a STREAM connection.
The base64 url-encoded shared secret to use when establishing a STREAM connection.
Examples
{ "id": "https://ilp.interledger-test.dev/incoming-payments/08394f02-7b7b-45e2-b645-51d04e7c330c", "walletAddress": "https://ilp.interledger-test.dev/alice/", "incomingAmount": { "value": "2500", "assetCode": "USD", "assetScale": 2 }, "receivedAmount": { "value": "0", "assetCode": "USD", "assetScale": 2 }, "completed": false, "expiresAt": "2022-02-03T23:20:50.52Z", "metadata": { "externalRef": "INV2022-02-0137" }, "createdAt": "2022-03-12T23:20:50.52Z", "updatedAt": "2022-04-01T10:24:36.11Z", "methods": [ { "type": "ilp", "ilpAddress": "g.ilp.iwuyge987y.98y08y", "sharedSecret": "1c7eaXa4rd2fFOBl1iydvCT1tV5TbM3RW1WLCafu_JA" } ]}401
Authorization required
Headers
The address of the authorization server for grant requests in the format GNAP as_uri=<URI>
403
Forbidden