# yatinsharda/payment-gateway-system-design architecture

> Architecture diagram of the GitHub repository yatinsharda/payment-gateway-system-design, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yatinsharda/payment-gateway-system-design
- Repository: https://github.com/yatinsharda/payment-gateway-system-design

## Overview

This repository is a system-design document for a payment gateway, not an implementation. Its principal workflow is a merchant request entering through the API Gateway, being authenticated, then orchestrated by the Payment Service through idempotency, risk checks, tokenization and processor routing. The design also documents payment lifecycle operations, ledger records, asynchronous webhooks and reconciliation. Relationships below follow the README’s diagrams and prose; the tree contains no service source, so implementation-level wiring is not available.

Main entry points: [`README.md`](https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md) (Payment Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Merchant Entry"]
  node_api["API Gateway<br/>[README.md]"]
  node_auth["Auth Service<br/>[README.md]"]
end

subgraph group_payments["Payment Processing"]
  node_payment["Payment Service<br/>[README.md]"]
  node_token["Tokenization<br/>[README.md]"]
  node_risk["Risk Service<br/>[README.md]"]
  node_router["Payment Router<br/>[README.md]"]
end

subgraph group_records["Records and Events"]
  node_paymentdb[("Payment Database<br/>[README.md]")]
  node_cache[("Redis Cache<br/>[README.md]")]
  node_ledger[("Ledger Database<br/>[README.md]")]
  node_broker["Message Broker<br/>[README.md]"]
end

subgraph group_operations["Operations"]
  node_webhook["Webhook Service<br/>[README.md]"]
  node_reconcile["Reconciliation Service<br/>[README.md]"]
  node_observability["Monitoring / Logging<br/>[README.md]"]
end

node_customer(("Customer"))
node_merchant(("Merchant App"))
node_processors["Processors / Acquirers"]

node_customer -->|"initiates payment"| node_merchant
node_merchant -->|"sends requests"| node_api
node_api -->|"authenticates"| node_auth
node_api -->|"routes requests"| node_payment
node_payment -->|"checks idempotency"| node_cache
node_payment -->|"reads and writes"| node_paymentdb
node_payment -->|"tokenizes method"| node_token
node_payment -->|"checks risk"| node_risk
node_payment -->|"routes payment"| node_router
node_router -->|"sends transactions"| node_processors
node_processors -->|"returns decisions"| node_router
node_payment -->|"records entries"| node_ledger
node_payment -->|"publishes events"| node_broker
node_broker -->|"dispatches events"| node_webhook
node_webhook -->|"sends webhooks"| node_merchant
node_reconcile -->|"compares records"| node_processors
node_reconcile -->|"reads records"| node_paymentdb
node_reconcile -->|"reads records"| node_ledger
node_api -->|"reports telemetry"| node_observability
node_payment -->|"reports telemetry"| node_observability
node_router -->|"reports telemetry"| node_observability
node_webhook -->|"reports telemetry"| node_observability

click node_api "https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md"
click node_auth "https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md"
click node_payment "https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md"
click node_token "https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md"
click node_risk "https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md"
click node_router "https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md"
click node_paymentdb "https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md"
click node_cache "https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md"
click node_ledger "https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md"
click node_broker "https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md"
click node_webhook "https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md"
click node_reconcile "https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md"
click node_observability "https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_auth toneBlue
class node_payment,node_token,node_risk,node_router toneAmber
class node_paymentdb,node_cache,node_ledger,node_broker toneMint
class node_webhook,node_reconcile,node_observability toneRose
class node_customer,node_merchant,node_processors toneIndigo
```

## Components

### Merchant Entry

- [API Gateway](https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md): `README.md`
- [Auth Service](https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md): `README.md`

### Payment Processing

- [Payment Service](https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md): `README.md`
- [Tokenization](https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md): `README.md`
- [Risk Service](https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md): `README.md`
- [Payment Router](https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md): `README.md`

### Records and Events

- [Payment Database](https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md): `README.md`
- [Redis Cache](https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md): `README.md`
- [Ledger Database](https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md): `README.md`
- [Message Broker](https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md): `README.md`

### Operations

- [Webhook Service](https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md): `README.md`
- [Reconciliation Service](https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md): `README.md`
- [Monitoring / Logging](https://github.com/yatinsharda/payment-gateway-system-design/blob/main/README.md): `README.md`

### Other components

- **Customer**
- **Merchant App**
- **Processors / Acquirers**

## Connections

- Customer → Merchant App: initiates payment
- Merchant App → API Gateway: sends requests
- API Gateway → Auth Service: authenticates
- API Gateway → Payment Service: routes requests
- Payment Service → Redis Cache: checks idempotency
- Payment Service → Payment Database: reads and writes
- Payment Service → Tokenization: tokenizes method
- Payment Service → Risk Service: checks risk
- Payment Service → Payment Router: routes payment
- Payment Router → Processors / Acquirers: sends transactions
- Processors / Acquirers → Payment Router: returns decisions
- Payment Service → Ledger Database: records entries
- Payment Service → Message Broker: publishes events
- Message Broker → Webhook Service: dispatches events
- Webhook Service → Merchant App: sends webhooks
- Reconciliation Service → Processors / Acquirers: compares records
- Reconciliation Service → Payment Database: reads records
- Reconciliation Service → Ledger Database: reads records
- API Gateway → Monitoring / Logging: reports telemetry
- Payment Service → Monitoring / Logging: reports telemetry
- Payment Router → Monitoring / Logging: reports telemetry
- Webhook Service → Monitoring / Logging: reports telemetry