Ledger Reconciliation: Keeping Books and Bank in Agreement
By Formance Staff
Reconciliation
Ledger
Guide
Loading article content
Loading table of contents
Loading author
Try Formance Ledger
Clone the Formance Ledger on GitHub, and post the pending → omnibus → fees settlement above. You can then redeliver the same webhook against a live ledger and verify that the deduplication holds and the daily reconciliation check passes.
Ledger reconciliation is the daily check that proves a payment or e-money firm's customer money sits where its ledger says it does. When the check breaks, engineering owns a safeguarding problem.
A nightly job runs against two card payment service providers (PSPs) and one omnibus account. The job flags a few hundred exceptions. Most are timing gaps that clear on the next cut-off. A handful are duplicate postings from a PSP webhook that retried after a timeout.
One is a credit no engineer can tie to a customer, a fee, or a timing window, and that stray credit might be a real shortfall. The exception log gets a new row flagged for review, and the safeguarding deadline does not move.
Engineering then has to decide to keep patching the reconciliation script, or redesign the account tree so the ledger explains its own gaps against the bank statement.
Why ledger balances and bank balances disagree
Ledger balances and bank balances disagree for three reasons: settlement lag, omnibus attribution, and retried or dropped webhook events.
1. Settlement lag delays bank credit after PSP capture
Settlement lag is the delay between a PSP capture and the matching bank credit. A PSP captures a card payment tonight and credits the merchant bank account net of fees, so for two days the ledger records customer money the bank hasn't received.
Compare the ledger balance against the bank balance on the same clock, and every in-flight capture looks like a shortfall even though the money is on its way.
2. Omnibus attribution hides per-customer balances behind one bank total
Omnibus attribution hides per-customer balances because a single bank figure sits behind thousands of customer balances.
The bank statement shows the total and nothing about who owns which part. If per-customer balances don't add up to the bank figure, no outside source can tell which customer's balance is wrong.
3. Retried and dropped webhook events create duplicates and missing postings
Retried webhook events create duplicate postings. A PSP webhook that times out and is redelivered credits one customer twice if the write path accepts both deliveries.
Dropped webhook events create bank credits with no matching ledger posting.
When the ledger cannot separate settlement lag, omnibus attribution, and duplicate or missing postings, it treats the mismatch as a potential shortfall. Reconciliation becomes a queue of unexplained differences that grows faster than engineering can clear it.
What ledger reconciliation must verify and how often
Ledger reconciliation runs as a daily, balance-level control that verifies four components of the customer-money position, with cadence set by payment volume.
The four components the daily balance check must verify
The daily check verifies four components: total customer liability recorded in the ledger, cash held in each omnibus bank account, cash held at each PSP, and in-flight funds captured but not yet settled.
The check confirms the components add up and that each component matches its external source. Customer liability is a sum over the ledger. Cash positions come from the bank statement and the PSP settlement feed. In-flight funds come from the ledger's pending accounts and should match the PSP's captured-not-yet-settled total.
A single end-of-day figure that doesn't break down into these four parts cannot be defended in an audit.
Balance-level and transaction-level reconciliation work in sequence
The four-component check is a balance-level control because it produces one signed-off figure the compliance officer attaches to the safeguarding return.
Transaction-level reconciliation is the investigation tool that runs when the balance check fails. It matches individual ledger postings against individual PSP settlement lines to identify which posting broke the balance.
The two checks work in sequence: the daily balance figure signals whether reconciliation held, and transaction-level matching identifies which posting broke it.
High payment volume compresses the reconciliation window
Higher instant-payment volumes shrink the window in which timing gaps clear on their own, so they push reconciliation intervals shorter.
Instant-payment rails settle in seconds and run 24/7, so the batch windows that once absorbed timing differences no longer exist. Any drift that appears has to be caught within the same operating day it was created.
At a high-payment cadence, sub-daily reconciliation intervals beat waiting for settlement exceptions to clear, and a monthly cadence only catches drift after the money has already moved.
Four ledger properties that make reconciliation provable
Four ledger properties make reconciliation provable: double-entry postings that sum to zero, immutability with compensating postings, idempotency on every write path, and bi-temporality for cut-off dates.
Formance is an open-source, programmable core ledger that unifies fiat and digital assets with regulatory-grade traceability. Open source is Formance's founding philosophy: teams accountable for customer money must read, audit, and modify the ledger code directly, something a closed system cannot support.
Formance Ledger enforces double-entry, immutability, and bi-temporality in the storage layer, so those three guarantees hold regardless of what the application code does.
1. Double-entry postings that sum to zero
Double-entry postings force every movement to debit one account and credit another, so every bank credit lands in a named internal account.
A ledger that rejects any transaction whose postings do not sum to zero turns internal balance consistency into a query. The bank backs the sum in every account, and the system compares it with the statement.
Any difference becomes an exception for reconciliation to investigate. Double-entry alone cannot prove that every external event was posted.
2. Ledger immutability with compensating postings
Immutability means posted transactions cannot be updated or deleted, and corrections are new postings that reverse and re-post the original.
When the reconciliation layer sees a balance change, it can read the compensating posting, its timestamp, and its author, and tell a legitimate correction apart from a rewritten history.
A mutable ledger offers no such distinction. If yesterday's balance changed, the audit row that recorded the prior balance is gone.
3. Idempotency on every write path
Idempotency rejects duplicate webhook deliveries before creating a posting. Every service that writes to the ledger should send a client-generated key enforced by a unique index in the database, so the second delivery of the same PSP webhook is rejected.
Write-path idempotency has to cover every code path that creates a posting, including the internal correction job.
For events without a stable key, and for retries that differ because of foreign exchange (FX) rounding, engineering teams need a written dedup rule (such as provider reference plus amount plus effective date) in place before the first duplicate arrives.
A duplicate posting matches nothing at the bank, and by the time the bank statement arrives, the customer has already seen the wrong balance.
4. Bi-temporality for cut-off dates
Bi-temporality records a posting's effective date separately from the date the ledger received the posting, so a cut-off comparison uses effective time regardless of when the posting arrived.
A settlement that arrives Tuesday morning for Monday's cut-off is posted with Monday's effective date, so Monday's balance check passes without anyone editing history. A backdated correction changes the effective view while the recorded view stays put.
A single timestamp forces every late-arriving settlement to choose between a false reconciliation exception on the prior day's balance check and a rewritten historical balance for that cut-off date.
How to model in-flight funds and omnibus attribution so the ledger agrees with the bank
Model in-flight funds and omnibus attribution in one account tree. Give in-flight funds a named counterparty account, hold per-customer sub-accounts under the omnibus bank account, and settle both in one atomic transaction when the bank credit arrives.
The four ledger properties keep postings trustworthy, but only the account tree shows why a bank balance disagrees with the sum of customer balances.
The tree uses four accounts:
1Customer balances sit at @users:{id}:available.
2The omnibus bank balance sits at @bank:omnibus:eur:main.
3In-flight funds sit at @psp:provider:pending.
4PSP fees sit at @expenses:psp:fees.
A card capture credits the customer and mirrors the amount into pending. When the bank credit arrives at T+2, one atomic settlement moves the net from pending to the omnibus account and sends the fee to fees. Pending returns to zero.
Two checks close the loop. The bank statement balance equals @bank:omnibus:eur:main, and the sum of @users:*:available equals @bank:omnibus:eur:main plus @psp:provider:pending.
If either check fails, look for duplicate and missing postings. If neither cause fits, treat the mismatch as a real shortfall.
Numscript, Formance's purpose-built language for describing financial transactions, writes the settlement as a single atomic send that both engineers and the finance lead who signs the safeguarding return can read:
// PSP_SETTLEMENT// Event: settle gross capture, route fee, and credit the bank netsend [EUR/2 125000000] ( source = @psp:provider:pending destination = { max [EUR/2 3750000] to @expenses:psp:fees remaining to @bank:omnibus:eur:main })set_tx_meta("event_type", "psp_settlement")set_tx_meta("settlement_id", "stl001")
If the settlement file comes up short, the send still runs and @psp:provider:pending holds the leftover amount with a provider and settlement-date tag.
The team investigates the leftover, and the remaining settlement lines reconcile without human review.
How to detect ledger drift before auditors do
Detect ledger drift early by running continuous checks over nightly batches, treating PASS, FAIL, and ERROR as three distinct states, classifying every exception, and checking every internal balance against an external source of truth.
Continuous reconciliation surfaces drift faster than nightly batches
Continuous reconciliation runs the ledger-versus-provider balance check at sub-daily intervals (every few minutes to every hour) instead of once overnight.
A mismatch surfaces while the posting that caused it is still recent, allowing the engineer to trace it.
Schedule the balance check on a fixed sub-daily interval and label it as a FAIL when the external fetch errors. Route any FAIL to the on-call queue with the account, expected balance, and actual balance attached.
PASS, FAIL, and ERROR must stay distinct reconciliation states
Each state triggers a different response, so PASS, FAIL, and ERROR must stay distinct.
•PASS means the ledger and provider agree within a set tolerance (for example, a currency-minor-unit rounding difference).
•FAIL means the ledger and provider disagree and need human triage.
•ERROR means no comparison happened because the external fetch failed.
Collapsing ERROR into FAIL buries real mismatches, and collapsing ERROR into PASS is worse: ledger drift hides behind a provider connection that stopped updating, so a stale feed reads as a balance that aligns.
Classify reconciliation exceptions as timing, duplicate, missing, or shortfall
Classify every open exception into one of four categories:
1Timing: a posting that will clear once the counterpart settles.
2Duplicate: a posting created by a retried event that already reconciled.
3Missing: a bank movement with no matching posting, usually a dropped event.
4Shortfall: a real gap between customer liabilities and cash held.
Timing exceptions clear on the next cut-off, duplicates and missings point to write-path faults, and a shortfall triggers the safeguarding process. Exceptions that fit none of the four justify redesigning the account tree.
External reconciliation checks turn a ledger into a control step
External reconciliation checks force every internal balance to answer to an outside source of truth. A ledger never checked against an outside source is a claim, and is not in control over financial transactions.
The cost of treating an unchecked ledger as authoritative shows up in the public record, which can damage reputations.
Volume 1 of the Post Office Horizon IT Inquiry's final report, published July 8, 2025, records that the Post Office prosecuted postmasters over shortfalls that Horizon itself had generated.
Post Office staff knew, or should have known, that Horizon could produce illusory losses. The Post Office treated its data as accurate and relied on it as authoritative rather than reconciling it against what branches physically held.
Five ledger reconciliation checks to run this week
Ledger reconciliation is effective only when the account tree can explain five checks: account tree, mutation grants, webhook replay, cut-off replay, and exception classification.
1Account tree: Draw the account tree and confirm each provider's in-flight funds has a named account. If the difference between bank balance and customer liabilities isn't a balance an engineer can point to, add the account.
2Mutation grants: Grep the codebase and database grants for UPDATE or DELETE against posted transactions, revoke the grants found, and route corrections through compensating postings.
3Webhook replay: Replay yesterday's PSP webhooks against a staging ledger and count how many duplicate postings land. Any duplicate count above zero points to a missing idempotency key.
4Cut-off replay: Re-run yesterday's balance check at the bank's cut-off using effective dates. If the ledger has one timestamp per posting, adding an effective-date column is the first migration.
5Exception classification: Classify every open exception as timing, duplicate, missing, or shortfall.
Each check reaffirms a different part of the reconciliation. The account tree explains mismatches, mutation grants protect history, and webhook replay proves idempotency. The cut-off replay proves bi-temporality, and exception classification keeps the safeguarding queue readable.
Formance Reconciliation runs the account-tree and exception-classification checks by comparing ledger balances against provider data with historicized balances and bi-temporal cut-offs. The underlying ledger enforces mutation grants, webhook idempotency, and cut-off replay at the storage layer.