Design a Payment System

Payment systems like Stripe enable merchants to accept payments from customers without building their own payment processing infrastructure. This is a challenging design problem because it requires handling real money—where correctness, security, and durability are non-negotiable.

This walkthrough follows the Interview Framework and focuses on what you'd actually present in a 45-60 minute interview.

Phase 1: Requirements

Functional Requirements

1. Merchants should be able to initiate payment requests (charge a customer for a specific amount)
2. Users should be able to pay with credit/debit cards
3. Merchants should be able to view payment status updates (pending, succeeded, failed)

Non-Functional Requirements

1. Security: The system must be highly secure (PCI DSS compliant)
2. Durability: No transaction data can ever be lost, even during failures
3. Financial integrity: No double-charging, no lost payments despite asynchronous external networks
4. Scalability: Handle 10,000+ TPS with bursty traffic (e.g., holiday sales)

Capacity Estimation

Phase 2: Data Model

Core Entities

Merchant
├── id (PK)
├── name
├── api_key_hash
├── webhook_url
├── bank_account_info (encrypted)
└── created_at

PaymentIntent
├── id (PK)
├── merchant_id (FK)
├── idempotency_key (unique per merchant)
├── amount_cents
├── currency
├── status: created | processing | requires_action | succeeded | failed | canceled
├── description
├── metadata (JSONB)
├── created_at
└── updated_at

Transaction
├── id (PK)
├── payment_intent_id (FK)
├── type: charge | refund | dispute
├── amount_cents
├── status: pending | authorized | captured | succeeded | failed | pending_resolution
│           ↳ Charges: pending → authorized → captured (success) or failed
│           ↳ Refunds/Disputes: pending → succeeded or failed
├── needs_reconciliation (boolean)
├── network_reference_id
├── error_code
├── created_at
└── updated_at

PaymentIntent vs Transaction

This distinction is crucial and often causes confusion:

• PaymentIntent: Represents the merchant's intention to collect money. Owns the state machine and enforces idempotency. One PaymentIntent exists per checkout.
• Transaction: Represents actual money movement attempts. Multiple transactions can link to one PaymentIntent (retries, partial payments, refunds).

PaymentIntent (Order #1234, $50)
├── Transaction 1: Charge attempt → Failed (insufficient funds)
├── Transaction 2: Charge attempt → Captured
└── Transaction 3: Refund → Succeeded ($10 partial refund)

Phase 3: API Design

Create PaymentIntent

POST /v1/payment-intents
Headers:
  Authorization: Bearer sk_live_xxx
  Idempotency-Key: order_1234_checkout

Request:
{
  "amount": 2499,
  "currency": "usd",
  "description": "Order #1234"
}

Response:
{
  "id": "pi_abc123",
  "status": "created",
  "client_secret": "pi_abc123_secret_xyz"
}

Process Payment (Charge)

POST /v1/payment-intents/{id}/confirm
Headers:
  X-Publishable-Key: pk_live_xxx

Request:
{
  "payment_method": "pm_card_visa",
  "client_secret": "pi_abc123_secret_xyz",
  "return_url": "https://merchant.com/complete"
}

Response:
{
  "id": "pi_abc123",
  "status": "processing",
  "next_action": null
}

If the issuer requires additional authentication (e.g., 3DS/SCA), return status: "requires_action" with a next_action payload describing the redirect or SDK flow.

Get Payment Status

GET /v1/payment-intents/{id}

Response:
{
  "id": "pi_abc123",
  "status": "succeeded",
  "amount": 2499,
  "currency": "usd",
  "transactions": [{
    "id": "txn_xyz",
    "type": "charge",
    "status": "captured",
    "amount": 2499
  }]
}

Webhook Notifications

POST {merchant_webhook_url}
Headers:
  Stripe-Signature: t=1234,v1=abc...

{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_abc123",
      "amount": 2499,
      "status": "succeeded"
    }
  }
}

Phase 4: High-Level Design

Component Responsibilities

Payment Flow Walkthrough

Step 1: Create PaymentIntent

1. Merchant server calls POST /payment-intents with amount and idempotency key
2. Payment Service creates record with status created
3. Returns client_secret for frontend to complete payment

Step 2: Collect Payment Details

1. Customer enters card in secure iframe (never touches merchant server)
2. Card tokenized into payment_method ID
3. Client receives payment_method token

Step 3: Confirm PaymentIntent

1. Client SDK calls POST /payment-intents/{id}/confirm with client_secret
2. Payment Service validates intent, runs risk checks, and asks Transaction Service to create a pending transaction

Step 4: Process with Card Network

1. Transaction Service sends authorization request via an acquiring bank/processor
2. Card network routes the request to issuer bank for approval
3. Response updates transaction status to authorized or failed
4. If capture_method=automatic, capture immediately and mark as captured

Step 5: Notify Merchant

1. CDC captures database changes, publishes to Kafka
2. Webhook Service consumes events
3. Delivers webhook to merchant's registered URL
4. Merchant triggers fulfillment (ship product, grant access)

Phase 5: Deep Dives

1. Preventing Double Charges (Idempotency)

The most dangerous failure mode in payments is charging a customer twice. This happens when:

• Network timeout occurs, merchant retries
• Customer clicks "Pay" multiple times
• Our service crashes mid-transaction

Solution: Idempotency Keys

