Wires API V2 Migration Guide - Lead

Lead is migrating the Wire API from V1 to V2. All partners must migrate to V2 before Lead’s migration deadline on November 12, 2026. V1 will be deprecated after the migration window closes. This guide describes what changed, what you need to update, and the timeline for completing your migration. It will be updated if additional changes are made, with those changes recorded in the Changelog at the top of the page.

This guide will be updated as decisions are finalized.

Changelog

Date	Change
July 9, 2026	Initial version published.

Why This Migration is Required

The November 16, 2026 Fedwire ISO 20022 changes are the forcing function for V2. As part of this release, Fedwire is replacing fully unstructured postal addresses with a hybrid address format. The new format supports either fully structured addresses or structured addresses with up to two free-form address lines, but at minimum requires country and town_name as structured fields. Today, the V1 create-wire request accepts a fully unstructured address (line_one, line_two, line_three). After November 16, that shape will no longer be accepted. V2 introduces a new address object that supports the ISO hybrid address format. Since this changes the request schema, it requires a new API version rather than an in-place update to V1. V2 also enforces stricter validation on all rail-bound text fields, rejecting carriage returns, line feeds, tabs, and whitespace-only values. Since this migration already requires a new API version, V2 also introduces a focused set of improvements including corridor classification, consolidated routing identifiers, and enum-based return and rejection reasons so partners only need to migrate once instead of absorbing multiple breaking changes over time.

Timeline

Date	Milestone	Required Action
End of August 2026	Wire V2 available in Sandbox	Begin testing against V2 Sandbox APIs and webhooks. Start planning your integration now.
October 2026	Wire V2 available in Production	Partners may begin migrating from V1 to V2 in production.
November 12, 2026	Migration deadline	Complete your migration from V1 to V2 by this date.
November 16, 2026	Fedwire ISO 20022 v2.0 takes effect	Fedwire removes fully unstructured address support. All wires must be V2-compatible by this point.

The detailed migration runbook including the per-program cutover sequence, V1 deprecation timing, and maintenance windows will be shared as the migration plan is finalized. Contact your TAM with questions about your specific timeline.

Summary of Changes

Endpoint	Summary of Changes
Wire object (Wire V2)	New `corridor_type` and `initiating_party`; `routing_number` replaced by `local_routing_identifier` on all agents; `return.code` removed (use `return.reason` enum, with new `other` value); transfer purpose and rejection/return reason enums expanded; statuses unchanged for now
`POST /v2/wires`	New required `corridor_type`; hybrid address on `creditor.address` (`line_three` removed; `town_name` and `country` now required); `routing_number` replaced by `local_routing_identifier`; new optional `ultimate_debtor.name`; new ISO character-set validations on rail-bound text fields
`GET /v2/wires`	New `corridor_type` query filter; response returns WireV2 objects
`GET /v2/wires/{wire_id}`	No request changes; response returns WireV2 object
`PATCH /v2/wires/{wire_id}`	No request changes; response returns WireV2 object
`POST /v2/wires/{wire_id}/cancel`	No request changes; response returns WireV2 object
`POST /v2/wires/{wire_id}/return`	`return_code` replaced by `reason` enum; may now be called on incoming return wires to support return-of-a-return (after November 16); ISO character-set validations applied to `return_additional_information`
`POST /v2/wires/{wire_id}/request_return`	May now be called on return wires to support return-of-a-return (after November 16)
`POST /v2/wires/{wire_id}/reject_return_request`	No V2-specific changes

Wire V2 Object

The V2 wire object keeps the overall V1 shape and field names, with a focused set of ISO-driven additions and changes. The most significant differences from V1 are the hybrid address model, the consolidation of routing numbers into local_routing_identifier, the new corridor_type and initiating_party fields, and the move from raw ISO codes to normalized enums on return reasons.

Key Changes vs. V1

