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

> Configure your system to receive incoming wires and initiate returns against them.

Receive incoming wire transfers and return them when necessary: statuses, webhooks, and creditor name match enforcement.

## Receiving Wires

Receiving an incoming wire creates a new `wire` object with an incoming direction. Incoming wires are received and posted automatically. No action is required to receive a wire.

### Statuses

Incoming `wire` objects have three potential statuses during their lifecycle, all of which trigger a webhook.

| Status         | Description                                                         | Webhook |
| -------------- | ------------------------------------------------------------------- | ------- |
| `under_review` | Incoming wire is under manual review by Lead.                       | Yes     |
| `posted`       | Funds have been credited to the account.                            | Yes     |
| `rejected`     | Incoming wire was rejected. See the `rejection` object for details. | Yes     |

### Webhook Events

| Event               | What happened                            | Recommended action                                               |
| ------------------- | ---------------------------------------- | ---------------------------------------------------------------- |
| `wire.under_review` | Incoming wire is under manual review.    | Notify your customer their payment is temporarily delayed.       |
| `wire.posted`       | Funds have been credited to the account. | Notify your customer that their funds are available.             |
| `wire.rejected`     | Incoming wire was rejected.              | See the `rejection` object for details and notify your customer. |

## Creditor Name Match

Lead validates all incoming wires against the receiving account's legal name. If the creditor name on the wire does not closely match the account's legal entity name, the wire is rejected with a `creditor_name_mismatch` rejection reason.

### How Matching Works

Matching is approximate to account for minor variations in formatting and spelling:

* **Individuals:** approximate match on first and last name
* **Businesses:** approximate match on legal name or DBA

### Examples

**Approved**

| Name on wire    | Account name              |
| --------------- | ------------------------- |
| thomas thompson | THOMAS THOMPSON RABINE    |
| triangle lab    | TRIANGLE LABORATORIES INC |
| Justin hurwanti | JUSTIN NURWANTI           |

**Rejected**

| Name on wire | Account name                     |
| ------------ | -------------------------------- |
| adl febriana | Adi Daniel                       |
| james har    | Mohamed Haruna                   |
| John Smith   | ABC Global Logistics Commodities |

To avoid rejections, instruct your counterparties to use the receiving entity's name as the creditor name when sending wires.

## Sending Returns

You can return a posted incoming wire using `POST /v1/wires/{wire_id}/return`. A return creates a new `wire` object with `type: return` and follows the same outgoing status lifecycle. Additionally, the active `return_request` sub-object of the original payment, if exists, moves into `accepted` status automatically.

### Endpoints

| Endpoint                          | Description                   |
| --------------------------------- | ----------------------------- |
| `POST /v1/wires/{wire_id}/return` | Return a posted incoming wire |

### Request Requirements

| Field                           | Requirement                                                                                 |
| ------------------------------- | ------------------------------------------------------------------------------------------- |
| `return_code`                   | Return reason code for the return. See [Rejection and Return Codes]() for available values. |
| `return_additional_information` | Required when `return_code` is `NARR`. Free-form explanation, up to 105 characters.         |

```json theme={null}
{
  "return_code": "MS02"
}
```

When using `NARR`, include a free-form explanation:

```json theme={null}
{
  "return_code": "NARR",
  "return_additional_information": "Wire received in error, please return funds to originator."
}
```

### Webhook Events

| Event               | What happened                          | Recommended action                                                                                  |
| ------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `wire.under_review` | Return wire flagged for manual review. | Notify the counterparty of the delay. The return wire will proceed or be rejected following review. |
| `wire.posted`       | Return wire has been sent.             | Notify your customer and the counterparty that the funds have been returned.                        |
| `wire.rejected`     | Return wire was rejected.              | Inspect the `rejection` object and contact Lead if needed.                                          |
| `wire.canceled`     | Return wire was successfully canceled. | Notify your customer and the counterparty that the return has been canceled.                        |