πŸ’¬
βœ‰οΈ
πŸ“Έ
▢️

Loading…

Design a payment system: ledgers, webhooks, and idempotency

PaymentGuided Mode

Step 5 β€” Immutable Ledger for Financial Auditability

Request Flow

1

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).

2

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.

3

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