Wire ISO 20022 Address Transition Guide

Overview

This guide explains Newline's transition from legacy unstructured Wire address formats to ISO 20022 structured address formats. It outlines current behavior, upcoming changes, transition timelines, validation requirements, migration expectations, and client actions required before the November ISO 20022 address cutover.

During the transition period, clients will be able to submit either the current unstructured address format or the new structured address format. After the transition period ends, only structured addresses will be accepted.

This guide should be used by clients to evaluate existing address collection processes, implement required API changes, and prepare existing Wire workflows for ISO 20022 compliance.

Newline currently supports unstructured, line-based address fields. Structured address support will be introduced as part of ISO 20022 compliance.

The ISO 20022 address enhancement introduces structured address support for Wire processing.

What clients Should Expect

Key changes include:

• New structured address fields
• Required city and country values for beneficiary addresses
• Additional validation requirements
• A migration period where both formats are supported
• Required updates to existing synthetic account records before November cutover

The largest impact for most clients will be the requirement to collect beneficiary city and country information that may not be captured today.

Supported Endpoints

The following endpoints include Wire address data:

• POST /transfers
• POST /synthetic_accounts
• GET /transactions
• POST /mock_transactions

Current Address Format

Unstructured Address (Supported Today)

Wire address data is currently represented using line-based fields.

Example

{
  "wire": {
    "wire_transmitter": {
      "line1": "123 Main St",
      "line2": "Suite 100",
      "line3": null,
      "country": "US"
    }
  }
}

Fields

Address Requirements

• Address must represent a complete mailing address
• Country must be included
• Address may be required depending on the Wire use case

Validation (Current State)

Validation is enforced at the API level.

Current behavior:

• Free-form text is supported in address lines
• Country must be a valid country code
• Additional validation rules are handled internally by the platform

ISO 20022 Structured Address (Future State)

Structured address support will introduce discrete address components aligned with ISO 20022 requirements.

The objective is to improve:

• Data quality
• Interoperability
• Regulatory compliance
• Straight-through processing

Address requirements differ depending on the Wire workflow.

Address Objects Impacted by ISO 20022

ISO 20022 structured address requirements impact two address objects used throughout Wire payment workflows:

• Beneficiary Address (counterparty.address)
• Originator Address (wire.wire_transmitter)

This section identifies the affected objects and their locations within the API. Subsequent sections describe the payload changes required to support ISO 20022 structured addresses.

Beneficiary Address

The beneficiary address is stored in the counterparty.address object on the Synthetic Accounts API and represents the Wire beneficiary.

• Endpoint: /synthetic_accounts
• Object: counterparty.address
• Requirement: A structured address will be required when ISO 20022 structured address support becomes mandatory.

{
  "counterparty": {
    "address": {
      "line1": "123 Main St",
      "line2": "Suite 100",
      "country": "US"
    }
  }
}

Originator Address

The originator address is stored in the wire.wire_transmitter object on the Transfers API and represents the Wire originator.

• Endpoint: /transfers
• Object: wire.wire_transmitter
• Requirement: Required only when initiating_type is set to transmitter.

{
  "wire": {
    "wire_transmitter": {
      "line1": "123 Main St",
      "line2": "Suite 100",
      "country": "US"
    }
  }
}

Summary

Note: The examples above illustrate the current object locations within the API. The ISO 20022 migration sections that follow provide examples of the current format, transition format, and final ISO-compliant structured address format.

Address Requirements by Endpoint

Important: When an address is supplied using the structured address format, city and country are required fields. During the transition period, clients should verify they are collecting this information from beneficiaries and originators where applicable.

Structured Address Fields

Validation Rules (Structured Format)

Format Rules

Format Coexistence

During the transition period, clients may submit either the unstructured address format or the structured address format.

Structured and unstructured formats are mutually exclusive and cannot be submitted together within the same address object.

Precedence Rules

No precedence rules exist.

If both structured and unstructured address formats are provided, the request will be rejected.

Mixed Payload Handling

Mixed-format payloads are not supported.

Requests containing both structured and unstructured address formats will fail validation and return an error.

Response Behavior

For retrieval endpoints such as:

• GET /transactions

all available address fields, including both structured and unstructured address data, will be returned in the response.

Following the ISO transition, the GET /transactions endpoint will continue to return all address fields, including any newly supported ISO address attributes, to maintain backward compatibility and provide complete address information.

Migration Plan

Phase 1: Unstructured Addresses

Current state. Existing address format remains supported.

Phase 2: Transition Period

Clients may submit either:
• Unstructured addresses
• Structured addresses

The two formats remain mutually exclusive.

Phase 3: Structured Address Enforcement

The unstructured format will no longer be accepted. Only structured addresses may be submitted.

Required Client Actions

Clients should review current address collection processes to ensure beneficiary city and country information is available before structured address enforcement begins.

For existing synthetic accounts, clients must either:

• Update existing records using PUT operations to provide structured address data

OR

• Delete and recreate synthetic accounts using the new structured address format

All required updates should be completed before the structured-address-only enforcement period begins.

Behavior Rules

Originator Address Sourcing

• Originator address information is supplied through the wire_transmitter address object on the Transfers endpoint.

Beneficiary Address Sourcing

• Beneficiary address information is supplied through the counterparty address object on the Synthetic Accounts endpoint.

Missing Transmitter Address Handling

• When initiating_type = transmitter, the originator address object becomes required and city and country must be supplied.
• When initiating_type = customer, the originator address object is optional.

Examples

Unstructured Address Example

{
  "wire": {
    "wire_transmitter": {
      "line1": "123 Main St",
      "line2": "Suite 100",
      "line3": null,
      "country": "US"
    }
  }
}

Structured Address Example

{
  "counterparty_address": {
    "building_number": "123",
    "street_name": "Main Street",
    "city": "Cincinnati",
    "state": "OH",
    "postal_code": "45202",
    "country": "US"
  }
}

Invalid Mixed Format Example

{
  "counterparty_address": {
    "line1": "123 Main Street",
    "line2": "Suite 100",
    "building_number": "123",
    "street_name": "Main Street",
    "city": "Cincinnati",
    "country": "US"
  }
}

Important: This payload is invalid because it combines unstructured address fields (line1, line2) with structured address fields (building_number, street_name).

Implementation Considerations

When ISO 20022 structured addresses become available:

• Existing integrations may continue using the current unstructured format during any supported transition period
• Clients should review address collection workflows for compatibility with structured fields
• Validation requirements may become more prescriptive than the current free-form model
• Additional address components may become required depending on regulatory and network requirements

Background

ISO 20022 is a global financial messaging standard that introduces structured data formats for improved consistency and interoperability.

The move from unstructured address lines to structured address components is intended to:

• Improve data quality
• Reduce ambiguity in address data
• Support regulatory compliance requirements
• Improve interoperability between financial institutions and payment networks
• Enable more reliable wire processing and screening

As Newline adopts ISO 20022 standards, structured address support will provide greater consistency across Wire payment workflows while maintaining a migration path for existing integrations.