Requirements

Functional Requirements

• Process credit/debit card payments
• Support refunds and chargebacks
• Merchant onboarding and KYC (Know Your Customer)
• Payment method management (saved cards)
• Transaction history and reporting
• Webhook notifications for payment events
• Multi-currency support

Non-Functional Requirements

• Correctness: Zero tolerance for financial errors
• Durability: Transaction logs must never be lost
• Idempotency: Retried requests must not cause duplicate charges
• Availability: 99.999% for payment processing
• Compliance: PCI-DSS Level 1, GDPR, SOX

Back-of-the-Envelope Estimation

API Design

POST /api/v1/payments
Request: {
  "amount": 5000,          // cents
  "currency": "USD",
  "source": "tok_visa_123",
  "description": "Order #12345",
  "idempotency_key": "order_12345_payment_1"
}
Response: {
  "payment_id": "pay_abc123",
  "status": "succeeded",
  "amount": 5000,
  "charge_id": "ch_xyz789"
}

POST /api/v1/refunds
Request: { "charge_id": "ch_xyz789", "amount": 2000 }
Response: { "refund_id": "ref_456", "status": "succeeded" }

GET /api/v1/payments/pay_abc123
Response: { "payment_id": "pay_abc123", "status": "succeeded", ... }

High-Level Architecture

Detailed Design

Idempotency

Double-Entry Ledger

Every payment creates two ledger entries that must balance:

Payment Processing Flow

Payment State Machine

Idempotency Design

Every payment request includes an idempotency key:

POST /api/v1/payments
Headers:
  Idempotency-Key: order_12345_payment_1
  Content-Type: application/json

The server checks Redis for the idempotency key:

1. Key exists → return cached response (no reprocessing)
2. Key doesn't exist → process payment, store result with 24h TTL

Fraud Detection

Integrate fraud detection in the payment flow:

Practice Exercises

1. Design: How would you implement a payment refund that partially refunds a multi-item order? Design the ledger entries for a partial refund.

2. Reliability: If the payment network (Visa) is temporarily unavailable, design a retry strategy that doesn't double-charge the customer.

3. Compliance: What data must be encrypted at rest and in transit for PCI-DSS compliance? Design the encryption strategy for card data.

4. Scale: If the system processes 10,000 TPS, estimate the Redis cluster size for idempotency checks and the PostgreSQL cluster size for ledger storage.

What to Learn Next