Understanding ISO 20022: The Language of Modern Payments

Introduction

Financial messaging has long suffered from a Babel of formats and terminologies. Different networks and schemes use their own data schemas—sometimes even the same word means different things—creating barriers to truly seamless interoperability. ISO 20022 was born to tackle these issues, offering a unified, semantically rich, and extensible framework for payments (as well as securities, trade, and more). In this post, we’ll explore the problem ISO 20022 solves, its methodology, adoption challenges, and how modern platforms like Mojaloop are evolving the standard for today’s API-driven world.

The Challenge: Fragmented Data

Before ISO 20022, every payment system essentially spoke its own language. You needed deep expertise in each syntax and its underlying business semantics to integrate end-to-end. This not only drove up development costs and time-to-market, it also delayed critical initiatives like cross-border payments and real-time settlements.

ISO 20022’s Promise

At its core, ISO 20022 is an international standard defining how financial messages should be modeled and encoded. By providing:

1. A common business model,

2. A library of reusable business components, and

3. Message definitions [1]

Four Layers of the ISO 20022 Methodology

We can understand the structure of an ISO 20022 message through the following layers:

1. Business Area

This defines the broader financial activity being carried out. Each business area is represented by a specific set of message categories, such as:

• pacs – Payments Clearing and Settlement

• pain – Payment Initiation

• camt – Cash Management

  

  Fig 1: Overview of Business Areas and ISO 20022 Usage in a Generic Cross-Border Payment System (Source:  Harmonization spec)

  2. Conceptual Model

  
  

  This layer outlines the high-level participants, and the business processes involved. For example:

  • Actors: Payer, Payee

  • Processes: Interbank Transfer, settlement It defines what needs to happen at a conceptual level, without going into technical details.

    

    Fig 2: Breakdown of Data Objects in a UML Diagram (Source: ISO 20022 for Dummies)

3. Logical Model

Here, we break down the message into its core components:

• Debtor: Name, address, account details

• Creditor: Name, address, account details

• Payment Instruction: A structure that groups these elements together to define the payment details (settlement type, number of payment transaction etc)

  
  

4. Physical Syntax

This is the actual representation of the message in a machine-readable format.

• XML is more widely used across the industry.

• However, JSON is gaining popularity, especially among API-first developers who prioritize lightweight, web-friendly formats.

The JSON Dilemma [4]

While XML enjoys official ISO schemas, JSON schemas are unofficial, and best practices for representing ISO 20022 in JSON remain fragmented. As more RESTful APIs adopt a minimalist JSON approach, the lack of standardized JSON definitions risks a new wave of inconsistency—exactly what ISO 20022 was meant to prevent. Industry groups are now working to publish guidelines and community-driven JSON schemas to bridge this gap.[4]

Adoption Drivers & Coexistence

• SEPA (Single Euro Payments Area): A major force behind ISO 20022 adoption in Europe.

• Global RTGS & Low-Value Systems: Many national payment systems are migrating or aligning with ISO 20022.

• Legacy Constraints: Large incumbents may delay a full migration due to cost, instead using adapters to map between internal formats and ISO 20022 messages. This coexistence phase is expected to be long-term—as we don’t “make the whole world speak English,” so too payments ecosystems will operate multiple syntaxes in parallel for years.

Extending the Standard: Developing New Messages

New business needs—for example, pre-execution notifications in Mojaloop—require the creation of new ISO 20022 messages. This involves submitting a business justification to the Registration Authority (SWIFT acts in that role since 2004), detailing the process, actors, and information elements.

Mojaloop’s Take on ISO 20022

Mojaloop demonstrates how a modern, open-source payments platform leverages and adapts ISO 20022:

• JSON Variant: use JSON representation, optimizing for API consumption.

• ULID Identifiers: Uses Unique Lexicographically Sortable Identifiers instead of UUIDs to enable natural ordering by creation time.

• ILPv4 Crypto: Embeds cryptographic signing and agreement steps within its “Agreement” phase and the overall transfer flow, ensuring message authenticity and non-repudiation beyond the base ISO 20022 spec.

Sample Mojaloop payload for put party call

