04.05 · Walkthrough
The Ledger and the Monthly Close
Record money with double-entry, append-only writes committed in one transaction, and reconcile your own numbers against the processor report and the bank.
A reliable payment ledger stores immutable debit and credit facts, not mutable balances. Each money movement is written as a balanced journal entry in one database transaction, with balances derived from the log. Monthly close then checks internal totals against processor reports and bank statements, using new correcting entries rather than rewriting history.
What this lesson answers
- how to design a payment ledger database
- why use double entry for payments
- how to reconcile processor reports with bank payouts
Notes
A ledger is the source of truth for money in your product. Instead of storing “balance = 42.17” as a mutable field, you store facts: an account was debited, another account was credited, and both lines belong to one journal entry. Double-entry means every movement has equal and opposite effects, so money is never created or destroyed by accident inside your database. The current balance is a derived value from the entries, not the primary truth.
For a software engineer, the mental model is an event log with accounting rules. A payment capture, refund, fee, payout, or adjustment becomes an…
Common questions
- Why is a balance column not enough for payments?
- A mutable balance can be corrupted by retries, partial writes, refunds, delayed processor events, and manual fixes. The safer model is to store the underlying debit and credit facts as an append-only history, then compute or cache balances from that history. If a cache is wrong, it can be rebuilt from the ledger.
- What does double-entry mean in a payment system?
- Every money movement is recorded with matching debit and credit lines in a single journal entry. The entry must balance, so your database does not accidentally invent or lose money internally. A capture, refund, fee, payout, or adjustment becomes a structured accounting event rather than an isolated row update.
- What happens during a monthly close for payments?
- Monthly close proves that your internal ledger agrees with outside evidence. You compare ledger totals with the payment processor’s reports, then compare processor payouts and fees with the bank statement. When differences appear, you investigate timing, fees, reversals, or errors, and record corrections as new ledger entries instead of changing old ones.
Short definition: what is Ledger and the Monthly Close?