karthik.dev
Back to projects
Infrastructure

Payment Gateway Simulation System

Distributed, fault-tolerant payment infrastructure simulation

GitHub
Node.jsTypeScriptPostgreSQLREST APIsWebhooksEvent-Driven ArchitectureDocker

Overview

A distributed payment infrastructure simulating the full authorization → capture → void → refund lifecycle, built to explore idempotency, fault tolerance, and transactional consistency under concurrency.

Problem

Payment systems must guarantee correctness under network retries, duplicate requests, and concurrent operations — mistakes here mean double charges or lost transactions.

Solution

Idempotent APIs for every state transition in the payment lifecycle, a webhook delivery engine with exponential backoff and dead-letter queues, and PostgreSQL row-level locking to guarantee ACID consistency under high concurrency.

Architecture

  1. 1Client/API layer exposing authorize, capture, void, and refund endpoints, each idempotent via request keys
  2. 2Webhook delivery engine with exponential backoff, dead-letter queues, and event replay for downstream consumers
  3. 3PostgreSQL with row-level locking guaranteeing consistency during concurrent state transitions
  4. 4Dockerized services for local development and reproducible testing

Technical Challenges

  • Preventing duplicate processing when clients retry requests after timeouts — solved with idempotency keys stored per transaction.
  • Guaranteeing at-least-once webhook delivery to downstream consumers without introducing duplicate side effects — solved with dead-letter queues and consumer-side deduplication.
  • Avoiding deadlocks while using row-level locking under high-concurrency payment operations.

Results

  • Demonstrated correct behavior for authorize/capture/void/refund lifecycles under simulated retry and concurrency scenarios.
  • Reusable webhook delivery pattern (backoff + DLQ + replay) applicable to any event-driven integration.