Double-Entry Ledgers for Engineers — Payments & Money APIs

Balances computed from mutable balance columns drift and can't be audited. A double-entry ledger records every money movement as an immutable journal entry with postings to accounts whose debits and credits sum to zero per currency. Balances are derived (or cached with checks). Corrections are new reversing entries, never updates. Accounts model reality: customer receivables, PSP clearing, PSP balance, bank, fees expense, revenue, refunds, seller payables, tax payable.

Tracking money

Criterion	Balance column	Transaction log	Double-entry ledger
Auditability	None	Partial	Full
Detects missing money	No	Hard	Yes (entries must balance)
Corrections	UPDATE (history lost)	New rows	Reversing entries
Multi-party flows (fees, sellers)	Hard	Hard	Natural
Complexity	Low	Medium	Medium–high

CREATE TABLE ledger_entries (
  id uuid PRIMARY KEY, occurred_at timestamptz NOT NULL, description text NOT NULL,
  external_ref text UNIQUE                     -- e.g. PSP event/charge id (idempotency)
);
CREATE TABLE ledger_postings (
  entry_id uuid REFERENCES ledger_entries(id), account text NOT NULL,
  currency char(3) NOT NULL, amount_minor bigint NOT NULL      -- +debit / -credit
);
-- Invariant (enforced in code + checked by job): SUM(amount_minor) = 0 per entry and currency

Entry: charge ch_123 succeeded
  DR  psp_clearing:usd          5000
  CR  revenue:usd                       5000
Entry: PSP fee for ch_123
  DR  fees_expense:usd           175
  CR  psp_clearing:usd                   175
Entry: payout po_9 (net)
  DR  bank:usd                  4825
  CR  psp_clearing:usd                  4825      → psp_clearing returns to 0 when reconciled

Common pitfalls

Updating or deleting ledger rows.
Mixing currencies in one balance.
No idempotency key on entries (double posting).

Key points

Immutable entries; debits = credits
Corrections via reversals
Clearing accounts expose mismatches

Further reading: Square: Books — an immutable double-entry accounting service

Practice questions

Why do double-entry ledgers make missing money detectable?

Answer

Every entry must balance, and clearing accounts should return to zero when flows complete; non-zero balances reveal mismatches.

How do you correct a wrong ledger entry?

Answer

Post a reversing entry (and a new correct one) instead of editing the original, preserving the audit trail.