Requirements: Process Payments - Payment System | OneNoughtOne

0/273

System Design HLDPayment System

Designing a Payment System

LevelAdvanced

Duration180 mins

TopicPayment System

1 / 6

Requirements: Process Payments

The Foundation of Digital Commerce

Every second, payment systems across the globe process over 50,000 transactions, moving trillions of dollars annually with a target uptime of 99.999% and an acceptable error rate approaching zero. A single miscalculated cent across millions of transactions translates to millions in discrepancies. A single security breach can cost companies billions in fines, lawsuits, and lost trust.

Payment system design is not merely a software engineering challenge—it's a discipline where correctness is non-negotiable, where eventual consistency is often unacceptable, and where regulatory compliance isn't optional but legally mandated. This module will equip you with the knowledge to design payment infrastructure that handles the most demanding financial workloads while maintaining absolute reliability and security.

What You Will Learn

By the end of this page, you will understand the comprehensive requirements for a production-grade payment system—functional capabilities, non-functional constraints, regulatory obligations, and the unique challenges that distinguish payment systems from typical distributed systems. You'll learn to think like a payments engineer, where every decision carries financial and legal consequences.

Understanding the Payment Domain

Before diving into requirements, we must understand the fundamental concepts and stakeholders in the payment ecosystem. Payment processing is not a single operation—it's a complex orchestration involving multiple parties, each with distinct responsibilities, incentives, and failure modes.

The Payment Ecosystem:

A typical payment transaction involves a minimum of five distinct parties, each adding latency, potential failure points, and processing fees:

Key Stakeholders in Payment Processing
Stakeholder	Role	Concerns	Example
Customer (Cardholder)	Initiates payment using payment instrument	Security, convenience, transaction speed, dispute resolution	End user with credit card
Merchant	Sells goods/services and accepts payment	Transaction fees, settlement speed, chargeback protection	Your e-commerce platform
Payment Gateway	Encrypts and routes transaction data	API reliability, security, multi-processor support	Stripe, Braintree, Adyen
Payment Processor	Handles transaction authorization and settlement	Transaction throughput, network connectivity, fraud prevention	First Data, Worldpay, Chase Paymentech
Card Network	Routes transactions between processors and issuers	Network availability, interchange fee collection, brand standards	Visa, Mastercard, American Express
Issuing Bank	Issues payment cards and approves/declines transactions	Credit risk, fraud detection, customer service	Chase, Bank of America, Capital One
Acquiring Bank	Merchant's bank that receives funds	Risk management, merchant underwriting, settlement	Bank that holds merchant account

Payment Transaction Lifecycle:

Understanding the full lifecycle of a payment is crucial for requirement definition. A single "payment" actually consists of multiple discrete operations:

