Case Study 9: Payment Gateway like Razorpay

A platform for merchants that accepts money by UPI, cards and netbanking, records it safely in a ledger and settles it to the merchant.

C.1 Requirements

Functional requirements:

• Merchant onboarding, API keys and webhook URL configuration.
• Create orders and show payment methods at checkout (UPI, cards, netbanking, wallets).
• Authorize/capture payments through the bank, card network or NPCI.
• Idempotency on every API: no double charge on a retry.
• Send webhooks for payment events to the merchant (payment.captured, refund.processed).
• Account for every rupee in a double-entry ledger.
• Merchant settlement (T+1/T+2) and reconciliation with bank files.
• Full and partial refunds.

Non-functional requirements:

• 99.99% availability of the payment API: downtime = the merchant's revenue loss.
• Payment create API p99 < 300 ms (bank latency is separate).
• Strong consistency in the ledger: debit = credit always, money must never vanish.
• PCI-DSS compliance: card data tokenized and encrypted, the vault isolated.
• Peak 10,000 TPS (sale days such as Big Billion Days).
• Data durability: retain financial records for 8-10 years (regulatory).

C.2 Estimation (back-of-the-envelope)

C.3 API design

C.4 Data model

C.5 High-level architecture

• Customer checkout comes via the CDN and the merchant server comes with an API key; both pass through WAF + DDoS -> Load Balancer -> API Gateway (auth, per-merchant rate limit).
• Order / Payment / Refund services; the card number lives only in the isolated Card Vault (token + HSM), so the PCI scope is small.
• Payment Service runs the state machine + Idempotency Redis; the Payment Router picks a route by success rate and cost, and adapters talk to NPCI / the bank.
• Status goes into the PostgreSQL merchant_id shard + outbox -> Kafka; Ledger Writer, Webhook Dispatcher, Settlement and Reconciliation run async.

C.6 Main flows

UPI payment flow:

1. The merchant server does POST /orders with an Idempotency-Key and gets an order_id.
2. The customer chooses UPI at checkout; POST /payments, status=CREATED.
3. The Payment Router sends a collect request or intent to NPCI via the PSP bank.
4. The customer enters the PIN in their UPI app; the bank debits.
5. An async callback arrives from NPCI/PSP; verify the signature and dedup on gateway_ref.
6. Payment status becomes CAPTURED (in a DB transaction) and a payment.captured event goes on Kafka.
7. The Ledger Writer writes the entries: customer clearing debit, merchant payable credit, fee credit.
8. The Webhook Dispatcher sends a signed webhook to the merchant; the merchant confirms the order.

Idempotent retry flow:

1. The merchant's network times out and they retry the request with the same Idempotency-Key.
2. The Payment Service looks up the key in Redis/DB.
3. If the key is IN_PROGRESS, 409 or wait; if COMPLETED, return the stored response.
4. If request_hash differs, a 422 error: the same key with a different body is not allowed.
5. This way the customer's money is deducted only once.

Refund and reconciliation flow:

1. The merchant does POST /payments/{id}/refunds with an amount.
2. The Refund Service checks: total refunded <= captured amount.
3. Reverse entries in the ledger; the amount is held from the merchant balance.
4. A refund request to the bank/NPCI; an async status callback.
5. At night the Reconciliation Job matches every txn against the bank file.
6. On a mismatch (for example success at the bank, failed with us), an auto-update or an ops ticket.

C.7 Deep dives

Double-entry ledger (a Rs 1000 payment: the merchant's share, fee and GST):

The ledger is append-only: a mistake is fixed with a reversal entry, never an update / delete. Refund = reverse entries + a merchant balance hold. At night the Recon Job matches the bank / NPCI settlement file against payments + ledger: match OK, or on a mismatch an auto-fix / ticket.

Problem: double charge on retry / network timeout. A merchant-scoped Idempotency-Key on every write API, stored with the request hash. A DB unique constraint is the final guard. Bank callbacks are also deduped on gateway_ref.

Problem: the payment state is unknown (bank timeout). Keep the status PENDING, poll the bank status-check API, and treat the reconciliation file as the final truth. Show the customer pending, not a wrong failure.

Problem: ledger correctness. A double-entry, append-only ledger; sum(debit) = sum(credit) is checked inside the DB transaction for every transaction. A mistake is fixed with a reversal entry, never an update.

Problem: webhook delivery reliability. The outbox pattern: the payment update and the event insert in one DB transaction, then Kafka. Retries with backoff, an HMAC signature, and merchant-side dedup by event_id.

Problem: bank/acquirer downtime. The Payment Router tracks every bank's real-time success rate; a circuit breaker shuts the bad route and moves traffic to another acquirer.

Problem: PCI-DSS and security. Card data only in an isolated vault, with tokenization + HSM encryption. Network segmentation, TLS everywhere, secrets rotation, audit logs.

C.8 Trade-offs

C.9 Interview tips

• Draw the payment as a state machine, with every transition idempotent.
• Explain the full Idempotency-Key lifecycle: store, in-progress, completed, hash mismatch.
• Explain why the ledger is double-entry and append-only: this is a senior-level signal.
• Call reconciliation the final safety net: mismatches are bound to happen in distributed systems.
• Be sure to mention the outbox pattern + retry + signature for webhooks.