Payment System

Problem Statement & Requirements

Design a payment processing platform that handles the full lifecycle of financial transactions — accepting payments from customers, routing to card networks, managing settlements, handling refunds, and preventing fraud — similar to Stripe, Square, Adyen, or PayPal.

Functional Requirements

• Charge a payment method — credit/debit cards, bank transfers (ACH), digital wallets (Apple Pay, Google Pay)
• Payment intents — two-phase: authorize (hold funds) → capture (collect funds), or single-phase direct charge
• Refunds — full or partial refund of a completed payment
• Payment methods — store, retrieve, and delete customer payment methods (tokenized)
• Idempotency — every API call accepts an idempotency key; retries are safe and produce identical results
• Webhooks — notify merchants of async events (payment succeeded, refund completed, dispute opened)
• Multi-currency — accept payments in 135+ currencies; settle in merchant's preferred currency
• Subscriptions / Recurring billing — charge customers on a schedule (monthly, annual)
• Dispute / Chargeback handling — manage the lifecycle of customer-initiated disputes
• Payout / Settlement — aggregate funds and transfer to merchant bank accounts on a schedule
• Ledger — double-entry bookkeeping for every money movement; audit trail

Non-Functional Requirements

• Correctness above all — money must never be created, lost, or double-counted
• Exactly-once processing — no duplicate charges, no lost refunds
• High availability — 99.999% for payment acceptance (< 5 min downtime/year)
• Low latency — payment authorization in < 2 seconds end-to-end
• PCI DSS compliance — Level 1; card data encrypted at rest and in transit; tokenization
• Strong consistency — payment state transitions must be ACID
• Auditability — every state change logged immutably for regulatory compliance
• Scalability — handle Black Friday traffic (10x normal peak)

Out of Scope

• Detailed card network protocol internals (ISO 8583 message format)
• KYC/AML onboarding flow for merchants
• Tax calculation engine
• Full invoicing system

Scale Estimations

Traffic

Storage

Bandwidth

Hardware Estimate

This first layer defines the system boundary. The next chapters add application logic and data dependencies. After examining the request paths and tradeoffs, we will add operational safeguards and bring the complete architecture together.

API Design

Create Payment Intent (Authorize)

POST /v1/payment_intents
Idempotency-Key: pi_req_abc123
Authorization: Bearer sk_live_...

Request:
{
  "amount": 2999,                        // cents (avoid floating point!)
  "currency": "usd",
  "payment_method": "pm_card_visa_4242",
  "capture_method": "manual",            // "automatic" for single-phase
  "description": "Order #1234",
  "metadata": {"order_id": "ord-1234"},
  "customer": "cus_abc123",
  "receipt_email": "alice@example.com"
}

Response (200 OK):
{
  "id": "pi_3MtwBwLkdIwHu7ix",
  "object": "payment_intent",
  "amount": 2999,
  "currency": "usd",
  "status": "requires_confirmation",
  "payment_method": "pm_card_visa_4242",
  "client_secret": "pi_3MtwBw_secret_YkS2...", // for frontend confirmation
  "created": 1712150400
}

Confirm Payment (Execute Authorization)

POST /v1/payment_intents/{id}/confirm
Idempotency-Key: pi_confirm_abc123

Response (200 OK):
{
  "id": "pi_3MtwBwLkdIwHu7ix",
  "status": "requires_capture",     // if manual capture
  // OR
  "status": "succeeded",            // if automatic capture
  "charges": {
    "data": [{
      "id": "ch_abc123",
      "amount": 2999,
      "currency": "usd",
      "status": "succeeded",
      "authorization_code": "A12345",
      "network_transaction_id": "NT98765",
      "risk_score": 12,
      "outcome": {
        "network_status": "approved_by_network",
        "risk_level": "normal"
      }
    }]
  }
}

Capture Payment

POST /v1/payment_intents/{id}/capture
Idempotency-Key: pi_capture_abc123

