Receiving & Returning Instant Payments

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.

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_updated`	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.

Foundations

API Guides

Receiving Payments

Statuses

Events

Endpoints

Receiving Return Requests

Statuses

Events

Endpoints

Sending Returns

Endpoints

Statuses

Events

​Receiving Payments

​Statuses

​Events

​Endpoints

​Receiving Return Requests

​Statuses

​Events

​Endpoints

​Sending Returns

​Endpoints

​Statuses

​Events

Receiving Payments

Statuses

Events

Endpoints

Receiving Return Requests

Statuses

Events

Endpoints

Sending Returns

Endpoints

Statuses

Events