Payment Gateway — Notes

Functional

• Accept payments (cards, wallets, bank, BNPL, UPI, ACH).
• Tokenize sensitive card data.
• Authorize, capture, refund, dispute.
• Subscriptions / recurring billing.
• Webhooks to merchants.
• Reports & payouts.

Non-functional

• p99 authorize < 1 s; capture < 2 s.
• Strict financial correctness (no double charge, no lost capture).
• 99.99% gateway availability; PCI-DSS scope.

Capacity

• 1B+ txns/yr for big providers.
• Peak ~1k txn/s globally; bursts 10k+.

API

POST /v1/payment_intents          (Idempotency-Key required)
POST /v1/payment_intents/{id}/confirm
POST /v1/refunds
POST /v1/webhooks_secrets

Schema

• payment_intents(id, amount, currency, status, idem_key, version)
• charges(id, intent_id, network_ref, status, ts)
• ledger_entries(id, account_id, debit, credit, ref, ts) immutable
• webhook_events(id, intent_id, status, signature, delivered, attempts)

Trade-offs

• Strict idempotency keys non-negotiable.
• Append-only ledger simpler audit; reconciliation rebuilds balances.
• Network reliability: many small failures; design assumes 5xx is normal.
• PCI scope minimization: tokenize early, never touch PANs in app services.

Refs

• Stripe API guide; "Online Migrations at Stripe".
• "Sagas" (Garcia-Molina '87).
• Square / Adyen / PayPal architecture talks.
• ByteByteGo "Design payment system", Alex Xu Vol 2.