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

# Sending Instant Payments

> Send outgoing FedNow instant payments with Lead's API: check counterparty availability, cancel pending payments, and submit return requests.

There are two requirements for sending instant payments. We recommend implementing both of these functions because instant payments, once sent, cannot be reversed.

1. **Sending Payments:** Send outgoing instant payments. 
2. **Sending Return Requests:** Send outgoing return requests to recover funds sent erroneously in previous outgoing instant payments.

<Warning>
  If your customers are victims of fraud or send payments erroneously, return requests are the only recourse to recover their funds. 
</Warning>

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

```mermaid theme={null}
graph TD
subgraph Outgoing instant_payment
   A(["created"])
   B(["under_review"])
   C(["rejected"])
   J(["canceled"])
   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 -- "You canceled" --> J
   B -- "You canceled" --> J
end

subgraph State Key
   direction LR
   T([Start])
   U([Pending])
   V([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;
classDef invisible fill:none,stroke:none
 
class A,D,W,T startStyle;
class B,X,U progressStyle;
class C,E,F,G,J,Y,Z,V terminalStyle;
```

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

```mermaid theme={null}
graph TD

subgraph Outgoing instant_payment
   A(["created"])
   B(["under_review"])
   C(["rejected"])
   J(["canceled"])
   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 -- "You canceled" --> J
   B -- "You canceled" --> J
	 
	 subgraph Outgoing return_request
		 D(["pending"])
		 F(["accepted"])
		 G(["rejected"])
		 D -- "Counterparty accepted" --> F
		 D -- "Counterparty rejected" --> G
	 end
	 
	 E -.- D
	 
end

subgraph State Key
   direction LR
   T([Start])
   U([Pending])
   V([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;
classDef brownStyle fill:#efebe9,stroke:#5d4037,stroke-width:2px;
classDef invisible fill:none,stroke:none

class A,D,W,T startStyle;
class B,X,U progressStyle;
class C,E,F,G,J,Y,Z,V terminalStyle;
class H,I brownStyle;
```

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