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

# Return Requests

> Configure your system to receive and send wire return requests.

<Info>
  **API Coming Q3**

  This guide is a preview of what to expect with the Return Requests API coming <Badge color="blue" icon="calendar">Q3 2026</Badge>.
</Info>

## Overview

Wire return requests allow you to request the return of funds for a previously sent wire. Return requests are always associated with a previous wire.

There are two distinct flows:

* Receiving a return request for an incoming wire
* Sending a return request for an outgoing wire

<Tip>
  A return request does not move funds and its status does not guarantee that a return will happen. Funds are only moved when an actual return wire is initiated by you or the counterparty.
</Tip>

## Return Request Object

Return requests are represented as sub-objects within the wire resource.

```json theme={null}
"return_requests": [{
  "created_at": "ISO-8601",
  "deadline": "ISO-8601",
  "status": "enum(response_needed|pending|accepted|rejected)",
  "reason": "enum",
  "details": "string",
  "resolution": {
    "resolved_at": "ISO-8601",
    "resolved_by": "enum(client|lead|counterparty)",
    "rejection_reason": "enum",
    "rejection_details": "string"
  }
}]
```

## Receiving Return Requests

The counterparty financial institution may send a return request if they want a previously sent wire to be returned.

Return requests are included as sub-objects within the wire object.

* A wire may have multiple return requests over time.
* Only one incoming return request may be active and can be responded to at a time. Additional incoming return requests received while one is in `response_needed` will be automatically rejected.
* You are responsible for reviewing and responding to each request.

### Incoming Return Request Statuses

The lifecycle of an incoming `return_request` sub-object begins after the original wire reaches `posted` status. The only incoming `return_request` status that triggers an event is `response_needed`.

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

### Key Behavior

Accepting a Return Request

* Use the [return a wire](https://docs.lead.bank/api-reference/endpoint/wire/return-a-wire-v1) endpoint to accept the return request. You may return the full or partial amount.
* The return request is considered accepted once the return wire is submitted

Rejecting a Return Request

* Done via a dedicated [endpoint](https://docs.lead.bank/api-reference/endpoint/wire/return-a-wire-v1)
* No funds are moved

Response Deadline

* If no response is provided within 10 business days, the return request is automatically rejected

### 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**                               | Webhook |
| :------------------------------------- | :------------------------------------------------------------------------- | :-------------------------------------------- | ------- |
| `wires.return_request_response_needed` | You received an incoming return request that requires a response from you. | Begin review and respond before the deadline. | Yes     |

### Endpoints

| **Endpoint**                                  | **Description**                                                          |
| :-------------------------------------------- | :----------------------------------------------------------------------- |
| `POST /wires/{wire_id}/return`                | Accept the return request by initiating a return wire (full or partial). |
| `POST /wires/{wire_id}/reject_return_request` | Reject the active return request associated with the wire.               |

## Sending Return Requests

You can send a return request when you previously sent a wire and need to recover the funds.

Sending a return request:

* creates a new return request sub-object in the pending state within the wire.
* sends the return request to the counterparty financial institution.
* does not guarantee that funds will be returned.

You may send additional return requests to follow up or provide more context before the original request reaches a terminal state. As a result, a wire may have multiple active outgoing return requests at the same time.

### Statuses

| **Status** | **Description**                                              | **Webhook** |
| :--------- | :----------------------------------------------------------- | :---------- |
| `pending`  | The return request has been sent and is awaiting a response. | No          |
| `accepted` | The counterparty accepted the request.                       | Yes         |
| `rejected` | The counterparty rejected the request.                       | Yes         |

### Key Behavior

* Return requests are non-binding
  * The counterparty is not obligated to return funds.
* Return requests and returns are not strictly coupled
  * The counterparty may return funds without accepting the return request.
  * The counterparty may accept the return request without actually returning funds.
* If accepted:
  * The counterparty may initiate a return wire.
  * The returned amount may be full or partial.
* If rejected:
  * The counterparty rejects the return request, indicating they do not intend to return funds.
* If no response is received:
  * The return request may remain pending indefinitely.

### Events

| **Event**                             | **Description**                                                                         | **Your Action**                                 | Webhook |
| :------------------------------------ | :-------------------------------------------------------------------------------------- | :---------------------------------------------- | ------- |
| `wires.return_request_pending`        | The outgoing return request is created and is pending a response from the counterparty. | No actions required.                            | No      |
| `wires.return_request_status_updated` | The status of an outgoing return request has changed.                                   | (Optional) Notify your customer of the outcome. | Yes     |

### Endpoints

| **Endpoint**                           | **Description**                                              |
| :------------------------------------- | :----------------------------------------------------------- |
| `POST /wires/{wire_id}/request_return` | Send a return request for a previously posted outgoing wire. |

## Integration Best Practices

* Track returns based on actual return wires
  * Do not rely on return request status to determine if funds have been returned as they are not coupled.
  * Always monitor incoming wires to confirm settlement.
* Respond within the required timeframe
  * Incoming return requests must be resolved by the 10th business day.
  * If no response is provided, the request is automatically rejected.
* Handle non-deterministic outcomes
  * Accepted requests may not result in a return.
  * Rejected requests may still result in a return.
  * Pending requests may remain unresolved.
* Design for partial returns
  * Returned funds may be full or partial.
* Account for multiple requests
  * Outgoing: multiple return requests may be active at once.
  * Incoming: only one request can be actively responded to at a time.