Why your ledger should not speak ISO 20022

ISO 20022 should stop at the ledger’s door. It is a rich language for financial institutions and market infrastructures to exchange instructions, statuses and reports. A ledger has a narrower job: record what changed economically, under rules that keep every movement balanced. Let the wire format become the ledger’s native model and an external message release can quietly become an internal accounting migration.

The productive design is a translation boundary. Validate the inbound message against its named scheme and usage profile. Preserve the original as evidence. Translate it into an explicitly versioned business event. Only then apply posting rules that produce balanced debits and credits. ISO 20022 remains the language at the boundary; the ledger speaks events and postings.

A message is not a journal entry

ISO 20022 is more than XML. Its Business Process Catalogue describes business areas, transactions, message definitions and syntax schemes; an XML schema is one processable expression of a message definition.1 Its repository also contains shared business concepts, message concepts and data types.2 That common vocabulary is precisely why it works between organisations.

But a shared vocabulary for communication is not an accounting invariant. A message can say that a customer credit transfer was instructed, report its status or return a previously settled payment. Swift’s public catalogue, for example, distinguishes pacs.008 as an FI-to-FI customer credit transfer, pacs.002 as a payment status report and pacs.004 as a payment return.3 Those are different statements in a payment lifecycle. None should move an internal balance merely because a parser found an amount and two parties.

Consider a service that credits a beneficiary account whenever it receives a pacs.008. Later it receives a rejection status. Or the transfer settles and a pacs.004 reports a return. If the ISO document is also the ledger record, the application must either mutate the original object or teach an ever-growing payment row to mean instruction, acceptance, settlement and return at once. A messaging lifecycle has swallowed the accounting model.

The safer question is not “Which ISO fields should we store as the transaction?” It is “What economic fact, if any, did this message establish under this rail’s rules?”

There is no timeless ISO 20022 dialect

The label “ISO 20022” does not identify one immutable runtime contract. The ISO catalogue exposes current message versions and archives earlier ones; ISO also notes that implementation depends substantially on the requirements of the community using the messages.45 A payload must therefore be understood with its full message identifier, version, usage guideline and scheme—not just the family name pacs.008.

Real infrastructures make different choices. Fedwire implemented mostly the message versions available in 2019, but selected a later pacs.004 version because it needed account identifiers in the return chain. Its Business Application Header version also differs from the one used by CBPR+ for a concrete retrieval requirement.6 Both are ISO 20022 implementations. They are not interchangeable schemas.

This variation is healthy at a network boundary. Each community needs constraints that match its legal, operational and technical environment. It is corrosive in a ledger core. If rail-specific fields become posting columns, every new scheme creates another nullable branch. If the parser’s current interpretation is used during replay, upgrading a schema library can change the meaning of old history. If accounts are named after message statuses, an external rule change becomes a chart-of-accounts change.

The Federal Reserve’s commentary on Regulation J makes the semantic boundary unusually concrete: financial-message terminology does not itself confer legal status or responsibility in Fedwire. An ISO 20022 label such as “agent” does not, by itself, create the corresponding legal duty.7 The message is evidence interpreted under a scheme. It is not self-executing financial truth.

Translate once, preserve twice

An ingress adapter should first establish what arrived: raw payload, header, rail, sender, received time, complete message-definition identifier and applicable usage guideline. Preserve that source record unchanged or address it through tamper-evident storage. This is the evidence needed to reproduce parsing, answer a reconciliation query or correct a mapping later.

Then translate the source into the institution’s own business language. A pacs.008 might yield TransferInstructionReceivedV1; a scheme-specific confirmation might yield SettlementConfirmedV2; a pacs.004 might yield PaymentReturnedV1. These names describe facts the rest of the system can reason about without importing the wire document’s entire shape.

Translation is not clerical copying. Swift documents two concrete losses when translating richer ISO 20022 messages to MT: a target field can be too short, or an ISO element can have no MT equivalent.8 The same structural problem exists whenever two models have different purposes. A good translator makes the decision visible: which source fields establish the event, which remain provenance, which are irrelevant to accounting, and which could not be interpreted.

Preserving both records resolves an apparent tradeoff. The raw message retains fidelity to what the counterparty sent. The canonical event gives internal consumers a stable meaning. One is evidence; the other is an owned interpretation.

