ISO 20022 Structured Address Compliance

1. Why Act Now?

A mandatory change to how address data is formatted in cross-border payments takes effect on 14 November 2026. From that date, fully unstructured (free-text) addresses will be rejected. Ripple Treasury will support the compliant hybrid address format from 14 August 2026, but you should start the data cleanup today.

2. What's Changing?

The global payments industry is transitioning to ISO 20022, the international standard for financial messaging. As part of that transition, address data in cross-border payment messages must be carried in discrete structured fields rather than free-text lines. This is being enforced across major payment networks, including SWIFT (CBPR+), CHAPS, SEPA, and others.

At a minimum, every address must include a valid Town or City and Country in their designated structured fields. Ripple Treasury will support the hybrid address format, which meets the requirement: the mandatory structured fields are provided alongside up to two free-text Address Lines for supplementary street and building detail.

Town or City and Country are the only fields required for compliance.
However, this is a good opportunity to review and improve the overall quality of your address data more broadly because the shift toward more detailed structured payment data is likely to continue across the industry. There's no requirement to do this now, and it shouldn't delay work on the mandatory fields. But when you're already reviewing a record, capturing complete and accurate address details can reduce the effort needed for any future changes.

2.1. Unstructured vs. Hybrid Address Example

The following example of an acceptable hybrid address is illustrative. Requirements and timelines vary by scheme, market infrastructure, message type, and jurisdiction. Confirm the applicable specifications for your payment flows with your banking partners.

Unstructured Address (Rejected from Nov 2026)	Hybrid Address (Supported and Compliant)
Name: JOHN SMITH Address: 123 CITY AVENUE 10004 NEW YORK NY US	Name: JOHN SMITH Town Name: NEW YORK Country Sub Division: NY Country: US Post Code: 10004 Address Line: 123 City Avenue

Unstructured Address (Rejected from Nov 2026)

Hybrid Address (Supported and Compliant)

Name: JOHN SMITH

Address: 123 CITY AVENUE 10004 NEW YORK NY US

Name: JOHN SMITH

Town Name: NEW YORK

Country Sub Division: NY

Country: US

Post Code: 10004

Address Line: 123 City Avenue

3. What You Need to Do Now

The following three steps put you ahead of the August platform release and the November deadline.

Move through these steps for Reports 1 and 2 before starting Report 3. This allows you to capture and update information found by the first two reports before moving on.

3.1. Run Reports to Audit Your Address Data

Your Ripple Treasury platform includes a set of reports built to identify exactly which records need attention.

Run and update the four standard reports in order as described below. Each one highlights the specific records with missing or invalid address data, so your team can focus remediation where it is needed instead of reviewing every record by hand.

3.1.1. Access Your Reports

Log in to your Ripple Treasury platform as you normally would.
Navigate to Reporting > Reporting > Repository.
A new browser window opens where your reports are housed.
Scroll to and open the Cloned category folder.
Select a report to load the results.
- Run, read, and update your data from the first two reports before starting 4.3. Payment Templates.
Near the top of the report, select the Excel icon (labelled Export to Excel on hover) to download the report.
Open the exported file from your Downloads folder to review the results.

3.1.2. Read Your Reports

Every report applies the same rule set. Records that need attention are highlighted in red and yellow.

Review and update the following fields:

Country: Confirm the country is present and is a valid ISO 3166-1 alpha-2 code (for example, US, GB, DE).
State or Region: State or Region is present only for records in the US, CA, and AU (countries highlighted in yellow). For all other countries, it isn't required.
City or Town: Confirm the city or town is present and is a real city name, not a placeholder such as “NA”, “ZZ”, “N/A” or “City”.
- If the value of this field is “City”, it appears in yellow. We strongly recommend you replace this value with the actual name of the city or town.
Address 1: Confirm this contains only the number and street portion of the address.

3.2. Determine the Correct Address Information

For every highlighted record, determine the accurate Town or City, Country, and State or Region (when required) from your internal records, beneficiary correspondence, or banking partners.

3.3. Engage Your Banking Partners

Contact each bank to confirm their specific requirements and testing availability. Some banks require more than the ISO 20022 minimum, and acceptance testing can take four to six weeks per bank. Start these conversations early and run them in parallel when you can.

4. Reports

Run, read, and update your data from the first two reports before starting 4.3. Payment Templates.

4.1. ISO20022: Bank ID Validation

Attribute	Detail
Purpose	Update bank static data.
What to Check	Ensure every entry has a valid `Country` and `City` or `Town Name`, and a `State` or `Region` if the country is `US`, `CA`, or `AU`.
Highlighting	Records to be updated are shown in red and yellow. This is typically a small number of records.
Key Fields	`Bank City`, `Bank Country`, `Bank State` or `Bank Region` (for AU, CA, US), `Bank Alt Address 1`, `Bank Alt City`.
How to Update Data	Update the highlighted records directly in the Ripple Treasury platform using `Common Data` > `Banks` > `Bank List`.

