Design an Online Payment Service

Before writing a single component, understand what makes this problem different from a digital wallet. A wallet asks "how does Alice's $50 reach Bob safely?" An online payment service asks "how does Stripe decide which processor handles a payment, settle funds to 100,000 merchants nightly, and guarantee consistency at 10,000 TPS?" You are designing the platform layer. The system that orchestrates payments across thousands of merchants, multiple processors, and multiple currencies.

This distinction drives every design decision. The wallet optimizes for correctness of a single transfer. The payment service optimizes for routing intelligence, settlement efficiency, and multi-tenant reliability at platform scale.

Functional

Let us anchor to a real-world reference: Stripe processes hundreds of millions of payments per day across millions of merchants. We will target a large but not maximum-scale platform to keep the numbers concrete.

Traffic

• Merchants: 100,000 active merchants, ranging from small shops (10 payments/day) to large retailers (100,000 payments/day)
• Payments: 100 million payments/day = roughly 1,150 TPS average, roughly 10,000 TPS peak (Black Friday, holiday shopping). The peak is not 10x one merchant's spike. It is every merchant spiking simultaneously.
• Write amplification: each payment generates roughly 8 database writes. Payment record, 2 ledger entries (debit merchant's customer, credit platform), idempotency key, webhook event record, settlement line item, fraud scoring log, and audit trail entry. At 10,000 TPS peak, the database sustains 80,000 write operations per second. This write amplification is the number that drives database sizing, not the raw payment TPS.
• Webhook traffic: each payment triggers 1-3 webhooks to merchant endpoints. At 100 million payments/day with an average of 3 events per payment (authorized, captured, settled) = 300 million outbound HTTP calls/day = roughly 3,500 calls/sec average, 35,000/sec peak. This is a separate scaling concern from payment processing, webhook delivery is an outbound HTTP workload, not a database workload.

All endpoints require authentication via merchant API keys (secret key in the Authorization header). The API Gateway validates the key, identifies the merchant, applies per-merchant rate limits, and routes requests. Every mutation endpoint accepts an Idempotency-Key header. Clients that retry without this header risk duplicate charges.

Payments

• POST /v1/payments. Create a payment intent. Body: { amount: 5000, currency: "usd", payment_method: "pm_card_visa", capture: false, metadata: { order_id: "ord_123" } }. Header: Idempotency-Key: <uuid>. Amount is in the smallest currency unit (5000 = $50.00). Setting capture: false creates an authorization-only hold. Returns payment object with status: "requires_capture" or status: "succeeded" if capture: true.
• POST /v1/payments/:id/capture. Capture a previously authorized payment. Optional body: { amount: 3000 } for partial capture (e.g., only 2 of 3 items shipped). If omitted, captures the full authorized amount. Authorization holds expire after 7 days on most card networks, uncaptured authorizations are voided automatically.
• POST /v1/payments/:id/refund. Full or partial refund. Body: { amount: 2000, reason: "customer_request" }. Routes back through the original processor. Adjusts the next settlement amount. The refund is deducted from the merchant's upcoming payout, not processed as a separate bank transfer.
• GET /v1/payments/:id. Retrieve payment with full status history. Response includes: current status, amount, currency, processor used, authorization code, timeline of state transitions (created, authorized, captured, settled), and linked refunds. Merchants poll this endpoint or rely on webhooks for status updates.
• GET /v1/payments?merchant_id=m_123&status=captured&created_gte=2026-01-01&limit=100&starting_after=pay_xyz. List payments with filters. Cursor-based pagination using starting_after parameter (not offset-based, for the same reasons discussed in the digital wallet editorial, new payments constantly shift offsets).

The payment platform requires ACID transactions for payment state management, but the data model differs significantly from a digital wallet. Instead of user wallets with balances, the core entities are payments, merchants, and settlements. PostgreSQL remains the backbone for the same reasons, financial correctness demands ACID guarantees.

PostgreSQL. Core Financial Data

merchants: one row per onboarded merchant

The payment platform uses a service-oriented architecture where each service owns a specific domain. Unlike the digital wallet where the critical challenge is atomicity of a single transfer, the payment platform's critical challenge is orchestrating payments across multiple external processors while maintaining consistency and delivering reliable notifications to merchants.

API Gateway

Card Payment Authorization and Capture Flow

This is the primary flow. It exercises the routing engine, processor adapters, and webhook delivery that distinguish the payment platform from a simple wallet.

Payment Routing Engine

The routing engine is the first half of this design's core challenge (GATE). Every payment platform routes payments. The quality of routing decisions directly determines authorization rates and processing costs. A naive router that always picks the cheapest processor leaves money on the table. A sophisticated router that balances cost, auth rate, and reliability is the platform's competitive moat.

Auth Rate vs Cost Routing

The most impactful routing decision is balancing authorization rate against processing cost. Consider a concrete example with a $100 payment:

• Processor A: 2.9% + $0.30 fee, 98% auth rate. Cost per attempt: $3.20. Expected cost per successful payment: $3.20 / 0.98 = $3.27.
• Processor B: 2.2% + $0.25 fee, 95% auth rate. Cost per attempt: $2.45. Expected cost per successful payment: $2.45 / 0.95 = $2.58.

Processor Outage During Peak Traffic

The highest-risk failure: the primary processor goes down during Black Friday when 100,000 merchants are processing at 10x normal volume. A cliff-edge failover (instantly routing 100% of traffic to the secondary processor) risks overwhelming it. The secondary was handling 20% of traffic and suddenly receives 100%.

ML-Powered Dynamic Routing

The current routing engine uses static rules and historical averages. An ML model trained on real-time transaction data can make per-transaction routing decisions that static rules cannot. Features include: time of day (authorization rates vary by hour. Issuing banks process differently during batch windows), cardholder's historical success rate per processor, current processor latency percentile (not just up/down but "responding 2x slower than normal"), and seasonal patterns (different processors perform better during holiday spikes vs steady-state).

The expected impact: 1-3% authorization rate improvement. At $10 billion in annual payment volume, a 1% lift means $100 million in additional successful payments. A 3% lift means $300 million. This is why payment companies invest heavily in routing ML. The ROI is directly measurable.