Design a Payment Processing System

1. Problem Statement & Scope

System Mission

Design a mission-critical, fault-tolerant payment processing platform (similar to Stripe or Adyen) capable of processing millions of transactions daily with absolute zero data loss, strict idempotency, multi-PSP smart routing, and automated financial reconciliation.

Functional Requirements

1. Pay-in (Charge): Process charges via third-party Payment Service Providers (PSPs: Stripe, Adyen).
2. Idempotency Guarantee: Guarantee network retries never charge a customer twice.
3. Double-Entry Ledger: Record every financial movement as an immutable credit and debit pair.
4. Reconciliation Engine: Nightly settlement matching against external bank files.

Non-Functional Requirements (SLAs/SLOs)

• Consistency: Strict ACID / Zero financial data loss ($100\%$ durability).
• High Availability: $99.999\%$ uptime SLA.
• Security: PCI-DSS Level 1 compliance, envelope encryption via AWS KMS.

2. Capacity & Scale Estimation

• Daily Payment Transactions: 10 Million transactions/day.
• Average QPS: $115\text{ TPS}$ (Peak $8\times$: $\mathbf{1,000\text{ TPS}}$).
• Annual Database Growth (Double-Entry Ledger): $\approx \mathbf{14.6\text{ TB/Year}}$.
• Nightly Reconciliation Volume: 10M internal ledger entries compared against 10M external bank CSV records ($< 1\text{ hour}$ SLA).

3. AWS-First High-Level Architecture

Interactive Architecture Diagram
100%Fit100%
Synthesizing vector architecture diagram...

4. API Interface Design & Idempotency Key

httpCopy
POST /v1/payments
Host: payments.production.aws.internal
Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Content-Type: application/json

{
  "amount_cents": 4999,
  "currency": "USD",
  "payment_method_token": "tok_visa_4242",
  "customer_id": "cust_88124",
  "order_id": "ord_9901"
}

Response: 200 OK
{
  "payment_id": "pay_7182938475",
  "status": "SUCCEEDED",
  "psp_reference": "ch_3N8vK2Lkd..."
}

5. Data Models & Storage Architecture

1. Double-Entry Bookkeeping Ledger (Amazon Aurora PostgreSQL Multi-AZ)

Every financial movement requires a pair of balanced, immutable debit and credit records adhering to the fundamental accounting equation: $\sum \text{Debits} - \sum \text{Credits} = 0$

sqlCopy
-- Immutable Ledger Transactions Table
CREATE TABLE ledger_transactions (
    transaction_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    idempotency_key VARCHAR(128) UNIQUE NOT NULL,
    payment_id VARCHAR(64) NOT NULL,
    status VARCHAR(20) CHECK (status IN ('PENDING', 'COMMITTED', 'REJECTED')),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Immutable Balanced Ledger Entries Table
CREATE TABLE ledger_entries (
    entry_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    transaction_id UUID NOT NULL REFERENCES ledger_transactions(transaction_id),
    account_id VARCHAR(64) NOT NULL, -- e.g. "CUSTOMER_WALLET:usr_102", "MERCHANT_SETTLEMENT:m_402", "PSP_RECEIVABLE:stripe"
    direction VARCHAR(6) CHECK (direction IN ('DEBIT', 'CREDIT')),
    amount_cents BIGINT NOT NULL CHECK (amount_cents > 0),
    currency VARCHAR(3) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Database Check Constraint: Total Debits == Total Credits per Transaction
CREATE INDEX idx_ledger_account_created ON ledger_entries(account_id, created_at DESC);

2. DynamoDB Idempotency & Payment State Machine (PaymentStateTable)

• PK = IDEMPOTENCY#<key>
• Attributes: payment_id, status (IN_FLIGHT, SUCCEEDED, FAILED), response_payload, ttl (7-day automatic expiration).