Loading…

The decisions that matter

One key per payment attempt, unique per merchant in the database.Retries get the first answer instead of a second charge.
Unknown, not failed, when the bank goes quiet.The resolver asks or cancels by your reference, so money is neither taken twice nor kept.
A card zone with tokens everywhere else.A leak anywhere outside the zone exposes no card numbers.
Captures bounded by the hold, refunds bounded by captures.The shopper pays exactly what she agreed to.
A short critical path; everything else from the saved payment.A side system’s outage doesn’t stop checkout.

Architecture diagramThe final design at a glance

Card numbers stay in the card zone; a payment and its request key are saved before any bank call; everything else (events, the resolver, settlement) runs from the saved record. Dashed lines are asynchronous.

Diagram as text

Components: Shopper’s browser (Client); Card service: locked-down zone (Service); Risk service (Service); Merchant server (Client); Payments API (API gateway); Payment service (Service); Acquirer connectors (Service); Acquirers, networks, issuers (External API); Event sender (Worker); Payments DB: payments, keys, attempts (SQL DB); Resolver: unknown outcomes (Worker); Settlement and ledger hand-off (Worker). Connections: Shopper’s browser → Card service: locked-down zone (card details); Shopper’s browser → Merchant server (card token); Merchant server → Payments API (create, capture, refund); Payments API → Payment service; Payment service → Risk service (risk check, time-limited); Payment service → Acquirer connectors (authorize); Acquirer connectors → Acquirers, networks, issuers (authorize, capture); Payment service → Payments DB: payments, keys, attempts (payment + key, first); Payments DB: payments, keys, attempts → Event sender (outbox), asynchronous; Event sender → Merchant server (signed events), asynchronous; Resolver: unknown outcomes → Acquirer connectors (ask or cancel by our reference), asynchronous; Acquirers, networks, issuers → Settlement and ledger hand-off (report and deposit), asynchronous.

Understanding the problem

A payment gateway sits between online shops and the card networks. A shop’s server asks it to charge a card; the gateway sends the request through an acquiring bank and the card network to the shopper’s bank, which decides. Around that call sit the hard parts: retries that must not charge twice, banks that don’t answer, card numbers that must not leak, holds that become charges, the shopper’s bank check, and paying shops what they are owed.

The practice brief states the requirements up front; confirm them in the first few minutes. The core is one payment from the checkout page to the shopper’s bank and back.

Functional requirements

CoreShops take card payments from their own checkout page through your API.
CoreA shop can take the money at once, or hold it at checkout and take it later, while the hold lasts.
CoreShops can cancel a held payment, and refund a payment in full or in part.
CoreShoppers can save a card with a shop and pay with it next time.
CoreWhen the shopper’s bank asks them to confirm a payment, they can do it with a code or their banking app.
CoreShops learn the outcome of every payment, and are paid what they are owed into their bank account.
Below the lineDisputes and chargebacks.A separate lifecycle owned by the books; the payment-system solution covers it.
Below the lineIn-person (card-present) payments.
Below the lineDashboards and reports for shops.Read models built from events, off the payment path.
Below the lineBank transfers, UPI, netbanking and wallets.Different rails with their own timing; the same principles apply.

Non-functional requirements

ConsistencyA shopper is never charged twice for one payment, however often the shop’s server retries.
ConsistencyA payment is never written off as failed while the shopper may have been charged: any early answer keeps being checked, and money taken without a payment always goes back.
LatencyThe shopper gets an answer within a few seconds of paying, apart from their bank’s own confirmation step.
SecurityCard numbers are protected to the card industry’s security standard (PCI DSS); a leak would be catastrophic.
QualityShops learn the final outcome of every payment, even if the shopper closes the browser.
Consistency

Scale

From the briefNumbers here are given in the practice brief.

ScaleAbout 1 million shops, from tiny ones to large marketplaces.
ScaleAbout 100 million card payments a day; on big sale days, peaks of about 10 times the average.
ScaleMost banks answer in a second or two; some answer late, and some never do.
ScaleSeveral acquiring banks in each region.

Out of scope

Out of scopeHow the risk service scores a payment.
Out of scopeConverting currencies.
Out of scopeSigning up and checking shops (onboarding).

Check yourself

Shops’ servers retry requests that time out. Why can’t the gateway simply ignore a request that looks like a recent one?
Show answerHide answer
Because “looks like” isn’t identity: a shopper may honestly buy the same thing twice, and two copies of a retry can both look new at the same moment. Only a key the merchant chose for one payment attempt says “this is the same request”.

