import { parseCamt053 } from "iso20022-ts/camt.053.001.08"

const res = parseCamt053(xmlFromBank)
if (!res.ok) {
  for (const i of res.issues) console.error(`${i.code} at ${i.path}`)
  process.exit(1)
}

for (const stmt of res.doc.BkToCstmrStmt.Stmt) {
  for (const entry of stmt.Ntry ?? []) {
    console.log(entry.Amt.value, entry.Amt.Ccy, entry.CdtDbtInd)
  }
}

Why

The reference open source ISO 20022 tooling is Java (Prowide), and it keeps validation, translation, and rulebook checks in its commercial products. The TypeScript ecosystem has only narrow single-message tools.

iso20022-ts does not chase catalogue parity. It wins on four axes instead.

| | Prowide OSS | Prowide commercial | iso20022-ts | |---|---|---|---| | Full catalogue model | yes | yes | no, SEPA core set only | | Parse XML to a typed model | yes | yes | yes | | Build a model to XML | yes | yes | yes | | JSON conversion | yes | yes | yes, the model is plain data | | Message detection | yes | yes | yes | | Schema validation | no | yes | yes | | Business rules (IBAN, BIC, cross-field) | no | yes | yes | | SEPA / EPC rulebook checks | no | yes | yes | | MT to MX translation | no | yes | no, out of scope | | Browser and edge runtimes | no | no | yes | | Typed, structured error values | no | partial | yes |

Install

npm install iso20022-ts     # bun add iso20022-ts, pnpm add iso20022-ts

One runtime dependency: saxes, for namespace-correct XML parsing. Published as ESM with declarations.

Messages

| Message | Version | Role | |---|---|---| | pain.001 | 001.09 | Customer credit transfer initiation | | pain.002 | 001.10 | Customer payment status report | | pain.008 | 001.08 | Customer direct debit initiation | | camt.053 | 001.08 | End-of-day bank statement |

Each version is its own subpath export, so importing one costs kilobytes rather than the whole catalogue. There is no "latest" alias: consumers pin a version, because a payment file that silently changes shape is a production incident.

Build a SEPA credit transfer

import { Amount, Iban } from "iso20022-ts/values"
import { buildPain001, pain001, validateSepaCreditTransfer } from "iso20022-ts/sepa"

const debtorIban = Iban.parse("ES9121000418450200051332")
if (!debtorIban.ok) throw new Error(debtorIban.issues[0].message)

const doc = pain001({
  msgId: "MSG-2026-0001",
  initiatingParty: { name: "ACME SL" },
  payments: [{
    paymentInfoId: "PMT-0001",
    debtor: { name: "ACME SL", iban: debtorIban.value, bic: "CAIXESBBXXX" },
    requestedExecutionDate: "2026-09-01",
    transfers: [{
      endToEndId: "INV-4711",
      amount: Amount.eur("1250.00"),
      creditor: { name: "Supplier GmbH", iban: "DE89370400440532013000" },
      remittance: "Invoice 4711",
    }],
  }],
})

const rulebook = validateSepaCreditTransfer(doc)   // Issue[], empty when clean

const built = buildPain001(doc)                    // schema-ordered XML
if (built.ok) console.log(built.xml)
else for (const i of built.issues) console.error(`${i.code} at ${i.path}`)

pain001 fills in what the scheme fixes anyway: TRF, service level SEPA, charge bearer SLEV, transaction counts, and control sums. pain008 does the same for direct debits, including the creditor identifier and mandate block.

Validate against the SEPA rulebook

import { validateSepaCreditTransfer } from "iso20022-ts/sepa"

validateSepaCreditTransfer(doc)
// [{ severity: "error",
//    code: "SEPA_CURRENCY",
//    path: "Document.CstmrCdtTrfInitn.PmtInf[0].CdtTrfTxInf[0].Amt.InstdAmt",
//    message: "SEPA requires EUR, got USD" }]

Covered: EUR only, the scheme amount ceiling, SLEV, service level SEPA, IBAN-only accounts with checksum and scheme-country checks, BIC validity, remittance limits, party name lengths, transaction counts and control sums, mandate completeness, sequence type, local instrument, and the creditor identifier scheme. Character set findings are warnings, because the payment still settles.

Detect an unknown message

import { detect } from "iso20022-ts/detect"

detect(xml)
// { ok: true,
//   msgDefIdr: "camt.053.001.08",
//   namespace: "urn:iso:std:iso:20022:tech:xsd:camt.053.001.08",
//   message: { domain: "camt", number: "053", version: "001.08", ... } }

Detection reads the namespace without building a document, so it works on payloads this build cannot parse and stays cheap on large statement files. It looks past a business application header to the payload inside.

Errors are values

Nothing on the happy path throws.

type ParseResult<T> =
  | { ok: true;  doc: T; issues: Issue[] }   // issues are warnings
  | { ok: false; issues: Issue[] }