CREATE TABLE payment_intents (
    id UUID PRIMARY KEY,
    merchant_id UUID NOT NULL,
    idempotency_key VARCHAR(255) NOT NULL,
    -- ... other fields
    UNIQUE(merchant_id, idempotency_key)
);

def create_payment_intent(merchant_id, idempotency_key, amount):
    # Use atomic upsert to prevent race conditions
    # If idempotency_key exists, return existing record
    # Otherwise, insert new record
    intent = db.query("""
        INSERT INTO payment_intents (merchant_id, idempotency_key, amount, status)
        VALUES (?, ?, ?, 'created')
        ON CONFLICT (merchant_id, idempotency_key)
        DO UPDATE SET updated_at = NOW()  -- No-op update to return existing row
        RETURNING *
    """, merchant_id, idempotency_key, amount)

    return intent

The ON CONFLICT clause makes this atomic—two concurrent requests with the same idempotency key will never both succeed in creating new records.

2. Handling Asynchronous Payment Networks

Payment networks are fundamentally asynchronous. A timeout doesn't mean failure—the payment might still be processing. This creates three dangerous scenarios:

Solution: Pending States + Reconciliation

def process_payment(payment_intent_id, payment_method):
    payment_intent = db.query("""
        SELECT amount_cents
        FROM payment_intents
        WHERE id = ?
    """, payment_intent_id)

    # 1. Create transaction in PENDING state BEFORE calling network
    txn = db.insert("""
        INSERT INTO transactions (payment_intent_id, status)
        VALUES (?, 'pending')
    """, payment_intent_id)

    try:
        # 2. Call card network with our transaction ID
        result = card_network.authorize(
            merchant_reference_id=txn.id,
            amount=payment_intent.amount_cents
        )

        # 3. Update based on response
        db.update("UPDATE transactions SET status = ? WHERE id = ?",
                  result.status, txn.id)

    except Timeout:
        # Don't assume failure! Mark for reconciliation
        db.update("""
            UPDATE transactions
            SET status = 'pending_resolution', needs_reconciliation = true
            WHERE id = ?
        """, txn.id)

Reconciliation Worker

def reconciliation_job():
    """Runs every few minutes to resolve uncertain transactions"""
    pending = db.query("""
        SELECT * FROM transactions
        WHERE status = 'pending_resolution'
        AND created_at < NOW() - INTERVAL '5 minutes'
    """)

    for txn in pending:
        # Query card network using our merchant reference ID (sent in original request)
        # If the network doesn't support this, fall back to acquirer reconciliation files
        actual_status = card_network.query_transaction(merchant_reference_id=txn.id)

        if actual_status == 'not_found':
            # Request never arrived—mark as failed (don't auto-retry to avoid double-charge risk)
            db.update("UPDATE transactions SET status = 'failed' WHERE id = ?", txn.id)
        else:
            # Update with actual status from network
            db.update("UPDATE transactions SET status = ? WHERE id = ?",
                      actual_status, txn.id)

3. Durability and Audit Trail

For a payment system, losing transaction data is catastrophic—both legally and financially. We need:

1. Immutable audit log for compliance
2. Event stream for real-time processing
3. Reconciliation with external systems

Solution: CDC + Event Streaming

Why CDC over Application Events?

With CDC, every database change is captured from the write-ahead log (WAL), ensuring no events are lost even if the application crashes.

4. Security: Protecting Card Data

Card data is extremely sensitive. PCI DSS compliance requires strict controls.

Solution: Tokenization with Secure Iframe

Key Security Measures:

1. Iframe isolation: Card form runs on our domain, merchant JavaScript can't access it
2. Tokenization: Raw card numbers converted to tokens immediately
3. Encryption at rest: Sensitive data (tokens, bank info) encrypted with HSM-managed keys
4. API key authentication: Separate publishable (frontend) and secret (backend) keys
5. Request signing: HMAC signatures prevent tampering

5. Authorization vs Capture

Payment processing has two distinct phases that some merchants need to control separately:

Why separate them?

• Hotels/Car Rentals: Authorize when booking, capture when guest checks out (final amount may differ)
• Marketplaces: Authorize buyer's card, capture only when seller ships
• Pre-orders: Authorize now, capture when product ships weeks later

POST /v1/payment-intents
{
  "amount": 10000,
  "capture_method": "manual"  // Don't capture immediately
}

// Later, when ready to charge:
POST /v1/payment-intents/{id}/capture
{
  "amount_to_capture": 8500  // Can capture less than authorized
}

6. Scaling to 10K+ TPS

Database Scaling

At 10K TPS, a single PostgreSQL instance is at its limit. Options:

Kafka Partitioning

Use payment_intent_id as the partition key. Kafka hashes the key to determine the partition:

Topic: payment-events (5 partitions)
Key: payment_intent_id

pi_abc123 → hash("pi_abc123") % 5 → Partition 2
pi_xyz789 → hash("pi_xyz789") % 5 → Partition 4

All events for the same PaymentIntent go to the same partition, guaranteeing order. Different PaymentIntents can be processed in parallel across partitions.

Data Archival

At 25 GB/day, storage grows fast. Implement tiered storage:

• Hot (0-90 days): Primary database, fast queries
• Warm (90 days - 2 years): Read replicas, slower queries acceptable
• Cold (2+ years): S3/Glacier, compliance retention only

Common Pitfalls

Interview Checklist

Summary