Payment System

Overview

Designing a Payment System tests your understanding of financial transactions, idempotency, and consistency. The core challenges include: processing payments reliably (no double charges, no lost payments), integrating with payment gateways (Stripe, PayPal), handling refunds and disputes, and maintaining audit trails. This design matters in interviews because payment systems have strict correctness requirements—money is involved—and you must demonstrate you understand idempotency keys, idempotent retries, and eventual consistency vs strong consistency. Companies like Stripe, Square, and PayPal build these systems, and showing you can design for failure (network issues, timeouts) and maintain a clear audit log demonstrates senior-level systems thinking.

Requirements

Functional

Process payments (card, wallet, bank transfer)
Support refunds and partial refunds
Idempotent operations (retry-safe)
Payment status tracking
Webhook for async notifications from gateway
Reconciliation and reporting

Non-Functional

Correctness — no double charge, no lost payment
Auditability — full transaction log
Availability — 99.99%
Compliance — PCI-DSS, data encryption

Capacity Estimation

Assume 10M transactions/day, $1B volume. Peak 1K TPS. Each transaction: auth, capture, webhook. Idempotency prevents duplicates on retry.

Architecture Diagram

Component Deep Dive

Payment API

Accepts payment requests. Validates, assigns idempotency key, forwards to gateway. Returns pending/success/failure.

Payment Gateway Adapter

Abstracts Stripe, PayPal, etc. Handles auth, capture, refund. Maps gateway errors to internal codes.

Idempotency Service

Stores idempotency_key → result. Prevents duplicate processing on retry. TTL 24h.

Transaction Store

Persistent log of all transactions. Append-only. Used for reconciliation, audit, dispute resolution.

Webhook Handler

Receives async events from gateway (payment confirmed, failed). Updates transaction state. Idempotent.

Reconciliation Service

Matches internal records with gateway settlement. Flags discrepancies. Runs daily.

Database Design

Transactions: id, idempotency_key, amount, status, gateway_ref, created_at. Idempotency: key (PK), result, created_at. PostgreSQL with strong consistency. Audit log append-only.

API Design

Method	Path	Description
`POST`	/api/v1/payments	Create payment. Header: Idempotency-Key. Body: {amount, currency, method}. Returns payment_id, status.
`GET`	/api/v1/payments/{id}	Get payment status.
`POST`	/api/v1/payments/{id}/refund	Refund. Idempotency-Key for partial refunds.
`POST`	/webhooks/gateway	Gateway webhook. Verifies signature, processes event.

Scalability & Trade-offs

Sync vs async: Sync auth gives immediate feedback; async capture reduces latency. Webhook for final status.
Idempotency: Client-provided key vs server-generated. Client key allows retry from client; server key simplifies client.
Consistency: Strong consistency for balance updates; eventual for reporting.

Related System Designs

Infrastructure