Field	V1	V2
`corridor_type`	Not present	New -`domestic` or `international`. For outgoing wires, set from the `POST /v1/wires` request; for incoming wires, derived from the payload and agent chain.
`status`	Full status set	No change for now. See Statuses for planned 2027 deprecations.
`*_agent.local_routing_identifier`	Not present	New - `{ scheme, value }`, replaces `routing_number`. For domestic wires, `scheme` is `USABA` and `value` is the 9-digit ABA. Applies to `debtor_agent`, `creditor_agent`, `instructing_agent`, `instructed_agent`, and charging agents.
`*_agent.routing_number`	Present on all agents	Removed; replaced by `local_routing_identifier`.
`initiating_party`	Not present	New - standard wire-party object. On outgoing wires, `initiating_party.name` is auto-populated with the partner’s name. On incoming wires, populated from the ISO payload when available.
`ultimate_debtor`	Response only	Now client-settable on create.
`*.address` (response)	Unstructured (`line_one`–`line_three`)	No change. Response keeps the existing shape, including `line_three`, to support legacy V1 wire data.
`remittance_details.transfer_purpose.type`	Outgoing purpose values only	Enum expanded to add incoming transfer-purpose values previously omitted to avoid a breaking change.
`return.code`	Raw ISO code	Removed. Use `return.reason` instead.
`return.reason`	Enum (mapped ISO reasons)	Full ISO reason set, plus a new `other` value for unmapped incoming codes. When `other`, the raw ISO code is placed in `return.additional_information` as `"ISO Code: <code>; <details>"`.
`rejection.reason`	Enum	Reason set revised for incoming and outgoing rejections.
`return_requests`	Not present in V1 today; being added to V1 before the V2 rollout	No V2-specific change.

Statuses

Wire statuses are unchanged from V1 for this migration. The full status set (created, scheduled, processing, posted, under_review, rejected, canceled, cancel_pending) continues to be returned as it is today.

Planned for 2027The wire status lifecycle changes are deferred until after the V2 rollout. Partners will receive at least three months’ notice before any status is removed. No action is required for the V2 migration itself.

The planned changes differ by direction:

Outgoing wires: scheduled, processing, and cancel_pending will be deprecated, leaving the lifecycle created → under_review → posted / rejected / canceled.
Incoming wires: under_review will become an active status (and the wire.under_review webhook will begin firing for incoming wires), leaving the lifecycle under_review → posted / rejected.

Example `Wire V2` Object

