Skip to content

How to design a digital wallet

The first sections are free. The deep dives, level expectations and quiz are part of Pro.

On this page
Practice this question

The problem

A digital wallet moves money between accounts inside one payments app: A pays B, A's balance goes down and B's goes up, and the two changes must stand or fall together. At a million transfers a second no single database keeps up, so balances are spread across shards by account id, and nearly all transfers touch two shards. The answer turns on two ideas: committing a transfer across shards without a lock that spans them, and recording each balance change as an immutable event so any past balance can be rebuilt and checked rather than taken on trust.

Clarifying questions

AskWhy it mattersA typical answer

How many transfers a second, and does each one touch two accounts?

The rate decides whether one database can hold the balances. If it can't, sharding is forced, and with it a transfer that crosses machines, which is where most of the difficulty lives.

A million transfers a second, each debiting one account and crediting another, so 2 million balance updates a second. Assume one relational node handles about 1,000 transactions a second.

Is a wallet-to-wallet move the whole scope, or do I also handle cards, banks and currencies?

Pay-in and pay-out involve third parties with their own failure modes and would take the whole round. Currency conversion adds a rate and a second ledger.

Wallet to wallet in a single currency. Cards, bank payouts and foreign exchange are out of scope.

What does transactional mean here: money is neither created nor lost, or also that nobody sees a half-finished transfer?

Conservation of money is a must. Hiding the in-between state is far more expensive and may not be needed, so it's worth pinning down before choosing how to commit across shards.

Money must not be created or lost in a transfer. A short window in which the sender's balance has dropped and the receiver's hasn't risen yet is acceptable, as long as it resolves.

Do we need to answer what a balance was at a past moment, with proof?

A current-balance table can answer today's balance. Proving a past one changes the storage model from a mutable row to a replayable history.

Yes. Auditors may ask for any wallet's balance at any past time and want to verify it, not just read it.

What availability do we promise, and may a transfer be delayed rather than refused when a node is down?

The target decides how many copies of the balance data we keep and whether the commit path may wait on a single machine.

99.99% availability. A transfer may take longer under failure, but a money move that was acknowledged must not be lost.

Do clients retry, and do they send an id with each transfer?

A retried transfer without an id can become a double payment unless something else deduplicates it. If the client sends a transaction id, the service can make a repeat harmless.

Yes. The transfer call carries a transaction_id chosen by the client, and the same id sent twice must move money once.

The requirements menu

RequirementScopeWhy

Transfer a balance from one wallet to another

Core

The product. Everything else in the round hangs off how one transfer gets committed when the two balances live on different machines.

See a wallet’s current balance

Core

The read that happens on each app open. It shapes where balance state lives and whether reads compete with the write path.

Rebuild any past balance by replaying history

Core

The audit requirement. It decides the storage model: a history of immutable changes rather than a row that is overwritten in place.

Treat a repeated transaction id as the same transfer

Optional

Take it: the API already carries a transaction_id, and a retry after a timeout is an easy way for a wallet to double-pay. It costs one lookup on the transfer path.

List a wallet's transfer history, newest first

Optional

Cheap once events exist, since the history is the event list filtered by account. Take it if time allows; mention that a read replica serves it so writes aren't slowed.

Reserve money now and settle it later (a hold)

Optional

Merchant flows need it, friend payments don't. Leave it unless asked; a hold is a third balance (available against total) and complicates the commit steps.

Notify the receiver when money arrives

Out of scope

A consumer of the event list, not part of the money path. Name where the event would be read from and move on.

Spending limits and velocity rules per account

Out of scope

It sits with fraud checks: a rule engine that runs before the transfer is accepted. Note that it would be a validation step on the command, then park it.

Foreign exchange

Out of scope

Adds a rate, a spread and a second currency ledger. The single-currency transfer is hard enough to fill the round.

Pay-in from cards and pay-out to banks

Out of scope

Those are the payment-system question: third parties, webhooks and reconciliation against external statements. Here money moves between wallets we own.

Fraud checks

Out of scope

A separate scoring system. Say that a transfer command could be held for a risk decision before it reaches the state machine, and leave it there.

Non-functional requirements

RequirementWhat it forces

1 million transfers a second

At about 1,000 transactions a second per relational node, 2 million balance updates need about 2,000 nodes, so the balances have to be split across shards by account id, and a transfer usually spans two shards. The transfer path has to work without a lock held across machines, and the stateless layer in front must scale sideways.

99.99% availability

That leaves about 52 minutes of downtime a year, so no shard's data may live on one machine: the event log of each shard is replicated with a consensus protocol, a leader failure is handled by election rather than a page, and a transfer in flight when a coordinator dies is finished or undone from a durable record.

Transactional: money is never created or lost in a transfer

Each transfer is a debit and a credit that end in the same state, done or undone. Across shards that means a protocol with a compensating step and a status record for each phase, with the debit first so money is not spendable in two places while the transfer is in flight.

Reproducible: the full history can be replayed to check every balance

Balance changes are recorded as immutable events rather than as updates to a row, and the code that applies an event to a balance must be deterministic: no clock, no randomness, no call to another system. A balance at any moment is then a replay, and a code change can be tested by replaying old events.

Estimates

QuantityWorkingResultWhat it sizes

