Receiving & Returning Wires

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.

{
  "return_code": "MS02"
}

When using NARR, include a free-form explanation:

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

Banking Infrastructure

Funding & Settlement

Payment Rails

Customers & Accounts

Receiving Wires

Statuses

Webhook Events

Creditor Name Match

How Matching Works

Examples

Sending Returns

Endpoints

Request Requirements

Webhook Events

​Receiving Wires

​Statuses

​Webhook Events

​Creditor Name Match

​How Matching Works

​Examples

​Sending Returns

​Endpoints

​Request Requirements

​Webhook Events

Receiving Wires

Statuses

Webhook Events

Creditor Name Match

How Matching Works

Examples

Sending Returns

Endpoints

Request Requirements

Webhook Events