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

# Run an Escrow Flow Over Wires

> Receive, verify, disburse, and return wires, using dedicated account numbers per transaction.

This guide walks through how to operate an escrow or trust-style flow using Lead’s wire rail: a payer funds a transaction by wire, you hold the funds until the required conditions are met, and then disburse them by wire.

Wires are well suited for large, time-sensitive payments where same-day settlement and finality are important. This guide covers the full flow, including receiving and verifying funds, disbursing at closing, returning incoming wires, and handling return requests.

## **How it works**

Funds are held in your **core account** at Lead. For each transaction, you provision a dedicated **Account Number** under the core account and associate it with the payer using `entity_id`. This allows you to identify which deal an incoming wire belongs to based on the receiving account number, rather than relying on memo fields.

Both incoming and outgoing payments are represented as wire objects. Wires submitted before the cutoff generally settle the same business day. Once a wire is posted, it cannot be reversed. Funds can only be sent back through a new return wire.

This guide covers the key escrow flows: receiving funds, disbursing funds, returning an incoming wire, and sending and responding to return requests.

## **Example scenario**

Keystone Escrow handles residential closings.

**Setup:** For the 14 Maple St. purchase, Keystone provisions a dedicated account number attributed to buyer Elena and puts the routing details on her wire instructions.

**Funding:** Elena's bank wires \$85,000. The wire lands on Keystone's escrow account, identified by the account number. Keystone verifies the originator and amount against the file before treating the deal as funded.

**Closing:** Keystone wires the payoff to the seller's lender and the net proceeds to the seller.

**Deal falls through:** Inspection kills the deal. Keystone returns Elena's \$85,000 by wire.

**Fraud:** Elena was tricked by a spoofed email into wiring twice. Her bank sends a return request to Keystone.

**Disbursement error:** Keystone sends the payoff to the wrong account and must send a return request.

## **Objects involved**

| Object              | Surface   | Role in this flow                                                 | Reference                                                                                    |
| ------------------- | --------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Core escrow account | core      | The Lead-managed account all deal funds sit in                    | [Banking Infrastructure](/products/banking-infrastructure/overview)                          |
| Account Number      | core      | Per-deal routable address, attributed to the payer via entity\_id | [Account Numbers endpoints](/api-reference/endpoint/account-number/create-an-account-number) |
| Entity              | user      | Elena (and other deal parties your program represents)            | [Entity endpoints](/api-reference/endpoint/entity/create-an-entity)                          |
| Wire (incoming)     | execution | The buyer's funding wire                                          | [Wires endpoints](/api-reference/endpoint/wire/create-a-wire-v1)                             |
| Wire (outgoing)     | execution | Closing disbursements  or return wires                            | [Wires endpoints](/api-reference/endpoint/wire/create-a-wire-v1)                             |
| Return request      | execution | The ask, in either direction, to send posted funds back           | [Wires - return requests](/api-reference/endpoint/wire/request-return-for-wire-v1)           |

## **Before you start**

* Sandbox credentials with wire, entity, and account-number scopes, plus the `account_id` for your core escrow account provided during onboarding.
* Build on the current wire API version. Existing integrations should read [wire V2 migration](/products/wire/v2-migration) first.
* Wires run on business days with same-day settlement inside Lead's published cutoffs — see [wire windows and cutoffs](/products/wire/processing-windows). A disbursement initiated after cutoff moves the next business day, which for a contractual closing date is an important fact to plan around.
* Domestic Fedwire is the focus here. USD international wires use the same API to support cross-border payments. See [international wires](/products/wire/international-wires) for more details.
* If your program represents deal parties as customers with reported balances, the daily reporting obligations apply unchanged. This guide covers only the wire mechanics.

## **Integration steps**

### **Step 1: Provision a dedicated account number for each deal**

Create an account number under your core escrow account and associate it with the entity funding the deal.

```text theme={null}
POST /v1/account_number
{
  "account_id": "your core escrow account_id",
  "entity_id": "Elena's entity_id",
  "...": "..."
}
```

The `account_id` is the identifier of your **core** account. The entity\_id identifies the party associated with the account number. Account numbers are always created under a core account, not a user Account. See [Object Model](/core-concepts/platform/object-model) for more details.

Once created, assign and activate the account number following the [Account Number lifecycle](/products/account-number/statuses), then provide its routing and account numbers in the wire instructions for the deal.

For escrow, we recommend using a unique account number for each deal. This makes it easier to attribute incoming funds to the correct deal and retire the account number when the deal closes. For recurring counterparties, a dedicated account number per party may be more appropriate.

