_FINANCIAL-OPERATIONS/
Ledger Balance Explained for Product and Engineering Teams
By Formance Staff
Ledger
Accounting
Reconciliation
Payments
Loading article content
Loading table of contents
Loading author
Preventable failures at UniRush and Mastercard left RushCard customers unable to access their money and receiving incorrect balance information, including zero balances and falsely inflated balances caused by double-posted deposits and delayed debits. Regulators later ordered an estimated $10 million in restitution and a $3 million civil penalty.
Ledger balance rarely means the same thing in every layer of a financial platform's stack, and the mismatches show up in production. High-profile failures like RushCard trace back to ambiguity about what “ledger balance” actually means and how it relates to the other balances your system tracks.
Every new payment rail, product line, and market multiplies reconciliation issues until the gap between what your system believes and what actually happened becomes hard to close. The decision to build a ledger is an architectural commitment that determines what your business can do as it grows.
This article defines ledger balance, contrasts it with available and pending balances, identifies five use cases and walks through how a production-grade ledger delivers on them.
Ledger balance is the settled account balance after all cleared transactions have posted, excluding pending or held amounts. The term has two definitions depending on context (traditional banking versus product ledger), and conflating the two causes real bugs.
In traditional banking, ledger balance is the settled balance after cleared transactions post during nightly batch processing, excluding any amounts on hold. It's a batch-computed value rather than a real-time figure, which is why bank-partner application programming interfaces (APIs) that return "ledger balance" can lag what your product ledger shows.
In a product ledger context, ledger balance is the current account state after all transactions have been posted. Balance is still derived from posted debits and credits, based on the account's normal balance, just as in banking. Some systems update ledger balances in real time, while end-of-day or nightly posting runs handle closing, reconciliation, and consistency tasks.
In both banking and product ledger contexts, balance is the sum of all postings against an account. If your infrastructure treats balance as a mutable field in a user table, you lose the ability to explain how the balance got there.
Ledger balance is only one of three balances you track day-to-day — ledger, available, and pending. When your code reads one balance but acts on another, that's balance conflation, and it causes most production bugs at fintechs.
You need ledger balance architecture when your product requires concurrent balance enforcement, per-merchant payout accuracy, real-time authorization, historical balance reconstruction, or atomic multi-account transfers. The five use cases below each push teams toward a ledger early.
When a wallet processes a payment, it usually does three things in order: read the current balance, check if there's enough money, and then subtract the amount. The problem is that two requests can hit the wallet at the same time. Both read a balance of $100, both see that $50 is available, and both subtract $50. The wallet ends up at $50 when it should be at $0, or worse, at -$50. Production wallets have hit this exact failure when users repay multiple debts at the same moment.
You need balance limits enforced in the database itself (not in application code), an append-only log of every transaction, double-entry rules that catch unbalanced postings, and idempotency keys so a retried request can't accidentally subtract the same amount twice.
A marketplace has to track money owed to every seller individually, not just one pool. Most teams start with an Orders table and a scheduled job that adds up completed orders and triggers payouts. That works until refunds, chargebacks, and returns show up. Each one needs its own special case in the payout logic, and within a year, the payout code is a tangle of if-statements that nobody wants to touch.
The deeper problem is fund attribution. Marketplaces usually hold every seller's money in one shared bank account, which means your system needs to know which dollar belongs to which seller at any moment. Solving that often requires capabilities like Assets Coloring, which tags funds inside a pooled account so they can still be traced to individual owners.
You need every event that moves money to be recorded as a double-entry posting, accounts organized in a clear hierarchy (sellers, fees, liabilities, pending versus settled), and a clean separation between funds that are pending and funds that have settled.
When your product approves or denies a payment in real time, the balance check and the deduction must occur as a single operation. If they happen separately, two authorizations can pass at the same time even though only one should.
A common pattern is the two-phase transfer. The first phase creates a pending debit that immediately reduces the available balance. The second phase either confirms the debit (the payment settled) or releases the hold (the payment failed).
In a programmable ledger, the two phases are two atomic postings: the first places the hold, and the second settles it.
Phase 1 (Authorization to place the hold)
send [USD/2 4000] (
source = @users:1234:available
destination = @users:1234:pending)
The user's available balance drops by $40, and their pending balance rises by $40, while posted remains unchanged.
Phase 2 (Settlement to clear the hold)
send [USD/2 4000] (
source = @users:1234:pending
destination = @world)
The pending balance returns to zero, and the $40 moves to the external world account that represents settled funds at the bank; each send is double-entry and atomic, so both legs commit or neither does.
Idempotency keys ensure that if a network glitch causes the same authorization to be sent twice, the balance moves only once. You need two-phase transfers built into the ledger, idempotency keys on every authorization, and available balance read directly from the ledger rather than from a cached copy that might be stale.
Disputes and audits often require knowing what the balance was at a specific point in the past. If your system stores the current balance in a single column and overwrites it whenever the balance changes, the past is lost. You can't answer "what was this account's balance on March 14 at 3:42 PM" from a column that's been overwritten a thousand times since.
The same record that makes historical reconstruction possible (an append-only log of every posting) is also what makes automated reconciliation against bank statements work.
You need an append-only log as the system of record, a timestamp on every posting, no soft deletes (which can hide or change history), and closed-period enforcement so nobody can sneak a backdated posting into a month that's already been reported.
Moving money between two accounts means a debit on one and a credit on the other. If those happen as separate database updates, there's a window where one succeeds and the other fails. Money leaves account A and never arrives in account B.
When both accounts live inside the same ledger system, this is solvable with a single database transaction. Either both updates commit or neither does. When the accounts live in different services or different systems, atomicity is much harder and usually requires distributed transaction patterns like the saga pattern or two-phase commit.
You need a ledger that treats multi-account transactions as a single operation, where every posting in the transaction either commits together or doesn't commit at all.
If any of those five use cases apply to your product, what follows is how a properly built ledger actually delivers them.
Ledger balances in fintech systems are produced by how balances are stored, how the zero-sum constraint is enforced, and how historical state is preserved.
Two approaches dominate the calculation of balance in production systems: running balance and aggregated balance.
A pre-computed balance updated atomically alongside each transaction write. One approach tracks cumulative posted debits and cumulative posted credits as independent, monotonically increasing counters. The application derives the net balance as either debits_posted - credits_posted or credits_posted - debits_posted, depending on the account type.
Keeping both sides separate avoids signed-number arithmetic and preserves information, since two accounts can share a zero net balance while having vastly different activity volumes. An account that has moved $10 million in and $10 million out carries different risk and audit implications than an account that has never transacted, even though both net to zero.
Storing a running balance as a standalone field in a user account table is often an anti-pattern. Failed transactions, concurrency issues, or data sync bugs can produce balance drift that's difficult to trace or correct.
No pre-computed balance field exists. Balance is computed at query time by summing all debits and credits from the immutable transaction log. Point-in-time queries follow naturally from the aggregated model. Filter by timestamp to get a historical balance without additional instrumentation.
Production systems frequently combine both approaches through CQRS (Command Query Responsibility Segregation). The write model is an immutable event log (the aggregated approach), and the read model is a materialized index updated alongside each write (the running balance approach). You get fast current balance reads while preserving point-in-time reconstruction from the underlying log.
Whichever storage approach you choose, the system needs a way to guarantee that the underlying numbers remain internally consistent.
The balance equation requires that total debits equal total credits across every transfer, and the zero-sum constraint is what keeps a double-entry system honest. The system-wide invariant is that the sum of all debits posted equals the sum of all credits posted. If the invariant breaks, the cause is either a bug or data corruption. Money should not appear or disappear without a corresponding posting.
The zero-sum constraint is strongest when enforced as low in the stack as possible. Application-layer validation is the weakest option, since application code is more exposed to bugs and race conditions. Purpose-built ledger databases that reject unbalanced writes at the API layer are stronger still, because the interface itself limits how postings can be created.
The zero-sum constraint keeps current balances consistent at the moment they are written. Keeping balances consistent across history requires a separate mechanism: an immutable transaction log.
Point-in-time queries depend on immutability of the underlying log. Because the transaction log is append-only, postings are not modified or deleted after writing. Corrections are handled through new compensating postings.
Reverse the original posting via a new posting with the opposite amount, then create a new posting with the correct amount. The original posting remains in place. Queries before the correction timestamp return the original state, and queries after return the corrected state.
Bi-temporality enables point-in-time correctness by tracking both when an event was recorded and when it became effective. For settlement-lagged payment systems where transactions arrive out of order, bi-temporality keeps historical balance queries accurate by separating the recorded timestamp from the effective timestamp.
Concurrent enforcement, zero-sum constraints, immutable logs, and bi-temporality can all be built from scratch, but doing so would mean rebuilding existing infrastructure.
Building concurrent enforcement, zero-sum constraints, immutable logs, bi-temporality, and atomic multi-account transfers yourself means implementing a solid ledger architecture. None of those components differentiates your product. Each one exists to prevent balance conflation: three balances, updated at different times, read as if they were one.
The engineering teams that hit this wall share the same signals: balance drift that nobody can explain, manual reconciliation work that grows every quarter, and schema migrations to fix balance bugs that should never have existed.
The neobank displaying a balance that doesn't match what's settled and the operations team reconciling a $3,000 variance with no transaction-level explanation are running into the same architectural gap.
Formance Ledger handles all five properties as part of the core. It's open source under the MIT license and programmable, with Numscript, a domain-specific language for transaction intent, so postings either commit together or not at all.
Our ledger enforces double-entry at the database level, preventing unbalanced postings and also stores every transaction in an append-only log, allowing you to reconstruct any past balance. Your team builds the product on top of the plumbing, not underneath.
Start with the Formance quick-start guide and post your first transaction in the sandbox.