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

> Receive Instant Payments and Return Requests

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.

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.

## 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. | 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 [returns and rejections](/products/instant-payments/rejections-and-returns) 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. |