> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
> Use this file to discover all available pages before exploring further.

# Receiving & Returning Instant Payments

> Configure your system to receive and return 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.

1. **Receiving Payments:** Handle the receipt of incoming instant payments.
2. **Receiving Return Requests:** Handle the receipt of incoming return requests related to instant payments previously received.
3. **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         |

```mermaid theme={null}
graph TD
subgraph Incoming instant_payment
	F(["START"])
	H(["rejected"])
	I(["under_review"])
	J(["posted"])
	F --> J
	F -- "Lead manual review"--> I
	I -- "Manual review failure" --> H
	I -- "Manual review success" --> J
	F -- "Lead validation failure" --> H
end

subgraph State Key
      direction LR
      X([Start])
      Y([Pending])
      Z([Terminal])
end

linkStyle 0 stroke:#155724,stroke-width:2px;

classDef startStyle fill:#d4edda,stroke:#155724,stroke-width:3px;
classDef progressStyle fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px;
classDef terminalStyle fill:#eceff1,stroke:#455a64,stroke-width:3px;
 
class F,A,X startStyle;
class I,Y progressStyle;
class C,D,H,J,Z terminalStyle;
```

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

<Tip>
  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.
</Tip>

### 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      |

```mermaid theme={null}
graph TD
subgraph Incoming instant_payment
subgraph Incoming return_request
	A(["response_needed"])
	C(["accepted"])
	D(["rejected"])
	A -- "You return" --> C
	A -- "You reject" --> D
end
	F(["START"])
	H(["rejected"])
	I(["under_review"])
	J(["posted"])
	F --> J
	F -- "Lead manual review"--> I
	I -- "Manual review failure" --> H
	I -- "Manual review success" --> J
	F -- "Lead validation failure" --> H
	J -.- A
end

subgraph State Key
       direction LR
       X([Start])
       Y([Pending])
       Z([Terminal])
end

linkStyle 2 stroke:#155724,stroke-width:2px;

classDef startStyle fill:#d4edda,stroke:#155724,stroke-width:3px;
classDef progressStyle fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px;
classDef terminalStyle fill:#eceff1,stroke:#455a64,stroke-width:3px;
 
class F,A,X startStyle;
class I,Y progressStyle;
class C,D,H,J,Z terminalStyle;
```

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

<Warning>
  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.
</Warning>

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

<Note>
  Returns are a type of outgoing instant payments, which are covered extensively on the [Sending](/api-integrations/instant-payments/sending-instant-payments) page.
</Note>

### Endpoints

You can initiate returns regardless of whether or not an active return request exists.

<Warning>
  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.
</Warning>

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

<Warning>
  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.
</Warning>

| **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          |

```mermaid theme={null}
graph TD
subgraph Incoming return_request
	D(["response_needed"])
	F(["accepted"])
	G(["rejected"])
	D -- "You accept" --> F
	D -- "You reject" --> G
end
subgraph Outgoing instant_payment return
   A(["created"])
   B(["under_review"])
   C(["rejected"])
   E(["posted"])
   A --> E
   A -- "Lead manual review" --> B
   A -- "Lead validation failure or network or counterparty rejection" --> C
   B -- "Manual review success" --> E
   B -- "Manual review failure" --> C
   A -.- F
end
subgraph State Key
   direction LR
   T([Start])
   U([Pending])
   V([Terminal])
end

linkStyle 2 stroke:#155724,stroke-width:2px;
 
classDef startStyle fill:#d4edda,stroke:#155724,stroke-width:3px;
classDef progressStyle fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px;
classDef terminalStyle fill:#eceff1,stroke:#455a64,stroke-width:3px;
classDef invisible fill:none,stroke:none

class A,D,T startStyle;
class B,U progressStyle;
class C,E,F,G,V terminalStyle;
class Z invisible;
```

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