System Design (High-Level Design) Module 27 – Case studies: payments, money and markets
Design an online payment gateway
Design a payment gateway: merchant APIs for orders, payments, captures and refunds, routing across acquiring banks, signed webhooks and card tokens.
What you will learn
- Design merchant APIs for orders, payments, captures, refunds and webhooks
- Route payments across methods and acquiring banks by their recent approval rates
- Isolate card numbers from the merchant's systems with hosted fields and tokens
- Estimate attempt rates, webhook deliveries and storage for a gateway
Before you start
What you’ll learn · Before you start
What you will learn
- Design merchant APIs for orders, payments, captures, refunds and webhooks
- Route payments across methods and acquiring banks by their recent approval rates
- Isolate card numbers from the merchant's systems with hosted fields and tokens
- Estimate attempt rates, webhook deliveries and storage for a gateway
Before you start
On this page
A payment gateway lets a merchant accept cards, bank-app payments, net banking and wallets, four kinds of network that each work differently, through one integration. The merchant’s server creates an order, and the shopper pays on a checkout page or card fields that the gateway hosts, so card numbers never touch the merchant. The gateway’s payment service turns each attempt into the request its network expects: a card authorisation through an The bank that a merchant's card payments go through: it connects the merchant, or its gateway, to the card networks, and pays out the captured payments., a request to a bank payment network, or a redirect to net banking. Card payments are authorised first and captured later, and a refund is a new transaction against a captured payment. Every write the merchant sends carries an idempotency key: A unique id that a client chooses once for an operation and sends with every attempt of it. The server stores the result under the key, so a repeat gets the stored result instead of a second charge or write. More in “How distributed systems fail”, every outcome reaches the merchant as a signed webhook that is retried until it is received, and a router spreads payments across acquiring banks by their recent approval rates, moving traffic away from one that starts to fail.
One API in front of networks that each work differently
What a gateway sits between
Merchants are on one side, and on the other are networks that each work differently: card networks reached through acquiring banks, real-time bank payments, net banking and wallets. Each has its own messages, timeouts and ways to fail:
| Method | What the gateway sends |
|---|---|
| Cards | An authorisation through an acquiring bank, captured later |
| Bank-app payments | A request to the bank payment network |
| Net banking | A redirect to the shopper’s bank |
| Wallets | A request to the wallet provider |
The gateway hides them behind one API and one state machine per payment, so a merchant integrates once, whichever methods its shoppers use. It also handles card numbers that nobody else should ever see.
Checkpoint
Check: What the gateway sits between
Requirements
Merchants create orders, take payments by several methods, capture authorised card payments, refund in full or in part, and receive every outcome as a webhook they can verify. No payment or refund happens twice, whatever is retried. Merchants never store card numbers, and the gateway keeps them in one vault. Payments keep flowing when an acquiring bank degrades, and payouts and the gateway’s books are reconciled every day against the acquirers’ reports. Ask first which payment methods and countries are in scope, whether the gateway holds merchants’ money or only routes it, and how soon merchants must be paid.
Estimates
Assume 20 million payment attempts a day with 12 % of them in the busiest hour, 80 % of attempts succeeding with 3 webhooks each, a 4 KB record per attempt kept in 3 copies, card payments as half of all attempts, and one acquiring bank, carrying 40 % of the card payments, whose approvals fall from 92 % to 60 %. Work out each figure first:
Checkpoint
Check the estimates
| Quantity | Result |
|---|---|
| Attempts a second, busiest hour | about 667 |
| Webhook deliveries a second | about 1,600 |
| Records a year, in 3 copies | about 88 TB |
| Extra declines a minute, one bank degraded | about 2,560 |
The volume is moderate; correctness and routing are the hard parts.
The first design
The merchant’s server talks to the gateway API, and the shopper talks to the hosted checkout, whose card fields send the card number only to the token vault. The diagram shows every part, top to bottom; only the vault’s box ever holds a card number:
The first design of an online payment gateway
Text description of the diagram
The diagram shows the gateway's parts from top to bottom.
- The merchant's server calls the gateway API to create orders, capture payments and refund them, with an idempotency key on every write.
- The shopper's browser or app pays on the gateway's hosted checkout, whose card fields send the card number only to the token vault, which never lets it out. The checkout passes a token to the payment service.
- The payment service keeps one state machine per payment and an outbox of events. It asks the router where to send each attempt; the router chooses by each acquirer's approvals over the last 60 seconds and sends the authorisation to the acquiring banks, card networks and bank payment networks.
- The payment service's events go to the webhook sender, which signs them and retries them; a dashed arrow shows the outcomes reaching the merchant's webhook endpoint.
The payment service receives a token, keeps one state machine per payment and asks the router where to send the authorisation. Every change writes an event to an outbox, and the webhook sender signs each event and delivers it to the merchant’s endpoint until it is acknowledged. Step through one card payment, from the order to the webhook:
The drawing shows the whole scene; its 8 steps are listed below.
Every step as text
- The order. The merchant's server creates an order for 1,000 through the gateway API, with an idempotency key on the request.
- The shopper pays. The shopper pays on the checkout page that the gateway hosts, with card fields that the gateway serves.
- The card number. The card fields send the card number only to the token vault. The merchant's pages and servers never see it.
- A token instead. The payment service receives a token, not the number, and starts the payment's state machine.
- Where to send it. The payment service asks the router which acquiring bank to use. The router chooses by each bank's recent approval rate.
- Authorised. The authorisation goes to the chosen acquiring bank and on to the card's network. The payment is authorised now and captured later.
- An event for every change. The change of state writes an event to an outbox, and the webhook sender takes it from there.
- The merchant hears. The webhook sender signs the event and delivers it to the merchant's endpoint, retrying until the endpoint acknowledges it.
Checkpoint
Check: The first design: one card payment
The deep-dive questions
- Which resources and states does the merchant API expose, and how is every write safe to retry?
- How do authorisation and capture work for cards, and what happens to an authorisation that is never captured?
- How are payments routed across acquiring banks, and how does the router notice one that degrades?
- How are card numbers kept out of the merchant’s systems and most of the gateway’s?
- How do outcomes reach merchants so they can trust them, and how are refunds kept from paying twice?
- What breaks at 10× and 100×, and which designs are rejected?
The merchant API moves each payment through a few states, and each write happens once Pro: opens with a Pro, Premium or Ultimate pass
In this part:
- Resources, states and the moves the API allows
- Every write safe to repeat, tested with duplicates
- Authorise, then capture, before the hold lapses
- Route by the last minute of approvals, and retry only the acquirer’s own failures
- Card numbers go to one vault, and everything else carries a token
- Webhooks merchants can trust are signed, deduplicated and never move a payment back
- Settlement pays each merchant the net, and a chargeback is a workflow of its own
- At 10× the key store gives way first, and at 100× one payment database
- Failure drills: five faults the gateway must survive
- Options considered and rejected
- What each level covers, and a 45-minute self-mock
- What each level is expected to cover
- A 45-minute self-mock
- Practise: route by the last minute, then the whole design
- Route card payments by each acquirer's last minute
- Interview questions
- One of your three acquiring banks carries 40 % of card payments. Within five minutes its approval rate falls from 92 % to 60 %, then recovers an hour later. Design routing that moves traffic away quickly, recovers the bank's share afterwards, does not swing traffic back and forth, and never charges anyone twice.
- A merchant wants one-click repeat payments, and its developers plan to keep customers' card numbers, encrypted, in their own database. What do you tell them, what should the merchant and the gateway store instead, and how does the choice change what each of them must protect?
- A support agent and an automatic returns job refunded the same order within a second of each other, and the customer received twice the amount paid. Both requests had idempotency keys. Explain why the keys did not help, and design refunds so this cannot happen.
- Key takeaways
5 diagrams · 3 runnable examples (JavaScript, Python) · 1 exercise with sample tests · 3 interview answers · about 50 minutes
Opening this part with your pass…
This part opens with any MySmartCoPilot pass.
- Pro pass · 1 week₹79$2.99
- 30 days₹179$5.99
- 1 year₹1,699$45
One payment; a pass never renews. The price shown is the total you pay: no fees or charges are added at checkout.
Passes can’t be bought right now, so this part can’t be opened at the moment. The free part above stands on its own. If you have a pass, enter your licence key.
It also opens every other in-depth part in Learn and every Pro tool. Sales are final, except where the law gives you a right to withdraw, for example in the EU and the UK (refund policy).
Read a complete sample first: Design movie seat booking like BookMyShow
References
- Idempotent requests (API reference) (Stripe)
- Place a hold on a payment method (separate authorisation and capture) (Stripe)
- Payments, payment states (Razorpay)
- Standard Webhooks specification (Standard Webhooks)
- PCI Data Security Standard (PCI DSS) (PCI Security Standards Council)
- Tokenisation, card transactions: permitting card-on-file tokenisation services (Reserve Bank of India)
- Restriction on storage of actual card data (card-on-file) (Reserve Bank of India)
- Guidelines on regulation of payment aggregators and payment gateways (Reserve Bank of India)
Related tools
Report a problem with this lesson
Kept only in this browser. Your Learn progress