Payment Gateway (Stripe-like) — Detailed

flowchart TB
  subgraph Merchant
    CHK([Checkout JS / SDK])
    SRV[Merchant server]
  end

  subgraph Edge
    CDN
    GW[Payments API gateway]
    WAF
    IDEM[Idempotency layer]
  end

  subgraph Core
    INTENT[PaymentIntent service]
    METHOD[PaymentMethod service]
    TOK[Tokenization Vault<br/>PCI scope]
    AUTH[Authorization service]
    CAP[Capture / settle]
    REFUND[Refund]
    DISP[Dispute / chargeback]
    SUB[Subscriptions / billing]
  end

  subgraph Networks[Acquirer / Networks]
    ACQ[Acquiring bank]
    NET[Visa / MC / Amex network]
    ISS[Issuer bank]
    THREE[3DS / SCA]
    AFT[ACH / SEPA / RTP]
    ALT[Alt methods<br/>UPI / Wallets / BNPL]
  end

  subgraph Risk
    RISK[Risk engine ML]
    RULES[Rule engine]
    REV[Manual review]
    BLOCK[Blocklists]
  end

  subgraph Ledger[Ledger & Reconciliation]
    LED[(Double-entry ledger)]
    RECONC([Reconciliation])
    REPORT[Reports / 1099]
  end

  subgraph Payout
    BAL[Balance service]
    PAYOUT[Payout service]
  end

  subgraph WHK[Webhooks Out]
    WHKQ[[Outbound queue]]
    DEL[Delivery + retry]
    DLQ[[(DLQ)]]
  end

  subgraph Compliance
    PCI[PCI DSS network seg]
    KMS[KMS / HSM keys]
    AUDIT[Audit log]
    KYC[KYC / AML / OFAC]
  end

  CHK --> GW
  SRV --> GW
  GW --> IDEM --> Core
  Core --> Networks
  Networks --> ISS
  ISS -. authorize .-> Networks --> Core
  Risk -. score .-> AUTH
  AUTH --> LED
  CAP --> LED
  REFUND --> LED
  LED --> RECONC --> Payout
  Core --> WHKQ --> DEL --> SRV
  DEL --> DLQ
  Compliance --- TOK
  Compliance --- LED

    classDef client fill:#dbeafe,stroke:#1e40af,stroke-width:1px,color:#0f172a;
    classDef edge fill:#cffafe,stroke:#0e7490,stroke-width:1px,color:#0f172a;
    classDef service fill:#fef3c7,stroke:#92400e,stroke-width:1px,color:#0f172a;
    classDef datastore fill:#fee2e2,stroke:#991b1b,stroke-width:1px,color:#0f172a;
    classDef cache fill:#fed7aa,stroke:#9a3412,stroke-width:1px,color:#0f172a;
    classDef queue fill:#ede9fe,stroke:#5b21b6,stroke-width:1px,color:#0f172a;
    classDef compute fill:#d1fae5,stroke:#065f46,stroke-width:1px,color:#0f172a;
    classDef storage fill:#e5e7eb,stroke:#374151,stroke-width:1px,color:#0f172a;
    classDef external fill:#fce7f3,stroke:#9d174d,stroke-width:1px,color:#0f172a;
    classDef obs fill:#f3e8ff,stroke:#6b21a8,stroke-width:1px,color:#0f172a;
    class CHK client;
    class GW edge;
    class SRV,IDEM,INTENT,METHOD,TOK,AUTH,CAP,REFUND,DISP,SUB,ACQ,NET,ISS,THREE,AFT,ALT,RISK,RULES,REV,BLOCK,REPORT,BAL,PAYOUT,DEL,PCI,KMS,KYC service;
    class LED,DLQ datastore;
    class WHKQ queue;
    class RECONC compute;
    class AUDIT obs;

Authorization flow (card)

1. Merchant collects card → tokenizes via vault → token returned.
2. Merchant calls POST /payment_intents with token + amount + idempotency key.
3. Risk score; if pass → submit to acquirer.
4. Acquirer routes to network → issuer authorizes (hold).
5. Later, capture (settle) → funds move.
6. Webhooks fire to merchant at each state.

Ledger

• Double-entry: every event credits one account, debits another.
• Append-only; balances are projections / materialized views.
• Reconciliation periodically reconciles internal vs acquirer statements.

Risk

• Real-time ML + rules combine velocity, BIN, geo, device fingerprint, blocklists.
• Strong Customer Authentication (3DS) triggered on suspicion / regulatory.

Webhooks

• At-least-once; signed body; idempotent on merchant side.
• Retries with backoff up to days; DLQ + manual replay.

Glossary & fundamentals

Concepts referenced in this design. Each row links to its canonical page; the tag column shows whether it is a high-level (HLD) or low-level (LLD) concept.

Tag	Concept	What it is	Page
HLD	CDN	edge caching for static assets	cdn
HLD	API gateway / BFF	single ingress, auth, rate limit, routing	api-gateway
HLD	Pub/Sub & message brokers	topics, consumer groups, delivery semantics	pub-sub-pattern
HLD	CAP / PACELC	C vs A under partition; L vs C otherwise	cap-pacelc
HLD	Idempotency & retries	safe re-execution, backoff + jitter	idempotency-retries
LLD	REST API design	verbs, statuses, pagination, errors	rest-api-design