The numbers that shape the design

Illustrative exampleNumbers here are illustrative: round figures to reason with, not measurements.

Work out only the numbers this design depends on, with one line of working each. The bank’s reply time is the assumption to say out loud.

Back of the envelope for the gateway

Quantity	Value	Working
Payments	About 1,200 a second; about 12,000 at a sale peak	100 million a day ÷ 86,400; ten times on a sale day, from the brief.
Calls waiting on banks	About 24,000 at the peak	12,000 a second × about 2 seconds per answer.
When banks slow down	About 240,000	The same rate × 20 seconds: why timeouts and breakers matter.
Events to merchants	About 3,600 a second	About three outcomes per payment.
New payment data	About 500 GB a day	About 5 KB per payment with its attempts and history.

What the numbers tell you

The payment rate is modest for a database.
Calls waiting on banks are what grow, so the bank leg needs time limits.
Every rupee must add up, so the money paths need strict checks.

Read:Learn: Numbers and capacity estimation

Try it: The numbers that shape the designGuided practice · Payment gateway, Card payments for online merchants · Senior

Check yourself

Which number sizes the connections to each acquirer?
Show answerHide answer
Calls waiting on banks: the payment rate times how long a bank takes to answer. It grows tenfold when banks slow down, even if the payment rate doesn’t change.

Core entities

Start from the reads: a merchant listing today’s payments, support tracing one payment, finance adding up a day. Amounts are whole numbers of the smallest unit with a currency (for example, ₹1,299.50 is 129950 paise), so totals don’t drift with rounding.

The records that matter

Record	Key fields	Why it exists
Payment	`payment_id`, `merchant_id`, `amount_minor`, `currency`, `status`, card token	The money and where it stands.
Request key	`merchant_id`, `key`, request hash, saved response	Recognises a retry; unique per merchant.
Attempt	`attempt_id`, `payment_id`, acquirer, our reference, response code	One row per request to a bank, for status checks and cancels.
Refund	`refund_id`, `payment_id`, `amount_minor`, `status`	Its own record; refunds in total stay within the capture.
Status change	`payment_id`, time, from, to	The trail support and finance read.
Saved card	card token, brand, last four, expiry	Everything outside the card zone holds only this.

Where each kind of data lives

Data	Store	Why
Payments, keys, attempts, refunds	A transactional database split by merchant: PostgreSQL, MySQL or Spanner	A payment and its key, or a refund and its total check, change together.
Card numbers	The card zone’s own store, encrypted with keys from a hardware key store	Nothing else may hold them.
Events and reports	An outbox table, then a log or warehouse	Off the payment path.

Architecture diagramPayments, their attempts and refunds, and where card numbers live

Read:Learn: Data model design Learn: PostgreSQL

Try it: Payments, attempts and refundsGuided practice · Payment gateway, Card payments for online merchants · Senior

Check yourself

Why is a refund its own record rather than an edit to the payment?
Show answerHide answer
The payment then keeps what happened, refunds can be partial and several, and the total of refunds, pending ones included, can be checked against the capture in one transaction.

The API

A small, stable surface that thousands of merchants code against. Every call that moves money carries an Idempotency-Key. A declined card is answered as a decline with the bank’s reason (a 402 in Stripe’s API, which uses it when parameters were valid but the request failed (Stripe API reference (opens in a new tab))), not as a bad request. The gateway also calls the merchant: each change to a payment becomes a signed event, sent until the merchant’s endpoint accepts it.

The calls a merchant’s server makes

Call	Request	Response	Errors
`POST /v1/payments`	amount, currency, card token, order id, now or later, key	payment id, status	`400`, `401`, `402`, `409`, `429`
`POST /v1/payments/{id}/capture`	amount (optional), key	status	`400`, `404`, `409`
`POST /v1/payments/{id}/cancel`	key	status	`400`, `404`, `409` once captured
`POST /v1/payments/{id}/refunds`	amount, key	refund id, status	`400` over the captured total, `404`
`GET /v1/payments/{id}`	none	the payment, refunds included	`404`
`GET /v1/payments?order_id=…`	none	the payments for that order	`400`
`POST /v1/customers/{id}/cards`	one-time card token from the checkout fields	card token, brand, last four	`400`, `402`

Architecture diagramTelling the merchant: an event written with the change

