Why I Built an Elixir ISO 20022 Parser (And why I hate banking standards)

ART — Tue, 12 May 2026 21:07:52 +0000

I'll be honest: I didn't build this library because I love ISO 20022. I built it because I had to work with it and I didn't find much in elixir to help with that.

ISO 20022 is the global messaging standard for financial transactions - used by SWIFT, SEPA, the UK's CHAPS system, and increasingly everywhere that money moves between banks. It is also, and I say this with the confidence of someone who has spent way too long staring at it, an XML format that feels like it was designed by a committee. Slowly. Over twenty years. With no one in the room who had ever actually written a parser.

This is the story of how I went from "I just need to parse one bank statement" to building ex_iso20022, an open-source Elixir library for parsing and generating ISO 20022 messages. Against my better judgement.

It Started With a Real Problem

I was working on a transaction processing system and needed to ingest camt.053 files - the ISO 20022 message type for end-of-day bank statements. A bank sends you one of these at the end of each business day and it contains every transaction that hit your account: amounts, counterparties, references, balances.

Here's what it looks like:

<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.053.001.02">
  <BkToCstmrStmt>
    <GrpHdr>
      <MsgId>9327649450</MsgId>
      <CreDtTm>2023-10-20T08:09:05.015Z</CreDtTm>
    </GrpHdr>
    <Stmt>
      <Acct>
        <Id><Othr><Id>5000007775</Id></Othr></Id>
        <Ccy>EUR</Ccy>
      </Acct>
      <Bal>
        <Tp><CdOrPrtry><Cd>CLBD</Cd></CdOrPrtry></Tp>
        <Amt Ccy="EUR">12000.00</Amt>
        <CdtDbtInd>CRDT</CdtDbtInd>
      </Bal>
      <Ntry>
        <!-- individual transactions... -->
      </Ntry>
    </Stmt>
  </BkToCstmrStmt>
</Document>

Yes, CdtDbtInd. Yes, BkToCstmrStmt. Yes, NtryDtls. The ISO 20022 working group apparently had a strict four-character budget for every field name and they certainly wouldn't waste it on vowels.

To make it more fun: the standard has been revised many times. You might get a v02 from one bank and a v08 from another. They're subtly different in ways that will bite you exactly once in production and never again in development. I've found this with the different samples I've collected from Deutsche, Goldman, etc.

Why Elixir Is Actually Great For This

I know, I know. But hear me out - despite the format being a nightmare, Elixir is genuinely a good fit for parsing it.

Pattern matching makes XML parsing expressive. Instead of nested conditionals checking node types and attributes, you write function clauses that read almost like the schema spec itself.

Structs give you a clean data layer. When you're done parsing, you want Elixir structs, not raw maps, not XML nodes dangling in memory. Something you can pass around, inspect in IEx, and pattern match on downstream without screaming.

The {:ok, result} | {:error, reason} convention fits perfectly. Bank messages are full of optional fields, missing data, and values that may or may not be present depending on the bank, the version, and apparently the phase of the moon. Elixir's error tuple pattern handles this without exceptions blowing up your pipeline.

Multi-version support is a first-class problem in the language. Function clauses dispatching on version while keeping the external API identical. Tidy.

Building the Parser

The core of the library is a pipeline: raw XML string → parsed XML tree → Elixir structs.

For the XML layer I used SweetXml, which wraps Erlang's :xmerl and gives you an XPath-like query interface. Here's a simplified version of how a transaction entry gets parsed:

defmodule ExIso20022.Camt053.Entry do
  defstruct [:amount, :currency, :credit_debit_indicator, :status, :booking_date, :transaction_details]

  def parse(entry_node) do
    %__MODULE__{
      amount: SweetXml.xpath(entry_node, ~x"./Amt/text()"s) |> parse_decimal(),
      currency: SweetXml.xpath(entry_node, ~x"./Amt/@Ccy"s),
      credit_debit_indicator: SweetXml.xpath(entry_node, ~x"./CdtDbtInd/text()"s) |> parse_cdi(),
      status: SweetXml.xpath(entry_node, ~x"./Sts/text()"s),
      booking_date: SweetXml.xpath(entry_node, ~x"./BookgDt/DtTm/text()"s) |> parse_datetime(),
      transaction_details: parse_transaction_details(entry_node)
    }
  end
end

The parse_cdi/1 function converts "CRDT" and "DBIT" to :credit and :debit atoms. Small thing, but it means downstream code can pattern match on :credit rather than string-comparing "CRDT" everywhere, because life is too short to write == "CRDT" in 2026.

Handling Multiple Versions

