Sign in

v1

latestOpenAPI 3.0.12026-07-26106359429.8 KB
Simulation

Simulate Incoming Return Request

Simulate an incoming return request (camt.056) from a counterparty financial institution against one of your outgoing wires. Creates a new return_request entry on the wire with status response_needed and a deadline, and fires the wires.return_request_response_needed webhook.

Repeat calls drive the auto-rejection edge cases:

  • Against a wire that is already fully returned → the new request is auto-rejected with reason returned_previously (ISO ARDT).
  • While another return request is still in response_needed → the new request is auto-rejected with reason narrative and ISO code ARPL in the details.
post/v1/simulate/wires/{wire_id}/incoming_return_request

Path parameters

wire_idstring required

ID of the outgoing wire you want to simulate an incoming return request against.

Request body

reason'creditor_account_number_invalid' | 'wrong_amount' | 'customer_requested' | 'duplication' | 'fraud_suspected' | 'narrative' | 'technical_problem' | 'undue_payment' | 'per_agent_request' | 'other' required

Reason for the return request.

  • creditor_account_number_invalid — ISO AC03. Wire was sent to the wrong account number.
  • wrong_amount — ISO AM09. Wire amount is not the agreed amount or expected.
  • customer_requested — ISO CUST. The partner's end customer requested the return.
  • duplication — ISO DUPL. Duplicate wire sent.
  • fraud_suspected — ISO FRAD. Fraud suspected.
  • narrative — ISO NARR. Catch-all when no structured reason fits; details field carries the explanation.
  • technical_problem — ISO TECH. A technical issue caused the wire to be sent.
  • undue_payment — ISO UPAY. Payment was not due or for services not performed.
  • per_agent_request — ISO AGNT. Incoming only — Lead is the agent for outgoing payments.
  • other — Incoming only. Catch-all for unmapped ISO codes received from the counterparty.
additional_informationstring

Free-text explanation included with the simulated request.

Response

The updated wire object, now containing the new return request entry.

idstring

Unique identifier of the wire object.

account_idstring

The ID of the Account object.

account_number_idstring

The ID of the Lead Bank Account Number object.

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

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_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
  },
  "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",
    "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"
    },
    "local_routing_identifier": {
      "scheme": "GBDSC",
      "value": "123456"
    }
  },
  "instructing_agent": {
    "name": "Bank of America",
    "routing_number": "021000021",
    "business_identifier_code": "CHASUS33"
  },
  "instructed_agent": {
    "name": "Bank of America",
    "routing_number": "021000021",
    "business_identifier_code": "CHASUS33"
  },
  "creditor_agent": {
    "business_identifier_code": "BOFAUS3NXXX",
    "name": "Bank of America",
    "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"
    },
    "local_routing_identifier": {
      "scheme": "GBDSC",
      "value": "123456"
    }
  },
  "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"
    }
  },
  "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",
      "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"
      },
      "local_routing_identifier": {
        "scheme": "GBDSC",
        "value": "123456"
      }
    },
    "previous_instructing_agent_two": {
      "business_identifier_code": "BOFAUS3NXXX",
      "name": "Bank of America",
      "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"
      },
      "local_routing_identifier": {
        "scheme": "GBDSC",
        "value": "123456"
      }
    },
    "previous_instructing_agent_three": {
      "business_identifier_code": "BOFAUS3NXXX",
      "name": "Bank of America",
      "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"
      },
      "local_routing_identifier": {
        "scheme": "GBDSC",
        "value": "123456"
      }
    },
    "intermediary_agent_one": {
      "business_identifier_code": "BOFAUS3NXXX",
      "name": "Bank of America",
      "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"
      },
      "local_routing_identifier": {
        "scheme": "GBDSC",
        "value": "123456"
      }
    },
    "intermediary_agent_two": {
      "business_identifier_code": "BOFAUS3NXXX",
      "name": "Bank of America",
      "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"
      },
      "local_routing_identifier": {
        "scheme": "GBDSC",
        "value": "123456"
      }
    },
    "intermediary_agent_three": {
      "business_identifier_code": "BOFAUS3NXXX",
      "name": "Bank of America",
      "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"
      },
      "local_routing_identifier": {
        "scheme": "GBDSC",
        "value": "123456"
      }
    }
  },
  "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",
          "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"
          },
          "local_routing_identifier": {
            "scheme": "GBDSC",
            "value": "123456"
          }
        }
      }
    ]
  },
  "related_wires": {
    "original_wire_id": "wire_xyz001",
    "return_wire_ids": [
      "wire_xyz002"
    ]
  },
  "return": {
    "reason": "honor_return_request"
  },
  "rejection": {
    "reason": "honor_return_request",
    "message_identification": "20241215MMQFMP2L017736"
  },
  "return_requests": [
    {
      "created_at": "2024-06-27T12:15:00Z",
      "details": "suspected unauthorized activity",
      "deadline": "2024-07-08T23:30:00Z"
    }
  ]
}