Lead is migrating the Wire API from V1 to V2. All partners must migrate to V2 before Lead’s migration deadline. 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. This page is updated when additional changes occur, 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.
July 15, 2026	Added summary of breaking changes
September 2, 2026	Updated launch and migration timeline following the Federal Reserve’s decision to reschedule its November 2026 Fedwire release

Why We’re Moving to Wires V2

Wires V2 prepares our API for upcoming Fedwire ISO 20022 requirements while also introducing several improvements to the wires experience. The primary breaking change is a new hybrid address format. V2 replaces the fully unstructured V1 address with an ISO-compatible address object that requires country and town_name, while still allowing up to two free-form address lines. V2 also introduces stricter validation for rail-bound text fields. Since these changes require a new API version, we are also including several related improvements in the same migration, including corridor classification, consolidated routing identifiers, and enum-based return and rejection reasons. Although the Fedwire release has been rescheduled from November 2026 to November 2027, Lead is still moving forward with Wires V2 so partners can adopt these improvements now and be prepared for the future Fedwire requirements.

Timeline

Date	Milestone	Required Action
To be announced	Wire V2 available in Sandbox	Begin testing against V2 Sandbox APIs and webhooks. Start planning your integration now.
To be announced	Wire V2 available in Production	Partners may begin migrating from V1 to V2 in production. We recommend migrating as soon as V2 is available in production to avoid disrupting wire processing.
Q4, 2026	Migration deadline	Complete your migration from V1 to V2 by this date.
November 16, 2027	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 Breaking Changes

Area	v1	v2
Create wire	No `corridor_type`	`corridor_type` required
Routing number	`creditor_agent.routing_number`	Removed — use `creditor_agent.local_routing_identifier.value`
BIC field	Optional for any wire	Required for international, rejected for domestic
Creditor address	3 unstructured lines; `line_one` required	`town_name` + `country` required; `line_three` removed
Wire return	Field `return_code` with ISO 20022 codes	Field `reason` with human-readable values

1. Update Wire Creation (`POST /v2/wires`)

Several fields in the request body have changed. The top-level diff:

 {
   "account_number_id": "acn_123",
   "amount": 100000,
   "currency_code": "USD",
+  "corridor_type": "domestic", // [!code ++]
   "creditor_agent": { ... },
   "creditor": { ... },
   "remittance_details": { ... }
 }

1a. `corridor_type` Is Now Required

Set to "domestic" or "international". This value drives the validation rules for several other fields below. In addition, you may also include the new optional ultimate_debtor object:

{
  "corridor_type": "international",
  "ultimate_debtor": { "name": "Acme Corp" }
}

1b. Routing Number Moved To `local_routing_identifier.value`

creditor_agent.routing_number no longer exists in v2. Pass the 9-digit ABA routing number through creditor_agent.local_routing_identifier.value instead. This field is required when corridor_type is "domestic".

   "creditor_agent": {
-    "routing_number": "021000021" // [!code --]
+    "local_routing_identifier": { // [!code ++]
+      "value": "021000021" // [!code ++]
+    } // [!code ++]
   }

The same applies to instructed_agent if you use it.

1c. `business_identifier_code` (BIC) Is Now Corridor-type Conditional

In v1, BIC was informally required for international wires. In v2 this is enforced:

corridor_type: "international" → business_identifier_code required
corridor_type: "domestic" → business_identifier_code not accepted

// domestic — use local_routing_identifier, no BIC
creditor_agent: { local_routing_identifier: { value: '021000021' } }

// international — use BIC, no routing number
creditor_agent: { business_identifier_code: 'CHASUS33' }

1d. `creditor.address` Is Restructured

v2 adopts an ISO 20022 hybrid address format. line_three is removed and two new required fields are added: town_name and country.

Field	v1	v2
`line_one`	Required, max 35 chars	Optional, max 70 chars
`line_two`	Optional, max 35 chars	Optional, max 70 chars
`line_three`	Optional, max 35 chars	Removed
`town_name`	—	Required, max 35 chars
`country_sub_division`	—	Optional, max 35 chars
`post_code`	—	Optional, max 16 chars
`country`	—	Required, ISO 3166-1 alpha-2 (e.g. `"US"`)

   "address": {
+    "line_one": "123 Main St",
+    "line_two": "Suite 400",
	"line_three": "IL, USA",
+    "town_name": "Springfield", // [!code ++]
+    "country_sub_division": "IL", // [!code ++]
+    "post_code": "62701", // [!code ++]
+    "country": "US"
   }

