System Design

Digital Wallet

Design a stored-value digital wallet like Apple Cash or Paytm.

Functional requirements

• Users can top up their wallet balance from a linked card (e.g., add $50 from a Visa ending in 4242) and see the new balance immediately.
• Users can pay a merchant or another wallet user from their balance; a payment larger than the available balance is rejected.
• Users can view their current balance at any time.
• Users can view a chronological transaction history (top-ups, payments, refunds) with amount, counterparty, time, and status.
• Merchants can refund a completed payment in full back to the payer's wallet balance.

Non-functional requirements

• Payments are the critical path: p99 under 300ms for a balance payment and under 100ms for a balance read; a card top-up may take up to 3s because of the external processor call.
• Correctness over availability: a balance must never go negative and no payment or top-up may be applied twice, even under client retries, double taps, or two devices acting on one wallet; rejecting a payment during a store outage is acceptable, applying it twice is not.
• Balance reads must reflect every payment and top-up already acknowledged to that user; history may lag by a few seconds.
• Acknowledged transactions are durable and immutable: no completed payment or top-up may be lost or edited later, and history is retained for 7 years.
• Card numbers are tokenized by the processor and never stored in the wallet service; only the token and last four digits are kept.

Scaling & constraints

• 20M wallets, 5M monthly active; ~400 payments per second at peak, ~80/sec average.
• Read:write ratio is roughly 10:1 (balance checks and history views vs. payments and top-ups).
• Each transaction record is ~300 bytes; an active wallet averages ~40 transactions per month, so ~200M new records per month.
• History is retained for 7 years; transaction volume grows ~30% per year.
• Traffic is bursty: peak is ~5x the daily average on paydays and evenings; no single wallet sees more than a few operations per minute, but mobile clients retry the same request 2-3 times on flaky networks.
• The external card processor for top-ups has p50 latency of 400ms, p99 of 3s, and ~0.5% of calls time out, some after the card was actually charged.

Out of scope

• User onboarding, identity verification, and card enrollment.
• Fraud detection and risk scoring.
• Bank withdrawals, cash-out, and merchant settlement or payouts.
• Multi-currency and foreign exchange.