This was the most annoying part, and I say that having dealt with the abbreviations. The namespace in the XML tells you which version you're looking at:

urn:iso:std:iso:20022:tech:xsd:camt.053.001.02  → v02
urn:iso:std:iso:20022:tech:xsd:camt.053.001.08  → v08

I extract the version upfront and dispatch from there:

def parse(xml_string) do
  with {:ok, doc} <- parse_xml(xml_string),
       {:ok, version} <- detect_version(doc),
       {:ok, result} <- parse_for_version(doc, version) do
    {:ok, result}
  end
end

defp detect_version(doc) do
  namespace = SweetXml.xpath(doc, ~x"//@xmlns"s)
  case Regex.run(~r/camt\.053\.001\.(\d+)/, namespace) do
    [_, version] -> {:ok, String.to_integer(version)}
    nil -> {:error, {:unknown_namespace, namespace}}
  end
end

Versions v02 through v14 are supported for camt.053. Most field paths are stable across versions, but the later ones add enough new wrinkles around charges and tax details that pretending versions don't exist will eventually hurt you.

The Goldman Sachs Test Fixture Moment

One of the most useful things I did was grab the sample camt.053 file from Goldman Sachs' public developer portal. It's a real-world example from an actual bank covering a parent DDA account and several virtual sub-accounts. Immediately I found edge cases I hadn't considered.

Non-IBAN account IDs. The Goldman sample uses <Othr><Id> rather than IBAN for account identification. Very common in the US, easy to miss entirely if you only tested against European bank samples like I had been.

Proprietary account types. Virtual accounts carry types like VIRTUAL_SUSPENSE and VIRTUAL_FEE - not ISO standard codes, just whatever strings Goldman felt like using. The parser had to handle these without choking.

Six statements in one document. A parser that implicitly assumed one statement per document would silently discard five of them. No error, no warning. Just missing money. Great.

The lesson: use real bank-published samples as test fixtures. It is not the same as having production data, but it is a lot closer to reality than synthetic XML you wrote yourself while optimistically assuming banks follow the spec. I have thankfully been burned like this so I was used to the expectation. Though the brazenness I did not expect.

Expanding to camt.052

Once camt.053 was solid, camt.052 was the obvious next step. Where camt.053 is the end-of-day statement, camt.052 is the intraday report, same basic structure, but delivered multiple times throughout the business day with pending and booked transactions mixed together.

This sounds simple. It is not quite simple.

The main differences that matter:

Transaction statuses are richer. You'll see PDNG (pending) alongside BOOK (booked), and pending transactions may not yet have a value date — because the bank is telling you about money that might arrive, not money that has definitely arrived.

Balances are provisional. The opening balance can change as the day progresses. You need to track ITBD (intraday booking) balance types alongside the standard OPBD/CLBD, and you need to not confuse "current best guess" with "settled fact."

Messages arrive in sequence — theoretically. Each camt.052 carries an ElctrncSeqNb (electronic sequence number). In practice, out-of-order delivery happens, and if your system assumes messages always arrive in order you will eventually have a very bad Tuesday.

The upside is that the external API looks identical:

{:ok, statement} = ExIso20022.Camt053.parse(xml_string)
{:ok, report}    = ExIso20022.Camt052.parse(xml_string)

The complexity is inside the library, which makes me happy.

What's Next

The library currently covers camt.052 and camt.053 parsing. The roadmap I'm working toward:

pain.001 - the credit transfer initiation message. Where camt is about receiving information from your bank, pain.001 is about sending payment instructions to it. This unlocks the full outbound payment flow.

pacs.008 - interbank credit transfers used in SWIFT CBPR+ (the cross-border payments standard). More complex, but increasingly relevant as SWIFT's ISO 20022 migration accelerates.

Validation against XSD schemas - right now the parser is tolerant of missing optional fields. Stricter validation mode with proper error paths would be useful for testing your own message generation.

Generation, not just parsing - building camt/pain messages, not just reading them. Useful for anyone building bank simulators or test harnesses.

Try It

The library is on Hex.pm and GitHub. If you're working with ISO 20022 messages in Elixir and find a message type or edge case it doesn't handle, open an issue, I'm happy to take a look.

The standard is enormous and no library covers it completely. But if we can make the common cases - the bank statements, the intraday reports, the payment initiations - boring and reliable, then it feels like a genuinely useful contribution to the Elixir fintech ecosystem. It was for me at least.

{:ok, _} = ExIso20022.Camt053.parse(your_bank_xml)
# That should just work.

That's the goal.

Art is a backend engineer building financial infrastructure. ex_iso20022 is open source under the MIT license.

Forem: ART