Digital APIs versus ISO 20022

Share on:


Are you Mr. Betamax? Oh no, sorry, surely you are Mr.VHS. Millennials outcry: “What the heck are you talking about?". Ok, you are surely Mr. USB-C, not Mr. Lighting connector. ISO 20022, to be or not to be, that’s the question, I understand. Do you want to be compliant, or non-compliant? Compliant, of course! (Firecrackers go off!).

How could you possibly be non-compliant? Just say, yes, “I comply”, that’s all Kim Jong-un wants to hear. The world would be a better place, if you just … did comply.

International Standards Organisation. ISO (Eye-So, or I-S-O). No, you didn't get it. It’s an international organisation. You can’t hide from it if you live on planet Earth. It sets standards, and you are in a financial institution that is not playing ball. You are drowning in anxiety. Don’t panic. I’m with you.

ISO 20022 ≠ APIs

You are tasked with modernising APIs—or maybe implementing a new greenfield application. The CEO has announced that the company aims to be ISO 20022 compliant in three years time. The pressure is on. You take a quick look at an example of a Payment Initiation message: pain.001

You are horrified:

  • It’s all XML: at a time when your team is in the process of replacing “legacy” REST APIs with GraphQL.
  • Tag names are cryptic: you haven’t got a clue as to how they map to your company’s own data sets.
  • So many mandatory tags! you don’t even know where to get the data to populate them, provided that you managed to decipher their semantics.

“This can’t possibly be the future” you say to yourself. You look at what your competitors are doing in the same space. You find that they all provide beautiful, compact REST APIs with meaningful, developer-friendly attributes. You scratch your head. “Am I missing a trick here?” you ask. Yes, it’s context.

Digital APIs are slim because most of the data is enriched by the platform.

ISO 20022 aims to standardise the exchange of electronic data (and transactions) in the corporate space (e.g. big payroll systems running batch) and the interbank space (banks, clearing and settling mechanisms, etc.).

“In general, you will go to your bank website or to a branch and no one will ask you to provide the pain.001 message. Who then uses pain.001 messages? Enterprises, associations, non-governmental organizations and similar institutions do. In short, any company or institution that needs to initiate a sizeable number of payment orders. Solutions for individuals are not appropriate for them.”

(Megue, 2018, p. 33)

The reason as to why the ISO 20022 message types are verbose is because the third party institution that receives the message knows nothing about your customers, their accounts, their addresses, and so on. In the case of a retail-facing API, the converse is true. The platform “knows” pretty much everything about the customer performing the transaction, so the API needs to ask only the bare minimum. For example, in a payment, the platform knows the customer’s address, their default account number or credit card, etc. Whilst a message that leaves your institution or bank may well be in an ISO 20022 message format such as pacs.008, it needs to be enriched with data from multiple databases before the message goes out the door.

You are relieved, “fine, I can forget about ISO 20022 then, it’s the mainframe guys’ problem”, you think. Not so fast.

Alignment versus Compliance

ISO 20022 compliance is a misnomer. It makes it look like a black and white deal. Being ISO 20022 compliant, if interpreted in a rigid manner, would be implementing all the provided physical XML messages but even that would not provide a seamless plug and play experience. This is because financial institutions have to agree on transports (MQ, TIBCO EMS, etc.), security, networking, and, most importantly, on the same message versions.

For example, your bank might have implemented the latest version of the Payment Initiation message pain.001.001_10, but if you want to be SEPA compliant, you need to implement a much older version. Furthermore, an ISO 20022 “compliant” address accepts up to seven address lines, whereas SEPA restricts this limit to two (Megue, 2018, p. 50). This means that if you implemented ISO 20022 and knew nothing about SEPA, it wouldn’t mean that you could just reuse your existing messages “AS IS”. This is not the only instance where SEPA breaks ISO 20022, which assumes more lenient bounds than those found in the provided XSD schemas.

As you can see, compliance is a problematic notion in the world of ISO 20022. Alignment is a more realistic approach to ISO 20022 and the way in which the standard is actually meant to be adopted. The ISO team repeatedly states that XML is just a possible physical representation (SWIFT, 2020, p. 13) and that the underlying semantics is what the standard is truly about. But this notion often falls on deaf ears. This arises from the misconception that ISO 20022 is an API.

Ultimately, ISO 20022 is about reducing and duplicate work, in addition to accelerating time to market in the financial sector. Alignment achieves all of this.

How to Align to ISO 20022

The areas of focus are three: business modelling, logical data modelling, and physical message implementation.

Business modelling is an overloaded notion. In the case of ISO 20022, the standard is not forcing you to run (and thus model) your business in a peculiar way so that you become undifferentiated. It just focuses on the processes that must be common across two or more financial institutions. But the ISO 20022 business processes are the last thing you would look at when aligning to ISO.

The first thing is aligning on naming conventions and the scope of each term. This is key. It’s not just “what do you call this thing in your bank” kind of deal. It may be that that “thing” is actually two different things. For example, in ISO 20022, payor and payee, are formally referred as debtor and creditor, respectively. But this is not all, the notions of debtor agent, and creditor agent, are also introduced to differentiate the institution that handles the payment from the actual parties (SWIFT, 2020, p. 11)

Once all business entities are aligned and a business dictionary is produced, it is much easier (and faster) to discuss and agree on requirements.

Using ISO 20022 in the context of alignment

Now let us turn our attention to the logical model. Here we find a wealth of primitives and complex entities (address, party, etc.) which we can use to model our database schemas and message types even in JSON, Protocol Buffers, Thrift, or any other transport/encoding mechanism. This is useful for internal representations, so that when the time of composing, say, a pacs.008 message comes, all of its constituent ingredients are served on the table already chopped.

Physical message implementation in the form of XML schemas is something that ISO 20022 provides as a reference, and as a valid way to encode messages, but it is not the only one. In fact, schemas in the ASN.1 format are also provided precisely to prove this point: ISO 20022 is not about XML.


Aligning to ISO 20022 for internal entity representation, and being able to provide the logical structure of both inbound and outbound messages types that apply to the corporate customer to bank, and interbank spaces is a good thing. An XML representation should be treated as one or many encoding types, rather than as the canonical interface per se.

Digital APIs (those that face retail customers through Digital front-ends such as websites, mobile apps, etc.) do not use ISO 20022 primarily because the spec was not meant for this use case. Even if you wanted to shoehorn ISO 20022 into this space (so that you can somewhat claim to be more standard), you would reduce security, increase friction, and provide a terrible developer experience: your employees will quit and your partners will use the competition’s alternative.

Why ask for account details that your platform already has stored in a database? Why ask for a postal address that your system has already stored and validated t? It’s utterly nonsensical. You would need to provide separate APIs to serve this data, and then revalidate it all over again when it appears in the ISO 20022 message.

Now you know. Digital APIs and ISO 20022? Yes, the same as oil and vinegar.


  1. Megue, J.P. (2018). SEPA Credit Transfer.
  2. The SWIFT Standards Team. (2000). ISO 20022, SWIFT 4th Limited Edition. John Wiley & Sons.