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.
- 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.
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.
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-Ididentifies the user for this standalone exercise; it is not intended to replace production authentication and authorization.
- Java 21
- Docker (for the local database and for running the test suite)
1. Start the database
docker compose up -d2. Run the application
./gradlew bootRunThe API is available at http://localhost:8080.
Ensure Docker is running — Testcontainers spins up a real PostgreSQL 16 container for the test suite.
./gradlew testThe 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.
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.
curl -s http://localhost:8080/wallets/me \
-H "X-User-Id: 00000000-0000-0000-0000-000000000001"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).
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.
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).