There are two requirements for receiving instant payments. All users of instant payments must implement the first requirement. However, we recommend implementing both because receiving return requests, particularly in cases of fraud, promote network health and safety.
- 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.
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.
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.
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.
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.
Endpoints
The rejection endpoint is below. Accepting a return request is combined with the return endpoint itself which is covered in the returns and rejections 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.
