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

All of the input parameters are optional.

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

For example, the client can specify an invoice number as the externalRef property of the incoming payment and this can be shared with the account holder to assist with reconciliation.

The payment has a state of pending when it is initially created.

After creating the incoming payment, the client SHOULD use the payment details returned by the server to send one or more payments to the account.


State transitions for an incoming payment

When the receiving account provider starts to receive payments using the provided payment details, it MUST change the state of the incoming payment to processing.

If the total received using these payment details equals or exceeds the specified incomingAmount then the receiving account provider MUST reject any further payments and update the incoming payment state to completed.

If an expiresAt value is defined, and the current date and time on the receiving account provider's systems exceeds that value, the receiving account provider MUST reject any further payments and transition the incoming payment to a state of expired.

A client with the appropriate permissions can update the state to completed indicating the client is not going to make any further payments toward this incoming payment.

For example, if the client has sent the maximum amount it is willing to send, but due to fees or exchange rates that were unforeseen when the incoming payment was created, less has arrived at the receiver than expected.

Click Try It! to start a request and see the response here!