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 API
cd 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