Authorization — Verify funds availability and reserve the amount (doesn't move money)
Capture — Convert authorization to actual fund transfer (can be immediate or delayed)
Settlement — Actual movement of funds between banks (typically batched, T+1 or T+2)
Reconciliation — Verification that all parties agree on transaction details
Chargeback/Dispute — Customer contests a transaction (can occur up to 120+ days later)

Each phase has distinct timing, failure modes, and recovery procedures. A robust payment system must handle all phases correctly.

Money Movement Takes Time

When a customer sees "Payment Successful," money hasn't actually transferred yet. Authorization only reserves funds. Settlement (actual fund transfer) typically occurs 1-2 business days later. Your system must accurately represent this reality and handle the interim states correctly.

Functional Requirements

Functional requirements define what the payment system must do. We'll categorize these into core payment operations, payment method support, merchant capabilities, and customer-facing features.

Core Payment Operations

•Process Payments — Accept and process payments across multiple payment methods (cards, digital wallets, bank transfers, buy-now-pay-later). Support one-time purchases and recurring billing.
•Authorization & Capture — Support both auth-and-capture (immediate charge) and auth-only (delayed capture) modes. Enable partial captures and multi-capture scenarios.
•Refunds & Voids — Process full and partial refunds. Support voiding authorized-but-uncaptured transactions. Handle original transaction reference linking.
•Recurring Payments — Manage subscriptions, scheduled payments, and stored credentials for repeat purchases. Handle renewal failures gracefully with retry logic.
•Multi-Currency Support — Accept payments in multiple currencies with real-time exchange rate handling. Support dynamic currency conversion (DCC) where customers pay in their home currency.
•Split Payments — Divide a single payment across multiple destinations (e.g., marketplace with sellers). Calculate and distribute platform fees automatically.

Payment Method Support

•Credit/Debit Cards — Support major card networks (Visa, Mastercard, Amex, Discover, JCB, UnionPay). Handle card-present and card-not-present transactions.
•Digital Wallets — Integrate Apple Pay, Google Pay, Samsung Pay, PayPal, Venmo, and regional wallets (Alipay, WeChat Pay for Asia, PIX for Brazil).
•Bank Transfers — Support ACH (US), SEPA (EU), Faster Payments (UK), wire transfers, and real-time payment rails where available.
•Buy Now, Pay Later — Integrate with BNPL providers (Affirm, Klarna, Afterpay) for installment payment options.
•Stored Payment Methods — Securely store customer payment credentials for future use via tokenization. Support payment method updates for expired cards.
•Alternative Payment Methods — Support region-specific methods: iDEAL (Netherlands), Bancontact (Belgium), Boleto (Brazil), Konbini (Japan), etc.

Merchant Capabilities

•Merchant Onboarding — Self-service merchant registration with identity verification (KYC), business verification (KYB), and risk assessment.
•Dashboard & Reporting — Real-time transaction monitoring, financial reporting, settlement reports, and analytics dashboards.
•Payout Management — Configure payout schedules (daily, weekly, monthly). Support multiple bank accounts per merchant. Handle payout failures.
•Dispute Management — Receive chargeback notifications, submit evidence for dispute resolution, track dispute outcomes.
•Webhook Notifications — Real-time event notifications for payment lifecycle events (success, failure, refund, dispute, payout).
•API Access — RESTful APIs for payment processing, reporting, and configuration. SDKs for major programming languages.

Interview Tip: Scope Carefully

In a system design interview, you cannot cover all functional requirements in 45 minutes. Clarify with your interviewer which subset to focus on. A typical scope might be: 'Let's design the core payment processing flow—authorization, capture, and refund—for card payments, with stored credentials for repeat customers.' This gives you a focused problem while demonstrating awareness of the broader scope.

Non-Functional Requirements

Non-functional requirements define how well the system must perform. For payment systems, these requirements are exceptionally stringent—financial systems cannot afford the relaxed consistency or "good enough" availability acceptable in other domains.

Non-Functional Requirements for Payment Systems
Requirement	Target	Justification	Consequence of Failure
Availability	99.99% - 99.999% (4-5 nines)	Payment failures directly translate to lost revenue	Lost sales, customer churn, SLA penalties
Latency (P99)	< 500ms end-to-end	Customer abandonment increases sharply with latency	Cart abandonment, poor user experience
Throughput	10,000 - 1,000,000+ TPS	Handle peak loads during sales events, Black Friday	System collapse during high-value periods
Consistency	Strong consistency for transactions	Double-charging or lost payments are unacceptable	Financial loss, legal liability, customer trust
Durability	Zero transaction loss	Every transaction must be recorded and recoverable	Financial reconciliation failures, audit failures
Security	PCI DSS Level 1 compliance	Legal requirement for card data handling	Fines up to $500K/month, losing ability to process cards
Auditability	Complete transaction history	Regulatory requirements, dispute resolution	Compliance violations, failed audits

Let's analyze each requirement in depth:

Availability Deep Dive

•99.99% availability = ~52 minutes downtime per year. For major payment processors, even this is too high.
•99.999% availability = ~5 minutes downtime per year. This is the target for critical financial infrastructure.
•Availability must be measured per-endpoint. Core payment endpoints may require 5 nines while reporting can tolerate lower.
•Degraded availability is preferred to complete outage. If full processing fails, queue transactions for later processing rather than rejecting.
•Geographic availability — The system must remain available even during regional cloud provider outages. Multi-region active-active deployment is essential.

Latency Deep Dive

•P50 (median) latency should be under 100ms for the payment service itself. External gateway calls add 200-500ms.
•P99 latency (worst 1%) matters more than average. A P99 of 2 seconds means 1 in 100 customers wait 2+ seconds.
•Latency budget allocation: Your service (~100ms) + Payment gateway (~200ms) + Card network (~100ms) + Issuer (~100ms) = ~500ms total.
•Timeouts must be carefully tuned. Too short = false failures. Too long = poor user experience and resource exhaustion.
•Async processing for non-critical paths. Settlement, reconciliation, and reporting can be processed asynchronously.

Consistency vs. Availability Trade-off

Payment systems are one of the few domains where you cannot trade consistency for availability. Double-charging a customer or losing a payment is never acceptable. This means payment systems often choose CP (Consistency + Partition tolerance) over AP in CAP theorem terms, accepting potential unavailability during network partitions rather than risking inconsistent state.

Back-of-Envelope Scale Estimation

Before designing a system, we must understand the scale we're designing for. Let's work through a realistic estimation for a mid-to-large-scale payment processor.

Assumptions:

100,000 merchants on our platform
Average merchant processes 1,000 transactions/day
Average transaction amount: $50
Peak traffic: 10x average (Black Friday, flash sales)
Geographic distribution: Global (US, EU, APAC)

scale-estimation.md
## Transaction Volume Estimation
 
### Daily Transactions
- Merchants: 100,000
- Transactions per merchant per day: 1,000
- Daily transactions: 100,000 × 1,000 = 100,000,000 (100M transactions/day)
 
### Transactions Per Second (TPS)
- Seconds per day: 86,400
- Average TPS: 100,000,000 / 86,400 ≈ 1,157 TPS
- Peak TPS (10x): ~11,570 TPS
- Design target (with headroom): 20,000 TPS
 
### Daily Payment Volume
- Average transaction: $50
- Daily volume: 100M × $50 = $5 billion/day
- Annual volume: ~$1.8 trillion/year
 
## Storage Estimation
 
### Transaction Record Size
- Transaction ID: 16 bytes (UUID)
- Merchant ID: 16 bytes
- Customer ID: 16 bytes
- Amount/Currency: 12 bytes
- Status: 4 bytes
- Timestamps: 16 bytes
- Payment method token: 64 bytes
- Metadata (JSON): ~500 bytes
- Total per transaction: ~650 bytes
 
### Daily Storage
- Transactions: 100M × 650 bytes = 65 GB/day
- With indexes (2x): 130 GB/day
- Monthly: ~4 TB
- Yearly: ~48 TB (before archival)
 
### Hot Storage (90 days)
- 90 × 130 GB = 11.7 TB hot storage
 
## Bandwidth Estimation
 
### Request Size
- Average API request: 2 KB
- Average API response: 1 KB
 
### Daily Bandwidth
- Inbound: 100M × 2 KB = 200 GB/day
- Outbound: 100M × 1 KB = 100 GB/day
- Total: 300 GB/day ≈ 28 Mbps average
- Peak (10x): 280 Mbps

Interview Tip: Show Your Math

In interviews, always show your calculations explicitly. Even if your numbers aren't perfect, interviewers want to see structured thinking. Round aggressively (100M not 100,000,000) and always add headroom for growth (2-3x current estimates).

Unique Challenges of Payment Systems

Payment systems face challenges that are either unique to financial systems or present at a severity level not seen in typical applications. Understanding these challenges is essential for designing robust payment infrastructure.

Critical Challenges

•Exactly-Once Processing — Unlike most distributed systems where "at-least-once" is acceptable, payment systems must guarantee exactly-once semantics. Charging a customer twice is a critical failure. This requires sophisticated idempotency mechanisms.
•External System Dependencies — Payment processing depends on external parties (card networks, banks) with their own latency, availability, and reliability characteristics. Your 99.99% availability target depends on systems you don't control.
•Regulatory Complexity — PCI DSS for card data, GDPR for European data, PSD2/SCA for strong authentication, state money transmitter licenses (US), and dozens of country-specific regulations. Non-compliance isn't a bug—it's a legal crisis.
•Long-Lived Transactions — A payment that appears complete today can be disputed 120 days later. Your system must maintain complete audit trails and support retroactive modifications for extended periods.
•Money as Mutable State — Unlike typical database records, money must balance. Every credit must have a corresponding debit. Off-by-one errors accumulate into significant discrepancies at scale.
•Fraud Arms Race — Fraudsters continuously probe for vulnerabilities. Your fraud detection must evolve faster than attack patterns while minimizing false positives that reject legitimate customers.

What Makes Payments Hard

•Cannot retry failed transactions blindly
•Must handle partial failures (auth succeeded, capture failed)
•Must reconcile with external systems daily
•Must support rollback weeks/months later
•Must maintain PCI compliance 24/7/365
•Must handle currency edge cases (rounding, conversion)

What Payments Get Right

•Well-defined transaction states and transitions
•Industry-standard protocols (ISO 8583, ISO 20022)
•Clear ownership and liability rules
•Mature tooling for reconciliation
•Established patterns for idempotency
•Strong incentives for all parties to cooperate

The Double-Charge Problem

Consider this scenario: A customer clicks "Pay," the request reaches your server, you call the payment gateway, the gateway charges the card successfully, but the response times out before reaching your server. Is the payment successful? If you retry, you'll double-charge. If you don't, you might lose the payment. This exact scenario is why idempotency is the most critical design consideration in payment systems.

API Contract Design Considerations

Before implementation, we must define the API contract. Payment APIs have particular requirements around clarity, safety, and compatibility that differ from typical REST APIs.

payment-api-contract.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
// Core Payment API Types
 
interface CreatePaymentRequest {
  // Idempotency key - REQUIRED for safe retries
  idempotencyKey: string;  // UUID, unique per intended payment
  
  // Amount in smallest currency unit (cents for USD)
  amount: number;          // 1000 = $10.00
  currency: string;        // ISO 4217 code: "USD", "EUR", "GBP"
  
  // Payment method (token, not raw card data)
  paymentMethodId: string; // Token from secure tokenization
  
  // Merchant context
  merchantId: string;
  orderId?: string;        // Merchant's order reference
  
  // Customer context (for fraud detection)
  customerId?: string;
  customerEmail?: string;
  customerIp?: string;
  
  // Processing options
  captureMethod: 'automatic' | 'manual';  // Auth+capture or auth-only
  
  // Metadata for merchant's use
  metadata?: Record<string, string>;
}
 
interface PaymentResponse {
  id: string;              // Our payment ID
  status: PaymentStatus;
  amount: number;
  currency: string;
  
  // Processing details
  authorizationCode?: string;
  networkTransactionId?: string;
  
  // Outcome details
  outcome: {
    networkStatus: 'approved' | 'declined' | 'pending';
    type?: 'issuer_declined' | 'fraud' | 'invalid' | 'network_error';
    reason?: string;
    riskScore?: number;
  };
  
  // Timestamps
  createdAt: string;       // ISO 8601
  updatedAt: string;
  authorizedAt?: string;
  capturedAt?: string;
  
  // Idempotency tracking
  idempotencyKey: string;
  idempotentReplayed: boolean;  // True if this was a replay
}
 
type PaymentStatus = 
  | 'pending'           // Created, not yet processed
  | 'requires_action'   // Needs 3DS or other auth
  | 'processing'        // Being processed
  | 'authorized'        // Auth successful, not captured
  | 'succeeded'         // Captured successfully
  | 'failed'            // Permanently failed
  | 'canceled'          // Voided before capture
  | 'refunded'          // Fully refunded
  | 'partially_refunded'; // Partially refunded
 
// Error response structure
interface PaymentError {
  code: string;          // Machine-readable code
  message: string;       // Human-readable message
  type: 'card_error' | 'validation_error' | 'api_error' | 'idempotency_error';
  declineCode?: string;  // Card network decline code
  param?: string;        // Which parameter caused the error
  requestId: string;     // For support/debugging
}

Key API Design Principles:

•Smallest Currency Unit — Always use integers in smallest currency unit (cents, pence). Never use floating-point for money. amount: 1000 = $10.00.
•Required Idempotency Keys — Make idempotency keys mandatory, not optional. Clients must think about retry safety from the start.
•Token-Based Payment Methods — Never accept raw card numbers in payment requests. Require tokenized payment methods from secure card capture.
•Explicit Capture Method — Force clients to specify capture intent. Default behavior should be the safest option.
•Comprehensive Error Responses — Include machine-readable codes, human-readable messages, and specific decline reasons. Enable clients to handle errors programmatically.
•Request ID in Every Response — Include a unique request ID for correlation across systems and support requests.

Payment State Machine

Payment transactions follow a well-defined state machine. Understanding valid state transitions is crucial for implementing correct payment logic and handling edge cases.

Converting Mermaid diagram...

Critical State Transition Rules:

•Irreversibility — Once a payment reaches failed, canceled, or refunded, it cannot transition to any other state. These are terminal states.
•Authorization Expiry — Authorizations expire (typically 7 days for card payments). Expired authorizations cannot be captured and must be re-authorized.
•Capture Finality — Once captured (succeeded), a payment cannot be voided—only refunded. Void is cheaper than refund, so prefer voiding when possible.
•Dispute Complexity — Disputes can occur on any succeeded or refunded payment. Dispute resolution is asynchronous and can take months.
•Partial Operations — Partial captures and refunds create complex state. Track amount_captured and amount_refunded separately from original amount.

Invalid State Transitions

Never allow: failed → succeeded (retry creates new payment), refunded → authorized (refunds are final), canceled → processing (cancellation is terminal). Invalid state transitions indicate bugs or fraud attempts. Log and alert on any attempts.

Summary: Payment System Requirements

We've established a comprehensive requirements foundation for designing a payment system. Let's consolidate the key takeaways:

Key Takeaways

•Payment systems involve multiple stakeholders — Customer, merchant, gateway, processor, card network, issuing bank, and acquiring bank all participate in each transaction.
•Payments are multi-phase operations — Authorization, capture, settlement, and potential dispute are distinct phases with different timing and failure modes.
•Non-functional requirements are stringent — 99.99%+ availability, sub-second latency, strong consistency, and zero data loss are baseline expectations.
•Scale estimation drives design — Understanding transaction volume, storage needs, and bandwidth requirements informs architectural decisions.
•Unique challenges require specialized solutions — Exactly-once processing, external dependencies, regulatory compliance, and long-lived transactions differentiate payment systems from typical applications.
•API contracts must prioritize safety — Mandatory idempotency keys, tokenized payment methods, smallest currency units, and comprehensive error handling are essential.
•State machines provide correctness — Well-defined states and valid transitions prevent bugs and enable audit trails.

What's Next:

With requirements established, we'll dive into payment gateway integration in the next page. We'll explore how to connect with external payment processors, handle their diverse APIs and protocols, implement fallback routing for resilience, and manage the complexity of multi-gateway architectures.

Page Complete

You now understand the comprehensive requirements for designing a production-grade payment system. These requirements will guide every architectural decision in subsequent pages—from gateway integration through fraud detection to regulatory compliance.