There are two requirements for sending instant payments. We recommend implementing both of these functions because instant payments, once sent, cannot be reversed.
- Sending Payments: Send outgoing instant payments.
- Sending Return Requests: Send outgoing return requests to recover funds sent erroneously in previous outgoing instant payments.
If your customers are victims of fraud or send payments erroneously, return requests are the only recourse to recover their funds.
Sending Payments
Sending an instant payment creates a new instant_payment object with an outgoing direction.
Endpoints
You can check if the recipient’s financial institution is available on the instant payment network and, if available, send instant payments to them. Once sent, outgoing instant payments can also be canceled. However, the cancellation window is very short and only possible if Lead has not yet submitted the payment to the network. This limited opportunity may occur during normal system processing or periods of manual review.
| Endpoint | Description |
|---|
POST /instant_payments/check_availability | Check the availability of a financial institution to accept instant payments. |
POST /instant_payments | Send an outgoing instant payment. |
POST /instant_payments/{id}/cancel | Attempt to cancel an outgoing instant payment. |
Statuses
Outgoing instant payments can transition through five potential statuses. Unlike returns, outgoing instant payments can terminate in the canceled status. The counterparty_status lifecycle only begins after the instant_payment object has reached a posted status. The purpose of this lifecycle is to precisely describe if/when the outgoing payment reaches the creditor.
| Instant Payment Status | Description | Webhook |
|---|
created | Lead created the outgoing instant payment. | No |
under_review | Lead is manually reviewing the outgoing instant payment before sending it to the network. | Yes |
canceled | You canceled the outgoing instant payment. | No |
posted | Lead posted the outgoing instant payment to your account. | Yes |
rejected | Lead, the counterparty, or the network rejected the outgoing instant payment. | Yes |
| Counterparty Status | Description | Webhook |
|---|
under_review | The counterparty is manually reviewing your payment before posting it to the creditor’s account. | Yes |
posted | The outgoing instant payment posted to the creditor’s account. | Yes |
rejected | The counterparty rejected your payment it before it reached the creditor’s account. | Yes |
Events
You can follow the status of an outgoing payment event throughout its entire lifecycle - from initiation at Lead to subsequent events at the counterparty financial institution.
| Event | Description | Partner Action |
|---|
.under_review | The outgoing instant payment is pending manual review from Lead before it will be sent to the network. | (Optional) Notify your customer that the instant payment has not yet been submitted to the network. |
.rejected | The outgoing instant payment has been rejected by Lead, the counterparty, or the network. | (Optional) Notify your customer that the instant payment has been rejected. |
.posted | The outgoing instant payment has been posted to the Lead account. | (Optional) Notify your customer that the funds for the instant payment have left their account. |
.counterparty_status_update | The counterparty status of the outgoing instant payment has been updated. | (Optional) If the counterparty_status is posted, notify your end customer that the instant payment was successfully posted to the creditor. |
Sending Return Requests
Sending a return request creates a new return_request sub-object within the existing outgoing instant_payment.
Endpoints
You can create a return request if you previously sent an instant payment and need to recover it.
| Endpoint | Description |
|---|
POST /instant_payments/id/request_return | Send an outgoing return request to the counterparty for a previously posted outgoing instant payment. |
Statuses
Outgoing return requests transition through three possible statuses from when the counterparty receives them through when they are ultimately resolved.
| Outgoing Status | Description | Webhook |
|---|
pending | The outgoing return request is pending a response from the counterparty. | No |
accepted | The outgoing return request was accepted by the counterparty. | Yes |
rejected | The outgoing return request was rejected by the counterparty. | Yes |
Events
Tracking an outgoing return request involves listening to a single event that is triggered upon each status change.
| Event | Description | Your Action |
|---|
.return_request_status_update | The status of the outgoing return request has been updated. | (Optional) Notify your customer that the outgoing return request has been accepted or rejected. |