Version the interpretation, not just the envelope

Every canonical event needs its own schema version, independent of the ISO message version. SettlementConfirmedV1 may say that an amount became available. A later V2 may distinguish settlement time from funds-availability time. Keeping those versions explicit prevents new code from silently assigning new semantics to stored facts.

This is not a theoretical edge case. A study of 19 event-sourced systems, based on interviews with 25 engineers, identified event evolution as a recurring challenge and found five strategies in use: versioned events, weak schemas, upcasting, in-place transformation, and copy-and-transform.9 For a financial history, versioned events plus named upcasters offer a useful property: old facts remain untouched while current consumers receive an explicit, testable interpretation.

Three versions should consequently travel together but remain separate: the external message version, the canonical event version and the posting-rule version. The first explains how the payload was decoded. The second explains the internal fact. The third explains why that fact produced these accounts and amounts. Collapsing them into a generic schema_version makes replay look deterministic while hiding which contract actually changed.

Post effects, not statuses

Canonical events still do not belong directly in balances. They are inputs to posting rules. The ledger accepts the result only as an atomic, balanced journal transaction: for each currency, total debits equal total credits.

Suppose a transfer of 100 units is accepted for processing. A posting rule might move 100 from customer available funds to customer funds pending settlement. A later settlement event moves the same 100 from pending settlement to settled cash or an external clearing account. A return is not a Boolean flipped on the first row; it is a new event that produces compensating postings linked to the original movement.

This separation handles a critical failure mode. A status message can be parsed perfectly and still be mapped to the wrong account. Balanced postings cannot prove that the mapping was economically correct, but they can prevent one-sided value creation. Square’s published Books design enforces journal entries that balance to zero, keeps its journal and book entries effectively append-only, and corrects a mistaken movement with a new entry instead of overwriting history.10

Posting rules can also evolve without teaching the ledger about every rail. If a new scheme introduces richer party data, the source adapter and event may change while the core debit-credit primitive does not. If accounting policy changes, a new posting-rule version can apply to new events while old entries retain the rule that created them. The seams localise change.

The ledger therefore should not be ignorant of ISO 20022. It should be able to trace every posting back through a canonical event to the exact message and profile that caused it. It just should not speak ISO 20022 as its native language.

That distinction keeps three truths legible. The message says what another participant communicated. The event says what the receiving system concluded. The postings say how that conclusion changed the books. When those layers disagree, operators can inspect the translation instead of rewriting the money.

Sources

“Understanding the ISO 20022 Business Process Catalogue.” ISO 20022 Registration Authority. https://www.iso20022.org/understanding-iso-20022-business-process-catalogue (opens in a new tab)

“The ISO 20022 Repository.” ISO 20022 Registration Authority. https://www.iso20022.org/financial-repository (opens in a new tab)

“Updated ISO 20022 usage guidelines for cross-border payments released.” Swift. https://www.swift.com/news-events/news/updated-iso-20022-usage-guidelines-cross-border-payments-released (opens in a new tab)

“Catalogue of messages.” ISO 20022 Registration Authority. https://www.iso20022.org/catalogue-messages (opens in a new tab)

“Frequently asked questions.” ISO 20022 Registration Authority. https://www.iso20022.org/faq (opens in a new tab)

“Format/Technical Documentation and MyStandards Frequently Asked Questions.” Federal Reserve Financial Services. https://www.frbservices.org/resources/financial-services/wires/faq/iso-20022/format-technical-documentation-mystandards (opens in a new tab)

“Commentary on Regulation J.” Board of Governors of the Federal Reserve System. https://www.federalreserve.gov/frrs/regulations/commentary-on-regulation-j.htm (opens in a new tab)

“ISO 20022 to MT Translation.” Swift. https://www.swift.com/de/node/308151 (opens in a new tab)

“An empirical characterization of event sourced systems and their schema evolution—Lessons from industry.” Elsevier, Journal of Systems and Software. https://doi.org/10.1016/j.jss.2021.110970 (opens in a new tab)

“Books, an immutable double-entry accounting database service.” Square Developer. https://developer.squareup.com/blog/books-an-immutable-double-entry-accounting-database-service/ (opens in a new tab)