Payments ledger design: recording money movement, balances and reconciliation

Design the ledger for a payment processing system. The ledger is the system of record for money: every time funds move through the processor, for example when a customer is charged, a fee is taken, a refund is issued or a merchant is paid out, the ledger records it, and the amount any party is owed must be derivable from those records at any point in time. Explain the requirements, the data model, how movements are written and read, how the design holds up at high volume, and how the business can trust that the numbers are right. ```hint Start from the invariant Before drawing any boxes, decide what must be true about the money in the system after every single write, and what must never be possible (such as a record silently changing). Then shape the tables and the write path so that rule cannot be broken, even when requests are retried. ``` ### Clarifying Questions - Is this the processor's internal book of record (merchant balances, fees, payouts to bank accounts), or a ledger product that merchants use to track money in their own businesses? - Which money movements must the first version handle: charges and refunds only, or also disputes, payouts, currency conversion and manual adjustments? - Must a payment be recorded in the ledger before the payment request returns, or may it be recorded shortly afterward as long as nothing is ever lost or duplicated? - Who reads from it: merchants checking balances and payouts, the finance team closing the books, auditors, or other internal services? ### What a Strong Answer Covers - Requirements that rank correctness, immutability and auditability above raw speed, tied to the people and teams that depend on the ledger. - A data model in which every money movement balances, amounts are exact and currencies are explicit. - A write path that stays correct under retries and concurrent updates, and a read path for balances, history and point-in-time questions. - Scaling choices, including how to handle accounts that nearly every payment touches. - Controls and metrics that prove the ledger matches reality, including reconciliation against bank and card-network records. ### Follow-up Questions - A service times out while posting a payment and retries, but the first attempt had already committed. How does your design stop the payment from being recorded twice? - The account that collects the processor's fee revenue receives an entry for almost every payment and becomes a write hotspot. How do you remove the bottleneck without weakening correctness? - Finance reports that yesterday's deposit from a card network does not match the total the ledger expected. How does the system surface the gap, and how is it resolved?