Return Requests

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.

Status	Description	Webhook
`response_needed`	You received an incoming return request that requires a response from you.	Yes
`accepted`	You accepted the incoming return request by initiating an outgoing return	No
`rejected`	You 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.

Event	Description	Your Action	Webhook
`wire.return_request_response_needed`	You received an incoming return request that requires a response from you.	Begin review and respond before the deadline.	Yes

Endpoints

Endpoint	Description
`POST /wires/{wire_id}/return`	Accept the return request by initiating a return wire (full or partial).
`POST /wires/{wire_id}/reject_return_request`	Reject 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

Status	Description	Webhook
`pending`	The return request has been sent and is awaiting a response.	No
`accepted`	The counterparty accepted the request.	Yes
`rejected`	The 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

Event	Description	Your Action	Webhook
`wire.return_request_pending`	The outgoing return request is created and is pending a response from the counterparty.	No actions required.	No
`wire.return_request_status_updated`	The status of an outgoing return request has changed.	(Optional) Notify your customer of the outcome.	Yes

Endpoints

Endpoint	Description
`POST /wires/{wire_id}/request_return`	Send 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.

Banking Infrastructure

Funding & Settlement

Payment Rails

Customers & Accounts

Overview

Return Request Object

Receiving Return Requests

Incoming Return Request Statuses

Key Behavior

Events

Endpoints

Sending Return Requests

Statuses

Key Behavior

Events

Endpoints

Integration Best Practices

​Overview

​Return Request Object

​Receiving Return Requests

​Incoming Return Request Statuses

​Key Behavior

​Events

​Endpoints

​Sending Return Requests

​Statuses

​Key Behavior

​Events

​Endpoints

​Integration Best Practices

Overview

Return Request Object

Receiving Return Requests

Incoming Return Request Statuses

Key Behavior

Events

Endpoints

Sending Return Requests

Statuses

Key Behavior

Events

Endpoints

Integration Best Practices