Design a Digital Wallet System

Double-Entry Ledger: The Foundation

Next we walk through each box on the diagram. I start with double-entry ledger invariants because every flow (top-up, P2P, and withdrawal) must balance debits and credits.

Double-entry is non-negotiable for money systems; explain why SUM(entries) = 0 is your self-check before your interviewer asks about reconciliation.

Every money movement creates balanced debit and credit entries. This is the same invariant explored in Banking Ledger System, but scoped to user wallets rather than a full chart of accounts. The wallet service owns user-facing balances; platform fee and external-bank accounts are internal ledger accounts.

Every transaction creates TWO ledger entries:
  Debit from one account, Credit to another. Sum of all entries = 0.

P2P Transfer: Alice sends $50 to Bob
  Entry 1: Alice's wallet DEBIT  -$50
  Entry 2: Bob's wallet   CREDIT +$50
  Sum: 0 (Balanced)

Top-up: Alice adds $100 from bank
  Entry 1: Alice's wallet  CREDIT +$100
  Entry 2: External_bank   DEBIT  -$100
  Sum: 0 (Balanced)

Merchant Payment: Alice pays $25 to Merchant M
  Entry 1: Alice's wallet      DEBIT  -$25
  Entry 2: Merchant M's wallet CREDIT +$24.25
  Entry 3: Platform fee account CREDIT +$0.75 (3% commission)
  Sum: 0 (Balanced)

Why double-entry? Self-validating (SUM=0), complete audit trail, regulatory requirement, reconciliation.

Atomic Balance Update: Preventing Double-Spend

P2P transfers need SERIALIZABLE isolation or SELECT FOR UPDATE, because interviewers will ask how you prevent double-spend under concurrent requests.

Critical: Two concurrent requests to spend Alice's last $50

Solution: PostgreSQL serializable transaction + row lock:

BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE;
  SELECT balance FROM wallets WHERE user_id = 'alice' FOR UPDATE;
  IF balance >= 50 THEN
    UPDATE wallets SET balance = balance - 50 WHERE user_id = 'alice';
    INSERT INTO ledger_entries (wallet_id, type, amount, ...) VALUES (...);
  ELSE
    RAISE 'Insufficient funds';
  END IF;
COMMIT;

Idempotent Transactions

Idempotency keys are non-negotiable at 50M transactions/day: walk through Redis fast-path, UNIQUE constraint, and FOR UPDATE as three defense layers.

User clicks "Send $50" but network timeout. Client retries.

Every API call includes idempotency_key (generated client-side per action):
  POST /api/v1/wallet/transfer
  Idempotency-Key: "txn-uuid-abc-123"
  { "to_user_id": "bob", "amount": 50.00 }

Server:
  1. Check: SELECT * FROM transactions WHERE idempotency_key = 'txn-uuid-abc-123'
  2. If not exists -> process transfer -> store result with idempotency_key
  3. Redis: SET idempotency:{key} {result} EX 86400

Three layers of defense: (1) Redis fast-path < 1ms, (2) PostgreSQL UNIQUE constraint, (3) Application-level FOR UPDATE within transaction.

Multi-Currency Wallet

User can hold balances in multiple currencies (USD, EUR, GBP, INR). wallet_balances table has ONE row per (user_id, currency) pair. Cross-currency transfers use FX rate service cached in Redis with 30s TTL.

Settlement and Reconciliation

Daily batch process: Net position calculation, bank settlement via ACH/SEPA, reconciliation matching bank confirmations against ledger, merchant settlement weekly/daily.

Event Bus Design (Kafka)

Topic: txn-events
  Partitions: 256
  Partition key: wallet_id (preserves per-wallet transaction ordering)
  Retention: 30 days (compliance + replay)
  Replication factor: 3, min.insync.replicas: 2

Producer: Transactional outbox (same DB txn as ledger INSERT; never direct publish)
  Event: { txn_id, wallet_id, type, amount, currency, counterparty_id, balance_after, timestamp }

Consumer groups:
  1. notification: email/SMS/push on every balance change
  2. fraud-detection: velocity, geo-anomaly, mule network scoring
  3. analytics: ClickHouse txn volume trends
  4. kyc-aml: sanctions screening on large transfers
  5. settlement: daily batch net positions to bank gateway

Sync path: double-entry ledger INSERT + outbox row in single ACID txn < 100ms
Async path: outbox poller publishes to Kafka; consumers at-least-once + idempotent
DLQ: txn-events-dlq; alert if outbox unpublished rows > 1000