Sign in

v1

latestOpenAPI 3.0.12026-07-26106359429.8 KB
Simulation

Simulate Incoming Return Request Acceptance

Simulate a counterparty financial institution accepting a return request you initiated. Acceptance arrives as a monetary return (pacs.004) crediting funds back to the original sender. Builds the incoming return wire and pushes it through the ingress path. Transitions the matching outgoing return request to accepted, populates the resolution, and fires the wires.return_request_status_updated webhook.

Requires an active outgoing return request (status = pending) on the wire. The amount must not exceed the original wire amount.

post/v1/simulate/wires/{wire_id}/incoming_return_request_acceptance

Path parameters

wire_idstring required

ID of the wire whose outgoing return request you want to simulate an acceptance of.

Request body

amountinteger required

The amount of the wire transaction in cents.

currency_code'USD' required

A three-letter currency code as defined in ISO 4217.

Example request

{
  "amount": 5000,
  "currency_code": "USD"
}

Response

The updated wire object, with the outgoing return request now in accepted status and a return wire credited.

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"
    }
  ]
}