payment-system

[![Forks][forks-shield]][forks-url] [![Stargazers][stars-shield]][stars-url] [![Issues][issues-shield]][issues-url] [![LinkedIn][linkedin-shield]][linkedin-url]

---

---

About The Project

A distributed payment processing system built with Spring Boot microservices — modeled after the infrastructure layer that powers platforms like Razorpay or PayPal. Handles peer-to-peer money movement with fraud detection, event-driven architecture, and production-grade reliability patterns.

Built to answer one question: what actually happens when you tap "Pay"?

Key capabilities:

• Never processes the same payment twice — Redis idempotency
• Prevents double spending — Pessimistic DB locking
• Zero message loss on crash — Outbox Pattern
• Automatic fraud reversal — Saga Pattern
• Real-time fraud detection — Rule-based engine with admin review queue

---

Architecture

                                        Client
                                           │
                                    ┌──────▼─────┐
                                    │ API Gateway│  JWT Auth · Rate Limiting
                                    │  Port 8080 │  Role-based Routing
                                    └─────┬──────┘
                                          │
                          ┌───────────────┼───────────────┐
                          │               │               │
                    ┌─────▼──────┐  ┌─────▼──────┐  ┌────▼───────┐
                    │    Auth    │  │  Payment   │  │   Fraud    │
                    │  Service   │  │  Service   │  │  Service   │
                    │  Port 8081 │  │  Port 8082 │  │  Port 8083 │
                    └─────┬──────┘  └─────┬──────┘  └────┬───────┘
                          │               │               │
                       Auth DB       Payment DB       Fraud DB
                      (Postgres)     (Postgres)      (Postgres)
                                          │
                                     Redis Cache
                                   (Idempotency +
                                    Rate Limiting)
                
                                ────── Kafka Event Bus ──────
                
                  Auth Service     → user-registered-topic   → Payment Service
                  Payment Service  → payment-topic           → Fraud Service
                  Payment Service  → payment-topic           → Notification Service
                  Fraud Service    → fraud-alert-topic       → Payment Service
                  Fraud Service    → fraud-review-topic      → Payment Service
                
                                    ┌──────────────┐
                                    │ Notification │
                                    │   Service    │
                                    │  Port 8084   │
                                    └──────────────┘
                
                              ┌─────────────────────────┐
                              │   Grafana LGTM Stack    │
                              │  Traces · Logs · Metrics│
                              └─────────────────────────┘
                
                         ╔════════════════════════════════════╗
                         ║      Docker Internal Network       ║
                         ║  Only port 8080 exposed externally ║
                         ╚════════════════════════════════════╝

---

Services

API Gateway (8080)

