Designing a Digital Wallet System

A digital wallet stores funds and enables transfers between users and merchants.

Core Features

• Top up wallet from bank/card
• Transfer to another user
• Pay merchants
• Withdraw to bank
• Transaction history
• Multi-currency support

Data Model

wallets(
  id, user_id,
  balance      DECIMAL(18,8),  -- Precise decimal
  currency     VARCHAR(3),
  status       ENUM('active', 'frozen', 'closed')
)

transactions(
  id, from_wallet_id, to_wallet_id,
  amount, currency, exchange_rate,
  type,    -- topup, transfer, payment, withdrawal
  status,  -- pending, completed, failed, reversed
  idempotency_key UNIQUE,
  created_at
)

Double-Entry Accounting

Every transaction has two entries:

-- Alice pays Bob $50
BEGIN TRANSACTION;
  UPDATE wallets SET balance = balance - 50
  WHERE id = alice_wallet AND balance >= 50;  -- Debit

  UPDATE wallets SET balance = balance + 50
  WHERE id = bob_wallet;                       -- Credit

  INSERT INTO transactions(...);
COMMIT;

If debit fails (insufficient funds), entire transaction rolls back.

Currency Handling

NEVER use floating point for money!
USE: DECIMAL(18, 8) or store as smallest unit (cents)

Currency conversion:
  amount_in_usd = amount_eur × exchange_rate
  Lock exchange rate at transaction creation
  Store both original and converted amounts

KYC (Know Your Customer)

Tier 1: Email only → $100/day limit
Tier 2: ID verified → $1000/day limit
Tier 3: Enhanced due diligence → Unlimited

KYC checks: ID scan → Biometric → Sanction list

AML (Anti-Money Laundering)

Report to FinCEN:
  Cash transactions > $10,000
  Suspicious patterns (structuring below $10K)
  Transactions with sanctioned entities

Velocity rules:
  > 50 transfers/day → Flag for review
  Sudden large deposits → Enhanced monitoring

Conclusion

Wallet systems require DECIMAL precision, double-entry accounting, ACID transactions, and regulatory compliance (KYC/AML) from day one.