Stripe System Design

Money is the one domain where “eventually consistent” is not a strategy — it’s a liability.

A social feed that shows a stale post for 30 seconds is a minor annoyance. A payment system that charges a customer twice, fails to credit a merchant, or loses a transaction in a network timeout is a legal, financial, and reputational catastrophe.

A generic system design interview covers scalability, databases, caching, and architecture. A payment system design must include financial constraints, payment lifecycles, idempotency, reconciliation, ledger separation, and failure handling.

This post covers the complete design — from the payment state machine to double-entry bookkeeping, the SAGA pattern, and the reconciliation pipeline that catches everything else.

Functional requirements:

• User initiates payment via merchant checkout

• System charges the user via external Payment Service Provider (PSP)

• Credit merchant wallet after successful payment

• Support refunds, partial refunds, and disputes

• Send payment notifications (email, push, webhook)

• Daily reconciliation with PSP and banks

Non-functional requirements:

• Reliability is critical — failed or duplicated transactions have serious consequences. Engineers commonly use idempotency keys, distributed databases, retries, message queues, and failover mechanisms to ensure payments are processed exactly once.

• Consistency over availability — prefer rejecting a payment over double-processing it

• Full audit trail — every state change immutably recorded

• PCI DSS compliance — card data never stored in application layer

Scale:

Transactions per day:      1 million
Peak TPS:                  ~200/sec (10x average)
Refund rate:               ~2% of transactions
Average transaction:       ¥5,000 (JPY)
PSP response time:         200-800ms
Reconciliation window:     Daily (T+1)
Audit log retention:       7 years (regulatory requirement)

We have to build a CP system — consistent over available. This is not a very high TPS and relational databases can handle this easily. The consistency requirement drives the architecture more than the scale requirement.

The core services are:

• API Gateway (auth, rate limiting, routing — never contains payment logic),

• Order Service (owns the business order; payment is a consequence of an order, not vice versa),

• Payment Service (owns gateway integration, payment state machine, idempotency), Wallet Service (owns internal balances, wallet ledger, transfers),

• Accounting Service (owns double-entry ledger, journal entries),

• Webhook Service (receives, verifies, deduplicates, and queues gateway events), Notification Service (emails/SMS/push on payment events).