PayFlow

PayFlow is a modular monolith payment system built with Spring Boot, Spring Security, Spring Data JPA, Flyway, and Spring Modulith. It supports merchant registration, HMAC-signed API access, payment ingestion, fraud assessment, ledger posting, email notifications, and merchant-scoped audit history.

What It Does

Current implemented flow:

A merchant registers and receives a raw API key.
The merchant signs requests with HMAC-SHA256 using that API key.
A payment is created in PENDING.
The fraud module evaluates the payment.
The payment is marked AUTHORISED or DECLINED.
Authorised payments generate a ledger entry.
Notifications send merchant email for final outcomes.
Audit persists the full event history.

Stack

Java 21
Spring Boot 4.0.4
Spring Security
Spring Data JPA
Spring Modulith 2.0.3
Flyway
PostgreSQL 16
H2 for tests
Maven

Modules

merchant Merchant registration, API key issuance, API key rotation, merchant lookup.
payments Payment API, idempotency, payment state transitions, payment event history.
fraud Rule-based fraud checks and fraud assessment query API.
ledger Double-entry journal posting and journal lookup API.
notifications Async email notifications using Spring Mail and Gmail SMTP.
audit Merchant-scoped audit event persistence and audit query API.
shared Shared events, error handling, response wrappers, common types.

Sequence Flow

sequenceDiagram
    autonumber
    participant Client as Merchant Client
    participant API as PayFlow API
    participant Payments as Payments Module
    participant Fraud as Fraud Module
    participant Ledger as Ledger Module
    participant Notify as Notifications Module
    participant Audit as Audit Module
    participant DB as PostgreSQL

    Client->>API: POST /api/v1/merchants/register
    API->>DB: Persist merchant + encrypted API key
    API-->>Client: merchantId + raw apiKey

    Client->>API: POST /api/v1/payments\nX-Merchant-ID, X-Timestamp, X-Signature
    API->>Payments: Validate and submit payment
    Payments->>DB: Insert payment (PENDING)
    Payments-->>Fraud: Payment.Transaction.Initiated
    Payments-->>Audit: Payment.Transaction.Initiated

    Fraud->>DB: Insert fraud assessment
    Fraud-->>Payments: Fraud.Assessment.Completed
    Fraud-->>Audit: Fraud.Assessment.Completed

    alt Fraud approves
        Payments->>DB: Update payment to AUTHORISED
        Payments-->>Ledger: Payment.Transaction.Authorised
        Payments-->>Notify: Payment.Transaction.Authorised
        Payments-->>Audit: Payment.Transaction.Authorised

        Ledger->>DB: Insert journal entry
        Ledger-->>Audit: Ledger.Entry.Posted
        Notify->>Client: Email notification
    else Fraud declines
        Payments->>DB: Update payment to DECLINED
        Payments-->>Notify: Payment.Transaction.Declined
        Payments-->>Audit: Payment.Transaction.Declined
        Notify->>Client: Email notification
    end

    Client->>API: GET /api/v1/payments/{id}/events
    API->>Audit: Find events for merchant + payment
    Audit->>DB: Query audit.event_log
    Audit-->>Client: Ordered event history

Authentication

POST /api/v1/merchants/register is public.

All other endpoints require these headers:

X-Merchant-ID
X-Timestamp
X-Signature

Signing model:

Algorithm: HmacSHA256
Payload: timestamp + "." + body
Signature format: lowercase hex
Max timestamp age: 300 seconds

For GET requests, the body is empty, so the payload becomes:

timestamp.

If the signature is missing, invalid, or expired, the API returns 401.

Local Run

Start PostgreSQL:

docker compose up -d

Run the app:

./mvnw spring-boot:run

Run tests:

./mvnw test

Configuration

Primary config lives in application.properties.

Main environment variables:

DATABASE_URL
DATABASE_USER
DATABASE_PASSWORD
ENCRYPTION_SECRET
LOG_FILE
MAIL_USERNAME
MAIL_PASSWORD
MAIL_FROM
JWK_SET_URI

Notes:

Flyway manages schema changes.
Virtual threads are enabled.
The current config still contains development fallback values and should be cleaned up before any real deployment.

Database Schemas

payments
merchant
fraud
ledger
notifications
audit

Flyway migrations are under src/main/resources/db/migration/postgresql.

API Surface

Base URL:

http://localhost:8080/api/v1

Merchant

POST /merchants/register
POST /merchants/keys/rotate

Payments

POST /payments
GET /payments
GET /payments/{id}
GET /payments/{id}/events

Fraud

GET /fraud/assessments/{transactionId}

Ledger

GET /ledger/journal/{correlationId}

Audit

GET /audit/events

Example Requests

Register Merchant

curl -X POST http://localhost:8080/api/v1/merchants/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "email": "merchant@example.com"
  }'

Payment Request Body

{
  "payeeAccountId": "11111111-1111-1111-1111-111111111111",
  "idempotencyKey": "unique-client-key-123",
  "amount": "150.00",
  "currency": "USD",
  "paymentMethod": {
    "type": "CARD",
    "token": "tok_test_1234"
  }
}

Generate Signature

TIMESTAMP=$(date +%s)
BODY='{"payeeAccountId":"11111111-1111-1111-1111-111111111111","idempotencyKey":"unique-client-key-123","amount":"150.00","currency":"USD","paymentMethod":{"type":"CARD","token":"tok_test_1234"}}'
SIGNATURE=$(printf '%s.%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$API_KEY" -hex | sed 's/^.* //')

Submit Payment

curl -X POST http://localhost:8080/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-Merchant-ID: $MERCHANT_ID" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -d "$BODY"

Error Handling

Current error behavior:

NotFoundException -> 404
DomainException -> 409
unexpected exception -> 500
invalid signature/auth -> 401

Response wrapper shape:

{
  "data": null,
  "message": "Error message",
  "statusCode": 404
}

The unauthorized signature response is currently written directly by the filter.

Testing

The project currently has coverage for:

merchant controller and module boundaries
payment controller and service behavior
fraud controller and listener behavior
ledger controller and service behavior
audit controller and service behavior

Current suite status:

33 tests
0 failures
0 errors

Current Tradeoffs

Authentication is API-key plus HMAC, not a full OAuth2/JWT flow.
API key recovery is not implemented yet.
Swagger/OpenAPI is intentionally not included.
Audit payloads are stored as serialized JSON.
Ledger lookup is merchant-scoped and only returns entries for the authenticated merchant.
Development defaults remain in config and should be removed before deployment.

Next Good Improvements

Merchant-scope the ledger journal lookup
Remove committed fallback secrets from config
Add Postgres/Testcontainers integration coverage
Add deployment notes for Railway or Render

FilesExpand file tree

README.md

Latest commit

History