Sign in

v1

latestOpenAPI 3.0.12026-07-26106359429.8 KB
Wire

Return a wire V2

Initiate a return against an incoming wire. In V2 this can also be called on an incoming return wire (pacs.004) to support return-of-a-return.

post/v2/wires/{wire_id}/return

Path parameters

wire_idstring required

ID of the wire object you want to return. May be an incoming transfer wire or an incoming return wire.

Headers

Idempotency-Keystring required

Idempotency key

Request body

reason'account_blocked' | 'wrong_amount' | 'creditor_name_mismatch' | 'honor_return_request' | 'fraud_suspected' | 'creditor_request' | 'narrative' | 'missing_debtor_data' | 'missing_creditor_data' required

The reason for returning the wire.

return_additional_informationstring

Additional details about why the wire is being returned that will be included with the returned wire. Required when reason is narrative.

amountinteger

The amount of the wire transaction in cents.

metadataMetadata

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

Example request

{
  "reason": "creditor_request",
  "amount": 5000
}

Response

The new outgoing return wire object.

idstring

Unique identifier of the wire object.

account_number_idstring

The ID of the Lead Bank Account Number object.

core_transaction_idsstring[]

Linked core transaction ID(s) associated with the wire.

created_atstring date-time

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

updated_atstring date-time

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

settlement_datestring date

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

direction'outgoing' | 'incoming'

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.

type'transfer' | 'return'

Indicates the type of wire message that the object represents.

corridor_type'domestic' | 'international'

Indicates whether the wire is domestic or international.

status'created' | 'scheduled' | 'processing' | 'posted' | 'under_review' | 'rejected' | 'canceled' | 'cancel_pending'

The current status of the wire object.

metadataMetadata

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

Example response

{
  "id": "wire_xyz123",
  "account_number_id": "account_number_xyz123",
  "core_transaction_ids": [
    "core_transaction_xyz123"
  ],
  "created_at": "2024-06-27T11:22:33Z",
  "updated_at": "2024-06-27T11:22:33Z",
  "settlement_date": "2024-06-27",
  "direction": "incoming",
  "type": "transfer",
  "corridor_type": "domestic",
  "status": "created",
  "amounts": {
    "settlement_amount": 5000,
    "settlement_currency_code": "USD",
    "instructed_amount": 5000
  },
  "debtor": {
    "name": "Alan Scott",
    "account_identifier": {
      "type": "other"
    },
    "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",
    "local_routing_identifier": {
      "scheme": "GBDSC",
      "value": "123456"
    },
    "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",
    "business_identifier_code": "CHASUS33",
    "local_routing_identifier": {
      "scheme": "GBDSC",
      "value": "123456"
    }
  },
  "instructed_agent": {
    "name": "Bank of America",
    "business_identifier_code": "CHASUS33",
    "local_routing_identifier": {
      "scheme": "GBDSC",
      "value": "123456"
    }
  },
  "creditor_agent": {
    "business_identifier_code": "BOFAUS3NXXX",
    "name": "Bank of America",
    "local_routing_identifier": {
      "scheme": "GBDSC",
      "value": "123456"
    },
    "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"
    },
    "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"
    }
  },
  "initiating_party": {
    "name": "Alan Scott",
    "account_identifier": {
      "type": "other"
    },
    "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"
    }
  },
  "ultimate_debtor": {
    "name": "Alan Scott",
    "account_identifier": {
      "type": "other"
    },
    "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"
    }
  },
  "ultimate_creditor": {
    "name": "Alan Scott",
    "account_identifier": {
      "type": "other"
    },
    "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",
      "local_routing_identifier": {
        "scheme": "GBDSC",
        "value": "123456"
      },
      "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",
      "local_routing_identifier": {
        "scheme": "GBDSC",
        "value": "123456"
      },
      "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",
      "local_routing_identifier": {
        "scheme": "GBDSC",
        "value": "123456"
      },
      "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",
      "local_routing_identifier": {
        "scheme": "GBDSC",
        "value": "123456"
      },
      "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",
      "local_routing_identifier": {
        "scheme": "GBDSC",
        "value": "123456"
      },
      "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",
      "local_routing_identifier": {
        "scheme": "GBDSC",
        "value": "123456"
      },
      "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"
    }
  },
  "charges": {
    "charge_bearer": "shared",
    "breakdown": [
      {
        "amount": "12.50",
        "currency_code": "USD",
        "charging_agent": {
          "business_identifier_code": "BOFAUS3NXXX",
          "name": "Bank of America",
          "local_routing_identifier": {
            "scheme": "GBDSC",
            "value": "123456"
          },
          "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"
          }
        }
      }
    ]
  },
  "related_wires": {
    "original_wire_id": "wire_xyz001",
    "return_wire_ids": [
      "wire_xyz002"
    ]
  },
  "return_requests": [
    {
      "created_at": "2024-06-27T12:15:00Z",
      "details": "suspected unauthorized activity",
      "deadline": "2024-07-08T23:30:00Z"
    }
  ],
  "return": {
    "reason": "honor_return_request"
  },
  "rejection": {
    "reason": "honor_return_request",
    "message_identification": "20241215MMQFMP2L017736"
  }
}