Skip to main content
POST
/
v1
/
wires
/
{wire_id}
/
return
Return a wire V1
curl --request POST \
  --url https://api.sandbox.lead.bank/v1/wires/{wire_id}/return \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "return_code": "AC06",
  "return_additional_information": "<string>",
  "amount": 5000,
  "metadata": {}
}
'
{
  "id": "wire_xyz123",
  "account_id": "account_xyz123",
  "account_number_id": "account_number_xyz123",
  "created_at": "2024-06-27T11:22:33Z",
  "updated_at": "2024-06-27T11:22:33Z",
  "settlement_date": "2024-06-27",
  "direction": "incoming",
  "type": "transfer",
  "status": "created",
  "amounts": {
    "settlement_amount": 5000,
    "settlement_currency_code": "USD",
    "instructed_amount": 5000,
    "instructed_currency_code": "<string>",
    "instructed_to_settlement_exchange_rate": 1
  },
  "debtor": {
    "name": "Alan Scott",
    "account_identifier": {
      "type": "other",
      "value": 1234567890
    },
    "address": {
      "department": "Procurement Department",
      "sub_department": "IT Procurement",
      "street_name": "Main Street",
      "building_number": "100",
      "building_name": "City Hall",
      "floor": "4th Floor",
      "post_box": "PO Box 12345",
      "room": "600",
      "post_code": "12345",
      "town_name": "Kansas City",
      "town_location_name": "Westside North",
      "district_name": "Manhattan",
      "country_sub_division": "NY",
      "country": "US",
      "line_one": "123 Main St",
      "line_two": "Suite 100",
      "line_three": "Kansas City, MO 64105"
    }
  },
  "debtor_agent": {
    "business_identifier_code": "BOFAUS3NXXX",
    "name": "Bank of America",
    "routing_number": "<string>",
    "address": {
      "department": "Procurement Department",
      "sub_department": "IT Procurement",
      "street_name": "Main Street",
      "building_number": "100",
      "building_name": "City Hall",
      "floor": "4th Floor",
      "post_box": "PO Box 12345",
      "room": "600",
      "post_code": "12345",
      "town_name": "Kansas City",
      "town_location_name": "Westside North",
      "district_name": "Manhattan",
      "country_sub_division": "NY",
      "country": "US",
      "line_one": "123 Main St",
      "line_two": "Suite 100",
      "line_three": "Kansas City, MO 64105"
    }
  },
  "instructing_agent": {
    "name": "Bank of America",
    "routing_number": "021000021"
  },
  "instructed_agent": {
    "name": "Bank of America",
    "routing_number": "021000021"
  },
  "creditor_agent": {
    "business_identifier_code": "BOFAUS3NXXX",
    "name": "Bank of America",
    "routing_number": "<string>",
    "address": {
      "department": "Procurement Department",
      "sub_department": "IT Procurement",
      "street_name": "Main Street",
      "building_number": "100",
      "building_name": "City Hall",
      "floor": "4th Floor",
      "post_box": "PO Box 12345",
      "room": "600",
      "post_code": "12345",
      "town_name": "Kansas City",
      "town_location_name": "Westside North",
      "district_name": "Manhattan",
      "country_sub_division": "NY",
      "country": "US",
      "line_one": "123 Main St",
      "line_two": "Suite 100",
      "line_three": "Kansas City, MO 64105"
    }
  },
  "creditor": {
    "name": "Alan Scott",
    "account_identifier": {
      "type": "other",
      "value": 1234567890
    },
    "address": {
      "department": "Procurement Department",
      "sub_department": "IT Procurement",
      "street_name": "Main Street",
      "building_number": "100",
      "building_name": "City Hall",
      "floor": "4th Floor",
      "post_box": "PO Box 12345",
      "room": "600",
      "post_code": "12345",
      "town_name": "Kansas City",
      "town_location_name": "Westside North",
      "district_name": "Manhattan",
      "country_sub_division": "NY",
      "country": "US",
      "line_one": "123 Main St",
      "line_two": "Suite 100",
      "line_three": "Kansas City, MO 64105"
    }
  },
  "other_agents": {
    "previous_instructing_agent_one": {
      "business_identifier_code": "BOFAUS3NXXX",
      "name": "Bank of America",
      "routing_number": "<string>",
      "address": {
        "department": "Procurement Department",
        "sub_department": "IT Procurement",
        "street_name": "Main Street",
        "building_number": "100",
        "building_name": "City Hall",
        "floor": "4th Floor",
        "post_box": "PO Box 12345",
        "room": "600",
        "post_code": "12345",
        "town_name": "Kansas City",
        "town_location_name": "Westside North",
        "district_name": "Manhattan",
        "country_sub_division": "NY",
        "country": "US",
        "line_one": "123 Main St",
        "line_two": "Suite 100",
        "line_three": "Kansas City, MO 64105"
      }
    },
    "previous_instructing_agent_two": {
      "business_identifier_code": "BOFAUS3NXXX",
      "name": "Bank of America",
      "routing_number": "<string>",
      "address": {
        "department": "Procurement Department",
        "sub_department": "IT Procurement",
        "street_name": "Main Street",
        "building_number": "100",
        "building_name": "City Hall",
        "floor": "4th Floor",
        "post_box": "PO Box 12345",
        "room": "600",
        "post_code": "12345",
        "town_name": "Kansas City",
        "town_location_name": "Westside North",
        "district_name": "Manhattan",
        "country_sub_division": "NY",
        "country": "US",
        "line_one": "123 Main St",
        "line_two": "Suite 100",
        "line_three": "Kansas City, MO 64105"
      }
    },
    "previous_instructing_agent_three": {
      "business_identifier_code": "BOFAUS3NXXX",
      "name": "Bank of America",
      "routing_number": "<string>",
      "address": {
        "department": "Procurement Department",
        "sub_department": "IT Procurement",
        "street_name": "Main Street",
        "building_number": "100",
        "building_name": "City Hall",
        "floor": "4th Floor",
        "post_box": "PO Box 12345",
        "room": "600",
        "post_code": "12345",
        "town_name": "Kansas City",
        "town_location_name": "Westside North",
        "district_name": "Manhattan",
        "country_sub_division": "NY",
        "country": "US",
        "line_one": "123 Main St",
        "line_two": "Suite 100",
        "line_three": "Kansas City, MO 64105"
      }
    },
    "intermediary_agent_one": {
      "business_identifier_code": "BOFAUS3NXXX",
      "name": "Bank of America",
      "routing_number": "<string>",
      "address": {
        "department": "Procurement Department",
        "sub_department": "IT Procurement",
        "street_name": "Main Street",
        "building_number": "100",
        "building_name": "City Hall",
        "floor": "4th Floor",
        "post_box": "PO Box 12345",
        "room": "600",
        "post_code": "12345",
        "town_name": "Kansas City",
        "town_location_name": "Westside North",
        "district_name": "Manhattan",
        "country_sub_division": "NY",
        "country": "US",
        "line_one": "123 Main St",
        "line_two": "Suite 100",
        "line_three": "Kansas City, MO 64105"
      }
    },
    "intermediary_agent_two": {
      "business_identifier_code": "BOFAUS3NXXX",
      "name": "Bank of America",
      "routing_number": "<string>",
      "address": {
        "department": "Procurement Department",
        "sub_department": "IT Procurement",
        "street_name": "Main Street",
        "building_number": "100",
        "building_name": "City Hall",
        "floor": "4th Floor",
        "post_box": "PO Box 12345",
        "room": "600",
        "post_code": "12345",
        "town_name": "Kansas City",
        "town_location_name": "Westside North",
        "district_name": "Manhattan",
        "country_sub_division": "NY",
        "country": "US",
        "line_one": "123 Main St",
        "line_two": "Suite 100",
        "line_three": "Kansas City, MO 64105"
      }
    },
    "intermediary_agent_three": {
      "business_identifier_code": "BOFAUS3NXXX",
      "name": "Bank of America",
      "routing_number": "<string>",
      "address": {
        "department": "Procurement Department",
        "sub_department": "IT Procurement",
        "street_name": "Main Street",
        "building_number": "100",
        "building_name": "City Hall",
        "floor": "4th Floor",
        "post_box": "PO Box 12345",
        "room": "600",
        "post_code": "12345",
        "town_name": "Kansas City",
        "town_location_name": "Westside North",
        "district_name": "Manhattan",
        "country_sub_division": "NY",
        "country": "US",
        "line_one": "123 Main St",
        "line_two": "Suite 100",
        "line_three": "Kansas City, MO 64105"
      }
    }
  },
  "payment_identifiers": {
    "message_identification": "20241215MMQFMP2L017736",
    "end_to_end_identification": "EndtoEnd12345",
    "uetr": "dae7d83c-1624-4a79-a8ef-3794de115c13",
    "instruction_identification": "Instruction12345",
    "return_identification": "ReturnInstruction12345"
  },
  "remittance_details": {
    "payment_notification": "ba77ae30-efb8-4139-8e51-37e3fd905b2b",
    "message_to_creditor": "Payment for invoice 12345",
    "message_to_receiving_fi": "message for receiving financial institution",
    "fi_to_fi_message": "message from financial institution to financial institution",
    "transfer_purpose": {
      "type": "invoice_payment",
      "other_details": "Payment for consulting services"
    }
  },
  "related_wires": {
    "original_wire_id": "wire_xyz001",
    "return_wire_ids": [
      "wire_xyz002"
    ]
  },
  "return": {
    "reason": "honor_return_request",
    "code": "<string>",
    "additional_information": "<string>"
  },
  "rejection": {
    "reason": "honor_return_request",
    "additional_information": "<string>",
    "message_identification": "20241215MMQFMP2L017736"
  },
  "metadata": {}
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Idempotency-Key
string
required

Idempotency key

Maximum string length: 255

Path Parameters

​
wire_id
string
required

ID of the wire object you want to return.

Pattern: ^wire_\w+$

Body

application/json
​
return_code
enum<string>
required

List of eligible return reason codes for wire transfers.

  • AC06 - account_blocked
  • AM09 - wrong_amount
  • BE01 - creditor_name_mismatch
  • FOCR - honor_return_request
  • FR01 - fraud_suspected
  • MS02 - creditor_request
  • NARR - narrative
  • RR02 - missing_debtor_data
  • RR03 - missing_creditor_data
Available options:
AC06,
AM09,
BE01,
FOCR,
FR01,
MS02,
NARR,
RR02,
RR03
Example:

"AC06"

​
return_additional_information
string

Additional details about why the wire is being returned that will be included with the returned wire.

Required string length: 1 - 105
Pattern: ^[ \w/\-\?:\(\)\.,'\+!@#$%^&\*=`\{\|\}~";<>\[\\\]]*[\w/\-\?:\(\)\.,'\+!@#$%^&\*=`\{\|\}~";<>\[\\\]][ \w/\-\?:\(\)\.,'\+!@#$%^&\*=`\{\|\}~";<>\[\\\]]*$
​
amount
integer<int64>

The amount to be returned in cents. If not provided, the original wire amount will be used.

Required range: 1 <= x <= 990000000000
Example:

5000

​
metadata
object

A set of key-value pairs that can be used to store additional information related to this object.

Response

The new outgoing return wire object.

​
id
string

Unique identifier of the wire object.

Pattern: ^wire_\w+$
Example:

"wire_xyz123"

​
account_id
string

The ID of the Account object.

Pattern: ^account_\w+$
Example:

"account_xyz123"

​
account_number_id
string

The ID of the Lead Bank Account Number object.

Pattern: ^account_number_\w+$
Example:

"account_number_xyz123"

​
created_at
string<date-time>

ISO 8601 format timestamp representing when the wire object was created.

Example:

"2024-06-27T11:22:33Z"

​
updated_at
string<date-time>

ISO 8601 format timestamp representing when the wire object was last updated.

Example:

"2024-06-27T11:22:33Z"

​
settlement_date
string<date>

The ISO-8601 Datestamp indicating the wire settlement date based on the Fedwire's business day definition.

Example:

"2024-06-27"

​
direction
enum<string>

Who is initiating the transaction.

outgoing: You are sending a wire transaction to a counterparty. incoming: You are receiving an wire transaction from a counterparty.

Available options:
outgoing,
incoming
Example:

"incoming"

​
type
enum<string>

Indicates the type of wire message that the object represents.

Available options:
transfer,
return
Example:

"transfer"

​
status
enum<string>

The current status of the wire object.

Available options:
created,
scheduled,
processing,
posted,
under_review,
rejected,
canceled,
cancel_pending
Example:

"created"

​
amounts
object
​
debtor
object

Details of the debtor sending funds.

​
debtor_agent
object

Details of the financial institution where the debtor (payer) holds their account. This object may be absent if the instructing agent does not provide this information.

​
instructing_agent
object

The financial institution that transmitted the payment through Fedwire. In some cases, this may differ from the bank where the account is held. This object will always be populated.

​
instructed_agent
object

The financial institution that received the payment through Fedwire. This may not always be the bank where the recipient's account is held. This object will always be populated.

​
creditor_agent
object

Details of the financial institution where the creditor (payee) holds their account. This object may be absent if the instructing agent does not provide this information.

​
creditor
object

Details of the creditor receiving funds.

​
other_agents
object

Details of any other agents involved in the wire transfer.

​
payment_identifiers
object

Wire payment identifiers.

​
remittance_details
object

Wire remittance details.

​
related_wires
object

Related wire objects.

​
return
object
​
rejection
object
​
metadata
object

A set of key-value pairs that can be used to store additional information related to this object.