## Reconciliation: Transactions and EntryDetails

Reconciliation is how a partner matches money movement seen from the bank
back to the specific invoice, payment, or business event that caused it.
Aritma exposes this through two related resources — **Transactions** and
**EntryDetails** — and understanding how they relate to each other is the
foundation for building reliable reconciliation logic.

### Transactions vs. EntryDetails

A **Transaction** is the header-level record of a movement on an account —
roughly equivalent to a single line on a bank statement. A Transaction can
contain **one or more EntryDetails**, which carry the underlying detail
needed to actually reconcile the movement (references, remittance
information, counterparty data, etc.).

In practice this means: don't assume a 1:1 relationship between a
Transaction and a single invoice or payment. Always fetch and inspect the
EntryDetails under a Transaction before attempting to match it to something
in the partner's own system — the reconciliation-relevant data usually
lives at the EntryDetails level, not the Transaction level.

### Reconciling incoming transactions

For incoming payments, reconciliation can be recommended in this order:

1. **Structured reference** — check first. This is the most reliable
match when present, since it's a reference the payer's bank has carried
through unmodified (e.g. an OCR/KID number or similar structured
reference depending on the bank/country).
2. **Unstructured reference** — if no structured reference is present, fall
back to matching against free-text remittance information. This is less
reliable since formatting varies by what the payer actually
typed, so matching logic here should be tolerant of formatting
differences (whitespace, casing, partial invoice numbers, etc.).
3. **Other data** — amount and date (and counterparty name/account, where
available) as a last resort or as a secondary check to increase
confidence when the reference match is ambiguous or missing entirely.


Build the matching logic to attempt these in sequence and fall through, not
as three independent, equally-weighted checks — a structured reference match
should always win over an amount+date coincidence.

### Reconciling outgoing payments

Outgoing is more straightforward: every payment line sent through the
Banking API carries an `endToEndIdentification`, and this comes back
unchanged on the resulting Transaction. This gives a reliable **1:1 match**
between the payment you initiated and the transaction that later appears on
the account — reconciliation for outgoing payments should be built around
this identifier rather than reference/amount/date matching, which is the
incoming-side fallback.

### Using account balance as a reconciliation check

In addition to matching individual Transactions, the account **balance** is
also available and can be used as a complementary reconciliation signal —
particularly useful as a sanity check rather than a per-transaction match.
Comparing the reported balance against the partner's own running total after
applying a batch of transactions helps catch cases where something was
missed, duplicated, or mismatched at the individual transaction level, even
if every single reference-based match appeared to succeed. Treat balance as
a control total, not a substitute for transaction/EntryDetails-level
matching.

## Common mistakes

### EntryDetails pagination

`EntryDetails` are paginated at **100 per page**. A common mistake is
fetching only the first page of EntryDetails for a Transaction and assuming
that's the complete set — this silently drops reconciliation data for any
Transaction with more than 100 EntryDetails, rather than failing loudly.
Always page through the full result set before treating EntryDetails as
complete for a given Transaction.

### Duplicate transactions from camt.053 + camt.054

A related and very common reconciliation mistake: consuming both
`camt.054` (credit/debit notification) and `camt.053` (statement)
simultaneously results in the same underlying transaction appearing twice,
since both file types report the same movement. Pin ingestion to a single
`transactionSource` rather than trying to de-duplicate after the fact.

**Recommendation:** Use `camt.053` as your `transactionSource` — this is
Aritma's recommended source of truth. Since `camt.053` derives from
`camt.054` — it's effectively the consolidated statement built from the
underlying notifications — it gives the complete picture of the account for
the period, rather than a stream of individual events that still needs to
be assembled into that picture yourself.

**When to expect each file type:**

- **`camt.054`** typically arrives in the afternoon, around 18:00, after
bank closing.
- **`camt.053`** typically arrives overnight, around 00:00, as an
end-of-day statement consolidating that day's activity into a single,
complete record.


This is also part of why the two shouldn't be mixed: the exact timing can
vary somewhat by bank, and `camt.054` doesn't reliably give you an
earlier or more complete picture than `camt.053` — it's simply a different
representation of the same underlying activity. Given `camt.053` arrives
only a few hours later and derives from the same data, it's the
recommended source unless there's a specific reason to need the `camt.054`
representation instead.