Problem statement
Complete the top-up endpoint of a wallet service: clients retry aggressively, the same request can arrive many times at once, and the wallet must still be credited exactly once.
Requirements
WalletTopUpController
- Expose POST /wallet/topup, reading the top-up from the request body as a TopUpRequest (walletId and amountCents) and the retry key from an Idempotency-Key request header
- Answer an accepted top-up with 200 and the JSON text the service produced, made of topUpId, walletId, amountCents and balanceCents
- Reject a request whose amountCents is missing with 400 and the message "Amount is required"
- Reject a request whose amountCents is below 1 with 400 and the message "Amount must be at least 1"; an amount of 1 is accepted
WalletTopUpService
topUp(String idempotencyKey, TopUpRequest request)
- Reject a request that arrives with no Idempotency-Key header, or with a blank one, with the message "Idempotency-Key header is required", answered as 400
- Reject a request naming a wallet that does not exist with the message "Wallet not found with id: " followed by the requested wallet id, answered as 404
- A key that has never been used credits the named wallet by amountCents and answers with the wallet's balance after the credit, whether or not that wallet has been topped up before; each accepted top-up gets its own topUpId, and no other wallet moves
- topUpId is the identifier of the top-up record that was written, and the exact text answered to the client is kept on that record
- A request repeating a key that was already used for the same walletId and amountCents credits nothing and answers with the text stored for that key, character for character
- The stored text is answered as it was stored, so a replay still reports the original topUpId and the original balanceCents even when later top-ups have moved the balance on since
- A request repeating a key that was already used for a different walletId or a different amountCents credits nothing and is rejected with the message "Idempotency-Key already used with a different request", answered as 409
- Two requests carrying the same key that arrive at the same moment never both credit: the wallet moves by one amount only, one top-up record exists for that key, and every accepted answer is the stored text of the single top-up that happened
- When requests that arrive at the same moment share a key but disagree on walletId or amountCents, only the ones agreeing with the top-up that happened are accepted; the rest are rejected with the same 409 message, and the wallet moves by the accepted amount only
- Requests carrying different keys do not interfere: each one credits its own wallet exactly once
- A rejected request writes no top-up record, moves no balance, and leaves its key free, so a later request may use that key successfully
TopUpWriter
creditAndRecord(String idempotencyKey, Long walletId, int amountCents)
- Perform one top-up as a single all-or-nothing piece of work: the credit to the wallet and the top-up record written for the key either both survive or neither does
- Claim the key before any balance moves, so that when several requests carrying one key run side by side only the request that owns the key can go on to credit
- Answer with the exact response text produced for this top-up, which is also what the record keeps
TopUpRecordRepository
- Look up the top-up record written for a given Idempotency-Key
Provided wallet machinery
- The Wallet and TopUpRecord entities are provided: a top-up record carries the Idempotency-Key it was made with, the wallet and amount it was made for, the moment it was made, and the exact response text that was sent back for it
- The database refuses to hold two top-up records with the same key
- TopUpResponseSerializer turns a TopUpResponse into the exact JSON text the API answers with, the same characters every time
- The domain exceptions and the error handler that renders them are provided; three wallets are seeded at startup for manual play
Sample Requests & Responses
Expand to view details on sample requests and responses.
POST /wallet/topup
Request:
{
"walletId": 1,
"amountCents": 500
}
Response (200 OK):
{
"topUpId": 1,
"walletId": 1,
"amountCents": 500,
"balanceCents": 1500
}
POST /wallet/topup retried with the same key
Request:
{
"walletId": 1,
"amountCents": 500
}
Response (200 OK):
{
"topUpId": 1,
"walletId": 1,
"amountCents": 500,
"balanceCents": 1500
}
POST /wallet/topup reusing that key for a different amount
Request:
{
"walletId": 1,
"amountCents": 700
}
Response (409 Conflict):
{
"error": "Idempotency-Key already used with a different request",
"timestamp": "2026-08-11T09:08:23.434469Z",
"path": "/wallet/topup"
}
POST /wallet/topup without the header
Request:
{
"walletId": 1,
"amountCents": 500
}
Response (400 Bad Request):
{
"error": "Idempotency-Key header is required",
"timestamp": "2026-08-11T09:08:23.446513Z",
"path": "/wallet/topup"
}
POST /wallet/topup for a wallet that does not exist
Request:
{
"walletId": 99,
"amountCents": 500
}
Response (404 Not Found):
{
"error": "Wallet not found with id: 99",
"timestamp": "2026-08-11T09:08:23.460678Z",
"path": "/wallet/topup"
}
POST /wallet/topup with no amount
Request:
{
"walletId": 1
}
Response (400 Bad Request):
{
"error": "Amount is required",
"timestamp": "2026-08-11T09:08:23.473859Z",
"path": "/wallet/topup"
}
POST /wallet/topup with an amount below 1
Request:
{
"walletId": 1,
"amountCents": 0
}
Response (400 Bad Request):
{
"error": "Amount must be at least 1",
"timestamp": "2026-08-11T09:08:23.485007Z",
"path": "/wallet/topup"
}
POST /wallet/topup with a key that has never been used
Request:
{
"walletId": 2,
"amountCents": 250
}
Response (200 OK):
{
"topUpId": 2,
"walletId": 2,
"amountCents": 250,
"balanceCents": 2750
}
