System Design: [Digital wallet name]

Reference design for a stored-value digital wallet: customer balances, peer-to-peer and merchant transfers, top-ups and withdrawals. It covers a double-entry ledger as the source of truth, cross-shard transfers with a saga versus two-phase commit versus event sourcing, idempotency keys, hot-account contention, reconciliation with banks and payment providers, limits and KYC (know your customer) hooks, and the operational controls a regulated wallet needs. It follows the structure of the System Design Document template and is pre-filled with a worked design to adapt. Replace every [bracketed] value and every row marked Example; values marked Example are assumptions, not benchmarks. Regulatory notes describe a documentation format only. This is a documentation format, not legal advice.

Document control

Approvals

Revision history

Contents

1. Overview
2. Requirements
3. Capacity estimation
4. API design
5. Data model
6. High-level design
7. Detailed design
8. Scalability and performance
9. Reliability, security and operations
10. Trade-offs and alternatives
11. Delivery plan and risks
12. Appendices

1. Overview

1.1 Problem statement

[Example: Our app lets 50 million customers hold a balance, pay each other and pay 300 000 merchants. Balances live in a single relational table that is updated in place. Last quarter a retry storm after a database failover applied 1 900 transfers twice, and finance needed 11 days to find them because there was no ledger to replay. The largest merchant receives so many credits during lunch hours that its balance row became a lock queue and transfer latency reached 8 seconds. Compliance cannot show which limits applied to a given transfer at the time it ran.]

1.2 Proposed solution

[Example: An append-only double-entry ledger becomes the source of truth. A balance is a derived, cached projection of ledger entries per account, updated in the same transaction as the entries. Accounts are sharded by account ID. A transfer between two shards is a saga: debit the sender into an in-flight (suspense) account on the sender shard, then credit the receiver from the in-flight account on the receiver shard, with an outbox carrying the second step. Every request carries an idempotency key that is stored with the result. Merchant hot accounts are split into sub-balances. A limits and risk service runs before the debit and records the rule version it applied. Reconciliation runs continuously against internal invariants and daily against bank and provider statements.]

1.3 Decisions requested from reviewers

1.4 45-minute interview path

Pick 7.2 as the default deep dive. Mention 7.5 (reconciliation) even if there is no time to detail it: a wallet without reconciliation is not credible.

2. Requirements

2.1 Core functional requirements

2.2 Non-functional requirements and invariants

2.3 Below the line (out of scope)

• [Example: foreign exchange between wallet currencies (separate FX design)]
• [Example: card issuing linked to the wallet]
• [Example: credit lines and overdrafts]
• [Example: interest or yield on balances]
• [Example: the card acquiring ledger (see Payment Ledger System Design (system-design/design-payment-ledger))]
• [Example: fraud model internals (see Payment Fraud Detection System Design (system-design/design-fraud-detection))]
• [Item deferred, with the release that will take it]

3. Capacity estimation

3.1 Assumptions

3.2 Throughput

3.3 Storage

3.4 Contention

The largest merchant at 2 000 credits/s would serialise on one balance row. If a row update with commit takes Example 2 ms under lock, one row sustains at most about 500 updates/s, so the merchant needs at least 4 sub-balances; choose 16 to absorb bursts (7.4).

3.5 Summary

4. API design

4.1 Endpoints

4.2 Request and response examples

POST /v1/transfers
Idempotency-Key: 4b7e0a3c-1f2d-4c8e-9a51-6d2b8e0f7c33
Authorization: Bearer [token]
Content-Type: application/json

{"from_wallet": "wal_81aa", "to_wallet": "wal_19fe", "amount": {"value": 2500, "currency": "EUR"}, "note": "Dinner"}

HTTP/1.1 202 Accepted
Content-Type: application/json

{"transfer_id": "trf_5c02", "status": "pending", "amount": {"value": 2500, "currency": "EUR"}, "created_at": "YYYY-MM-DDThh:mm:ssZ"}

Amounts are integers in the minor unit of the currency. The API never accepts floating-point amounts. A same-shard transfer may return 201 with completed; a cross-shard transfer returns 202 and completes asynchronously (7.2).

4.3 Idempotency and errors

• The client generates a unique key per logical operation and reuses it on every retry. The server stores the key, a hash of the request body, the owning client and the final response for 7 days.
• The same key with the same body returns the stored response. The same key with a different body returns 422. A request that arrives while the first is still running returns 409 request-in-progress.
• Errors use RFC 9457 problem details with a stable type URI.

5. Data model

5.1 Entities

Account types: customer, merchant, in_flight (one per shard and currency), fees, bank_settlement (mirrors the safeguarding or partner bank account), provider_clearing (one per top-up and withdrawal provider).

5.2 Storage choices and invariants

5.3 Access patterns

6. High-level design

7. Detailed design

7.1 Double-entry ledger and balances

Every movement of value posts at least two entries whose amounts sum to zero in one currency. A transfer of EUR 25.00 from Alice to Bob on the same shard:

Rules:

• Entries are immutable. Corrections are new transfers that reference the original (FR-08).
• The balance column is a projection maintained in the same transaction as the entries. A nightly job recomputes balances from entries and alerts on any difference (NFR-01).
• A pending balance (holds for review, unsettled top-ups) is a separate account type, not a flag on entries, so available balance is always one read.

Options for the balance: compute on read from entries (always correct, slow for long histories); store a projection updated with entries (fast, needs a recompute check); store only snapshots plus recent entries (bounded read cost). Choice: stored projection plus monthly snapshots. Reason: AP-01 is the hottest path and must be one row read, while snapshots keep statements and audits cheap.

7.2 Deep dive: cross-shard transfers

About 98 percent of transfers cross shards (3.5). The sender debit and the receiver credit cannot share a local transaction.

Choice: saga through an in-flight account. Reason: it keeps the ledger balanced at every commit (the in-flight account carries the value), uses only local transactions, and fits the team's relational operating model. Event sourcing remains the path if throughput grows beyond what sharding can absorb (10).

• Step T2 deduplicates on event ID, so redelivery is harmless.
• The in-flight account per shard must net to zero once all sagas settle; a non-zero in-flight balance older than Example 5 minutes is an alert.
• The sender sees the debit immediately; the receiver sees the credit when T2 commits. The UI shows "sent" after T1 and "received" after T2.

7.3 Deep dive: idempotency

Choice: client-generated key stored in the sender shard in the same transaction as T1. Reason: the key and the debit commit or fail together, so a retry after a timeout finds either nothing (safe to apply) or the stored response (return it). Internal saga steps reuse transfer_id:step as their key, and calls to external providers pass a derived key so providers also deduplicate.

How real systems do it (paraphrased from a public write-up; not copied)

Stripe's engineering post on idempotency describes the client side of the contract: a client creates a unique key for each operation it wants to happen once, attaches it to every attempt, and on a network failure retries with the same key, so the server can answer with the result of the first attempt instead of acting again. The post also recommends retrying with exponential backoff plus random jitter so that many clients recovering from the same outage do not hit the server in lockstep. This design adopts both ideas: the wallet SDK owns key generation and the retry schedule, and the server treats the key as part of the transaction.

Source: Brandur Leach, "Designing robust and predictable APIs with idempotency", Stripe blog, 22 February 2017, https://stripe.com/blog/idempotency

7.4 Deep dive: hot accounts

Choice: sub-balances with Example 16 buckets for accounts flagged hot. Reason: credits never need to lock the whole account, debits (payouts) are rare and can lock all buckets briefly, and the ledger remains exact. An hourly sweep moves bucket balances into bucket 0 to keep reads cheap.

7.5 Reconciliation

Every break has an owner, an age and a resolution code. Resolution is always a new adjusting transfer approved by two people, never an edit.

7.6 Limits and KYC hooks

• Each wallet has a KYC tier. Each tier maps to a limit set (single transfer, daily, monthly, maximum balance). Limit sets are versioned configuration with an approver.
• The limits service is called synchronously before T1 with the wallet, amount and counterparty. It returns allow, deny(limit_id) or step_up(required_tier). The transfer records the limit set version (NFR-08).
• Risk scoring runs in parallel; a review verdict sends funds to a pending account instead of the receiver and opens a case.
• Sanctions screening and suspicious activity reporting are owned by compliance systems. The wallet emits events and accepts freeze orders (status frozen, error 423) through an authenticated internal API.

7.7 Regulatory notes (format only)

Record, for your jurisdiction, in your own words and with links to the current consolidated texts: the licence or programme under which balances are held; the safeguarding method for customer funds; KYC tiers and the evidence each needs; record retention periods; complaint and dispute handling duties; and the reports the reconciliation in 7.5 must feed. This section is a placeholder for that analysis, not the analysis itself.

8. Scalability and performance

Latency budget for a same-shard transfer (p99 target 400 ms):

9. Reliability, security and operations

9.1 Failure modes

Score these in a Software FMEA (ops/fmea-software) and rehearse FM-01 and FM-02 with a Chaos Experiment Plan (ops/chaos-experiment).

9.2 Security and abuse

Model the rest in a Threat Model (security/threat-model).

9.3 Observability

9.4 Cost estimate

10. Trade-offs and alternatives

11. Delivery plan and risks

11.1 Milestones

11.2 Migration and rollback

[Example: Run the new ledger in shadow mode, posting the same transfers as the old balance table and comparing balances hourly. Cut over wallets in cohorts by shard. Rollback for a cohort before cutover is a routing switch; after cutover, the old table is rebuilt from new ledger entries.]

11.3 Risks

12. Appendices

12.1 Traceability

12.2 Open questions

12.3 Glossary

12.4 References

Standard and licence note

Based on common industry practice for double-entry ledgers and stored-value wallets and on the public references in 12.4. Books and company blogs were used as inspiration only; the text, diagrams and numbers are original and illustrative. The Idempotency-Key header field is an IETF draft, not a published RFC. Regulatory content is a documentation format, not legal advice: check the current consolidated texts and licence conditions for your jurisdiction. Template licence: MIT.