{
  "id": "wire_xyz123",
  "account_number_id": "account_number_xyz123",
  "created_at": "2026-05-25T10:00:00Z",
  "updated_at": "2026-05-25T10:05:00Z",
  "settlement_date": "2026-05-25",
  "direction": "outgoing",
  "type": "transfer",
  "corridor_type": "domestic",
  "status": "posted",
  "amounts": {
    "settlement_amount": 10000,
    "settlement_currency_code": "USD",
    "instructed_amount": 10000,
    "instructed_currency_code": "USD",
    "instructed_to_settlement_exchange_rate": "1"
  },
  "debtor": {
    "name": "Alex Smith",
    "account_identifier": { "type": "account_number", "value": "..." },
    "address": {
      "line_one": "string | null",
      "line_two": "string | null",
      "line_three": "string | null",
      "town_name": "string | null",
      "country_sub_division": "string | null",
      "post_code": "string | null",
      "country": "string | null"
    }
  },
  "debtor_agent": {
    "business_identifier_code": "string | null",
    "name": "string | null",
    "local_routing_identifier": { "scheme": "USABA", "value": "021000021" },
    "address": { "...": "..." }
  },
  "instructing_agent": {
    "name": "Lead Bank",
    "business_identifier_code": "string | null",
    "local_routing_identifier": { "scheme": "USABA", "value": "101019644" }
  },
  "instructed_agent": {
    "name": "JPMorgan Chase Bank",
    "business_identifier_code": "CHASUS33",
    "local_routing_identifier": { "scheme": "USABA", "value": "021000021" }
  },
  "creditor_agent": {
    "business_identifier_code": "CHASUS33",
    "name": "JPMorgan Chase Bank",
    "local_routing_identifier": { "scheme": "USABA", "value": "021000021" },
    "address": { "...": "..." }
  },
  "creditor": {
    "name": "Example Beneficiary Inc.",
    "account_identifier": { "type": "account_number", "value": "..." },
    "address": {
      "line_one": "123 Main St",
      "line_two": "Suite 100",
      "line_three": null,
      "town_name": "Kansas City",
      "country_sub_division": "MO",
      "post_code": "64105",
      "country": "US"
    }
  },
  "initiating_party": {
    "name": "Your Company Name",
    "account_identifier": { "type": "enum", "value": "string" },
    "address": { "...": "..." }
  },
  "ultimate_debtor": { "name": "John Smith" },
  "ultimate_creditor": {},
  "other_agents": {
    "previous_instructing_agent_one": {},
    "previous_instructing_agent_two": {},
    "previous_instructing_agent_three": {},
    "intermediary_agent_one": {},
    "intermediary_agent_two": {},
    "intermediary_agent_three": {}
  },
  "payment_identifiers": {
    "message_identification": "string | null",
    "end_to_end_identification": "string | null",
    "uetr": "string | null",
    "instruction_identification": "string | null",
    "return_identification": "string | null"
  },
  "remittance_details": {
    "payment_notification": "string | null",
    "message_to_creditor": "string | null",
    "message_to_receiving_fi": "string | null",
    "fi_to_fi_message": "string | null",
    "transfer_purpose": { "type": "enum", "other_details": "string | null" }
  },
  "charges": {
    "charge_bearer": "enum | null",
    "breakdown": [
      { "amount": "string", "currency_code": "string", "charging_agent": {} }
    ]
  },
  "related_wires": {
    "original_wire_id": "wire_xyz321 | null",
    "return_wire_ids": ["wire_xyz456"]
  },
  "return_requests": [
    {
      "status": "response_needed",
      "reason": "customer_requested",
      "details": "ISO Code: CUST; Beneficiary has not received funds",
      "deadline": "2026-06-10T23:30:00-04:00",
      "resolution": {
        "resolved_at": null,
        "resolved_by": null,
        "rejection_reason": null,
        "rejection_details": null
      },
      "created_at": "2026-05-26T09:00:00Z"
    }
  ],
  "return": {
    "reason": "enum",
    "additional_information": "string | null"
  },
  "rejection": {
    "reason": "enum",
    "additional_information": "string | null",
    "message_identification": "string | null"
  },
  "metadata": {}
}

Detailed API Changes by Endpoint

Create a Wire: POST /v2/wires

Field	V1	V2
URL path	`POST /v1/wires`	`POST /v2/wires`
`corridor_type`	Not present	New required enum - `domestic` or `international`. Determines which `creditor_agent` routing fields are required.
`creditor_agent.routing_number`	9-digit ABA	Removed; replaced by `creditor_agent.local_routing_identifier.value`. Required when `corridor_type=domestic`. Scheme is auto-populated by Lead.
`creditor_agent.business_identifier_code`	Required for international wires	Still required for international wires; now keyed to `corridor_type=international`. Not accepted when `corridor_type=domestic`.
`instructed_agent.routing_number`	Optional	Removed; replaced by `instructed_agent.local_routing_identifier.value`.
`creditor.address`	`line_one`, `line_two`, `line_three` (unstructured)	Hybrid address. `line_three` removed. `line_one` and `line_two` now optional (max 70 chars each).
`creditor.address.town_name`	Not present	New - required (max 35 chars).
`creditor.address.country`	Not present	New - required (ISO 3166-1 alpha-2, uppercase).
`creditor.address.country_sub_division`	Not present	New - optional.
`creditor.address.post_code`	Not present	New - optional.
`ultimate_debtor.name`	Not settable on create	New - optional (max 35 chars). Useful for nested payments where the ultimate customer differs from the debtor.
Text field validations	Standard	New ISO character-set validations on rail-bound text fields. CR, LF, Tab, and whitespace-only values are rejected.
Response	WireV1	WireV2

V2 Request Example