• JWT validation on every request — no token, no entry
• Role-based access control — /fraud/** restricted to ADMIN
• Rate limiting per IP via Redis — 5 req/min on login, 10 req/min on payments
• Strips untrusted X-User-Id headers — injects verified identity downstream

Auth Service (8081)

• User registration and login
• JWT issuance with userId as subject and role as claim
• BCrypt password hashing
• Publishes user-registered event on registration

Payment Service (8082)

• Double-entry ledger — every transaction creates DEBIT and CREDIT entries
• Idempotency via Redis — duplicate requests return same response without reprocessing
• Pessimistic DB locking — prevents double spending on concurrent requests
• Outbox Pattern — guaranteed Kafka delivery even on service crash
• Account ownership validation — users can only move money from their own accounts
• Account number abstraction — UUIDs stay internal, users interact via account numbers
• Consumes user-registered → auto-creates account on registration
• Consumes fraud-alert → reverses transaction and freezes account (Saga)
• Consumes fraud-review → unfreezes account on admin approval

Notification Service (8084)

• Consumes payment events from Kafka
• Async payment confirmations — never blocks payment processing
• Extensible to email/SMS providers

Fraud Detection Service (8083)

• Rule-based fraud engine — evaluates every transaction
• Rules: high value (≥ ₹10,000), round numbers, self-transfer, rapid successive payments
• Saves alerts to dedicated fraud DB with risk levels (LOW, MEDIUM, HIGH)
• Admin review queue — approve (unfreeze) or reject (keep frozen) via outbox pattern
• Publishes fraud alerts to trigger Saga compensation in Payment Service

---

Key Design Decisions

Outbox Pattern — Direct Kafka publishing risks message loss if service crashes mid-transaction. Events are written to an outbox table in the same DB transaction. A scheduler reads and publishes. Atomicity guaranteed.

Idempotency with Redis — Every payment request carries a client-generated Idempotency-Key header. Redis stores the key with TTL. Duplicate requests return the original response without reprocessing — prevents double charges on network retries.

Pessimistic Locking — Concurrent payments to the same account can cause double spending. @Lock(PESSIMISTIC_WRITE) on account fetches ensures one transaction processes at a time per account.

Saga Pattern — Fraud detection is async. Payment processes first, fraud analysis follows. When fraud is confirmed, a compensation event reverses the transaction and freezes the account. No records deleted — full audit trail preserved.

Kafka over RabbitMQ — Multiple services consume every payment event independently. Kafka's message retention means no events are lost if a service goes down — consumer catches up on restart.

Database per Service — Each service owns its data. No cross-service JPA relationships. Services communicate via events. Payment DB, Fraud DB, and Auth DB are completely independent.

Account Number Abstraction — Users share account numbers (e.g. ABC123DEF456). Internal UUIDs never surface in the API. Account number to UUID resolution happens server-side.

JWT at Gateway Only — Auth Service issues JWT. Gateway validates it using a shared secret — no Auth Service call needed per request. Downstream services trust the X-User-Id header injected by Gateway.

---

Microservices Patterns

Pattern	Implementation
API Gateway	Spring Cloud Gateway — single entry point
Database per Service	Auth DB, Payment DB, Fraud DB
Event-Driven Architecture	Kafka backbone across all services
Outbox Pattern	Payment Service + Fraud Service
Idempotent Consumer	Redis idempotency keys
Saga Pattern	Fraud reversal compensation flow
Pessimistic Locking	Account fetches during payment processing

---

Security

• JWT validation at Gateway — no unauthenticated request reaches any service
• Header stripping — client-supplied X-User-Id removed, Gateway injects verified identity
• Account ownership validation — users can only deposit/transfer from their own accounts
• Role-based access — ADMIN role required for fraud endpoints
• Rate limiting per IP — brute force and spam protection on auth and payment routes
• BCrypt password hashing
• Internal network isolation — only port 8080 exposed externally via Docker
• No UUIDs in API surface — account numbers only
• IDOR prevention — account ownership checked on every write operation

---

Built With

[![Java][Java-shield]][Java-url] [![Spring][Spring-shield]][Spring-url] [![Kafka][Kafka-shield]][Kafka-url] [![Redis][Redis-shield]][Redis-url] [![Postgres][Postgres-shield]][Postgres-url] [![Docker][Docker-shield]][Docker-url] [![Grafana][Grafana-shield]][Grafana-url]

---

Getting Started

Prerequisites

• Docker and Docker Compose
• Java 21
• Maven

Installation

1. Clone the repository

   git clone https://github.com/abubakkar-siddhiq/payment-system.git
   cd payment-system
   

2. Start infrastructure

   docker-compose up -d
   

   Starts: PostgreSQL (x3), Redis, Kafka (KRaft), Grafana LGTM

3. Build each service

   cd payment-service && mvn clean package -DskipTests && cd ..
   cd authservice && mvn clean package -DskipTests && cd ..
   cd frauddetectionsystem && mvn clean package -DskipTests && cd ..
   cd notificationservice && mvn clean package -DskipTests && cd ..
   cd gateway && mvn clean package -DskipTests && cd ..
   

4. Start services in order

   1. Auth Service          → port 8081
   2. Payment Service       → port 8082
   3. Fraud Service         → port 8083
   4. Notification Service  → port 8084
   5. API Gateway           → port 8080
   

5. Create admin user

   UPDATE users SET role = 'ADMIN' WHERE email = 'admin@yourdomain.com';
   

---

API Reference

Auth

POST /api/v1/auth/register    → Register, returns JWT + userId
POST /api/v1/auth/login       → Login, returns JWT + userId

Accounts

GET  /api/v1/accounts/me                        → My account info
GET  /api/v1/accounts/{accountNumber}/balance   → My balance
POST /api/v1/ac