@fin.cx/camt

ISO 20022 CAMT.052/053/054 bank statement parser with exact integer-cent amounts and SEPA reference extraction. The go-forward statement format for EBICS banking (MT940 is legacy — see @fin.cx/mt940 for that).

Built as the ingestion layer for @fin.cx/bankrec (bank reconciliation) and the @fin.cx/skr accounting core: amounts never touch IEEE floats — they are parsed from the XML strings straight into integer cents.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

What This Package Does

• Parses camt.053 (statements), camt.052 (account reports), and camt.054 (debit/credit notifications), normalized into one statement model
• Handles the namespace versions in circulation (.001.02 classic through .001.08+ post-2019 EBICS); structural differences are normalized
• Exact integer-cent amounts (amountCents) — 0.01 parses to 1, never 0.010000000000000002
• Extracts SEPA references (EndToEndId, MandateId, TxId), counterparty name/IBAN/BIC (direction-aware: debtor for credits, creditor for debits), unstructured and structured remittance info (RF creditor references), return reasons (e.g. AC04), reversal flags, and bank transaction codes
• Reads a reference field as absent where it holds a placeholder such as NONREF or NOTPROVIDED (see References)
• Reads the batch an entry books as one amount (NtryDtls/Btch), which names the payment file the account holder sent (see Batch Bookings)
• Identifies the statement account with or without an IBAN: Acct/Id/Othr (the bank's own account number with its scheme and issuer) and the account servicer (BIC, clearing system member id such as a German BLZ, LEI, name, other identification)
• Statement-internal completeness check: opening booked balance + booked movement must equal the closing booked balance to the cent

Installation

pnpm add @fin.cx/camt

Usage

import { parseCamt, validateStatementConsistency } from '@fin.cx/camt';

const statements = parseCamt(camtXmlString);

for (const statement of statements) {
  const consistency = validateStatementConsistency(statement);
  if (!consistency.valid) {
    throw new Error(`Statement broken: ${consistency.issues.join('; ')}`);
  }
  for (const entry of statement.entries) {
    entry.amountCents; // integer cents, exact
    entry.creditDebit; // 'CRDT' | 'DBIT'
    entry.details[0]?.endToEndId;
    entry.details[0]?.counterpartyIban;
    entry.details[0]?.remittanceUnstructured;
  }
}

Cross-statement continuity (gapless statement sequences across files) is the job of @fin.cx/bankrec, which consumes this model.

Booking Days and Moments

BookgDt and ValDt are a choice of a day (Dt) or a moment (DtTm). An entry carries its days as bookingDate and valueDate (YYYY-MM-DD, the day as the file writes it) where the file gives them. Where BookgDt states a moment, the entry keeps it as bookingDateTime, the ISO 8601 date-time as the file writes it, with its offset where the file gives one (2026-10-07T09:12:33+02:00). A file that states only the day leaves bookingDateTime absent; no moment is made up for it. A moment without an offset is the bank's local time, which the file does not name: the consumer decides how to read it.

Account Identification

Each ICamtStatement identifies its account through these fields; all are optional and set only when the document carries them:

| Field | Source element | Notes | | --- | --- | --- | | accountIban | Acct/Id/IBAN | | | accountOtherId | Acct/Id/Othr | ICamtGenericIdentification, present when the account has no IBAN | | accountOtherId.id | Othr/Id | verbatim, leading zeros kept | | accountOtherId.schemeName | Othr/SchmeNm | { kind: 'code' \| 'proprietary', value } for Cd or Prtry, e.g. { kind: 'code', value: 'BBAN' } | | accountOtherId.issuer | Othr/Issr | | | accountCurrency | Acct/Ccy | | | accountOwnerName | Acct/Ownr/Nm | | | servicerBic | Acct/Svcr/FinInstnId/BICFI or BIC | same value as servicer.bic | | servicer | Acct/Svcr/FinInstnId | ICamtFinancialInstitution | | servicer.bic | BICFI (*.001.03 and later) or BIC (*.001.02) | | | servicer.clearingSystemMemberId | ClrSysMmbId | { memberId, clearingSystemId? }, e.g. { memberId: '20000000', clearingSystemId: { kind: 'code', value: 'DEBLZ' } } | | servicer.lei | LEI | *.001.08 and later | | servicer.name | Nm | | | servicer.other | Othr | ICamtGenericIdentification |

These fields are read the same way for camt.052, camt.053 and camt.054, schema versions .001.02 through .001.14.

References

The reference fields carry a reference or nothing. A field that is empty or holds a placeholder a bank or payer writes for "no reference" is undefined:

| Placeholder | Origin | | --- | --- | | NONREF | SWIFT MT940 field 61, the constant for a missing reference | | NOTPROVIDED | SEPA, the constant for a missing end-to-end identification |

Placeholders are recognized in any case and with surrounding whitespace, in every reference field:

| Field | Source element | | --- | --- | | entry.accountServicerRef | Ntry/AcctSvcrRef | | entry.entryRef | Ntry/NtryRef | | details.endToEndId | TxDtls/Refs/EndToEndId | | details.mandateId | TxDtls/Refs/MndtId | | details.instructionId | TxDtls/Refs/InstrId | | details.transactionId | TxDtls/Refs/TxId | | details.paymentInformationId | TxDtls/Refs/PmtInfId | | entry.batches[].messageId | NtryDtls/Btch/MsgId | | entry.batches[].paymentInformationId | NtryDtls/Btch/PmtInfId | | details.creditorReference | TxDtls/RmtInf/Strd/CdtrRefInf/Ref |

A real reference is passed through unchanged, also where it contains a placeholder (NOTPROVIDED-2026 stays). A reference is still not unique within a statement: banks give several entries the same AcctSvcrRef (a cheque and its fee in Bundesbank's camt.053 example), so ids derived from it must be made unique by the consumer.

The rule is exported for values read elsewhere or stored before 2.0.0:

import { isReferencePlaceholder, REFERENCE_PLACEHOLDERS } from '@fin.cx/camt';

isReferencePlaceholder(' notprovided '); // true
isReferencePlaceholder(''); // true: empty is no reference either
isReferencePlaceholder('RF18539007547034'); // false
REFERENCE_PLACEHOLDERS; // ['NONREF', 'NOTPROVIDED']

Batch Bookings

A bank that books a payment file as one amount (a "Sammler" of credit transfers or direct debits) names the file in the entry's NtryDtls/Btch: the MsgId and PmtInfId of the pain.001 or pain.008 the account holder sent, the number of its transactions, and its total. The DK's camt.053 example (Gesamtbeispiel, corrected 8 July 2025) books such a file with one TxDtls that holds only the amount, so the batch is the only place the file is named.

entry.batches holds one batch per NtryDtls that has a Btch, in the order of the file, and is empty where there is none. Each transaction detail carries the batch of the NtryDtls it sits in as details.batch, the same object:

const [entry] = statement.entries;
entry.batches; // [{ messageId: 'ACME-PAYROLL-2026-03', paymentInformationId: 'ACME-PAYROLL-2026-03-SALA', numberOfTransactions: 3 }]
entry.details[0].batch === entry.batches[0]; // true

The ids follow the reference rule above. numberOfTransactions is absent where NbOfTxs is no number of 1 to 15 digits; totalAmountCents, currency and creditDebit come from TtlAmt and CdtDbtInd where the bank gives them.

Development

pnpm build
pnpm test

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at [email protected].

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.