Designing a Payment System

Payment systems require the highest levels of reliability, consistency, and security.

Core Requirements

• Process payments reliably (no double charges)
• Handle failures gracefully
• Fraud detection
• Reconciliation
• PCI DSS compliance

Idempotency

The most critical property: same request processed twice = same outcome.

Client → Payment Service with idempotency_key

First call:  Process + Store result by key
Second call: Return stored result (don't charge again)

Architecture

Client → API Gateway
           ↓
    Payment Service
    ↙            ↘
Ledger DB     Payment Processor
(PostgreSQL)  (Stripe/Adyen/Braintree)
           ↓
     Reconciliation Service

Double-Entry Ledger

Debit:  User Account     -$100
Credit: Merchant Account +$100

Sum of all entries always = 0

Exactly-Once Payment Flow

1. Create payment record (Pending) with idempotency_key
2. Call payment processor
3. On success: Update to Completed
4. On failure: Update to Failed
5. On timeout: Query processor for status

Fraud Detection

Rule-based + ML hybrid:

Rules: Amount > $5000 AND new device → Flag
ML: Anomaly detection on transaction patterns

Reconciliation

Daily job: Compare internal ledger with payment processor statements. Flag any discrepancies for manual review.

Conclusion

Idempotency + double-entry ledger + reconciliation are the three pillars of reliable payment systems.