Skip to main content

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.

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

​
Return Request Object

Return requests are represented as sub-objects within the wire resource. 
"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.
StatusDescriptionWebhook
response_neededYou received an incoming return request that requires a response from you.Yes
acceptedYou accepted the incoming return request by initiating an outgoing returnNo
rejectedYou rejected the incoming return request and provided a reason why.No

​
Key Behavior

Accepting a Return Request
  • Use the return a wire 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
  • 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.
EventDescriptionYour Action
wires.return_request_response_neededYou received an incoming return request that requires a response from you.Begin review and respond before the deadline.

​
Endpoints

EndpointDescription
POST /wires/{wire_id}/returnAccept the return request by initiating a return wire (full or partial).
POST /wires/{wire_id}/reject_return_requestReject 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

StatusDescriptionWebhook
pendingThe return request has been sent and is awaiting a response.No
acceptedThe counterparty accepted the request.Yes
rejectedThe 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

EventDescriptionYour Action
wires.return_request_status_updatedThe status of an outgoing return request has changed.(Optional) Notify your customer of the outcome.

​
Endpoints

EndpointDescription
POST /wires/{wire_id}/request_returnSend 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.