Run an Escrow Flow Over Wires

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
Account Number	core	Per-deal routable address, attributed to the payer via entity_id	Account Numbers endpoints
Entity	user	Elena (and other deal parties your program represents)	Entity endpoints
Wire (incoming)	execution	The buyer’s funding wire	Wires endpoints
Wire (outgoing)	execution	Closing disbursements or return wires	Wires endpoints
Return request	execution	The ask, in either direction, to send posted funds back	Wires - return requests

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 first.
Wires run on business days with same-day settlement inside Lead’s published cutoffs — see wire windows and cutoffs. 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 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.

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 for more details. Once created, assign and activate the account number following the Account Number lifecycle, 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 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 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.

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

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

Lend

Store

Issue

Move

How it works

Example scenario

Objects involved

Before you start

Integration steps

Step 1: Provision a dedicated account number for each deal

Step 2: Receive and verify the funding wire

Step 3: Disburse at closing

Plan around wire cutoffs

Step 4: Return a wire you received

Step 5: Send a return request

Step 6: Respond to incoming return requests

Handling exceptions

Testing this flow in sandbox

​How it works

​Example scenario

​Objects involved

​Before you start

​Integration steps

​Step 1: Provision a dedicated account number for each deal

​Step 2: Receive and verify the funding wire

​Step 3: Disburse at closing

Plan around wire cutoffs

​Step 4: Return a wire you received

​Step 5: Send a return request

​Step 6: Respond to incoming return requests

​Handling exceptions

​Testing this flow in sandbox

How it works

Example scenario

Objects involved

Before you start

Integration steps

Step 1: Provision a dedicated account number for each deal

Step 2: Receive and verify the funding wire

Step 3: Disburse at closing

Step 4: Return a wire you received

Step 5: Send a return request

Step 6: Respond to incoming return requests

Handling exceptions

Testing this flow in sandbox