Payment Gateway (Stripe)

Overview

Introduction
Requirements
Data Model
API Design
High Level Design
Deep Dive 1: Idempotency
Deep Dive 2: PCI-DSS Compliance
Deep Dive 3: Distributed Transactions
Deep Dive 4: Automated Reconciliation
Complete Architecture
Additional Discussion Points

Introduction

A payment gateway acts as the intermediary between a merchant's application and the broader financial network (issuing banks, acquiring banks, and card networks like Visa/Mastercard).
Unlike a digital wallet (which primarily manages internal ledger transfers), a payment gateway's primary job is to securely capture payment information, assess risk, route the transaction to the appropriate financial institution for authorization, and handle the subsequent capture, settlement, and potential refunds.

Requirements

Functional Requirements
- Process Payments: Clients should be able to charge a customer's credit card or payment method.
- Process Refunds: Clients should be able to issue full or partial refunds.
- Webhooks/Notifications: The system must asynchronously notify merchants of payment state changes (e.g., authorized, captured, failed).
- View Payment Status: Merchants can query the status of a specific transaction.
Non Functional Requirements
- Strict Consistency & Accuracy: "No lost money, no double charges." Consistency is prioritized over availability in the CAP theorem context.
- High Availability & Reliability: Targeting 99.99%+ uptime. Payment downtime directly equals lost revenue.
- Security & Compliance: Must adhere to PCI-DSS standards. Raw card data must be handled with extreme care.
- Idempotency: Network failures will happen; retries must not result in duplicate charges.
- Performance: Low latency for the initial synchronous authorization step (usually < 2-3 seconds) to ensure a good user checkout experience.

Data Model

For a payment gateway, Relational Databases (e.g., PostgreSQL, MySQL) are the standard choice because ACID compliance is non-negotiable.

Merchant: Stores profile and authentication details for the businesses utilizing the payment gateway to process transactions.
PaymentOrder: Serves as the central state machine and financial ledger for tracking the lifecycle and monetary value of an individual checkout attempt.
PaymentEvent: Acts as an immutable, append-only audit log that permanently records every raw interaction and response payload from external acquiring banks.
OutboxEvent: Functions as a reliable, temporary staging area for the Transactional Outbox pattern to guarantee that asynchronous events (like merchant webhooks) are safely published to Kafka without data loss.
CardVault: Resides in a physically isolated database to securely store encrypted credit card numbers (PANs) and minimize the system's overall PCI compliance scope.

API Design

The API should be RESTful and must enforce idempotency.

plaintext

1. Create a Payment
   POST /v1/payments
   Headers:
     Authorization: Bearer <merchant_api_key>
     Idempotency-Key: <uuid_generated_by_client>
   Body:
   {
     "amount": 5000, 
     "currency": "USD",
     "payment_method_token": "tok_12345", // Tokenized card details
     "description": "Order #987"
   }
  
  
2. Get Payment Status
   GET /v1/payments/{payment_id}
  
  
3. Issue a Refund
   POST /v1/payments/{payment_id}/refunds
   Headers:
     Idempotency-Key: <uuid>
   Body:
   {
     "amount": 5000 // Partial refunds are possible
   }

High Level Design

At a high level, the system can be broken down into two core paths:

1. The Authorization Path (Synchronous)

This path focuses on securely capturing the payment intent and getting real-time approval from the financial network.

API Gateway: Acts as the entry point for merchant clients, handling SSL termination, rate limiting, and routing checkout requests to internal services.
Payment Service: Orchestrates the payment flow by creating a transaction record in the database and managing the communication with downstream systems.
Main Ledger DB (PostgreSQL): The relational "Source of Truth" that stores merchant data, transaction amounts, and the current state (e.g., PENDING vs AUTHORIZED) of every payment.
Fraud/Risk Service: Evaluates transaction metadata (IP, device fingerprint, velocity) synchronously to block suspicious payments before they reach the bank.
External Gateway Adapter: Translates our internal JSON payloads into the specific protocols (e.g., ISO 8583, legacy XML) required by various external networks.
Acquiring Bank / Network: The external financial institution (e.g., Chase, Visa) that validates the cardholder's funds and returns an "Approved" or "Declined" response.

2. The Post-Processing Path (Asynchronous)

This path focuses on updating the merchant and eventually finalizing the movement of funds.

Kafka: Acts as the central event bus, decoupling the fast, synchronous authorization path from slower downstream tasks.
Webhook Listener: Consumes payment success/failure events from Kafka and fires HTTP callbacks to the merchant's backend systems.

While this implementation technically facilitates a payment, it contains significant architectural "anti-patterns" and missing features (e.g., storing raw credit card numbers, vulnerability to network retries, and dual-write data loss) that prevent us from fulfilling strict financial and compliance requirements.

Deep Dive 1: Idempotency

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.