Separate financial entries, displayed balances and external settlement. Define invariants and correction paths before relying on ledger totals.
A ledger is a record of financial movements whose rules can be explained and checked. A displayed balance is a view over that record, possibly with holds and pending amounts. Treating the balance as an ordinary editable field makes it difficult to explain how it changed or repair an interrupted workflow. Start with the financial model and operation boundaries, then choose storage and projection mechanisms that preserve them.
Name the amounts your product exposes
Available, pending, reserved and settled amounts answer different questions. Write examples showing what happens when an authorisation expires, a capture is partial or a refund arrives after settlement. Define which amount a customer may spend and which amount an operator may report. Do not make every screen invent its own interpretation of the same financial state.
| Concern | Design decision | Verification |
|---|---|---|
| Amount representation | Exact decimal arithmetic or integer units with explicit currency precision | Test rounding boundaries and supported currencies. |
| Operation identity | A stable identity for each intended business movement | Retry the operation and check for duplicate effects. |
| Corrections | A traceable reversal or adjustment linked to the original | Reconstruct the history before and after correction. |
| Read models | Derived balances with a defined refresh and recovery process | Rebuild a projection and compare it with the live view. |
State invariants before choosing implementation
An invariant is a condition that must remain true after an operation. In a double-entry model, define how entries balance within the relevant currency and accounting boundary. Separately define constraints around reservations, spending and provider reconciliation. A balanced pair of entries can still represent the wrong payment, so structural checks and business identity checks are both necessary.
Keep atomic work inside a clear boundary
Identify the records that must commit together and what happens when an external provider cannot participate in that commit. Avoid assuming a database transaction also rolls back a completed network call. Record the intended external action and reconcile its outcome. If operators need a repair tool, it should enforce the same model, permissions and auditability rather than allowing silent database edits.
Test reconstruction and correction
- Rebuild a balance projection from authoritative entries and compare the result for a representative dataset.
- Exercise concurrent spending, retries and interrupted operations against the intended constraints.
- Apply an authorised correction, then verify the original record, reason, approval and resulting balances remain explainable.
The deliverable is a documented model plus executable checks, not a claim that one schema fits every business. Review financial semantics with the people responsible for accounting and operations. A technical design review does not replace that responsibility or certify compliance.
- Fintech audit
- Refund and chargeback workflows: test the failure cases
- Payment integration audit: duplicate charges and missing payments
Frequently asked questions
Does every product need a double-entry ledger?
The financial model depends on the product's obligations. Double-entry can support strong accounting controls, but adopting its terminology without modelling actual operations does not ensure correctness.
Can balances be cached?
Yes, if the authoritative source, update mechanism and recovery procedure are explicit. Test rebuilding and detecting divergence between the projection and its source.
Are integer minor units always sufficient?
Not for every calculation. Precision requirements depend on currency and operation. Define exact arithmetic and rounding rules rather than assuming every amount has two decimal places.
Can an administrator correct a mistake?
Yes through an authorised, traceable correction workflow. Preserve the original entry, link the adjustment and record its reason and approval.
What is the first useful ledger test?
Choose a complete operation, repeat it under concurrent and interrupted execution, then reconstruct the resulting financial state from its records.
Bring the scope. We will help make it buildable.
Share the user journey, integrations and launch constraints. We can clarify the scope and prepare an estimate with assumptions and exclusions.
Further reading
Refund and chargeback workflows: test the failure cases
Model refunds and disputes as separate workflows. Verify partial outcomes, repeated events and the operational consequences for access, stock and reporting.
Payment integration audit: duplicate charges and missing payments
Trace a payment across checkout, provider events and internal records. Build an audit checklist that distinguishes duplicate processing from reporting delays.
Webhook idempotency: prevent repeated payment effects
Design payment-event processing around durable identifiers, atomic updates and recovery. Learn what to test when a webhook arrives twice or processing stops.