jackhenry.dev
jXchange - SOAP API
ISO 20022 Hybrid Address ISO 20022 Hybrid Address
On this page... Executive Summary Key Mandate Changes Scope & Impacted APIs Version Terminology Detailed Validation Rules 1. Version Match Check (all entry points) 2. Agent Validation (vldtagent) - Version-Specific Rules Rules Applicable to Both Versions (v22 & v26) Rules Applicable to Version 26 (v26) Rules Applicable to Version 22 (v22) 3. Agent Free-Form Address Lines Rules Applicable to Version 22 (v22) Rules Applicable to Version 26 (v26) 4. Party Validation (vldtparty) - Version-Specific Rules Related Remittance Location (Both Versions) Rules Applicable to Version 26 (v26) Rules Applicable to Version 22 (v22) Debtor/Creditor Existence Checks (Both Versions - Restructured) 5. Party Free-Form Address Lines Rules Applicable to Version 22 (v22) Rules Applicable to Version 26 (v26) 6. camt.056/camt.029 Return Request & Response (vldtrrqrs) When WIRRQSAORP = 'A' (Agent) When WIRRQSAORP = 'P' (Party) When Neither Agent nor Party Version-Specific Rules for Return Request/Response 7. Other ID Validation (vldtothid) Rules Applicable to Version 26 (v26) Rules Applicable to Both Versions (Restructured) Rules Applicable to Version 22 (v22) Executive Summary Starting November 16, 2026 , the Federal Reserve (FED) will eliminate the ability to populate postal addresses as purely unstructured text across all message types, parties, and agents.
Key Mandate Changes Removal of 3-Line Free-Format Addresses: The legacy format of 3 free-format address lines will no longer be supported.Mandatory Address Elements: Town Name (TownName) and Country (Ctry) are now mandatory when an address is provided.Hybrid Address Model: Addresses can be populated as a hybrid postal address , which allows a maximum combination of up to 2 free-format lines alongside structured address elements. Purely unstructured 3-line addresses will fail validation.Scope & Impacted APIs These validation rules apply to the Add and Modify (Mod) APIs for the following ISO 20022 message types (unless otherwise noted):
pacs.008 (Financial Institution Transfer / Customer Credit Transfer)pacs.009 (Financial Institution Credit Transfer)pacs.004 (Payment Return)camt.056 / camt.029 (Payment Cancellation Request / Resolution)pain.013 (Creditor Payment Activation Request)Version Terminology Version 22 (v22): Refers to the current ISO 20022 implementation version prior to November 2026.Version 26 (v26): Refers to the new ISO 20022 implementation version effective November 16, 2026.Detailed Validation Rules 1. Version Match Check (all entry points) Validates that the incoming wire message version matches the expected system version.
Error Code Description 103497Wire created version does not match system version
2. Agent Validation (vldtagent) - Version-Specific Rules Rules Applicable to Both Versions (v22 & v26) Error Code Description 103061Agent Name required when no BIC present 103062Agent Name required when postal address present
Rules Applicable to Version 26 (v26) Error Code Description 103064Town Name and Country required (when address present or name without BIC, for qualifying agent types)
Rules Applicable to Version 22 (v22) Error Code Description 103064Town Name and Country required (when structured address with name but no BIC, no free-form) 103063Structured address mutually exclusive with free-form address
Rules Applicable to Version 22 (v22) Error Code Description Limit / Restriction 103442Address line exceeds 35 characters Max 35 chars per line 103365Too many address lines Limit 3 lines on v22
Rules Applicable to Version 26 (v26) Error Code Description Limit / Restriction 103365Too many address lines Limit 2 lines on v26 (No 35-char limit on v26)
4. Party Validation (vldtparty) - Version-Specific Rules Error Code Description 103087Town Name and Country required 103085Party Name required 103268Related Remittance and Unstructured Remittance cannot be combined
Rules Applicable to Version 26 (v26) Error Code Description 103086Name required when no BIC (non-RelatedRemittLocation parties) 103085Name required when address present 103087Town/Country required for qualifying party/message types with address
Rules Applicable to Version 22 (v22) Error Code Description 103094Structured address mutually exclusive with free-form address
Debtor/Creditor Existence Checks (Both Versions - Restructured) Error Code Description Note 103098Debtor party type required Mandatory field 103099Creditor party type required Mandatory field 103086Party type exists in free-form only No WITPARTY record found 103474GHInitiatingParty required Applicable to pain.013
Rules Applicable to Version 22 (v22) Error Code Description Limit / Restriction 103442Address line exceeds 35 characters Debtor/Creditor only 103363Too many address lines Limit 3 lines for Debtor/Creditor/RtnChain on v22
Rules Applicable to Version 26 (v26) Error Code Description Limit / Restriction 103363Too many address lines Limit 2 lines for all party types on v26
6. camt.056/camt.029 Return Request & Response (vldtrrqrs) When WIRRQSAORP = 'A' (Agent) Error Code Description Version Scope 103061BIC or Name required Both Versions 103062Name required when address present Both Versions 103280Town/Country required On v26, or when structured address present
When WIRRQSAORP = 'P' (Party) Error Code Description Version Scope 103086BIC or Name required Both Versions 103085Name required when address present Both Versions 103087Town/Country required when structured address present Both Versions
When Neither Agent nor Party Error Code Description Version Scope 103231BIC or Name required Both Versions
Version-Specific Rules for Return Request/Response Error Code Description Version Scope 1033653rd free-form address line not allowed (Agent) v26 Only 1033633rd free-form address line not allowed (Party) v26 Only 103279Free-form address mutually exclusive with structured address v22 Only
7. Other ID Validation (vldtothid) Rules Applicable to Version 26 (v26) Error Code Description 103496Proprietary scheme name (WITOIDSPRY) no longer allowed 103504Scheme Name Code (WITOIDSCDE) now required
Rules Applicable to Both Versions (Restructured) Error Code Description 103102Other ID value (witoid) is required
Rules Applicable to Version 22 (v22) Error Code Description 103103Cannot have both scheme code and proprietary
Topics in this section
Have a Question?
Have a how-to question? Seeing a weird error? Get help on our collaborative Discourse Register for the Developer Office Hours Please ignore this field
Thank you for your feedback!
Last updated Mon Aug 10 2026