_FINANCIAL-OPERATIONS/
What Is a Ledger? A Guide for Software Engineers
By Formance Staff
Ledger
Accounting
Reconciliation
Loading article content
Loading table of contents
Loading author
You're running a fintech product that moves customer money through a payment processor, and one morning, a reconciliation job flags a $42,000 gap between your internal balances and the processor's settlement report.
As engineers, your team spends three days grepping application logs, replaying webhook payloads, and diffing the transactions table against the payment processor's API because the wallet has to match what the processor says happened. The root cause of the $42,000 discrepancy: a webhook retry posted the same transfer twice because the debit and credit were written as two separate, uncoordinated database calls instead of a single atomic transaction.
That discrepancy comes from moving money without a real ledger. And "ledger" is one of those words engineers use loosely: sometimes it means a transactions table, sometimes an event log, or sometimes whatever code sits closest to the payment processor. Those things are not the same, and the difference determines whether bugs like the one above are even possible.
This guide is a working definition for software engineers: what a ledger actually is, the rules it must enforce, and what happens when those rules are missing.
A ledger is the system that records every movement of money in your product as a pair of postings (a debit and a matching credit) and computes balances by summing those postings.
This ledger infrastructure ensures auditability and makes every balance verifiable by reconstruction: balance(account) = ∑ postings(account)
Engineers often mistake a ledger for transaction tables, event logs, and payment processors, but none of those enforce double-entry or own the financial truth the way a core ledger does.
A transactions table can be edited and has no rule that total debits equal total credits, an event log is append-only but enforces no financial rules, and a payment processor moves money over external rails while the ledger records what those events did to your balances.
A properly built ledger rests on four things working together: double-entry balance validation checked on every write, a chart of accounts naming scheme, balances calculated from financial postings, and two timestamps on every entry. Each one prevents a specific failure that occurs during ledger management and execution.
Double-entry is checked by the system before it writes the transaction, not after. Every transaction must produce financial postings where the total amount of debits equals the total amount of credits, and the system rejects any write that doesn't balance.
The chart of accounts is a naming scheme in which account numbers indicate the account type and its position in the hierarchy.
A prefix system like 1xx, 2xx, 3xx, 4xx, and 5xx lets you query ranges and roll up totals without storing the type as a separate column on every row.
Each account type has a sign rule enforced by the database. Asset and expense accounts have debit-normal balances (balance = debits_posted − credits_posted). Liability, equity, and income accounts have credit-normal balances.
A ledger never stores a balance as a number you can update. Instead, it adds up all the entries for an account whenever you ask: balance = sum of postings.
The moment you save a running total in its own column, that number can fall out of sync with the actual history, and you won't know which one is correct without adding the entries up again.
Every financial posting needs two timestamps:
A card transaction authorized on Monday but settled on Wednesday has an effective time of Monday (when the cardholder authorized the spend) and a recorded time of Wednesday (when settlement was confirmed and your system recorded it).
A ledger with only one timestamp can't answer "What was the balance on Tuesday?" accurately, because the transaction was committed on Monday but only recorded on Wednesday — single-timestamp systems will either miss it or backdate everything.
Most teams calling their system a "core ledger" have actually built a sub-ledger. It's a mislabel that costs them the moment a second product line ships or finance asks a cross-product question.
Most teams don't need a general ledger at all because their finance team or ERP already owns one. What they've built and labeled a "core ledger" is usually a sub-ledger for one product domain (wallets, payouts, cards) quietly elevated to source-of-truth status.
Three distinctions worth keeping straight:
Open-source ledgers, which are core ledgers published under permissive licenses such as MIT or Apache 2.0, let you read the code that handles your money, avoid vendor lock-in, and run them on your own infrastructure.
Four rules must hold for a ledger to produce the right balances: immutability, idempotency, consistency, and atomicity. They depend on each other, so breaking any one of them weakens the infrastructure of the remaining.
A financial posting, once written, can't be changed or deleted. The right way to amend a wrong posting is a reversal: a new entry that cancels out the original. That keeps history from being rewritten, but it doesn't prevent the same writing from being recorded twice, leading to integrity issues during audits.
Safe retries stop a request from being processed twice when a client retries a failed call. Consider a payment that goes through, but the confirmation gets lost on the way back. The client retries, and without safe retries, both charges run.
For the client to generate a stable key for each business event and send it with every request, the server must check whether it has already processed that key and return the saved result if so.
A common mistake is generating a fresh UUID on each retry, which defeats the whole thing. Safe retries handle duplicates from a single client, but writes occurring simultaneously from different clients still need to be coordinated.
When two requests read the same balance, change it separately, and write it back without coordinating, one update overwrites the other. One common approach is optimistic locking: a version number that goes up every time the row changes. The last failure mode lives between the two sides of a single transaction.
A partial transaction occurs when a debit is recorded, but the matching credit never reaches its destination, usually because the two legs were processed by different services.
The requirement is that the smallest unit the ledger writes is a transaction with at least two postings that balance, and there's no API for writing just one side.
A broken ledger costs you in three escalating ways: silent balance drift, reconciliation debt that eats engineering time, and homegrown systems that fail outright under production load. The CFPB action against Synapse is the public case study for what happens when those problems pile up.
Balance drift happens when a ledger write succeeds, but a matching downstream update fails. For example, when a cache update fails, when a distributed saga partially completes, or when an outbox pattern fails to publish an event. The cached balance and the real ledger value disagree.
One contributing architectural pattern is to store a running balance as a column in a user account table, without an append-only log as the real source of truth; however, drift can occur in distributed systems even with proper append-only ledgers if downstream propagation fails. Drift between systems eventually shows up somewhere, and that somewhere is the reconciliation queue.
Reconciliation debt builds up when mismatches require a human to investigate them rather than being matched automatically. As a ledger collects design debt, more mismatches need a human, and each one pulls engineers away from product work.
Homegrown ledgers fail in three predictable ways under production load:
The real-world consequences are documented. The CFPB filed an action against Synapse Financial Technologies after its internal records of individual customer balances were found to exceed the actual funds in the pooled accounts supporting them.
With no source of truth to figure out who owed what, Synapse filed for bankruptcy, and customers lost access to their money.
Do not consider your ledger as a feature inside the application. Treat your ledger as its own piece of infrastructure, sitting between your payment rails and your general ledger. The issue is that the application code says what a transaction is supposed to do, while the ledger handles writing it atomically, calculating balances, and keeping the audit history.
Formance Ledger is one way to build this solid infrastructure foundation. It's open-source and MIT-licensed, with the four rules built in as native primitives. Transactions are written in Numscript — Formance's language for moving money, readable by both engineers and finance — so instead of juggling debits, credits, and balance checks in application code (where race conditions and partial writes live), you describe what the transaction should do, and the ledger writes it all in one go and won't let you change it after.
Teams that build a ledger from scratch end up with correctness bugs that are hard to spot and expensive to amend. The build-versus-buy question is whether your team can build a ledger while maintaining one, or if it is the best use of your engineering time.
If you want to go deeper, explore the Formance Ledger open-source repo on GitHub to read the code, run it locally, and see how the four invariants are enforced as native primitives.