Finally, configure the account number [controls](/products/account-number/controls) to accept incoming wires only. The account number used to fund the deal should not accept ACH payments.

### **Step 2: Receive and verify the funding wire**

When the incoming  wire is posted, Lead sends a `wire.posted` event confirming that the funds have arrived. The account number that received the wire identifies the associated deal.

Before treating the deal as funded, verify the incoming wire against the expected funding details, including:

* Originator information
* Funding amount
* Receiving account number

Define how mismatches should be handled before going live. For example, an unexpected originator, duplicate wire, or incorrect amount may require the wire to be returned rather than held in the escrow account. See Step 4 for the return flow.

In Sandbox, use the incoming wire simulator to test this flow. See [Simulate Incoming Wire](/api-reference/endpoint/simulation/simulate-incoming-wire) for details.

### **Step 3: Disburse at closing**

When the deal is ready to close, initiate an outgoing wire from the deal’s account number to the beneficiary.

```text theme={null}
POST /v1/wires
{
  "amount": 8500000,
  "debtor": {
    "account_number_id": "the deal's account number"
  },
  "creditor": {
    "...": "beneficiary bank and account details"
  },
  "...": "..."
}
```

Before sending the wire, independently verify the beneficiary’s payment instructions. For example, confirm any instructions received by email using a known phone number or another trusted channel. This is especially important when payment instructions have changed.

Once a wire has been sent, it cannot be reversed. If funds are sent incorrectly, you can request a return, but the receiving financial institution is not required to return them.<br />Track the wire until it reaches `posted` and retain the wire identifiers as part of your closing records.

##### **Plan around wire cutoffs**

Initiate closing disbursements early enough to meet the [cutoff](/products/wire/processing-windows). A wire initiated after cutoff will be sent the next business day, which can affect time-sensitive closing obligations.

### **Step 4: Return a wire you received**

If the deal falls through or the funding wire fails the verification in Step 2, return the funds to the originator. Use the wire return flow to return the funds and reference the original incoming wire. See [Return a Wire](/api-reference/endpoint/wire/return-a-wire-v1) for API details.

Once the deal is complete and the account number is no longer needed, cancel it to prevent additional funds from being sent to the closed deal.

### **Step 5: Send a return request**

If you sent a wire in error, for example to the wrong beneficiary, for the wrong amount, or as a duplicate, you can request that the receiving financial institution return the funds.

```text theme={null}
POST /v1/wires/{id}/request_return
{
  "...": "reason and reference details"
}
```

Track the return request through its status and webhooks.

A return request does not move funds, and an accepted request does not guarantee that the funds will be returned. Funds are only returned when the receiving financial institution sends a return wire. For this reason, submit the return request as soon as you identify the error.

### **Step 6: Respond to incoming return requests**

If the sending financial institution requests the return of a wire you received, you’ll receive a return request with a deadline for response.

Review the request based on the status of the funds and your established policies. For example, whether the funds are still available or have already been disbursed may affect how you respond.

Respond to the request through the API before the deadline. Because return requests are time-sensitive, define your review process before launch so your team can respond consistently and on time.

## **Handling exceptions**

| What happens                              | Signal                                       | What to do                                                                                                                          |
| ----------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Outgoing wire rejected                    | wire status → rejected                       | Review the wire’s error code or rejection reason, correct the underlying issue, then resubmit if appropriate.                       |
| Inbound wire matches no deal              | Your Step 2 verification                     | Return the wire (Step 4) if you cannot identify or verify the intended recipient of the funds.                                      |
| Amount doesn't match the expected funding | Step 2 verification                          | Review the discrepancy and handle it according to your established funding policy. If the wire needs to be returned, follow Step 4. |
| Your return request is declined           | Return-request status                        | Review the decline reason to understand why the request was rejected and determine the appropriate next steps.                      |
| Return request arrives on disbursed funds | Incoming request notification                | Respond according to your policy by the deadline.                                                                                   |
| Disbursement misses cutoff                | [cutoffs](/products/wire/processing-windows) | The wire will be sent the next business day. Account for cutoff times when planning time-sensitive disbursements.                   |

## **Testing this flow in sandbox**

Before going live, test the key parts of your escrow flow in Sandbox:

* Simulate an incoming wire to a deal account number and verify that it is attributed correctly.
* Create an outgoing wire and test its lifecycle through `posted`.
* Test returning an incoming wire.
* Test sending and responding to return requests.