Your integration with the instant payments API will include both receiving and returning instant payments. Returning payments is a requirement because instant payments are push-only from debtor to creditor and irrevocable. These two overall requirements are broken down into three sections within this guide.
- Receiving Payments: Handle the receipt of incoming instant payments.
- Receiving Return Requests: Handle the receipt of incoming return requests related to instant payments previously received.
- Sending Returns: Send return payments and respond to corresponding return requests if they exist.
Receiving Payments
Receiving an incoming instant payment creates a new instant_payment object with an incoming direction.
Statuses
Incoming instant_payment objects have three potential statuses during their lifecycle, all of which trigger a webhook.
| Instant Payment Status | Description | Webhook |
|---|
under_review | Lead is manually reviewing the incoming instant payment. | Yes |
posted | Lead posted the incoming instant payment to your account. | Yes |
rejected | Lead rejected the incoming instant payment. | Yes |
Events
For incoming instant payments, the only event you must handle is posted. Upon this event, you are required to notify your customers that the transferred funds are now available. You have the option to also act on the under_review and rejected events if you choose.
| Event | Description | Your Action |
|---|
.under_review | Lead is manually reviewing the incoming instant payment. | (Optional) Inform your customer that incoming funds are pending. |
.posted | Lead posted the incoming instant payment to your account. | (Mandatory) Inform your customer of available funds. |
.rejected | Lead rejected the incoming instant payment. | (Optional) Look at the rejection hash to investigate why rejection occurred. |
Endpoints
Incoming instant payments require no further action on your part. However, if the original incoming payment was defective (e.g., fraud, duplicate, or technical error), a return may be requested.
Receiving Return Requests
The counterparty financial institution will send a return_request if they want a payment they previously sent to be returned. The return_request is structured as a sub-object of the original instant_payment.
A single instant_payment may eventually have multiple return_request sub-objects. However, only one incoming return_request will require a response at any given time.
Statuses
The lifecycle of a return_request sub-object begins after the original instant_payment reaches posted status. The only incoming return_request status that triggers an event is response_needed.
| Return Request Status | Description | Webhook |
|---|
response_needed | You received an incoming return request that requires a response from you. | Yes |
accepted | You accepted the incoming return request by initiating an outgoing return (covered in the next section). | No |
rejected | You rejected the incoming return request and provided a reason why. | No |
Events
The return_request_response_needed event indicates that a new return request has been received which requires your response and a potential return of funds as soon as possible. Listening to this event and taking action is required.
| Event | Description | Your Action |
|---|
| .return_request_response_needed | You received an incoming return request that requires a response from you. | (Mandatory) Begin your review process and respond as soon as possible, or, at the latest, by the 10th business day. |
Endpoints
The rejection endpoint is below. Accepting a return request is combined with the return endpoint itself which is covered in the next section.
For incoming return requests, you are required to investigate and respond by accepting or rejecting the request as soon as possible or, at the latest, by the 10th business day. If this deadline is not met, Lead will automatically reject the return request on your behalf to maintain our compliance with network requirements.
| Endpoint | Description |
|---|
POST /instant_payments/{id}/reject_return_request | Reject the active return request associated with an instant payment. |
Sending Returns
Returning an instant payment creates a new instant_payment object with an outgoing direction. Additionally, the active return_request sub-object of the original payment, if one exists, moves into accepted status automatically.
This section includes the subset of statuses and events that relate to returns only.
Returns are a type of outgoing instant payments, which are covered extensively on the Sending page. Endpoints
You can initiate returns regardless of whether or not an active return request exists.
For incoming return requests, you are required to investigate and respond by accepting or rejecting the request as soon as possible or, at the latest, by the 10th business day. If this deadline is not met, Lead will automatically reject the return request on your behalf to maintain our compliance with network requirements.
| Endpoint | Description |
|---|
POST /instant_payments/{id}/return | Return an instant payment that was previously received. If there is an outstanding return request, calling this endpoint will also accept the return request. |
Statuses
Outgoing returns, once initiated, will transition through four possible statuses. If an active return request is present, it will move to the accepted status after Lead validates the outgoing return.
The status of a return request is not the authoritative source of payment success. Accepting a return request represents an intention to send a return but is not a guarantee of it.
| Instant Payment Status | Description | Webhook |
|---|
created | Lead created the outgoing return. | No |
under_review | Lead is manually reviewing the outgoing return before sending it to the network. | Yes |
posted | Lead posted the outgoing return to your account. | Yes |
rejected | Lead, the counterparty, or the network rejected the outgoing return. | Yes |
| Return Request Status | Description | Webhook |
|---|
accepted | You accepted the incoming return request by initiating an outgoing return. | No |
Events
Tracking the outgoing return requires listening to a broad set of events. These events cover exceptions and notifications when the funds returned are now available to the receiving party.
| Event | Description | Your Action |
|---|
.under_review | The outgoing return is pending manual review from Lead before it will be sent to the network. | (Optional) Notify your customer that the return has not yet been submitted to the network. |
.rejected | The outgoing return has been rejected by Lead, the counterparty, or the network. | (Optional) Notify your customer that the return has been rejected. |
.posted | The outgoing return has been posted to the Lead account. | (Optional) Notify your customer that the funds for the return have left their account. |
.counterparty_status_update | The counterparty status of the outgoing return has been updated. | (Optional) If the counterparty_status is posted, notify your end customer that the return was successfully received by the recipient. |
