+
+ | Requirement |
+ Description |
+
+
+ | Payment method support |
+ Allow merchants to accept payments via multiple payment methods such as card, netbanking, UPI, etc. |
+
+
+ | Manage payment transaction |
+ Create a transaction when a user initiates a payment and track its lifecycle (created, auth_pending, authorized, failed, refunded). |
+
+
+ | Payment authorization |
+ Send payment requests to the appropriate payment networks/banks and receive authorization or rejection responses. |
+
+
+ | Refunds |
+ Allow merchants to initiate refunds against a successful payment and track the refund lifecycle. |
+
+
+ | Webhook notifications |
+ Notify merchant backend asynchronously for key payment events (e.g., payment.authorized, payment.failed, payment.refunded) so merchant systems can update order state reliably. |
+
+
+ | Idempotent write operations |
+ Prevent duplicate charges/duplicate resources when the same request is retried due to network failures or client retries (especially for write operations like initiating or paying). |
+
+
+
+### Non-Functional Requirements
+
+
+
+ | Requirement |
+ Description |
+
+
+ | Consistency |
+ Maintain correct and consistent transaction states. A payment should never result in conflicting states such as both success and failure. |
+
+
+ | Security |
+ Protect sensitive financial data using strong encryption in transit and at rest, with strict access controls and least-privilege. |
+
+
+ | Availability |
+ Remain highly available (e.g., 99.99% uptime) so that merchants can continue accepting payments even during peak traffic. |
+
+
+ | Scalability |
+ Handle large spikes in transaction volume, especially during peak shopping periods or promotional events. |
+
+
+ | Durability |
+ Guarantee that no transaction record is ever lost when infrastructure fails. |
+
+
+ | Auditability |
+ Maintain detailed logs and records of all payment activities to support auditing, dispute resolution, and regulatory compliance. |
+
+
+
+---
+
+## API Design
+### Initiate
+This endpoint starts the payment process by creating a transaction record in the gateway and generating a secure checkout URL for the customer.
+
+
+
+#### HTTP Method & Endpoint
+We use the **POST** method to create a new payment resource. The endpoint is `/v1/payments`
+
+#### HTTP Request Header
+* **Authorization**: Merchant Secret Key (Bearer token). This authenticates the merchant and the payment gateway
+* **Idempotency-Key**: A unique string to prevent duplicate payment creation during retries.
+
+#### HTTP Request Body
+
+```json
+{
+ "orderId": "order123",
+ "merchantCustomerId": "customerId123",
+ "amount": "90",
+ "tax": "10",
+ "currency": "INR",
+ "productInfo": {
+ "name": "Garnier Facewash",
+ "quantity": 1
+ }
+}
+```
+
+> Note: `amount` and `tax` are strings intentionally to avoid floating point precision issues. In production systems, money is typically stored/processed as an integer in the smallest currency unit (e.g., paise/cents) or as a fixed-precision decimal (Ex: 19.99 not 19.999999999).
+
+#### HTTP Response
+```json
+{
+ "paymentId": "payment123",
+ "paymentPageUrl": "https://payments.com/v1/payments/payment123/payselect?sessionToken=xyz"
+}
+```
+> paymentId - unique identifier of the payment transaction for the checkout.
+
+---
+
+### Pay
+#### Register Payment Method
+
+This endpoint securely adds the customer's payment details to the system. For example, for a card payment, we collect and save card number, and expiry.
+
+
+
+**HTTP Method & Endpoint**
+
+We use the **POST** method to securely register a new payment instrument. The endpoint is `/v1/payments/payment-methods`. Note that we didn't use `/v1/payments/{paymentId}/payment-methods` because adding a card is not specifically tied to a checkout flow. The added card can be used in the future for other checkouts as-well.
+
+**HTTP Request Header**
+
+* **sessionToken**: The random string received from the `paymentPageUrl`. This proves the user has an active, valid session.
+
+**HTTP Request Body**
+
+```json
+{
+ "cardNumber": "4242424242424242",
+ "expiry": {
+ "month": "08",
+ "year": "2027"
+ },
+ "cvv": "123"
+}
+```
+
+> For simplicity, card details in the request body are added as plain text. As the card details are sensitive information, the real payment system will encrypt the data using **client-side encryption** before sending it to the server. We will discuss more about this in the [high level design section](#payment-registration).
+
+**HTTP Response**
+
+```json
+{
+ "paymentMethodId": "paymentMethod123",
+ "displayString": "Visa Card ending in 4242",
+ "expiry": {
+ "month": "08",
+ "year": "2027"
+ }
+}
+```
+
+---
+
+#### Make Payment
+
+This endpoint executes the actual payment attempt. It connects the `paymentId` with the chosen `paymentMethodId` and triggers the communication with the bank or card network.
+
+
+
+#### HTTP Method & Endpoint
+
+We use the **POST** method to execute the transaction. The endpoint is `/v1/payments/{paymentId}/pay`
+
+#### HTTP Request Header
+
+* **sessionToken**: Required for user authentication.
+* **Idempotency-Key**: A unique string to prevent double charge if the client retries this request.
+
+#### HTTP Request Body
+
+```json
+{
+ "paymentMethodId": "paymentMethod123"
+}
+
+```
+
+#### HTTP Response
+
+```json
+{
+ "paymentId": "payment123",
+ "status": "PENDING",
+ "nextAction": {
+ "type": "REDIRECT",
+ "method": "GET",
+ "url": "https://hdfcbank.com/netbanking/login?token=bank_auth_999&returnUrl=https://payment.com/v1/payment/redirect",
+ "description": "Redirecting customer to HDFC Bank for authentication"
+ },
+ "metadata": {
+ "expiry": "2026-03-14T11:00:00Z",
+ "orderId": "order123"
+ }
+}
+```
+
+### Payment Status
+
+This endpoint allows the frontend to verify if a payment was successful after the user returns from the bank redirect.
+
+
+
+#### HTTP Method & Endpoint
+
+We use the **GET** method to retrieve the current state. The endpoint is `/v1/payments/{paymentId}`
+
+#### HTTP Request Parameter
+
+* **paymentId**: Passed in the URL path to identify the specific transaction.
+
+#### HTTP Request Header
+
+* **sessionToken**: Required to securely access the status of this specific session.
+
+#### HTTP Response
+
+```json
+{
+ "status": "SUCCESS",
+ "paymentId": "payment123"
+}
+
+```
+
+---
+
+### Refund
+
+Refunds are initiated by the **merchant backend** (for example from a customer support tool) after a payment has succeeded/authorized. Refund is a critical write operation, so it must be idempotent.
+
+
+
+#### HTTP Method & Endpoint
+
+We use the **POST** method to create a refund resource for a payment. The endpoint is `/v1/payments/{paymentId}/refunds`.
+
+#### HTTP Request Header
+
+* **Authorization**: Merchant Secret Key (Bearer token). This authenticates the merchant and the payment gateway.
+* **Idempotency-Key**: A unique string to prevent duplicate refunds if the merchant retries the request.
+
+#### HTTP Request Body
+
+```json
+{
+ "reason": "CUSTOMER_REQUEST"
+}
+```
+
+#### HTTP Response
+
+```json
+{
+ "refundId": "refund123",
+ "paymentId": "payment123",
+ "status": "REFUND_PENDING"
+}
+```
+
+---
+
+## High Level Design
+
+The payment system can support multiple payment methods such as **cards, UPI, and netbanking**. Each method follows a slightly different workflow and may involve different systems. For example, Cards involve Card Network, UPI involves UPI system, and Netbanking involves direct integration with the bank.
+
+To keep the explanation simple, this article uses **card payments as an example**. The overall system design remains similar for other payment methods, with only some differences in the payment flow.
+
+### Payment Initiation
+
+Payment initiation is the stage where a payment request is created by the merchant when the user starts the checkout process.
+
+
+
+1. User clicks "Buy Now" from the merchant's website. The request goes to the **Merchant Backend**
+2. **Merchant Backend** invokes the **Payment Gateway's** `/v1/payments` endpoint to initiate the payment. The **Merchant Backend** passes the Secret Key to authenticate itself with the **Payment Gateway**
+3. The **Payments API Gateway** receives the request and routes it to the **Payments Gateway Backend**.
+4. The **Payment Gateway** checks in the **Payment Database** if an existing payment session is available for the idempotency key sent by the merchant. If present, it fetches and returns the response immediately.
+5. If not present, The **Payment Gateway** creates a payment entry on the **Payment Database** to track the life cycle of the payment for the checkout flow.
+6. The **Payments Gateway Backend** creates a random session token and persists it in the **Session Cache**. The session token should be short lived and hence a TTL of 15 minutes is set on the cache entry. The session token will be linked to the paymentId in the session cache.
+ * There is a high risk of data loss when Session Cache cluster crash. To avoid this we can have a fallback backup like **Append Only File - AOF** in Redis which adds every cache entry to an append only log file. If the cache cluster crash, it is reconstructed from the AOF.
+7. The **Payment Gateway** generates the payment selection URL and returns it to the **Merchant Backend** via the **Payments API Gateway** (Step 7a and 7b).
+8. The **Merchant Backend** redirects the user to the payment selection URL sent by the Payment Gateway.
+
+### Payment Execution
+When the user is redirected to the payment selection page, the **Payment Gateway** fetches the payment methods configured for the merchant and displays them to the user. It also allows the user to add a new payment method, such as a credit or debit card.
+
+While rendering the page, the **Payment Gateway** also provides a public encryption key to the client. This key is used by the frontend to perform client-side encryption of sensitive card details before sending them to the backend. The corresponding private key is securely stored in the **Payment Processor's** system.
+
+
+
+#### Payment Registration
+
+
+
+ | Database |
+ Deciding Factors |
+ Decision |
+
+
+ | Payment Database |
+
+
+ - Financial Source of Truth – Stores payment transactions.
+ - Strong Consistency – A payment cannot be both success and failure.
+ - Durability – Payment records must never be lost.
+
+ |
+ Relational (ACID) |
+
+
+ | Payment Method Database |
+
+
+ - Stores tokenized card metadata – Card tail, expiry, token reference.
+ - Moderate read/write frequency.
+ - Data integrity important.
+
+ |
+ Relational |
+
+
+ | Merchant Database |
+
+
+ - Merchant configuration such as MID, Acquirer ID.
+ - Strong consistency required.
+
+ |
+ Relational |
+
+
+ | Payment Event Stream |
+
+
+ - Append-only events such as payment.authorized.
+ - High write throughput.
+ - Event-driven architecture.
+
+ |
+ Log-based system (Kafka / Pulsar) |
+
+
+ | Audit / Logging Database |
+
+
+ - Large volume of logs.
+ - Append-only events.
+ - Used for auditing and compliance.
+
+ |
+ NoSQL (Wide Column, e.g., Cassandra) |
+
+
+
+> A log-based streaming system (like Kafka) is an append-only distributed log where producers publish events and consumers read them in order. It fits payments well because it can handle high write throughput, allows replay for system recovery, and decouples event producers (processor) from multiple consumers (gateway, analytics).
+
+### Database Modelling
+#### Payment Schema
+
+
+
+* **Database Type:** Relational (ACID)
+* **Common Queries:**
+ * Fetch payment by `paymentId`
+ * Fetch payments for a merchant using `merchantId`
+ * Check payment status using `paymentId`
+* **Indexing:** `paymentId`, `merchantId`
+
+#### Payment Method Schema
+
+
+
+* **Database Type:** Relational
+* **Common Queries:**
+ * Fetch saved payment methods by `customerId`
+ * Fetch payment method details using `paymentMethodId`
+ * Retrieve token reference for processing payment
+* **Indexing:** `paymentMethodId`, `customerId`
+
+#### Merchant Schema
+
+
+
+* **Database Type:** Relational
+* **Common Queries:**
+ * Fetch merchant configuration using `merchantId`
+ * Retrieve acquiring bank configuration for payment routing
+* **Indexing:** `merchantId`
+
+#### Audit Log Schema
+
+
+
+* **Database Type:** NoSQL (Wide Column / Time-series, e.g., Cassandra)
+* **Common Queries:**
+ * Retrieve audit logs for a `paymentId`
+ * Fetch events within a time range for compliance checks
+ * Investigate suspicious activity using `merchantId`
+* **Indexing:** `paymentId`, `timestamp`, `merchantId`
+
+Audit logs are stored in an **append-only format** to maintain a permanent record of all payment-related activities.
+
+### Audit Payment Transactions
+Assume that a customer claims they were charged ₹500 but never completed the payment. Without proper audit logs, the payment gateway cannot determine whether:
+* The user actually initiated the payment
+* The bank authorized the transaction
+* The payment failed after authorization
+* A retry caused a duplicate payment attempt
+
+Auditability ensures that the system maintains a complete and verifiable history of all payment-related activities. This includes when the payment was created, when it was authorized, who initiated the action, and which systems were involved.
+
+
+
+### PCI DSS Compliance
+Payment systems handle sensitive data such as card numbers, CVV, and expiry dates. If this data leaks, attackers can directly steal money or perform fraudulent transactions. To prevent this, the payment industry follows a global security standard called **Payment Card Industry Data Security Standard**, commonly known as PCI DSS.
+
+PCI DSS focuses on protecting cardholder data such as Card Number, CVV, PIN, etc. PCI DSS enforces several requirements not limited to the below:
+
+* Encryption - Client side encryption, TLS
+* Strong Access Control - Only systems who need access to card data should have it.
+* Firewalls - Install and maintain network security controls.
+
+### Keeping Sensitive Data Secure
+A **Hardware Security Module (HSM)** is a special device that is used to securely store encryption keys. These keys are used to encrypt/decrypt sensitive data such as card numbers. In a normal system, an application might retrieve the encryption key from the storage, use it to encrypt/decrypt data. This means that the key temporarily exists in the application server’s memory, which can be risky if the system is compromised.
+
+With an HSM, the system **never retrieves the key**. Instead, the application sends the data that needs to be encrypted or decrypted to the HSM. The HSM performs the cryptographic operation internally using the key stored inside it and returns the result. The key always remains inside the HSM and is never exposed to the rest of the system.
+
+
+
+You can think of it like a **secure vault where the key always stays inside**. Normally, we would take the key out of a locker to lock or unlock something. With an HSM, we don’t take the key out. Instead, we bring the item to the vault, the operation happens inside, and you receive the result while the key remains safely inside.
+
+### Preventing Payment Data Loss
+Imagine a situation where a customer buys a product for Rs.100 from a merchant website. The flow looks like `User → Merchant → Payment Gateway → Bank`. The bank approves the payment. But right after the approval, the payment gateway server crashes before saving the result. Now the system has a problem: **Bank says payment succeeded** and **Gateway database has no record**
+
+This problem is addressed by making our system **durable**. Durability in a payment system is the promise that once a payment is recorded, it will never disappear, even if servers crash, networks fail, or a data center burns down. In simple terms: when someone pays ₹100, the system must never “forget” that the payment happened.
+
+Durability in a system can be achieved through several mechanisms such as:
+* Database Replication
+* Write-Ahead Logging (WAL)
+
+#### Database Replication
+Replication keeps same data in multiple machines. When a payment record is written it is stored in the primary database and replicated to the replica databases. If the primary server crashes, one replica becomes the new primary. So, the payment record still exists.
+
+
+
+#### Write-Ahead Logging (WAL)
+In WAL, before modifying the database, the system first appends the change to a log file. Only after this log entry is safely stored on disk does the database update the actual table. If the database crashes midway, it can replay the log to restore the correct state.
+
+WAL is actually fast because it performs **sequential writes** and they are cheap. In HDD, random disk writes are slow because the disk head has to move. Sequential writes are fast because the disk just keeps writing forward.
+
+
+
+
+In addition, this design can recover from the exact “gateway crashed before saving approval” scenario using the **Payment Event Stream** and **reconciliation**:
+
+* The **Payment Processor** publishes an immutable event (e.g., `payment.authorized`) to the Payment Event Stream once it receives the bank/network decision.
+* The **Payment Event Consumer** in the gateway is a durable subscriber: if it crashes, it resumes by replaying events from the stream and applies them idempotently to the Payment Database.
+* A periodic **reconciliation job** compares gateway records vs processor/acquirer settlement/authorization reports to detect and fix any missing updates (e.g., gateway missed an event due to prolonged outage).
\ No newline at end of file
diff --git a/16. Design Payment System/Resources/API_Initiate.png b/16. Design Payment System/Resources/API_Initiate.png
new file mode 100644
index 0000000..75a15ea
Binary files /dev/null and b/16. Design Payment System/Resources/API_Initiate.png differ
diff --git a/16. Design Payment System/Resources/API_Pay.png b/16. Design Payment System/Resources/API_Pay.png
new file mode 100644
index 0000000..80669f5
Binary files /dev/null and b/16. Design Payment System/Resources/API_Pay.png differ
diff --git a/16. Design Payment System/Resources/API_Refund.png b/16. Design Payment System/Resources/API_Refund.png
new file mode 100644
index 0000000..93929fa
Binary files /dev/null and b/16. Design Payment System/Resources/API_Refund.png differ
diff --git a/16. Design Payment System/Resources/API_RegisterPayment.png b/16. Design Payment System/Resources/API_RegisterPayment.png
new file mode 100644
index 0000000..7349431
Binary files /dev/null and b/16. Design Payment System/Resources/API_RegisterPayment.png differ
diff --git a/16. Design Payment System/Resources/API_Status.png b/16. Design Payment System/Resources/API_Status.png
new file mode 100644
index 0000000..9215546
Binary files /dev/null and b/16. Design Payment System/Resources/API_Status.png differ
diff --git a/16. Design Payment System/Resources/DiveDeep_AuditSchema.png b/16. Design Payment System/Resources/DiveDeep_AuditSchema.png
new file mode 100644
index 0000000..614b44c
Binary files /dev/null and b/16. Design Payment System/Resources/DiveDeep_AuditSchema.png differ
diff --git a/16. Design Payment System/Resources/DiveDeep_Auditability.png b/16. Design Payment System/Resources/DiveDeep_Auditability.png
new file mode 100644
index 0000000..d628239
Binary files /dev/null and b/16. Design Payment System/Resources/DiveDeep_Auditability.png differ
diff --git a/16. Design Payment System/Resources/DiveDeep_DatabaseReplication.png b/16. Design Payment System/Resources/DiveDeep_DatabaseReplication.png
new file mode 100644
index 0000000..4446cd2
Binary files /dev/null and b/16. Design Payment System/Resources/DiveDeep_DatabaseReplication.png differ
diff --git a/16. Design Payment System/Resources/DiveDeep_HSM.png b/16. Design Payment System/Resources/DiveDeep_HSM.png
new file mode 100644
index 0000000..d90db69
Binary files /dev/null and b/16. Design Payment System/Resources/DiveDeep_HSM.png differ
diff --git a/16. Design Payment System/Resources/DiveDeep_MerchantSchema.png b/16. Design Payment System/Resources/DiveDeep_MerchantSchema.png
new file mode 100644
index 0000000..a017b16
Binary files /dev/null and b/16. Design Payment System/Resources/DiveDeep_MerchantSchema.png differ
diff --git a/16. Design Payment System/Resources/DiveDeep_PaymentMethodSchema.png b/16. Design Payment System/Resources/DiveDeep_PaymentMethodSchema.png
new file mode 100644
index 0000000..0aadef3
Binary files /dev/null and b/16. Design Payment System/Resources/DiveDeep_PaymentMethodSchema.png differ
diff --git a/16. Design Payment System/Resources/DiveDeep_PaymentSchema.png b/16. Design Payment System/Resources/DiveDeep_PaymentSchema.png
new file mode 100644
index 0000000..fe40ad7
Binary files /dev/null and b/16. Design Payment System/Resources/DiveDeep_PaymentSchema.png differ
diff --git a/16. Design Payment System/Resources/DiveDeep_WAL.png b/16. Design Payment System/Resources/DiveDeep_WAL.png
new file mode 100644
index 0000000..e00e2dd
Binary files /dev/null and b/16. Design Payment System/Resources/DiveDeep_WAL.png differ
diff --git a/16. Design Payment System/Resources/Glossary.png b/16. Design Payment System/Resources/Glossary.png
new file mode 100644
index 0000000..ced0fbe
Binary files /dev/null and b/16. Design Payment System/Resources/Glossary.png differ
diff --git a/16. Design Payment System/Resources/HLD_HandlingCardData.png b/16. Design Payment System/Resources/HLD_HandlingCardData.png
new file mode 100644
index 0000000..39f84ba
Binary files /dev/null and b/16. Design Payment System/Resources/HLD_HandlingCardData.png differ
diff --git a/16. Design Payment System/Resources/HLD_Payment.png b/16. Design Payment System/Resources/HLD_Payment.png
new file mode 100644
index 0000000..0ae3b12
Binary files /dev/null and b/16. Design Payment System/Resources/HLD_Payment.png differ
diff --git a/16. Design Payment System/Resources/HLD_PaymentFlow.png b/16. Design Payment System/Resources/HLD_PaymentFlow.png
new file mode 100644
index 0000000..0d28c26
Binary files /dev/null and b/16. Design Payment System/Resources/HLD_PaymentFlow.png differ
diff --git a/16. Design Payment System/Resources/HLD_PaymentInitiation.png b/16. Design Payment System/Resources/HLD_PaymentInitiation.png
new file mode 100644
index 0000000..81484f6
Binary files /dev/null and b/16. Design Payment System/Resources/HLD_PaymentInitiation.png differ
diff --git a/16. Design Payment System/Resources/HLD_PaymentRegistration.png b/16. Design Payment System/Resources/HLD_PaymentRegistration.png
new file mode 100644
index 0000000..a449feb
Binary files /dev/null and b/16. Design Payment System/Resources/HLD_PaymentRegistration.png differ
diff --git a/16. Design Payment System/Resources/HLD_PaymentStateMachine.png b/16. Design Payment System/Resources/HLD_PaymentStateMachine.png
new file mode 100644
index 0000000..1aa205c
Binary files /dev/null and b/16. Design Payment System/Resources/HLD_PaymentStateMachine.png differ
diff --git a/16. Design Payment System/Resources/HLD_Payment_Status.png b/16. Design Payment System/Resources/HLD_Payment_Status.png
new file mode 100644
index 0000000..36429d3
Binary files /dev/null and b/16. Design Payment System/Resources/HLD_Payment_Status.png differ
diff --git a/16. Design Payment System/Resources/HLD_Refund.png b/16. Design Payment System/Resources/HLD_Refund.png
new file mode 100644
index 0000000..66ba602
Binary files /dev/null and b/16. Design Payment System/Resources/HLD_Refund.png differ
diff --git a/16. Design Payment System/Resources/HLD_Settlement.png b/16. Design Payment System/Resources/HLD_Settlement.png
new file mode 100644
index 0000000..3731669
Binary files /dev/null and b/16. Design Payment System/Resources/HLD_Settlement.png differ
diff --git a/16. Design Payment System/Resources/Intro_PaymentSystem.png b/16. Design Payment System/Resources/Intro_PaymentSystem.png
new file mode 100644
index 0000000..aa60a31
Binary files /dev/null and b/16. Design Payment System/Resources/Intro_PaymentSystem.png differ
diff --git a/16. Design Payment System/Resources/Intro_PhysicalPayment.png b/16. Design Payment System/Resources/Intro_PhysicalPayment.png
new file mode 100644
index 0000000..c97e82f
Binary files /dev/null and b/16. Design Payment System/Resources/Intro_PhysicalPayment.png differ