Read:Learn: API contract design Learn: Idempotency and retries

Try it: The API merchants callGuided practice · Payment gateway, Card payments for online merchants · Senior

Check yourself

A merchant gets an error back. How does it know whether to ask for another card, fix its code or try again?
Show answerHide answer
From the answer’s type: a decline with the bank’s reason means ask for another card; a 400 means fix the request; a 429, or a 409 while the first copy runs, means try again later with the same key. A server error is ambiguous: retry with the same key, and if the same error comes back, look the payment up by its order id before trying anything new.

High-level design

Build the design one flow at a time; the deep dives then harden the parts an interviewer pushes on.

Pay with a new card

The gateway doesn’t approve cards: the shopper’s bank does. The gateway records the payment, checks its risk, and reaches the bank through an acquirer and the card network.

The shopper types her card into fields the gateway serves on the checkout page; the card service returns a card token.
The merchant’s server creates the payment with the token and the amount, sending its key.
The payment service saves the payment and the key, then runs the risk check.
An acquirer connector sends the authorization; the acquirer passes it over the network to the shopper’s bank, which approves and holds the money.
The payment becomes authorized, and the merchant gets the answer.

Architecture diagramPay with a new card: the path to the shopper’s bank

The shopper’s bank decides; the PSP records the payment, checks its risk, and reaches the bank through an acquirer and the card network.

Diagram as text

Components: Shopper’s browser (Client); Card service (Service); Risk service (Service); Card network → shopper’s bank (External API); Merchant server (Client); Payments API (API gateway); Payment service (Service); Acquirer connector (Service); Acquirer (External API); Payments DB (SQL DB). Connections: Shopper’s browser → Card service (card details → token); Shopper’s browser → Merchant server (token and order); Merchant server → Payments API (create the payment); Payments API → Payment service; Payment service → Payments DB (record); Payment service → Risk service (risk check); Payment service → Acquirer connector (authorize); Acquirer connector → Acquirer (authorization); Acquirer → Card network → shopper’s bank (approve and hold?).

Read:Learn: High-level architecture

Try it: From the checkout to the shopper’s bankGuided practice · Payment gateway, Card payments for online merchants · Senior

Check yourself

Who decides whether the card is approved?
Show answerHide answer
The shopper’s bank, the issuer. The gateway carries the request to it through an acquirer and the card network, and records the answer.

Where the card number goes

Every system that stores, processes or sends card data is in PCI DSS scope; handling raw card numbers can mean over 300 controls (Stripe docs (opens in a new tab)). So the number goes from the browser straight into a small card zone, which hands back a token; everything else holds the token and the last four digits.

Card fields served by the gateway send the number straight to the card service, bypassing the merchant’s servers.
The card service encrypts it with a data key protected by the key store, stores the ciphertext, and returns a token.
Only the acquirer connector, inside the zone, decrypts the number, and only to send the authorization.

Architecture diagramThe card zone: the only place a card number lives

Take the money when it ships

Shops that ship later hold the money at checkout and capture it on shipping; the money itself arrives days later.

The merchant’s server calls capture with the amount that shipped, and its key.
The payment moves to capture requested in one conditional update, bounded by the hold.
The connector sends the capture with our reference; when the acquirer accepts it, the payment is captured. If the answer is lost, it stays capture requested and is checked by that reference.
Clearing and settlement bring the money on the acquirer’s schedule, about two working days in the brief.

Architecture diagramTake the money later: capture, then clearing and settlement

Design a Stripe-style payment gateway

The answer in two minutes

Also asked as

What interviewers look for

The decisions that matter

Understanding the problem

Functional requirements

Non-functional requirements

Scale

Out of scope

The numbers that shape the design

Core entities

The API

High-level design

Pay with a new card

Where the card number goes

Take the money when it ships

Sign in with Google to read the rest

Practise this

Merchants that send card numbers themselves

Where storing card numbers isn’t allowed

The answer in two minutes

Also asked as

What interviewers look for

The decisions that matter

01Understanding the problem

Functional requirements

Non-functional requirements

Scale

Out of scope

02The numbers that shape the design

03Core entities

04The API

05High-level design

Pay with a new card

Where the card number goes

Take the money when it ships

Sign in with Google to read the rest

12Practise this

Merchants that send card numbers themselves

Where storing card numbers isn’t allowed

Understanding the problem

The numbers that shape the design

Core entities

The API

High-level design

Practise this