{
  "account_number_id": "account_number_xyz123",
  "corridor_type": "domestic",
  "amount": 10000,
  "currency_code": "USD",
  "creditor_agent": {
    "local_routing_identifier": { "value": "021000021" }
  },
  "instructed_agent": {
    "business_identifier_code": "BOFAUS3N",
    "local_routing_identifier": { "value": "026009593" }
  },
  "creditor": {
    "name": "Example Beneficiary Inc.",
    "account_identifier": {
      "type": "account_number",
      "value": "GB29NWBK60161331926819"
    },
    "address": {
      "line_one": "123 Main St",
      "line_two": "Suite 100",
      "town_name": "Kansas City",
      "country_sub_division": "MO",
      "post_code": "64105",
      "country": "US"
    }
  },
  "ultimate_debtor": { "name": "John Smith" },
  "remittance_details": {
    "message_to_creditor": "Payment for invoice 12345",
    "transfer_purpose": { "type": "enum", "other_details": "string" }
  },
  "payment_identifiers": { "end_to_end_identification": "E2E-20260525-001" },
  "metadata": { "client_reference_id": "abc123" }
}

List All Wires: GET /v2/wires

Field	V1	V2
URL path	`GET /v1/wires`	`GET /v2/wires`
`corridor_type` filter	Not present	New query parameter - `domestic` or `international`.
Other filters	`account_number_id`, `direction`, `status`, `created_at`, `limit`, `starting_after`, `ending_before`	No change.
Response	Array of WireV1 objects	Array of WireV2 objects.

Retrieve a Wire: GET /v2/wires/{wire_id}

Field	V1	V2
URL path	`GET /v1/wires/{wire_id}`	`GET /v2/wires/{wire_id}`
Request	No change	No change.
Response	WireV1	WireV2.

Update a Wire: PATCH /v2/wires/{wire_id}

Field	V1	V2
URL path	`PATCH /v1/wires/{wire_id}`	`PATCH /v2/wires/{wire_id}`
Request	`metadata` only	No change.
Response	WireV1	WireV2.

Cancel a Wire: POST /v2/wires/{wire_id}/cancel

Field	V1	V2
URL path	`POST /v1/wires/{wire_id}/cancel`	`POST /v2/wires/{wire_id}/cancel`
Request	No change	No change.
Response	WireV1	WireV2.

Return a Wire: POST /v2/wires/{wire_id}/return

Field	V1	V2
URL path	`POST /v1/wires/{wire_id}/return`	`POST /v2/wires/{wire_id}/return`
Target wire	Incoming transfer wires only	May also be called on incoming return wires to support return-of-a-return. Available only after the November 16, 2026 Fedwire ISO release.
Return reason	`return_code` - raw ISO code (e.g. `AC06`, `NARR`)	`return_code` removed. Replaced by `reason` - a normalized enum: `account_blocked`, `wrong_amount`, `creditor_name_mismatch`, `honor_return_request`, `fraud_suspected`, `creditor_request`, `narrative`, `missing_debtor_data`, `missing_creditor_data`.
Additional information	`return_additional_information`, required when `return_code=NARR`	`return_additional_information`, required when `reason=narrative`. Max 105 chars; new ISO character-set validations applied.
Amount	Optional (defaults to original wire amount)	No change.
Response	WireV1	WireV2.

Request Return: POST /v2/wires/{wire_id}/request_return For the full request and response schema, see the Return Requests guide.

Field	V1	V2
URL path	`POST /v1/wires/{wire_id}/request_return`	`POST /v2/wires/{wire_id}/request_return`
Target wire	Transfer wires	May also be called on incoming return wires to support return-of-a-return. Available only after the November 16, 2026 Fedwire ISO release.

Reject Return Request: POST /v2/wires/{wire_id}/reject_return_request For the full request and response schema, see the Return Requests guide.

Field	V1	V2
URL path	`POST /v1/wires/{wire_id}/reject_return_request`	`POST /v2/wires/{wire_id}/reject_return_request`
Behavior	No change	No change.

​Why This Migration is Required

​Timeline

​Summary of Changes

​Wire V2 Object

​Key Changes vs. V1

​Statuses

​Example Wire V2 Object

​Detailed API Changes by Endpoint

Why This Migration is Required

Timeline

Summary of Changes

Wire V2 Object

Key Changes vs. V1

Statuses

Example `Wire V2` Object

Detailed API Changes by Endpoint