If you were putting city/state/country into line_two or line_three, split those values into the new structured fields.

1e. Read-only Fields Removed From Request Schemas

In v1, payment_identifiers and remittance_details included several readOnly fields that were silently ignored in requests. In v2 these are absent from the request schema entirely — sending them will cause an error. If your code serializes a full wire object back into a create request, strip these fields first. payment_identifiers — only end_to_end_identification is accepted; remove:

message_identification, uetr, instruction_identification, return_identification

remittance_details — only message_to_creditor and transfer_purpose are accepted; remove:

payment_notification, message_to_receiving_fi, fi_to_fi_message

2. Update Wire Return Reasons

POST /v2/wires/{wire_id}/return renames return_code to reason and replaces ISO 20022 codes with human-readable strings. v1 request:

{
  "return_code": "AC06"
}

v2 request:

{
  "reason": "account_blocked"
}

Full Mapping

v1 `return_code`	v2 `reason`
`AC06`	`account_blocked`
`AM09`	`wrong_amount`
`BE01`	`creditor_name_mismatch`
`FOCR`	`honor_return_request`
`FR01`	`fraud_suspected`
`MS02`	`missing_debtor_data`
`RR02`	`creditor_request`
`NARR`	`narrative`
`RR03`	`missing_creditor_data`

// v1
await client.post(`/v1/wires/${wireId}/return`, {
  return_code: 'AC06',
  return_additional_information: 'Account is frozen',
});

// v2
await client.post(`/v2/wires/${wireId}/return`, {
  reason: 'account_blocked',
  return_additional_information: 'Account is frozen',
});

3. Handle New Response Fields

v2 wire responses include new fields. You don’t have to use them, but you should not break if they appear.

const wire = await getWire(wireId);

// New in v2 — safe to use, ignore if not needed
wire.corridor_type       // "domestic" | "international"
wire.core_transaction_ids // ["ctx_abc", "ctx_def"]
wire.initiating_party    // object — the party that initiated the wire

Detailed 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, 2027 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, 2027 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.

Banking Infrastructure

Lending & Receivables

Payment Rails

Customers & Accounts

Network Settlement

Wires API V2 Migration Guide

Why We’re Moving to Wires V2

Timeline

Summary of Breaking Changes

1. Update Wire Creation (`POST /v2/wires`)

1a. `corridor_type` Is Now Required

1b. Routing Number Moved To `local_routing_identifier.value`

1c. `business_identifier_code` (BIC) Is Now Corridor-type Conditional

1d. `creditor.address` Is Restructured

1e. Read-only Fields Removed From Request Schemas

2. Update Wire Return Reasons

Full Mapping

3. Handle New Response Fields

Detailed Changes

Wire V2 Object

Key Changes vs. V1

Statuses

Example `Wire V2` Object

Detailed API Changes by Endpoint

​Why We’re Moving to Wires V2

​Timeline

​Summary of Breaking Changes

​1. Update Wire Creation (POST /v2/wires)

​1a. corridor_type Is Now Required

​1b. Routing Number Moved To local_routing_identifier.value

​1c. business_identifier_code (BIC) Is Now Corridor-type Conditional

​1d. creditor.address Is Restructured

​1e. Read-only Fields Removed From Request Schemas

​2. Update Wire Return Reasons

​Full Mapping

​3. Handle New Response Fields

​Detailed Changes

​Wire V2 Object

​Key Changes vs. V1

​Statuses

​Example Wire V2 Object

​Detailed API Changes by Endpoint

Why We’re Moving to Wires V2

Timeline

Summary of Breaking Changes

1. Update Wire Creation (`POST /v2/wires`)

1a. `corridor_type` Is Now Required

1b. Routing Number Moved To `local_routing_identifier.value`

1c. `business_identifier_code` (BIC) Is Now Corridor-type Conditional

1d. `creditor.address` Is Restructured

1e. Read-only Fields Removed From Request Schemas

2. Update Wire Return Reasons

Full Mapping

3. Handle New Response Fields

Detailed Changes

Wire V2 Object

Key Changes vs. V1

Statuses

Example `Wire V2` Object

Detailed API Changes by Endpoint