System Design: UPI Platform (Walnut Switch: Routing, Deemed Payments, Net Settlement for 741 Banks)
Goal: Design the system in the middle of UPI (Unified Payments Interface), India's system for instant bank-to-bank payments. In the real UPI, NPCI (National Payments Corporation of India) runs it. We build our own version, Walnut Switch, for 741 banks, about 802 million payments a day and up to 40,000 a second. We also design how a bank's own UPI system plugs in.
Walnut Switch is not WalnutPe or Walnut Pay, the payer's app and the shop gateway from our other posts (section 1.5).
1. What We Are Building
🔒 Premium section
2. Requirements and Scale
2.1 What the System Must Do
Each FR (functional requirement) is something the system must do.
The switch
| ID | Requirement |
|---|---|
| FR-01 | Take pay requests from payer PSP banks and route them (section 6). |
| FR-02 | Find the payee's account through the payee's PSP bank, or a central directory for phone-number IDs (section 14). |
| FR-03 | Run the debit (take money out), then the credit (put money in), inside NPCI's time limits (section 6). |
| FR-04 | No debit answer: undo it. No credit answer: mark it "deemed approved" and wait for the bank to confirm or return the money (section 8). |
| FR-05 | Answer status checks ("what happened to this payment?") inside NPCI's limits (section 8). |
| FR-06 | Reject repeats: the same transaction id (the payment's unique id, made on the payer's side) from the same payer PSP gets the saved answer (section 9). |
| FR-07 | Route other messages: name checks (validate address), balance checks and the daily list of public keys (section 4). |
| FR-08 | Settle: 10 settlement cycles a day for payments and 2 for disputes, one net amount per bank, and a file per bank (section 10). |
| FR-09 | Cap what each bank can owe inside one cycle; decline at the cap with NPCI's code U03 (section 10). |
| FR-10 | Route complaints, and decide chargebacks (returns forced by a complaint) from the banks' confirmations (section 8). |
| FR-11 | Measure each bank's technical and business declines; publish them monthly (section 15). |
| FR-12 | Score each payment for fraud with signals from all apps and banks (section 14). |
The bank side
| ID | Requirement |
|---|---|
| FR-13 | The bank's UPI switch answers fast, checks the PIN in an HSM and posts debits and credits to the core (section 11). |
| FR-14 | Keep UPI working while the core is down (stand-in); store and forward reversals (section 12). |
| FR-15 | Reconcile daily: match the switch's, the bank switch's and the core's records (section 11). |
| FR-16 | Sign up merchants as their acquiring bank (the bank that holds the merchant contract, section 3.1) and answer lookups for their UPI IDs (section 11.8). |
| FR-17 | Act on fraud alerts with a lien (a hold on one amount), a debit freeze (nothing goes out) or a full freeze (nothing goes in or out), and keep accepting credits unless the account is fully frozen or closed (section 11.9). |
2.2 How Well It Must Do It
An SLO (service level objective) is a target we set and measure monthly. p50 is the time half of all requests beat, and p99 the time 99 of every 100 beat, so p99 shows the slow tail.
- NFR-01. Our part is fast. The switch's own work, without bank time, is under 1 s for a typical payment (section 6).
- NFR-02. Never pay twice. One transaction id from one payer PSP is debited at most once.
- NFR-03. Never lose a payment. Every state change is copied to its copy site, one of the other two sites (section 5.2), before the switch sends anything for that payment.
- NFR-04. Contain bank problems. A slow or dead bank must not raise failures for payments that don't touch it.
- NFR-05. Stay up. 99.99% a month for the payment path, about 4.3 minutes of failure (our SLO). Losing one of three sites must not stop payments.
- NFR-06. Recover in time. RTO (recovery time objective) is how long a part may stay down; ours is under an hour for any critical part, NPCI's published figure for its own. RPO (recovery point objective) is how much recent data may be lost; ours is zero for any change the switch has acted on, as long as one of its two copies survives (section 17.2).
- NFR-07. Settle exactly. Every payment lands in exactly one cycle, and all banks' net amounts add up to exactly zero.
- NFR-08. Keep declines low. RBI's targets are TD under 1% and BD under 5% (2022). The switch's own share of TD should be near zero.
- NFR-09. Safe and in India. Signed messages, private links, payment data kept in India (RBI, 6 April 2018).
2.3 The Numbers
These are planning numbers. Section 16 does the full sizing.
Payments.
- Per day. About 802 million (September 2026).
- Average. 802,000,000 / 86,400 seconds is about 9,300 a second.
- Evening peak. About 3 times the average, about 28,000 a second (our planning estimate, not an NPCI figure).
- Design target. 40,000 a second, for festival evenings and salary days. Our payer app plans for 10,000 a second at 25% of UPI, which implies about 40,000 for the whole network.
Messages, bytes, records. About 10 messages per payment (section 3.7), so about 400,000 a second at the design target, each with an ack (a short receipt, section 3.3). Each message is about 3 KB of XML, the text format of the messages (section 3.3; our planning number, as sizes are not public). That makes about 10 Gbps (billion bits a second) across all bank links.
Records kept in memory for the 2-hour status-check window (apps asking "what happened to this payment?") need about 66 GB per copy at the design target. Durable rows need about 130 GB a day. One settlement cycle holds about 80 million payments.
Banks. 741, very uneven. In July 2025 SBI sent about 27% of all debits, and Yes Bank received about 41% of all credits. (SBI report via Business Standard; the shares are our arithmetic.) (Section 13 shows what this does to credits.) So each bank gets its own connections and limits.
2.4 Out of Scope
- The payer's app. WalnutPe, in the payer app post: device binding, the PIN screen, the app's status schedule.
- The merchant gateway. Walnut Pay, in the gateway post.
- The inside of RTGS, RBI's system that moves money between banks. We send it one amount per bank per cycle (section 3.6). How RBI runs it is not our design.
3. How UPI Moves Money
🔒 Premium section
4. The Messages and the Data
🔒 Premium section
5. High-Level Design
🔒 Premium section
6. Deep Dive: One Payment Through the Switch
🔒 Premium section
7. Deep Dive: When a Bank Is Slow or Down
🔒 Premium section
8. Deep Dive: Deemed Approved, Reversals and Status Checks
🔒 Premium section
9. Deep Dive: The Transaction Store
🔒 Premium section
10. Deep Dive: Settlement and Netting
🔒 Premium section
11. Deep Dive: The Bank Side
🔒 Premium section
12. Deep Dive: Core Banking Downtime and Stand-in
🔒 Premium section
13. Deep Dive: Hot Accounts and Uneven Banks
🔒 Premium section
14. Deep Dive: Address Resolution and Network-Level Risk
🔒 Premium section
15. Deep Dive: Peaks and Bad Days
🔒 Premium section
16. Capacity
🔒 Premium section
17. What Happens When Each Part Goes Down
🔒 Premium section
18. Bottlenecks
🔒 Premium section
19. Sites and Data
🔒 Premium section
20. Security
🔒 Premium section
21. Running It
🔒 Premium section
22. Options We Did Not Pick, and When They Are Right
🔒 Premium section
23. In the Interview
🔒 Premium section
24. How We Measured
🔒 Premium section
25. Further Reading
🔒 Premium section
Explore the Technologies
🔒 Premium section