---
title: "Simulate Incoming Wire V2"
method: POST
path: "/v2/simulate/wires/incoming"
tags: ["Simulation"]
---

# Simulate Incoming Wire V2

`POST /v2/simulate/wires/incoming`

Simulates an incoming wire against a creditor account in sandbox. Automatically advances to posted on creation; no call to advance required.

## Headers

- `Idempotency-Key` string, required

## Request body

- SimulateIncomingWireRequestV2 — Request body to simulate an incoming wire in sandbox. The corridor is inferred from the shape of `debtor_agent` rather than an explicit field, matching how Lead derives the corridor from the ISO 20022 payload on real incoming wires: a `business_identifier_code` with a non-US country code produces an international wire, while providing only `local_routing_identifier` produces a domestic wire.
  - `amount` integer, required — The amount of the wire transaction in cents.
  - `creditor_account_number_id` string, required — The ID of the Lead Bank Account Number object.
  - `debtor` SimulateWireDebtorRequestV2, required — The party sending the wire.
    - `name` string, required — Name of the sending party.
    - `account_identifier` object, required — Account identifier of the sending party.
      - `type` 'account_number' | 'iban', required — Type of account identifier.
      - `value` string, required — Account identifier value of the sending party.
    - `address` WirePostalAddressRequestV2, required — Hybrid ISO 20022 postal address. `country` and `town_name` are required; up to two unstructured lines plus the structured fields are otherwise optional.
      - `line_one` string — Line one of the address in unstructured format.
      - `line_two` string — Line two of the address in unstructured format.
      - `town_name` string, required — Name of a built-up area, with defined boundaries, and a local government.
      - `country_sub_division` string — Identifies a subdivision of a country such as a state, region, or county.
      - `post_code` string — Identifier of letters and/or numbers added to a postal address to assist mail sorting.
      - `country` string, required — ISO 3166-1 alpha-2 code representing a nation with its own government.
  - `debtor_agent` SimulateWireDebtorAgentRequest, required — The debtor's financial institution.
    - `local_routing_identifier` LocalRoutingIdentifierRequest — Routing or transit code used by the creditor agent's local clearing system for international wire transfers, such as a sort code, IFSC, or BSB. This field may be required for certain destinations.
      - `value` string — The value of the local routing identifier.
    - `business_identifier_code` string — Business Identifier Code (BIC) of the financial institution. A foreign financial institution's BIC is required to simulate an international wire.
  - `instructing_agent` SimulateWireInstructingAgentRequest — The financial institution that transmitted the payment to Lead.
    - `local_routing_identifier` LocalRoutingIdentifierRequest — Routing or transit code used by the creditor agent's local clearing system for international wire transfers, such as a sort code, IFSC, or BSB. This field may be required for certain destinations.
      - `value` string — The value of the local routing identifier.
  - `remittance_details` WireRemittanceDetails — Wire remittance details.
    - `payment_notification` string — Information about the payment notification.
    - `message_to_creditor` string — Information intended specifically for the creditor.
    - `message_to_receiving_fi` string — Information intended specifically for the receiving financial institution.
    - `fi_to_fi_message` string — Financial institution to financial institution information, most often used by a financial institution to explain additional detail of a wire.
    - `transfer_purpose` WireTransferPurposeV1 — The purpose or reason for which the wire is being sent.
      - `type` 'salary_payment' | 'invoice_payment' | 'gift' | 'payment_for_goods' | 'payment_for_services' | 'insurance_premium_payment' | 'interest_payment' | 'loan' | 'loan_repayment' | 'account_management' | 'cash_management_transfer' | 'tax_payment' | 'government_payment' | 'benefits_payment' | 'pension_payment' | 'rent_payment' | 'utilities_payment' | 'education_payment' | 'healthcare_payment' | 'charitable_payment' | 'refund' | 'fee_payment' | 'intercompany_transfer' | 'investment_payment' | 'fx_or_treasury' | 'derivatives_payment' | 'card_network_settlement' | 'other', required — Code representing the purpose of the transfer.
      - `other_details` string — Free-formatted text for wire sender if `other` is selected for `type`.
  - `payment_identifiers` WirePaymentIdentifiers — Wire payment identifiers.
    - `message_identification` string — Point to point reference, as assigned by the instructing party, and sent to the next party in the chain to unambiguously identify the message..
    - `end_to_end_identification` string — Unique identification that the initiating party in a wire message can use to unambiguously identify the transaction. This is passed through, unchanged, throughout the entire wire chain.
    - `uetr` string, uuid — Universally unique identifier to provide an end-to-end reference of a payment transaction.
    - `instruction_identification` string — Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction.
    - `return_identification` string — Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the returned transaction.
  - `metadata` Metadata — A set of key-value pairs that can be used to store additional information related to this object.

## Response `200`

Incoming wire object created. The response body is empty.

- SimulateResponse

## Other responses

- `422` — Your request parameters did not validate. Field-level detail is returned, including CPMI character set violations, a US BIC on `debtor_agent.business_identifier_code`, neither routing field present on `debtor_agent`, or an invalid nine-digit ABA on `debtor_agent.local_routing_identifier.value` or `instructing_agent.local_routing_identifier.value`.

---

[API](https://skmtc.net/lead/apis/lead-bank.md) · [All operations](https://skmtc.net/lead/apis/lead-bank/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lead/lead-bank/revisions/25c2a92d55e2/schema)