Payforge

A Spring Boot payment initiation platform with multi-tier caching and idempotent processing.

Payforge models the edge of a modern payment system: accept a transfer, validate it rigorously, and guarantee that client retries never create duplicate payments. Built for production-style concerns — latency, correctness under retries, and clean service boundaries.

 ┌──────────────────────────────────────┐
Client ────────► │ Payforge Edge API │
│ Validation · Idempotency · Caching │
└──────────────┬───────────────────────┘
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
Caffeine Redis PostgreSQL
L1 (in-process) L2 (shared) L3 (source of truth)
~ms ~ms durable

---

Highlights

Capability	Implementation
Create transfer	POST /api/v1/transfers
Input validation	Bean Validation + curated ISO-4217 currency catalog
Idempotent retries	Idempotency-Key header — same key returns the original result
Multi-tier cache	Caffeine (process) → Redis (shared, TTL) → PostgreSQL (durable)
Modular design	Edge API, domain library, and core service modules
Stack	Java 17 · Spring Boot · PostgreSQL · Redis (Lettuce) · Caffeine · Maven

---

Architecture

Idempotency at the edge

Payment clients retry when networks fail. Payforge treats every create as potentially a duplicate:

1. Client sends Idempotency-Key (or reuses transferId)
2. Edge looks up the key in Caffeine → Redis → PostgreSQL
3. Hit → return the known payment (DUPLICATE) without creating a new one
4. Miss → accept the payment (ACCEPTED) for processing

Cache-aside with promotion

Hot duplicate traffic is answered from process memory. On a miss, values found in Redis or the database are written upward so the next request is faster — a pattern used in high-throughput financial APIs.

Module layout

Module	Responsibility
edge	REST API, currency catalog, idempotency store (:8080)
domain	Transfer model, persistence contracts, response envelope
core	Processing service shell (:8081)

Package root: dev.harsh.payforge · Edge packages: api, currency, idempotency, infrastructure

---

Tech stack

• Language: Java 17
• Framework: Spring Boot (Web, Cache, Data JPA, Data Redis)
• Data: PostgreSQL
• Caching: Caffeine + Redis
• Build: Maven (multi-module)

---

Quick start

Requirements: JDK 17+, PostgreSQL, Redis

# Database & cache
createdb payforge
redis-server
# Build shared module, then start the edge APIcd domain && ./mvnw -q install -DskipTests &&cd ..
cd edge && ./mvnw spring-boot:run

API base: http://localhost:8080

Create a transfer

curl -sS -X POST http://localhost:8080/api/v1/transfers \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: payDemo001' \
-d '{ "transferId": "payDemo001", "amount": 1500.00, "currency": "INR", "payer": { "holderName": "Ada Lovelace", "accountNumber": "123456789012", "routingCode": "HDFC0001234" }, "payee": { "holderName": "Bob Builder", "accountNumber": "987654321098", "routingCode": "ICIC0001234" } }'

Replay the same Idempotency-Key after the payment is stored — the API returns the original transfer instead of creating another.

---

What this demonstrates

• Payment-domain thinking — initiation, validation, and retry safety as first-class concerns
• Systems design — multi-level caching, cache promotion, clear read/write paths
• Spring mastery — REST, validation, JPA, Redis, modular Maven structure
• API design — versioned routes, structured responses (ACCEPTED / DUPLICATE), standard idempotency headers

---

Author

Harsh Srivastava
github.com/HarshDevelops