Request:
{
  "amount_to_capture": 2999           // can be less than authorized (partial capture)
}

Response (200 OK):
{
  "id": "pi_3MtwBwLkdIwHu7ix",
  "status": "succeeded",
  "amount_captured": 2999
}

Create Refund

POST /v1/refunds
Idempotency-Key: ref_req_xyz789

Request:
{
  "payment_intent": "pi_3MtwBwLkdIwHu7ix",
  "amount": 1500,                     // partial refund (in cents)
  "reason": "customer_request"        // customer_request | duplicate | fraudulent
}

Response (200 OK):
{
  "id": "re_abc123",
  "amount": 1500,
  "currency": "usd",
  "status": "pending",               // pending → succeeded (async from network)
  "payment_intent": "pi_3MtwBwLkdIwHu7ix"
}

Webhook Event

POST https://merchant.example.com/webhooks/stripe
Stripe-Signature: t=1712150400,v1=sha256_hmac_signature

{
  "id": "evt_abc123",
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_3MtwBwLkdIwHu7ix",
      "amount": 2999,
      "status": "succeeded"
    }
  },
  "created": 1712150400
}

Merchant must respond 2xx within 10 seconds.
No 2xx → retry with exponential backoff (up to 3 days, ~20 attempts).

Data Model

Payment Intent

Ledger Entry (Double-Entry Bookkeeping)

Payment State Machine

Core Design Decisions

Decision 1: How to Guarantee Exactly-Once Payment Processing

This is the single most important design problem. Charging a customer twice is catastrophic.

Solution: Multi-Layer Idempotency

Decision 2: The Double-Entry Ledger

Decision 3: Smart Routing to Maximize Authorization Rate

Detailed Flow Diagrams

Payment Authorization Flow

Refund Flow

Settlement / Payout Flow

Payment status is correctness-sensitive, so caching cannot replace the authoritative operation record. Cache stable configuration and provider routing data instead. Move receipts and nonessential analytics off the charge path, while keeping durable recording and idempotency checks within the acceptance boundary.

Tokenization & PCI Compliance

Fraud Detection Engine

Subscription / Recurring Billing

Handling Edge Cases

Partial Capture / Over-Capture

Authorized: $100.00

Case 1: Partial capture (customer removed items from cart)
  → Capture $75.00. Remaining $25.00 auth released to cardholder.
  → Ledger: DEBIT network $75, CREDIT merchant $72.82, CREDIT fees $2.18

Case 2: Multi-capture (ship items separately)
  → Capture $40.00 (shipment 1)
  → Capture $35.00 (shipment 2)
  → Total captured: $75.00. Remaining $25.00 released.
  → Each capture is a separate ledger transaction.

Authorization Expiry

Problem: Merchant authorizes $100 but never captures

  Card network rules:
    Visa: auth expires in 7 days
    Mastercard: auth expires in 7-30 days (varies)
    If not captured → funds released to cardholder automatically

  Our handling:
    Background job scans for old uncaptured auths
    After 6 days: send webhook warning merchant
    After 7 days: mark as expired, release ledger hold
    Merchant can re-authorize if needed

Network Timeout (Ambiguous Response)

Problem: We send auth request to Visa → timeout after 30s
         Did Visa approve it? Decline it? Never receive it?

  This is the HARDEST edge case in payments.

  Solution: Status Inquiry + Reconciliation

  1. Immediately: mark payment as "processing" (not succeeded/failed)
  2. After 30s: send "status inquiry" to Visa
     → "I sent request REQ-123, what happened?"
     → Visa responds: approved / declined / not found
  3. If "not found": safe to retry with new request ID
  4. If approved/declined: update our state accordingly
  5. If status inquiry also times out:
     → Mark as "requires_manual_review"
     → Nightly reconciliation batch compares our records
       with network settlement files
     → Catches ALL discrepancies within 24 hours

Double-Charge Prevention on Retry

