System Design Learning Hub

Payments

Secure payment processing with PCI compliance, fraud detection, and multi-provider routing.

Learning Objectives

By the end of this case study, you will understand:

  • Design PCI-compliant payment processing architecture
  • Implement secure tokenization and encryption for sensitive data
  • Build fraud detection systems with real-time risk assessment
  • Design payment routing across multiple processors for optimization
  • Implement reconciliation and dispute management workflows

Real-World Examples

Stripe: Processes $640+ billion annually with 99.99% uptime

PayPal: Handles 19+ billion payment transactions per year

Square: Powers payments for 4+ million businesses

Adyen: Processes payments for Uber, Netflix, and Facebook

Requirements

Functional Requirements

  • Accept cards, digital wallets, bank transfers
  • Tokenize sensitive payment data
  • Route to optimal payment processors
  • Detect and prevent fraudulent transactions

Non-functional Requirements

  • High auth success rate; low latency to provider
  • Ledger integrity and consistency
  • Resilience to provider outages

High-Level Design

  • API layer with idempotency and tokenization
  • Payment gateway adapters to multiple PSPs
  • Ledger DB append-only with reconciliation

Capacity & Sizing

  • Payment TPS during peak, auth/capture ratios
  • Ledger write throughput and storage

Key Components

  • Payments API, Tokenization service
  • Gateway adapters, Webhooks handler
  • Ledger DB

Architecture

High-level components and data flow

Data Model

Core entities and relationships

  • payments (payment_id PK, amount, currency, status, ts)
  • tokens (token PK, card_last4, brand, exp)
  • ledger_entries (entry_id PK, payment_id, debit, credit, ts)

APIs

  • POST /api/payments { token, amount, currency }
  • POST /api/payments/:id/capture
  • POST /api/payments/:id/refund { amount }

Hot Path

  1. Auth: tokenize → provider → ledger pending auth
  2. Capture: ledger capture entry

Caching & TTL

  • Cache provider metadata and configuration with long TTL

Scaling

  • Shard ledger by payment_id; append-only segments
  • Queue and retry provider timeouts
  • Idempotency keys to dedupe retries

Trade-offs

  • Strong consistency in ledger vs throughput
  • Provider diversity vs integration complexity
  • PCI scope vs UX (e.g., hosted fields)

Failure Modes & Mitigations

  • Provider outage → failover or queue for retry
  • Double charge risk → strict idempotency
  • Chargeback → dispute workflows

Observability

  • SLIs: auth success rate, p95 auth latency
  • Refund/Capture error rates
  • Ledger balance checks and reconciliation