4.2. ISO20022: Bank Account ID Validation

Attribute	Detail
Purpose	Update bank account static data.
What to Check	Ensure every entry has a valid `Country` and `City` or `Town Name`, and a `State` or `Region` if the country is `US`, `CA`, or `AU`.
Highlighting	Records to be updated are shown in red and yellow. This is typically a small number of records.
Key Fields	`Account City`, `Account State` or `Account Region` (for AU, CA, US), `Account Country`, `Account Alt Address 1`, `Account Alt City`.
How to Update Data	Update the highlighted records directly in the Ripple Treasury platform using `Common Data` > `Bank Accounts` > `Bank Account List`.

4.3. ISO20022: Payment Templates

Attribute	Detail
Purpose	Update payment templates data.
What to Check	Ensure every entry has a valid `Country` and `City` or `Town Name`, and a `State` or `Region` if the country is `US`, `CA`, or `AU`.
Highlighting	Records to be updated are shown in red and yellow.
Key Fields	`Credit Account Address 1`, `Credit Account City`, `Credit Account State` or `Credit Account Region`, `Credit Account Country`, `Alternate Credit Account Address 1`, `Alternate Credit Account City`, `Alternate Credit Bank City`, `Debit Account City`, `Debit Account State` or `Debit Account Region`, `Debit Account Country`, `Alternate Debit Account Address 1`, `Alternate Debit Account City`, `Alternate Debit Bank City`, `IBK1 Bank City`, `IBK1 Bank Country`.
How to Update Data	Update the data in your downloaded report and submit the changes to Ripple Treasury.

4.4. ISO20022: Historical Payments Transaction History

Attribute	Detail
Purpose	Review the last 180 days of payments data to identify address data that needs remediation where it was imported from third-party sources such as ERP accounts-payable (AP) files.
What to Check	Ensure every entry has a valid `Country` and `City` or `Town Name`, and a `State` or `Region` if the country is `US`, `CA`, or `AU`.
Highlighting	Records to be updated are shown in red and yellow.
Key Fields	`Credit Account Address 1`, `Credit Account Address 2`, `Credit Account City`, `Credit Account State` or `Credit Account Region`, `Credit Account Country`, `Alternate Credit Account Address 1`, `Alternate Credit Account City`, `Alternate Credit Bank City`, `Credit Bank State` or `Credit Bank Region`, `Credit Bank Country`, `Debit Account City`, `Debit Account State` or `Debit Account Region`, `Debit Account Country`, `Alternate Debit Account Address 1`, `Alternate Debit Account City`, `Alternate Debit Bank City`, `Debit Bank City`, `Debit Bank State` or `Debit Bank Region`, `Debit Bank Country`, `Intermediary Bank City`, `Intermediary Bank State` or `Intermediary Bank Region`, `Intermediary Bank Country`.
How to Update Data	Update the static data in your third-party system. These payments were initiated in third-party systems and uploaded into Ripple Treasury. For example, AP payments loaded from your ERP. For records that need to be corrected, update the master data at the source (for example, the vendor record in your ERP) so future payment files carry the corrected address into Ripple Treasury.

5. Submitting Corrected Data (Payment Template Report)

This section explains the process to submit updates from Report 3: Payment Templates for the Ripple Treasury team to apply your updates in the backend, starting with a test environment. No manual entry in the platform is required.

Download and review the Payment Templates report.
Delete the rows that don’t need to be updated. Remaining rows should represent records needing a corrected Country, City or Town, State or Region, or Address.
Fill in the corrected values. Enter a real city name (not a placeholder) and a valid 2-character ISO country code. Add State or Region for US, CA, and AU records.
Submit the updated Report 03 via a support ticket.
We apply your updates. Our team validates the data and applies the corrections to your payment templates via bulk database update on your behalf. We update your test environment first before anything is promoted to production.
You receive a notification when the update is complete so you can begin bank acceptance testing.

6. Key Dates

Date	Milestone
Now	Run the four reports, remediate data, and engage your banking partners.
14 August 2026	Ripple Treasury hybrid address support available. Configuration is opt-in and backward compatible.
14 November 2026	Industry deadline. Fully unstructured addresses are rejected across major networks.

7. Questions?

Raise a support ticket or contact your customer success manager. A detailed configuration guide and readiness checklist will be shared ahead of the August hybrid address release. We're here to help you cross the line well before November.

This material is provided for general guidance only. ISO 20022 requirements and timelines vary by scheme, market infrastructure, message type, and jurisdiction, and may change. Confirm the specifications applicable to your payment flows with your banking partners. Ripple Treasury, Powered by Ripple Treasury.