Payments Infrastructure

Fault-Tolerant Payment Gateway

Designing a resilient microservice capable of processing high-volume transactions. Focus on Idempotency, ACID compliance, and Zero Data Loss.

99.99%
Uptime Design
0%
Double Spending
REST
Architecture

01 The Challenge

Why was this hard?

The business needed to integrate a new PSP (Stripe/Adyen) for global expansion. The legacy system treated payments as synchronous "fire-and-forget" requests, leading to critical issues:

  • Double Spending Risk Network timeouts caused clients to retry requests, resulting in users being charged twice for the same order.
  • Inconsistent States Database said "Pending", Bank said "Success". No reconciliation mechanism.

02 Technical Solution & Artifacts

1. Idempotency Flow (Sequence)

Request Deduplication Logic SVG
Sequence Diagram showing Idempotency

Logic: Before processing, the API checks Redis for the Idempotency-Key. If the key exists (locked), it returns the cached result, preventing duplicate calls to the Bank.

2. Data Model (ERD)

ER Diagram

3. OpenAPI Specification

openapi.yaml 
paths:
  /v1/payments:
    post:
      summary: Initiate a secure transaction
      parameters:
        - in: header
          name: Idempotency-Key # Critical for safety
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [amount, currency, token]
              properties:
                amount:
                  type: integer
                  example: 5000 # in cents
                currency:
                  type: string
                  example: "USD"
      responses:
        '201':
          description: Transaction Created
        '409':
          description: Conflict (Idempotency Key used)

Technologies & Standards

REST API Redis (Locking) PostgreSQL PCI DSS Scope