By Shivacha Engineering
Balances that cannot be explained are a liability
Early fintech products often store a balance column and update it as transactions arrive. It works — until a webhook is delivered twice, a card authorisation is reversed after settlement, or a partner statement disagrees with your numbers and nobody can explain why.
A double-entry ledger replaces mutable balances with an immutable journal of balanced entries. Every balance becomes the sum of explainable movements, and every discrepancy can be traced to a specific entry.
Model the money before the screens
Before designing onboarding flows or dashboards, define the account structure: customer accounts, holds, fees, settlement and suspense accounts, partner accounts. Then model each money movement as a state machine with the ledger entries each transition produces.
This exercise surfaces the hard questions early: what happens when an authorisation expires, how refunds after settlement are recorded, how currency conversion is represented and where fees land.
- Holds are separate from settled balances
- Every movement has an idempotency key
- Journal entries are never edited — only reversed
Idempotency and the outbox pattern
Distributed systems retry. Payment providers resend webhooks. Mobile clients double-tap. Every operation that moves money must be idempotent: repeating it returns the original result rather than moving money twice.
When a ledger transaction must also publish an event — to notify the user, update analytics or trigger a payout — write the event to an outbox table in the same database transaction and publish it asynchronously. This avoids the classic failure where money moves but the event is lost, or vice versa.
Reconcile from day one
Reconciliation is how you prove your ledger matches reality: bank statements, processor settlement files, custodian balances. It should run daily from the first day of production, with automated matching and exception queues, not as a month-end scramble.
The same principle applies to digital assets: on-chain balances and custodian records must reconcile with the internal ledger continuously.
Owning the ledger means owning your future
A ledger you own — independent of any single BaaS provider or processor — is what allows you to add partners, switch providers, launch new products and answer auditors with confidence. It is also what makes hybrid products possible: a stablecoin is simply another asset in a well-designed multi-asset ledger.
