Distributed Payment Processing Engine

A ledger is the money notebook. In double-entry bookkeeping, every movement of money is written as at least two entries: one account goes down and another goes up by the same amount. If Sam gives Ana 5 marbles, we write Sam minus 5 and Ana plus 5. Add them up and you get zero.

That zero is a built-in alarm. Inside the books, money never appears out of nowhere and never vanishes. It only moves. If the entries of any transaction, or of the whole notebook, do not add up to zero, we know right away that something is broken.

A payment can touch more than two accounts. When Kim pays 20 dollars for a book, the shop might get 19.40 and the payment company 0.60 as its fee. That is three entries, and they still add up to zero.

Amounts are stored as whole numbers of the smallest coin, like 2,000 cents instead of 20.00 dollars. Computers store decimal fractions in a way that can be very slightly off, and tiny errors pile up over millions of payments. Whole cents are always exact.

Ledger entries are written once and never changed or deleted. It is like writing in pen in a notebook with numbered pages. A mistake is never rubbed out with an eraser. Instead, the teacher writes a new line that cancels it, called a reversing entry, and then writes the correct line.

This keeps a full history. Anyone can read the notebook from page one and see exactly what happened and when, which is what auditors, the grown-ups who check the books, need. It also makes bugs easier to find, because nothing was quietly painted over.

A balance, like how much money Ana has, comes from adding up all of Ana's entries. Adding up years of entries on every request would be slow, so systems usually also keep a stored balance and update it in the same database transaction as the new entries, so the two can never disagree. The trade-off: the notebook only grows, so it needs more and more storage, and fixing a mistake takes extra entries instead of a quick edit.

If the computer crashed after writing Sam minus 5 but before writing Ana plus 5, five marbles would vanish. To stop that, all entries of one transfer are saved inside a single database transaction. A transaction is an all or nothing promise: either every line is saved, or none of them are.

Databases that keep this promise are called ACID. In plain words: the change happens all at once, the rules always hold, two changes at the same moment do not trip over each other, and once saved, it stays saved even if the power goes out. Ledgers usually live in a relational database, the kind built from tables, because it keeps these promises well and gives strong consistency, meaning every reader sees the latest saved truth.

Rules are checked inside the same transaction. For example, the database locks Sam's balance, checks that Sam has at least 5, and only then writes the entries. Because the check and the write happen together, two payments at the same moment cannot both spend the same 5 marbles.

The trade-off is speed. Strong promises mean waiting for locks, and one very busy account, like a huge shop, can become a traffic jam. When teams split a ledger across several databases, they try hard to keep all entries of one transaction in the same database.

Networks are unreliable. A phone sends, pay 20 dollars, the server charges the card, and then the reply gets lost on the way back. The phone cannot tell whether it worked, so it tries again. Without protection, Kim pays twice.

The fix is an idempotency key, a fancy name for a ticket number. The phone makes up a unique ticket for each payment and sends the same ticket with every try. The server saves the ticket together with the result, in the same transaction as the payment itself. When a retry arrives with a ticket it has already seen, it does not charge again. It simply hands back the saved answer.

A few details make it safe. If two copies arrive at the very same moment, a lock or a unique rule in the database lets only one through, and the other is told, still working, please try again soon. If the same ticket comes back with a different amount, that is a mistake, and the server refuses it. Tickets are kept for a while, often about 24 hours, then cleared away, so retries must happen within that time.

One payment touches many services: a fraud check, the card network and bank, the ledger, and the receipt sender. They cannot all share one database transaction. So we use a saga, which is a list of steps where each step has a matching undo step, called a compensation.

An orchestrator is the coach who runs the list. It does the steps in order: check for fraud, authorize (ask the bank to hold the money, like putting a toy on layaway), write the ledger entries, capture (actually collect the held money), and send the receipt. After each step it writes down where it is, so if the orchestrator itself restarts, it picks up from its notes instead of starting over.

If a step fails, the coach runs the undo steps in reverse order. If capture fails, it writes reversing entries in the ledger and voids the hold, so the money is released. If money had already been collected, the undo would be a refund. Every call to an outside service carries its own idempotency key too, because the coach may repeat a step after a crash.

The trade-off is that a saga is not instant and not invisible. For a short while, other parts of the system can see a half finished payment, like money on hold, so screens and reports must clearly show states such as pending.

Even a careful system can drift from reality. A bank might reject a payment we thought went through, or a glitch might leave a step half done. So every day the payment company receives settlement files from banks and card processors that list what really moved, and compares them line by line with its own ledger.

Each payment should appear in both places with the same amount. Lines that are missing on one side, or that have different amounts, are flagged. A person or an automatic job then follows up, and any fix is made with new ledger entries, never by editing old ones.

Reconciliation does not prevent mistakes. It catches them. It is the last safety net under all the other ideas on this page.