Scenario:
  1. Merchant calls POST /confirm (Idempotency-Key: IK-123)
  2. We auth with Visa → approved → our server crashes BEFORE responding
  3. Merchant times out → retries with same IK-123
  4. We see IK-123 exists with status="processing" (not completed)

  Handling:
  → Check: is there a network_txn_id for this payment?
  → Yes: we already sent to Visa and it was approved
  → Return the original approval result (don't send to Visa again)
  → Update idempotency cache with final result

  If network_txn_id is NULL:
  → We crashed before sending to Visa
  → Safe to send authorization now (first attempt from network's POV)

Dispute / Chargeback Handling

Customer calls bank: "I didn't make this purchase!"

Timeline:
  Day 0:   Issuer initiates dispute, debits merchant's account
  Day 1:   We receive dispute notification from network
           → Webhook: "charge.dispute.created"
           → Ledger: DEBIT merchant, CREDIT dispute_reserve
  Day 1-21: Merchant submits evidence (receipt, tracking, logs)
           → We forward evidence to network (representment)
  Day 30-75: Issuer reviews evidence
           → Won: funds returned to merchant (CREDIT merchant)
           → Lost: funds stay with customer (dispute_reserve cleared)
           → Webhook: "charge.dispute.closed" with outcome

  Financial impact tracking:
  dispute_rate = disputes / total_charges (by merchant)
  If > 1%: warn merchant (Visa/MC programs penalize high dispute rates)
  If > 2%: risk of losing processing privileges entirely

Tradeoffs & Design Decisions Summary

Reliability & Fault Tolerance

Single Points of Failure & Mitigations

Disaster Recovery

Reconciliation — The Ultimate Safety Net

High-Level Architecture

Component Breakdown

Full System Architecture (Production-Grade)

A provider reports success through a webhook before the original API request returns. Trace how both paths converge on the same payment record. Then deliver that webhook again and out of order with a later status update. The state machine should reject regressions rather than trusting arrival order.

Interview Tips

1. Lead with correctness, not performance — "The #1 requirement is money never gets lost or double-counted." Explain idempotency keys, ACID transactions, double-entry ledger. Performance is secondary to correctness for payments.

2. Draw the payment lifecycle state machine — requires_payment_method → requires_confirmation → requires_capture → succeeded → refunded. Show you understand the two-phase (auth + capture) model and why it exists (hotel holds, preorders).

3. Explain idempotency concretely — Walk through the retry scenario: merchant sends charge, times out, retries with same key. Show how SETNX in Redis prevents duplicate processing, and how stored results return the original response.

4. Double-entry ledger is the showstopper answer — Most candidates say "store balances in a column." Explain: every money movement creates debit + credit entries; sum must always be zero; corrections are reversing entries, never updates. This invariant catches bugs, fraud, and data corruption.

5. Use integers for money, never floats — $29.99 = 2999 cents as BIGINT. Floating point: 0.1 + 0.2 = 0.30000000000000004. In payments, one cent off in a billion transactions = audit nightmare.

6. Tokenization minimizes PCI scope — Card numbers never touch your main infrastructure. Token Vault (< 5 servers in PCI scope) vs entire platform (100+ servers). Dramatically reduces audit cost and security risk.

7. Network timeout is the hardest edge case — Don't handwave "just retry." Explain: timeout is ambiguous (approved? declined? lost?). Solution: status inquiry to network + nightly reconciliation as safety net.

8. Smart routing improves auth rates — Not all acquirers are equal. Routing based on BIN, country, card type, historical performance can lift auth rates 2-5%. At scale, this is millions in recovered revenue.

9. Reconciliation is the last line of defense — Three-way nightly comparison: our records vs network settlement files vs ledger balances. Any mismatch = alert. This catches everything that all other safeguards missed.

10. End with fraud and disputes — Mention ML scoring (< 10ms real-time), 3DS challenges for medium-risk, and the dispute lifecycle. Show you understand the business impact: > 1% dispute rate = card network penalties.