Design a digital wallet (Paytm)

A wallet balance is a liability we owe the user, so it must be exact and provable. Use double-entry: every movement is a journal whose lines sum to zero across accounts. Users, merchants, the escrow cash account, cashback expense, fee revenue and clearing accounts are all accounts. Keep a balance column on each account for fast reads, but update it only in the same database transaction that inserts the ledger lines, so the cached balance and the lines can never disagree. The debit is a conditional update: UPDATE accounts SET balance = balance - x, version = version + 1 WHERE id = ? AND balance >= x. If no row changes, the payment fails with insufficient balance; there is no read-then-write race. A CHECK constraint (balance >= 0) is a second guard. Idempotency comes from a unique key on the journal, so a retried request returns the original result. Money is integer paise. Corrections are reversing journals, never edits. Continuous integrity jobs check that every journal sums to zero, that each account's balance equals the sum of its lines, and that the total of all user and merchant balances equals the escrow bank balance plus in-flight amounts, the key regulatory invariant.

With 100M accounts, the ledger is sharded by account_id, so a P2P transfer or merchant payment often touches two shards. Distributed two-phase commit across shards works but adds latency and blocking during failures. The common alternative is a saga with clearing accounts. Step one, on the payer's shard: debit the payer and credit a clearing account 'outgoing to shard B', in one local transaction, and write an outbox event. Step two, a worker consumes the event and on shard B debits the 'incoming from shard A' clearing account and credits the payee, idempotent on the journal ID. The payer sees success after step one because the money has left their account safely; the payee sees it within milliseconds to seconds. If step two fails permanently (payee account blocked), a compensating journal on shard A reverses the transfer. Clearing accounts across shards must net to zero once all events are processed; a monitor alerts if they do not drain. Co-locating frequently paired accounts (a user and their own promo account) on the same shard avoids sagas where possible.

A large merchant can receive thousands of payments a second during a sale. If every payment updates one merchant balance row, that row becomes a lock hotspot and throughput collapses to a few hundred per second. Fixes: split the merchant account into N sub-accounts (e.g. 32) and credit a random one; the merchant balance is the sum. Or credit merchants asynchronously: the payment transaction debits the user and credits a per-shard 'merchant payable' clearing account, and a batch job aggregates hundreds of payments into one merchant credit every second. Merchants rarely need sub-second balance; they need reliable notifications and correct settlement. The user's side remains synchronous and strongly consistent, which is what matters for preventing double spend.

Cashback is not the same as money the user loaded. It may be usable only at some merchants, it expires, and it must be accounted as a marketing expense. Store promotional balance as lots with amount, remaining, campaign and expiry. Crediting cashback posts: debit cashback expense (per campaign), credit user_promo. Spending consumes lots in order of earliest expiry, and the journal records which lots were used so refunds can restore them correctly. Expiry is a nightly job that posts reversing journals for expired remaining amounts. Campaign budgets are enforced with a counter per campaign, decremented atomically when cashback is granted, so a viral campaign cannot overspend. Fraud teams watch for patterns like many new wallets on one device claiming cashback.

Balances need transactions, conditional updates and constraints. Sharded Postgres/MySQL (or distributed SQL) gives these directly. NoSQL stores scale writes but you rebuild transactional safety. Purpose-built ledgers like TigerBeetle give very high throughput for double-entry with strict invariants.

2PC gives atomicity but blocks on coordinator failure and adds latency. A saga with clearing accounts is non-blocking and fast but the payee is credited a moment later and needs compensations. Wallets usually choose sagas.

Synchronous credit is simple and shows the merchant balance immediately but creates hot rows. Batched credit scales and is enough for merchants who settle daily.

Summing lines on every read is too slow; keeping only a balance column loses auditability. Keep both, updated together in one transaction, and verify continuously.

A big campaign brings 20x traffic in minutes. Pre-scale, protect the ledger with admission control, and make cashback crediting asynchronous so it does not compete with payments.

Sub-accounts or batched merchant credits remove the lock hotspot.

Old lines move to cold storage; statements use an index on (account_id, created_at) and a read replica, with monthly statements pre-generated.

The top-up stays pending. A reconciler queries the gateway for pending top-ups older than a few minutes and posts the credit idempotently; the daily settlement file is the final check.

Payers are already debited into clearing accounts; payees see credits delayed. When the worker resumes it processes the outbox backlog idempotently. Monitors alert on clearing account balances that do not drain.

Failover to a synchronous replica (no committed transaction lost). Payments for users on that shard fail fast for seconds and clients retry with the same Idempotency-Key.