Sending Instant Payments

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.

Testing in Sandbox

Instant payments in sandbox use the same endpoints as production. Unlike ACH and wire transfers, instant payment statuses advance automatically in sandbox — you do not need to call a simulation endpoint to move an outgoing payment from created to posted. A few practical notes when testing:

Routing numbers. Lead does not publish a fixed list of designated sandbox routing numbers for instant payments. Any well-formed routing number can be used in the creditor_agent.routing_number (outgoing) or debtor_agent.routing_number (simulated incoming) field. The values shown in code examples (such as 987654321) are illustrative, not reserved test values.
Availability checks. Call POST /instant_payments/check_availability first to confirm the routing number is reachable on the network before sending.
Simulating an inbound payment. Use POST /v1/simulate/instant_payments/incoming and supply your own debtor_agent.routing_number. The value is not validated against a real network.
Simulating a return. Use POST /v1/simulate/instant_payments/{instant_payment_id}/incoming_return against an existing posted outgoing payment.

If you need a specific routing number to exercise a particular code path in sandbox, contact your Technical Account Manager.

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 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_updated`	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_updated`	The status of the outgoing return request has been updated.	(Optional) Notify your customer that the outgoing return request has been accepted or rejected.

Foundations

API Guides

Sending Payments

Endpoints

Testing in Sandbox

Statuses

Events

Sending Return Requests

Endpoints

Statuses

Events

​Sending Payments

​Endpoints

​Testing in Sandbox

​Statuses

​Events

​Sending Return Requests

​Endpoints

​Statuses

​Events

Sending Payments

Endpoints

Testing in Sandbox

Statuses

Events

Sending Return Requests

Endpoints

Statuses

Events