Bank reconciliation for the fin.cx accounting stack: one canonical signed-integer-cent transaction model fed by @fin.cx/camt (CAMT.052/053/054) and @fin.cx/mt940 (legacy MT940), a cross-statement continuity control, and a confidence-scored matching engine for settling open items.

Everything is pure functions — no database. The caller executes match decisions (e.g. via the @fin.cx/skr booking recipes) and owns the thresholds; matches stay reversible until the period is festgeschrieben.

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

Canonical transactions: fromCamtStatement() / fromMt940Statement() normalize either format into IBankTransaction — signed integer cents (credits positive), SEPA references, counterparty data, return reasons, stable ids derived from bank references, the booking day and, where a CAMT statement states it (BookgDt/DtTm), the moment of the booking (bookingDateTime, as the statement writes it), and the payment file a movement belongs to (paymentInformationId, see Payment information ids)
Continuity control: checkStatementContinuity() verifies per account that every closing balance equals the next opening balance and electronic sequence numbers are gapless — the hard monthly-close gate against silently missing statements. The statements are ordered by date when every one states a date, else by sequence number when every one states one; the sequence numbers are checked across the numbered statements in that order, so a gap next to an unnumbered statement is found. An account with more than one statement whose statements state neither order completely is reported as not checkable
Matching engine: matchTransactions() scores bank transactions against open items with weighted signals (exact reference 50, invoice number in remittance 35, exact amount 30, Skonto-window short payment 20, known IBAN 20, name similarity 10, date proximity 5). Direction is a hard filter, returns/reversals never auto-settle, ambiguous ties force review, and every auto decision consumes its open item exactly once

Installation

pnpm add @fin.cx/bankrec

Usage

import { parseCamt } from '@fin.cx/camt';
import {
  fromCamtStatement,
  checkStatementContinuity,
  matchTransactions,
} from '@fin.cx/bankrec';

const statements = parseCamt(xml);
const normalized = statements.map(fromCamtStatement);

const continuity = checkStatementContinuity(normalized.map((entry) => entry.link));
if (!continuity.valid) throw new Error(continuity.issues.join('; '));

const decisions = matchTransactions(
  normalized.flatMap((entry) => entry.transactions),
  openItems, // receivables/payables from your ledger
  { autoThreshold: 85, reviewThreshold: 50 },
);

for (const decision of decisions) {
  // 'auto'      -> book via skr recipes (bookBankPayment)
  // 'review'    -> human queue with decision.candidates + signals
  // 'unmatched' -> suspense (bookToSuspense) or manual handling
}

Movement ids

IBankTransaction.id identifies a movement across imports, so the same statement imported twice yields the same ids. Every id is distinct within its statement; an adapter that cannot give two movements distinct ids throws rather than hand out one id twice.

CAMT: <accountIban>:<statementId>:<reference>, plus :<detailIndex> for each transaction of a batch entry split by its per-transaction amounts. The reference of a booked entry is the first of its AcctSvcrRef, its NtryRef and <statementId>-<entryIndex> (its position among all entries) that no earlier entry of the statement has taken. @fin.cx/camt reports a placeholder such as NONREF as no reference
MT940: <accountId>:<statementNumber>:<reference>. The reference is the first of the mt940-js transaction id, the bank reference of :61: and the transaction's index that no earlier transaction of the statement has taken. An empty value and a placeholder (isReferencePlaceholder of @fin.cx/camt) count as absent

Ids that 1.x assigned stay as they were for entries with a unique bank reference, for entries that state neither AcctSvcrRef nor NtryRef, for the first holder of a repeated reference and for MT940 transactions with a unique mt940-js id. 2.0.0 changed these ids (a placeholder includes an empty value):

a CAMT entry whose AcctSvcrRef is a placeholder such as NONREF now has its NtryRef or its position as reference, where 1.x used the placeholder
a CAMT entry without AcctSvcrRef whose NtryRef is a placeholder now has its position as reference, where 1.x used the placeholder
the second and later CAMT entries of a statement that repeat a reference, such as a cheque and its fee booked under one AcctSvcrRef, now have their NtryRef or their position, where 1.x gave them the first holder's id
the second and later of identical MT940 :61: lines (mt940-js derives its id from the :61: line alone) now have their bank reference or their index
an MT940 transaction with an empty id, which 1.x gave the id <accountId>:<statementNumber>:, now has its bank reference or its index
an MT940 transaction without an id whose bank reference is a placeholder now has its index, where 1.x used the placeholder

Payment information ids

IBankTransaction.paymentInformationId names the payment file a movement belongs to: the PmtInfId of the pain.001 or pain.008 the account holder sent. A bank that books such a file as one amount names it in the entry's NtryDtls/Btch, and may name it nowhere else: the DK's camt.053 example books a credit transfer file with one TxDtls that holds only the amount.

a CAMT entry taken as one transaction has the id its batches and its transaction details name (Btch/PmtInfId, TxDtls/Refs/PmtInfId)
each transaction of a split batch entry has the id its own TxDtls/Refs/PmtInfId and the batch of its NtryDtls name
where these name several different ids, or none, the field is absent; @fin.cx/camt reports a placeholder such as NOTPROVIDED as no id
an MT940 statement has no such field; the :86: text, with a KREF it may hold, stays in remittanceInfo

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.

readme.md

@fin.cx/bankrec