ADR: Why a double-entry ledger for payment systems
A short architecture decision record for choosing accounting correctness, auditability, and reconciliation over a simple mutable balance table.
Mutable balances are attractive because they are simple to query. They are also dangerous when money moves through retries, reversals, provider callbacks, and delayed settlement. The moment finance asks why a balance changed, a single current-value table stops being enough.
Current Status · Accepted · 2025-04-12
Background & Context
The payment platform must support wallet integrations, provider callbacks, refunds, partner settlement, and finance reconciliation. Auditors need an immutable trail for every posted movement.
Final Decision
Use a double-entry ledger with append-only postings. Every movement creates balanced debit and credit entries inside a transaction; derived balances can be cached, but the journal remains the source of truth.
Tradeoffs & Consequences
**Positive:** reconciliation and audit become explainable from data. **Negative:** engineers must model accounting events explicitly, and write paths need stronger transactional discipline.