{

  "party": {

    "partyIdInfo": {

      "partyIdType": "MSISDN",

      "partyIdentifier": "16135551212",

      "partySubIdOrType": "string",

      "fspId": "string",

      "extensionList": {

        "extension": [

          {

            "key": "string",

            "value": "string"

          }

        ]

      }

    },

    "merchantClassificationCode": "8",

    "name": "string",

    "personalInfo": {

      "complexName": {

        "firstName": "Henrik",

        "middleName": "Johannes",

        "lastName": "Karlsson"

      },

      "dateOfBirth": "1966-06-16",

    "supportedCurrencies": [

      "AED"

    ]

  }

}

Updated ISO payload format

{

"Assgnmt": {

"MsgId": "01JBVM14S6SC453EY9XB9GXQB5",

"CreDtTm": "2024-11-04T12:57:37.318Z",

"Assgnr": { "Agt": { "FinInstnId": { "Othr": { "Id": "payee-dfps" }}}},

"Assgne": { "Agt": { "FinInstnId": { "Othr": { "Id": "payer-dfsp" }}}}}

"Rpt": {

"Vrfctn": true,

"OrgnlId": "MSISDN/16665551002",

"UpdtdPtyAndAcctId": {"Pty": {"Id": {"PrvtId": {"Othr": {"SchmeNm": {"Prtry": "MSISDN"},

"Id": "16665551002"}}},

"Nm": "Chikondi Banda"},

"Agt": { "FinInstnId": { "Othr": { "Id": "payee-dfsp" }}},

"Acct": { "Ccy": "MWK" }}}

ISO20022 Message Formats of Mojaloop APIs

API	Descrption	ISO20022 message	Main Message components
Discovery phase GET /parties/{type}/{partyIdentifier} [/{subId}]	Account validation request	(request for parameters are added in the url)	NA
Discovery phase PUT /parties/{type}/{partyIdentifier} [/{subId}]	Account validation Response	Acmt.024.001.04 Account Identification Verification Report	Msg sender(payee DFSP), receiver(payer DFSP) + account validation information (status + account info)
Discovery phase PUT /parties/{type}/{partyIdentifier} [/{subId}]/error	Account validation error return	Acmt.024.001.04 Account Identification Verification Report	Msg sender(payee DFSP), receiver(payer DFSP) + error msg object ( status, Reason)
Agreement phase POST /fxQuotes	FX quote request	Pacs.091.001.01 Financial Institution Credit Transfer Quote Request	Settlement Info (type and etc) + (Credit Tnx info [ID, From, To, Amount, Expiry of the payment instructionCurrency)  (Type: Send Vs Receive)  Eg I want to send 50 USD to XX account,  Vs I want XX account to receive 50 USD.
Agreement phase Put /fxQuotes	Response for FX quote	pacs.092.001.01 Financial Institution Credit Transfer Quote Response	Response by FX provider Verification of term (ILP V4 digital signature)  Expiry of the payment instruction, amount in source currency, target currency
Agreement phase PUT /fxQuotes/{ID}/error	Error Response for FX quote	pacs.002.001.15 Financial Institution to Financial Institution Payment Status Report	IDs + error message
Agreement phase POST /quotes/{ID}	Quote and fee confirmation request	pacs.081.001.01 Financial Institution to Financial Institution Customer Credit Transfer Quote Request	Transfer request info (Payer Payee Account, Agent, Amount,Currency, settlement type)
Agreement phase PUT /quotes/{ID}	Quote and fee confirmation response	pacs.082.001.01 Financial Institution to Financial Institution Customer Credit Transfer Quote Response	Verification of Term (ILP V4 packet)  (Payer Payee Account, Agent, Amount,Currency, settlement type)
Agreement phase PUT /quotes/{ID}/error	Quote and fee confirmation error response	pacs.002.001.15 Financial Institution to Financial Institution Payment Status Report	IDs + Error Message
Transfer Phase POST /fxTransfers/{ID}	Currency conversion transfer request	pacs.009.001.12 Execute Financial Institution Credit Transfer	Payer To Hub (Amount sender: Payer DFSP, receiver: FXP) (Tnx overview info, account, agent, amount, currency, verification term
Transfer Phase PUT /fxTransfers/{ID}	Currency conversion transfer response	pacs.002.001.15 Financial Institution to Financial Institution Payment Status Report	FXP to Hub ILP fulfillment to indicate the terms has been met. + Tnx status
Transfer Phase PUT /fxTransfers/{ID}/error	Currency conversion transfer error response	pacs.002.001.15 Financial Institution to Financial Institution Payment Status Report	From Hub to Payer DFSP Payload [IDs + Error message]
Transfer Phase PATCH /fxTransfers/{ID}/error	Currency conversion transfer error response status update to Payee DPSP	pacs.002.001.15 Financial Institution to Financial Institution Payment Status Report	From Hub to FXP Payload [IDs + Status update]
Transfer Phase POST /transfers/{ID}	Transfer request (from Payer DFSP to Hub )	pacs.008.001.13 Financial Institution to Financial Institution Customer Credit Transfer	Payer To Hub (Amount sender: Payer DFSP, receiver: Payee DFSPor FXP to Payee DFSP) (Tnx overview info, account, agent, amount, currency, verification term
Transfer Phase PUT /transfers/{ID}	Transfer response (from Hub to Payer PSP)	pacs.002.001.15 Financial Institution to Financial Institution Payment Status Report	From Payee DFSP to Hub Payload [ILP fulfillment to indicate the terms has been met. + Tnx status ]
Transfer Phase PUT /transfers/{ID}/error	Transfer error response (from Hub to Payer PSP)	pacs.002.001.15 Financial Institution to Financial Institution Payment Status Report	From Hub to Payer DFSP Payload [IDs + Error message]
Transfer Phase PATCH /transfers/{ID}/error	Transfer error response status update to Payee DPSP	pacs.002.001.15 Financial Institution to Financial Institution Payment Status Report	From Hub to Payee DFSP Payload [IDs + Status update]

Recommended Study path:

1. Start with “ISO 20022 for Dummies” to get comfortable with the terminology and high‐level benefits.

2. Move on to the Harmonisation spec for a system-agnostic, deep-dive into the ISO 20022 specification.

3. Read the Mojaloop context write-up to see a real-world, open-source implementation and learn how ISO 20022 maps to modern APIs.

4. Finish with the MasterCard blog post for practical guidance on choosing between XML and JSON representations in your own RESTful designs, to see how an established player views the JSON vs XML issue.

References: 

1. BIS – ISO 20022 in Cross-Border Payments: Ready for Adoption?

2. SWIFT – ISO 20022 for Dummies

3. Mojaloop – ISO 20022 Market Practice Documentation

4. Mastercard – ISO 20022 and JSON: Balancing Standardisation and Flexibility in APIs 

*****

---

By Ei Nghon Phoo (Product Manager) Connect