Skip to content

About

RESTful wallet ledger API — Spring Boot 3.5, PostgreSQL, Flyway, Testcontainers. Concurrency-safe credit/debit with idempotency guarantees.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Wallet Ledger API

A RESTful wallet ledger service that supports creating wallets, crediting/debiting funds with idempotency guarantees, and paginated transaction history. Built with Spring Boot 3.5, PostgreSQL 16, and Flyway.

This project demonstrates how to build a small financial API with correctness and concurrency in mind. It keeps balance mutations in the database, makes repeated requests safe, validates input at the API boundary, and verifies behavior with integration tests against PostgreSQL.

What This Demonstrates

  • Correctness under concurrency: debit uses an atomic database update that succeeds only when sufficient balance is available, preventing negative balances and lost updates.
  • Idempotent money operations: a database uniqueness constraint on (wallet_id, idempotency_key) ensures retries do not create duplicate transactions or apply a balance change twice.
  • Clear layering: controllers handle HTTP concerns, services coordinate business rules and transactions, repositories own persistence queries, and DTOs define the API contract.
  • Production-minded persistence: Flyway manages the schema, PostgreSQL enforces invariants, and monetary amounts use integer minor units (BIGINT) rather than floating-point values.
  • Behavior-focused testing: Testcontainers runs integration tests against a real PostgreSQL 16 instance, including duplicate requests, insufficient funds, and concurrent debits.

Architecture

HTTP request
    |
WalletController  ->  WalletService  ->  Spring Data repositories  ->  PostgreSQL
       |                   |                         |
     DTOs          transactions and rules       atomic updates and constraints

The main business flow is Controller -> Service -> Repository. The service layer uses Spring transactions, while PostgreSQL provides the final concurrency and data-integrity guarantees. See src/main/java for the implementation and src/test/java for end-to-end behavior coverage.

API At A Glance

All endpoints require an X-User-Id header containing the user's UUID.

Method Endpoint Purpose Success
POST /wallets Create the user's wallet 201 Created
GET /wallets/me Read the current balance 200 OK
POST /wallets/me/credit Add funds with an idempotency key 200 OK
POST /wallets/me/debit Remove funds with an idempotency key 200 OK
GET /wallets/me/transactions Read paginated transaction history 200 OK

Credit and debit requests use positive integer amounts in minor units, such as cents. Repeating a request with the same idempotency key returns the original transaction. A debit that would exceed the available balance returns 422 Unprocessable Entity; attempting to create a duplicate wallet returns 409 Conflict.

Compatibility note: Spring Boot was bumped to 3.5.0 because 3.4.x is no longer served by Spring Initializr. The APIs used in this scope are identical. The project uses Java 21 and standard Spring Boot and Spring Data APIs.

Scope note: X-User-Id identifies the user for this standalone exercise; it is not intended to replace production authentication and authorization.

Prerequisites

  • Java 21
  • Docker (for the local database and for running the test suite)

Local Setup

1. Start the database

docker compose up -d

2. Run the application

./gradlew bootRun

The API is available at http://localhost:8080.

Testing

Ensure Docker is running — Testcontainers spins up a real PostgreSQL 16 container for the test suite.

./gradlew test

The integration suite covers the happy path, insufficient balances, duplicate wallet creation, idempotent credits, and concurrent debits. The concurrent debit scenario verifies that exactly the affordable number of requests succeeds and that the final balance remains correct.

API Reference


Create Wallet

curl -s -X POST http://localhost:8080/wallets \
  -H "X-User-Id: 00000000-0000-0000-0000-000000000001"

Returns 201 Created. Returns 409 Conflict if a wallet already exists for that user.


Get Wallet

curl -s http://localhost:8080/wallets/me \
  -H "X-User-Id: 00000000-0000-0000-0000-000000000001"

Credit

curl -s -X POST http://localhost:8080/wallets/me/credit \
  -H "X-User-Id: 00000000-0000-0000-0000-000000000001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "reference": "top-up",
    "idempotencyKey": "credit-001"
  }'

Repeating the same idempotencyKey returns the original transaction unchanged (idempotent).


Debit

curl -s -X POST http://localhost:8080/wallets/me/debit \
  -H "X-User-Id: 00000000-0000-0000-0000-000000000001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "reference": "purchase",
    "idempotencyKey": "debit-001"
  }'

Returns 422 Unprocessable Entity if the wallet has insufficient balance.


Get Transactions

curl -s "http://localhost:8080/wallets/me/transactions?page=0&size=20" \
  -H "X-User-Id: 00000000-0000-0000-0000-000000000001"

Returns a paginated list of transactions ordered by most recent first. size must be between 1 and 100 (default 20).

About

RESTful wallet ledger API — Spring Boot 3.5, PostgreSQL, Flyway, Testcontainers. Concurrency-safe credit/debit with idempotency guarantees.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages