Payment Processing

The Problem

Accepting online payments is one of the highest-stakes features in software. A bug can charge customers twice, lose money, or create compliance violations. Payment processing requires integrating with payment gateways (Stripe, Adyen, Braintree), handling asynchronous payment flows (3D Secure, bank transfers), ensuring idempotency (never charge twice for the same operation), reconciling payments via webhooks, managing subscriptions and refunds, and maintaining PCI DSS compliance to protect card data. The system must be auditable, resilient to failures at any point in the flow, and eventually consistent between your database and the payment provider.

Architectural Approaches

Architecture

Loading diagram...

Key Components

Data Model

Loading diagram...

Idempotency in Payment Processing

Double-charging a customer is the worst bug in payment processing. Idempotency prevents it.

How it works:

1. Client generates a unique idempotency key (UUID v4) for each payment attempt
2. Client sends: POST /payments with header Idempotency-Key: abc-123
3. Server checks if key exists in the idempotency store
4. If found: return the cached response (same status, same payment ID)
5. If not found: process the payment, store the result keyed by the idempotency key

Storage: Redis with 24-48 hour TTL is ideal. Store the full response (status code + body) so retries return identical responses.

Race condition: Two requests with the same key arrive simultaneously. Use Redis SETNX (set-if-not-exists) as a distributed lock. The first request wins and processes; the second waits and returns the cached result.

Stripe’s approach: Stripe accepts an Idempotency-Key header on all POST requests. Results are cached for 24 hours. If the same key is sent with different parameters, Stripe returns a 400 error — the key is tied to the original request parameters.

Critical rule: The idempotency key must be generated by the client, not the server. If the server generates it, a network failure between server and client means the client can’t retry with the same key.

Webhook-Driven Payment State Machine

Payments are inherently asynchronous. A credit card charge may go through 3D Secure, bank verification, and fraud checks before succeeding or failing. Model payments as a state machine driven by gateway webhooks.

Payment states: created → processing → requires_action → succeeded → (refunded)

Webhook events (Stripe example):

• payment_intent.created → set status to “processing”
• payment_intent.requires_action → redirect user to 3D Secure
• payment_intent.succeeded → fulfill order, update ledger
• payment_intent.payment_failed → notify customer, allow retry
• charge.refunded → update ledger, notify customer

Reliability rules:

1. Process webhooks idempotently — Stripe may send the same event multiple times. Use the event ID for deduplication.
2. Verify webhook signatures — Stripe signs webhooks with HMAC. Verify before processing.
3. Return 200 quickly — Process the webhook asynchronously (enqueue and ack). Stripe retries if you don’t respond within 20 seconds.
4. Don’t rely solely on webhooks — Use webhooks as the primary signal but also poll the payment status API as a backup. Belt and suspenders.
5. Handle out-of-order events — A “succeeded” event may arrive before a “processing” event. Check the current state before applying transitions.

PCI Compliance Strategy

PCI DSS (Payment Card Industry Data Security Standard) has strict requirements for handling card data. Minimizing your PCI scope saves months of compliance work.

SAQ-A (minimal scope): Use hosted payment fields (Stripe Elements, Adyen Drop-in). Card numbers are entered in an iframe served by the gateway. Your servers never see card data. Easiest compliance — a self-assessment questionnaire.

SAQ A-EP: Your server serves the payment page but card data is submitted directly to the gateway (JavaScript tokenization). More scope than SAQ-A but less than full PCI.

Full PCI DSS: If you handle raw card numbers (e.g., call center, legacy integration), you need full compliance: network segmentation, encryption, access controls, penetration testing, annual audits. Extremely expensive and time-consuming.

Best practice: Always use SAQ-A. Never let card data touch your infrastructure.

Token vault: If you need to store payment methods for recurring billing, use the gateway’s token vault. Stripe stores the card and gives you a payment method ID (pm_xxx). You store only the ID, not the card number.

Logging: Never log card numbers, CVVs, or full card details. If you accidentally log them (stack traces, request logging), you’ve expanded your PCI scope. Use middleware to redact sensitive fields from logs.

Real-World Examples

Architectural Tradeoffs

# Learn the System Design of: Payment Processing

You are an expert software architect and teacher. I want to understand payment processing as a practical system design capability. (Idempotent charges, webhook reconciliation, and PCI compliance for online payments).

Use the following architectural guide as a learning reference. Avoid one-size-fits-all recommendations. Keep assumptions, costs, and tradeoffs explicit.

---

import { Mermaid, ComponentList, ComponentCard, ApproachList, Approach, Example, Tradeoff } from '@/components/mdx';

## The Problem

Accepting online payments is one of the highest-stakes features in software. A bug can charge customers twice, lose money, or create compliance violations. Payment processing requires integrating with payment gateways (Stripe, Adyen, Braintree), handling asynchronous payment flows (3D Secure, bank transfers), ensuring idempotency (never charge twice for the same operation), reconciling payments via webhooks, managing subscriptions and refunds, and maintaining PCI DSS compliance to protect card data. The system must be auditable, resilient to failures at any point in the flow, and eventually consistent between your database and the payment provider.

## Architectural Approaches

<ApproachList>
<Approach
  name="Payment Gateway Integration (Stripe, Adyen)"
  pros={[
    'PCI scope is minimized — card data never touches your servers',
    'Mature SDKs handle edge cases (3D Secure, retries, currency conversion)',
    'Built-in fraud detection and risk scoring',
    'Comprehensive dashboard for payment operations',
  ]}
  cons={[
    'Per-transaction fees (2.9% + $0.30 typical for Stripe)',
    'Vendor dependency for a critical business function',
    'Complex webhook integration for async payment events',
    'Each gateway has its own API patterns and quirks',
  ]}
>
Integrate directly with a payment gateway API. Your server creates payment intents, the client collects card details via the gateway's embedded UI (Stripe ...

[Full prompt copied to clipboard]