Skip to main content

​
Returns

Returning payments is important because instant payments are push-only from debtor to creditor and irrevocable. 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.

​
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.

​
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.

​
Rejections

Rejections surface on the instant_payment object’s rejection hash, which carries rejected_by, reason, and details. Unless a case says otherwise, handle the .rejected webhook and read those fields.

​
Outgoing payment rejected by Lead or the network

The payment never reached the counterparty. rejected_by is lead or network. Follow up with Lead if the reason is unclear.

​
Outgoing payment rejected by the counterparty

Lead submitted the payment to the network and the counterparty rejected it. rejected_by is counterparty. Retry if appropriate.

​
Outgoing payment posted but subsequently rejected by counterparty

The outgoing payment reached posted status and completed its lifecycle, but counterparty_status changed to rejected afterward. Listen for .counterparty_status_updated rather than .rejected to inspect the rejection reason. Expect the counterparty to send the funds back as a separate return, which arrives as its own incoming instant_payment with a .posted webhook. Reconcile it against the original through related_objects.original_payment_id.

​
Incoming payment rejected by account number controls

Lead rejected an incoming payment, most often because of your configured account number controls, which govern who may send to an account number. If the rejections are unexpected, update the controls.

​
Incoming payment accepted but subsequently rejected

Account number controls are the only way to refuse an incoming payment before it posts. If you want to implement other rejection criteria, simply return the payment after it posts with POST /instant_payments/{id}/return, which creates a new outgoing return payment.