Design a Digital Wallet

The ask

A wallet holds value inside the service. The owner spends from the balance without touching a bank on each purchase.

People receive money into a wallet through an address that receives payments, such as a phone number or a chosen name tag.

Top-ups add money from a bank account. Withdrawals send money back to a bank account.

The hard rule is simple. A wallet balance never goes below zero.

Estimate the scale

The design holds 200,000,000 wallets.

Wallet payments run at 50,000,000 a day. 50,000,000 / 86,400 = 579 payments per second.

Top-ups run at 10,000,000 a day. 10,000,000 / 86,400 = 116 top-ups per second.

Payments and top-ups together give the main write load. 50,000,000 + 10,000,000 = 60,000,000 balance movements a day.

Reads of a balance are far more common than writes. A cache can serve balance views, and the ledger stays the truth.

API and data

The operations are pay from wallet, top up, withdraw, read balance and list history.

A pay request carries the sender wallet, the receiver, an amount and an idempotency key. A repeat with the same key returns the first result.

Each wallet payment writes two ledger entries under double entry. 50,000,000 x 2 = 100,000,000 entries a day from wallet payments.

The balance is a stored value plus the ledger behind it. The stored value serves fast reads and the entries prove it.

A top-up is pending until the bank confirms the money arrived. Pending money is shown apart from spendable money.

High-level design

An app server receives wallet requests and checks identity and limits.

A wallet service owns the balance rule. It checks the balance, writes the entries and updates the stored balance as one guarded step.

A bank connector handles top-ups and withdrawals. Bank answers arrive through a queue because banks can be slow.

A fraud check takes payment facts and returns a risk score. A high score holds the payment for human review.

Notifications tell both sides that money moved. A notification failure never undoes a finished payment.

Deep dive: the balance check

Every payment checks the balance before it writes. That order is the core rule of the design.

Two payments can arrive for one wallet at the same moment. Each one alone fits the balance, and together they exceed it.

One writer per wallet solves the race. Payments for a wallet pass through a single ordered path, often a distributed lock or a shard leader.

The second payment then sees the balance left by the first. It is refused when the money is no longer there.

The check and the write stay in one transaction on the wallet shard. Splitting them reopens the race.

Deep dive: two wallets, one payment

A wallet payment moves value between two balances. The sender falls and the receiver rises by the same amount.

A crash between the two updates would break the pair. The two ledger entries are written first in one transaction where both wallets share a shard.

Wallets on different shards use a saga. Each step has a compensating action that undoes it when a later step fails.

While a cross-shard payment runs, the sender shows a hold. The hold stops the same money being spent again in flight.

Top-ups and withdrawals

A top-up starts at the bank and ends in the wallet. The wallet credits only after the bank confirms.

A withdrawal starts in the wallet and ends at the bank. The wallet debits at once and the bank leg follows through the connector.

A failed withdrawal returns the money with a correcting entry. Old entries are never edited.

Daily limits cap both flows per wallet. Limits slow theft and mistakes without blocking normal use.

Failures and retries

A phone can retry a payment after a timeout. The idempotency key makes the retry return the stored result.

A bank confirmation can arrive late or twice. The top-up record holds a state, and a second confirmation changes nothing.

Reconciliation compares wallet ledgers with bank records. A gap becomes a case for a person, never a silent edit.

A frozen wallet refuses new payments and still shows its history. Freezing is a state, not a deletion.

Evaluation and trade-offs

The stored balance gives fast reads and fast checks. The ledger behind it gives proof and a rebuild path.

One writer per wallet limits speed for a single hot wallet. Most wallets are quiet, so the limit rarely binds.

Cross-shard payments pay the saga cost. Keeping popular paired wallets close is an operational choice, not a promise.

The design trades a little speed for a hard promise. No wallet goes below zero and every unit can be traced.

Wallet flows