Database nodes for the balance updates

A million transfers a second × two balance updates each = 2 million updates a second; 2,000,000 ÷ 1,000 per node = 2,000 nodes. At 100 a node: 20,000 nodes; at 10,000 a node: 200 nodes

About 2,000 relational nodes, between 200 and 20,000 depending on node speed

Why, at the node speeds assumed here (100 to 10,000 transactions a second), one database is out and sharding by account follows.

Load on one shard, and how often a transfer stays on one shard

2 million updates ÷ 2,000 shards = 1,000 updates a shard a second; a cross-shard transfer makes one update on each shard it touches, so about 1,000 transfers touch each shard a second. With accounts spread over 2,000 shards, the chance both parties share a shard is about 1 ÷ 2,000 = 0.05%

About 1,000 transfer touches a second per shard, and about 99.95% of transfers cross shards

What one shard's consensus group must accept per second, and why the cross-shard path is the normal path, not an edge case.

Events written a day

2 million balance changes a second × 86,400 seconds = 172.8 billion, about 173 billion a day; ÷ 2,000 shards = about 86 million events a shard a day

About 173 billion events a day, about 86 million per shard

How fast each shard's event log grows, and why a restart that replays from the beginning is not an option without snapshots.

Events a year, for the audit replay

173 billion a day × 365 days = about 63 trillion a year; per shard, 86 million × 365 = about 31 billion a year

About 63 trillion events a year across the system, about 31 billion per shard

The size of a replay that proves last year's balances were unchanged by a code change: run per shard, from a snapshot, in parallel.

Downtime that 99.99% allows

0.01% × 525,600 minutes a year ≈ 52.6 minutes a year; 0.01% × 43,200 minutes a month ≈ 4.3 minutes a month

About 52 minutes a year, about 4 minutes a month

How fast failover of a shard leader or a coordinator must be: automatic, within seconds, not a person paged.

Core entities

EntityWhat it holds

Account

One wallet. Its balance is state derived from events, kept materialized for fast reads.

Transfer command

A request to move money: an intent, not yet a fact. It may be refused.

Event

An applied debit or credit, immutable once written. The balance of an account is the sum of its events.

Phase status row

The coordinator's durable memory of one transfer: which steps are done, so a restart can finish or undo it.

The API

EndpointNotes

POST /v1/wallet/balance_transfer { from_account, to_account, amount, currency, transaction_id } → { status, transaction_id }

The client picks transaction_id and reuses it on a retry. The wallet service looks the id up first: a known id returns the recorded outcome without touching balances. Amount is an integer in minor units. In this design the response status is one of done, failed or pending; pending means the debit committed and the credit is still being applied, and the client polls or gets a push.

GET /v1/wallet/{account}/balance → { balance }

Served by a read replica of the account's shard, so reads don't compete with the state machine that commits transfers. It may trail the leader by the replication delay; say so when asked.

GET /v1/wallet/{account}/balance?at={time} → { balance } rebuilt from events

Loads the newest snapshot before the time, applies the shard's events up to it and returns the result. In this design the response also carries the event sequence the replay stopped at, so the caller can repeat the replay and get the same answer; that repeatability is the proof the auditors want.

The high-level design

transferdebit, creditClientWallet serviceShard A statemachine

Step 1 of 5

One service, one balance store

Start with the smallest thing that moves money. A stateless wallet service takes the transfer call, checks that the sender has the funds, and runs one database transaction that lowers one balance and raises the other. Balance reads go to the same store. The service holds no state, so it scales by adding instances. With a single database, a transfer is one local transaction and the hard problem doesn't exist yet. It can't stay this simple: one relational node handles about 1,000 transactions a second, and we need 2 million balance updates a second.

transferroutephasestryconfirmappendsnapshotreplicateapplyClientWallet servicePartition mapPhase statusShard A statemachineShard B statemachineEvent logSnapshotsFollowersRead replica
The whole design

What breaks first

The deep dives

A transfer across two shards. A pays B a dollar and the two balances live on different machines. What does the wallet service do on each shard, in what order, and how does the transfer end correctly if the service crashes between the debit and the credit?

A concept that helps here: Sagas and two-phase commitA concept that helps here: Sharding and partition keysA concept that helps here: Idempotency keys

Reproducible balances. Auditors want A's balance at noon last Tuesday and a way to verify it, not a number to trust. What does each shard record per transfer, how is a past balance rebuilt from it, and what happens when the node holding the records dies?

A concept that helps here: Event sourcing and ledgersA concept that helps here: Replication and read replicas

Concepts this guide uses

Sources

  1. Digital Wallet: key concepts and system design (notes on the digital wallet chapter of System Design Interview volume two)
  2. Wikipedia: Two-phase commit protocol
  3. microservices.io: Pattern: Saga
  4. Apache Seata documentation: TCC mode
  5. Apache Seata blog: Distributed transaction Seata and its three modes
  6. The Raft consensus algorithm (raft.github.io)
  7. Wikipedia: Raft (algorithm)
  8. Apache ZooKeeper: a distributed coordination service for distributed applications
  9. RocksDB wiki: Home
  10. Martin Fowler: Event Sourcing
  11. System Design Academy: Digital wallet system design interview
Sign in to report a mistake