Design a payment system: ledgers, webhooks, and idempotency
Payment
Guided ModeStep 5 β Immutable Ledger for Financial Auditability
Request Flow
Why a separate ledger?
A transactional database supports UPDATEs β but financial records must never be updated or deleted. We introduce a dedicated Ledger Service backed by an append-only database that enforces immutability at the schema level (no UPDATE/DELETE grants).
Double-entry bookkeeping
Every financial event produces two ledger entries: a debit on one account, a credit on another. The Ledger Service enforces the invariant that total debits always equal total credits. Any imbalance triggers an immediate alert.
Separate concerns: state vs. history
The Pay DB tracks current state (what is the status of this charge?). The Ledger DB stores history (what financial movements occurred and when?). The Settlement Worker moves gateway events into the ledger pipeline, while regulators, auditors, and fraud investigators query the ledger β never the transactional DB.
Why We Need This
Financial regulations (PCI-DSS, SOX) require an immutable audit trail. Using a regular database with UPDATE permissions is a compliance violation. The ledger is also your last line of defence β if your application has a bug that silently corrupts charge records, the ledger will catch the discrepancy.
Key Insight
Ledgers are append-only, never updated. Balance is always computed by summing ledger entries β never stored as a column. This makes fraud and bugs immediately visible as an imbalance.
Step 5 of 7