type Issue = {
  severity: "error" | "warning"
  code: string   // stable, e.g. "SEPA_AMOUNT_MAX" or "XSD_PATTERN"
  path: string   // "Document.CstmrCdtTrfInitn.PmtInf[0].CdtTrfTxInf[2].Amt"
  message: string
}

Every code is documented in docs/issue-codes.md, and every one of them has a fixture that xmllint --schema rejects too.

By default parsing is strict: unexpected or misordered elements are errors, matching what libxml2 does. Real bank files sometimes disagree with the schema in harmless ways, so { strict: false } downgrades those to warnings.

Money

Amounts are decimal strings, never number. Amount wraps a validated decimal with its currency and does arithmetic on BigInt.

import { Amount, sumAmounts } from "iso20022-ts/values"

Amount.eur("0.1").plus(Amount.eur("0.2"))     // { ok: true, value: 0.30 EUR }
Amount.parse("1250.005", "EUR")               // { ok: false, AMOUNT_SCALE }
Amount.parse("1250", "JPY")                   // JPY has no minor unit
sumAmounts([Amount.eur("1.10"), Amount.eur("2.20")])

An Amount is shaped like the ISO element it becomes (value plus Ccy), so it drops straight into a document with no conversion.

No casts

The whole repository, generated code included, contains zero as type assertions. This is enforced in CI. Parsing produces typed documents because the codegen emits explicit decoders, not because a cast papers over the gap between unknown and the model.

// Choice groups become unions, narrowed the ordinary way.
if ("IBAN" in account.Id) console.log(account.Id.IBAN)
else console.log(account.Id.Othr.Id)

Size

Measured minified and gzipped, enforced as a budget in CI.

| Entry point | Size | |---|---| | detect | 0.5 KB | | values (Iban, Bic, Amount) | 2.2 KB | | pain.001.001.09 parse | 19 KB | | pain.001.001.09 parse + build | 24 KB | | camt.053.001.08 parse + build | 35 KB |

CLI

npx iso20022 detect   statement.xml
npx iso20022 inspect  statement.xml
npx iso20022 validate payments.xml       # exit 1 when the document has errors
cat payments.xml | npx iso20022 validate - --json

$ iso20022 inspect samples/camt.053.001.08/statement.xml
camt.053.001.08  Bank to customer statement

Message id:         CAMT053-2026-08-29-001
Created:            2026-08-30T02:10:00
Statements:         1
Statement:          STMT-2026-241, account ES9121000418450200051332
  OPBD:             24500.00 EUR CRDT
  CLBD:             23189.25 EUR CRDT
  Entries:          2

validate runs schema checks and, for pain.001 and pain.008, the SEPA rulebook. --json makes every command machine-readable, --lenient softens structural findings, --quiet prints only the verdict.

How it is built

packages/core/       xml adapter, value types, Result and Issue, detection
packages/messages/   GENERATED, one directory per message version
packages/sepa/       EPC rulebook checks and builders, hand written
packages/codegen/    XSD to IR to emitters, dev only, never published
packages/iso20022-ts/ the published package, assembled from the above
apps/cli/            the iso20022 command
schemas/             vendored XSDs, a manifest with SHAs, and a fetch script
samples/             golden files, and one negative fixture per issue code

Codegen emits four files per message: types that compile away to nothing, an element-order metadata table that drives serialisation and validation, explicit decoders, and thin entry points. Element order in xs:sequence is load-bearing for output, choice groups map onto discriminated unions, and facet checks become plain data. The IR models exactly the constructs the ISO schemas use and fails the build on anything else, rather than emitting a plausible wrong type.

Adding a message version is a config change, not a coding task: add an entry to schemas/manifest.json, run bun run schemas:fetch, run bun run codegen.

Development

bun install
bun test              # 180+ tests
bun run typecheck
bun run codegen       # regenerate packages/messages
bun run ci            # everything CI runs

The CI gate is deliberately wide:

• typecheck under strict and noUncheckedIndexedAccess
• lint:no-casts, which fails on any as assertion anywhere
• schemas:verify, which checks the vendored XSDs against their SHAs
• codegen:check, which fails if the committed output is stale
• bun test
• oracle, which cross-checks every sample against xmllint --schema and fails if our verdict ever differs from libxml2's
• size, the per-entry-point bundle budget
• verify:package, which packs the tarball, installs it, and runs it under plain node

Scope

In: SEPA credit transfer, direct debit, and account reporting, done deeply.

Out: the full ISO 20022 catalogue (securities, trade, cards), MT to MX translation, and network connectivity. This is a message toolkit, not a client.

See PLAN.md for the architecture and roadmap.

Licence

MIT. The licence covers this repository. The vendored ISO 20022 schemas are published by the Registration Authority under a royalty-free licence; see schemas/README.md.