_ENGINEERING/
Transaction Reconciliation at Scale: An Engineering Guide
By Formance Staff
Guide
Reconciliation
Flows
Loading article content
Loading table of contents
Loading author
Transaction reconciliation forces engineering and finance teams to prove ownership and location of each transaction when two records disagree.
Most reconciliation failures start in ledger design, including missing idempotency, double-posting retries, mutable balance columns drifting, and missing canonical timestamps that leave cut-off queries guessing. By the time your reconciliation rules flag a mismatched transaction, the damage has already been written into the ledger.
Wirecard’s insolvency revealed that €1.9 billion was "missing" from trust accounts supposedly held in the Philippines, which made up a quarter of the company's balance sheet. The company's own records could not be reconciled against any authoritative external bank statement; it conceded that the balances likely did not exist. An immeasurable reconciliation measures the absence of a system of record for transaction data and balances.
If your team treats reconciliation as a reporting step, you are solving the wrong problem. Reconciliation should occur only after the ledger architecture is enforced.
Enforce four ledger invariants before writing a single reconciliation rule, including double-entry, idempotency, immutability, and bi-temporality. Ensure you keep enforcement in the storage layer, where the data lives.
Every posting debits one account and credits another for the same amount. The sum of every transaction is zero, and no unbalanced transaction can be committed. Derive balances by summing postings. Avoid storing a mutable running total.
A stored running total can fall out of sync with actual history, and re-summing is required to determine which number is correct. Enforcing this at write time prevents orphan values from creeping in and keeps balances lined up with reality.
A retry on any payment rail event must produce exactly one posting. A client may resend a request that the server has already processed after the network drops the response. An idempotency check prevents the server from booking the same payment twice. Persist a client-generated idempotency key to a unique index before processing begins.
Idempotency controls reduce the risk of duplicate processing during retries and under network stress. Generating a new UUID on each retry breaks idempotency in the execution.
Once written, a posting is never overwritten or deleted. Corrections are new compensating postings that supersede the original, while both records stay visible.
Revoke UPDATE and DELETE on the postings table for every application service account. Immutable ledgers preserve auditability by recording corrections as new entries while prior postings stay visible. Use append-only histories rather than UPDATE statements for audit review.
A ledger must reconcile with systems that use asynchronous settlement, so that every posting requires two independent time dimensions:
A card payment captured by a card processor tonight may not land in your bank's settlement file until T+2; a reconciliation job comparing the two on the same clock flags in-flight items as missing. Bi-temporal ledger design lets you run a cut-off by a transaction's effective_at date, so late-arriving items land in the period where they belong without mutating history.
These four invariants depend on each other: idempotency stops the same posting from being recorded twice, while immutability preserves the written record. Bi-temporality is required for correct cut-off reconciliations when webhooks arrive late.
Make sure you enforce double-entry and immutability at the database level first, add idempotency keys to every write path, and then connect new rails. Connecting a new rail to an inconsistently written ledger almost always increases reconciliation risk.
Every payment service provider (PSP) and bank feed reports differently, so most teams standardize provider data into a canonical transaction schema before any reconciliation rules run.
A practical schema carries:
Those fields give the reconciliation pipeline stable transaction facts to compare before provider-specific differences reach the rule layer.
Store provider-reported amounts as integers in minor units (cents, pence, and fils), and avoid binary floating-point arithmetic for money.
The goal is to keep arithmetic deterministic across systems. Preserve the value-date distinction, and ensure the booking date records when a payment is booked to the balance account. The value date records when funds are actually available, often later.
Per-rail ingest adapters should be stateless and idempotent. Card processors and banks each report payouts differently. Cross-border providers add conversion and settlement details, and a team that wires them up one at a time ends up maintaining a separate normalization adapter for each.
Those adapters are where reconciliation bugs hide. When a provider changes a file format or a status code, the adapter quietly mismaps a field, and the issue only surfaces downstream when balances no longer match. An adapter that carries implicit state turns a routine format change into a silent data drift.
Before reconciliation, make the amount conversion explicit and timestamp normalization consistent across the pipeline. Fees should be decomposed into discrete line items rather than swallowed into a single net figure.
In the common gross-to-net case, expected net settlement is modeled as captured amount minus refunds, disputes, processor fees, scheme and interchange fees, and foreign exchange (FX) charges. The gross-to-net formula hides messy input data.
Account-level reconciliation confirms that the closing balance in your core ledger matches the closing balance on a bank or PSP statement. Transaction-level reconciliation matches individual postings to individual external events. They answer different questions and require separate pipelines.
Account-level reconciliation detects that a discrepancy exists. Transaction-level reconciliation localizes the source.
Account-level checks can show that a variance exists. Transaction-level reconciliation identifies the transactions behind it, where they are far easier to trace and fix.
Transaction-level reconciliation needs its own pipeline because match cardinality is harder. In Numscript transaction language, Formance's purpose-built language for describing financial transactions, the gross amount, each fee, and the net credit are posted as discrete amounts against named accounts:
// CARD_SETTLEMENT
// Event: a $100,000.00 card payment settles; provider-reported fee lines are separated
send [USD/2 10000000] (
source = @counterparties:paymentProcessors:provider:clearing allowing unbounded overdraft
destination = {
max [USD/2 120000] to @platform:fees:markup
max [USD/2 50000] to @platform:fees:scheme
max [USD/2 130000] to @platform:fees:interchange
remaining to @merchants:acme:payable
}
)
set_tx_meta("event_type", "card_settlement")
set_tx_meta("settlement_id", "stl001")
Gross is $100,000.00; the markup fee is $1,200.00; the scheme fee is $500.00; the interchange fee is $1,300.00; and the net credit to the merchant is $97,000.00.
Because each fee posts to its own named account rather than disappearing into a net figure, the reconciliation engine can match each fee line item against the PSP report independently. When the bank shows a net deposit with no transaction-level breakdown, you still have the gross-to-net waterfall recorded in the ledger to reconcile against.
Schedule reconciliation on the cadence the rails demand, such as intraday for wires and card settlement, and T+2 alignment for anything that clears through a bank file.
Production reconciliation engines usually combine exact-match logic for clean, deterministic cases with tolerance bands and field-weight scoring for near-matches. Unresolved exceptions move to a manual triage queue with full context attached.
Tier one matters because it is fast and deterministic. Exact matching on its own leaves gaps when data is not perfectly comparable, which is exactly what different PSP reference formats produce.
Tier two is a field-weighted score that combines per-field similarity into a single confidence number, such as name score times its weight, plus email score times its weight, and so on, with weights summing to one.
High-confidence automated matches require documented similarity thresholds, and tiered matching can improve automated resolution when the input data is normalized well.
Set tolerance thresholds by reconciliation type. Card settlements warrant a narrow, documented rounding tolerance. Foreign-currency conversions after FX revaluation need a percentage-based band where rounding and conversion-rate differences are expected, since amount tolerances are commonly used for those cases.
Wire transfers, being large-value, time-critical, warrant strict amount treatment. A tolerance rule that addresses a material transaction rounds the truth away instead of reconciling it. A single global threshold either masks true breaks or floods the queue with false positives.
Throughput depends on architecture. You need sequential rule evaluation, which can become a bottleneck as reconciliation volume grows, and horizontal capacity that does not remove the sequential processing constraint.
Design the reconciliation engine as a parallel, stateless worker pool that reads from an event queue and writes match results to a separate output store. Keep the source ledger unchanged and write reconciliation results to separate Findings and Audit tables, so that when the matching logic changes, you can regenerate results by replaying the stream.
Timing differences occur when a transaction posted in the ledger today settles in the bank feed tomorrow: a card payment captured tonight that lands in the settlement file at T+2, an ACH return referencing a transaction from weeks ago. Time-window matching handles these. A true break is a mismatch that persists after the expected settlement window closes and falls outside the known lag. That is what escalates.
Resolve a true break using bi-temporal correction. Post a correcting entry whose effective_at is set to the original value date, while its inserted_at reflects the wall-clock moment of the correction.
A webhook arriving April 2 with an effective date of March 31 is recorded April 2 but counted in the March 31 balance, so the late correction lands in the cut-off where it belongs. Both the erroneous posting and its correction stay in the immutable log. An auditor can then answer what the system believed the balance was at 3 pm Tuesday, before the correction was posted at 4 pm.
A useful minimum-viable exception record makes the break and its resolution traceable in one record. At a minimum, capture the source posting ID, the external event ID from the payment rail, the discrepancy amount, and the break classification, with data-quality and timing categories separated from identifier problems. Also capture the assigned owner, the resolution timestamp, and a link to the correcting posting.
With Formance Reconciliation, policy-based matching can pair internal records against external statements and surface unmatched items, drift, or settlement discrepancies for investigation and correction using normalized source data from connected providers.
Route exceptions by financial impact. High-value breaks above a defined threshold go directly to finance leadership under a short, documented service-level agreement (SLA).
Lower-impact breaks can enter an engineering queue or, when they are minor rounding differences below a configured tolerance, be auto-resolved with a journal entry or rounding-account posting. That keeps manual review focused on higher-risk anomalies.
Four reconciliation key performance indicators (KPIs) belong on your engineering dashboard next to uptime and latency.
A reconciliation SLA that tolerates daily runs creates architectural risk. A daily batch means you are flying blind between runs, and the risks compound as volume increases. Any 24-hour lag means a drift discovered at the end of the day may represent a full day of compounding errors across thousands of transactions.
Reconciliation means building a programmable core ledger that keeps mismatches rare and localizable, with corrections recorded without destroying history. Build that ledger first, and the matching engine becomes the easy part. Then, run reconciliation alongside Formance Connectivity to ingest data from supported providers into a uniform model and extend coverage through the generic connector framework for custom providers.
For a hands-on first step, run Formance Ledger and model one gross-to-net flow in Numscript before wiring another rail.