Glossary
Idempotency means the retry is harmless
An operation is idempotent if doing it twice has the same effect as doing it once. Wallet debits and credits need to be idempotent because networks retry when a response is lost.
3 min readUpdated By the Turnkeyxgaming team
Store the decision before you move the money
The practical test is a unique transaction id and a stored result. The debit guide shows the failure mode: a second debit that creates a second stake. Idempotency is not the same as a timeout policy. One says the retry is safe. The other says what you do when you never hear back.
GET requests are often idempotent by accident. Money movement is not. You have to build it.
Debit ids and credit ids are different keys
A unique index on transaction id only works if debit, credit and rollback do not share a namespace by accident. A credit that collides with a debit id will return the debit's result and the player will not be paid.
Keep the row longer than the retry window and longer than a next-day dispute. Deleting keys after ten minutes makes the next retry a second stake.
One debit, delivered four times
The game sends a €50.00 debit for round 8f21 at 12:00:01. The wallet commits it, the balance moves from €120.00 to €70.00, and the response is lost to a reset connection. The game retries at 12:00:04 with the same transaction id, again at 12:00:09, and a fourth time at 12:00:31 with the same id and a different amount.
Attempts two and three must return the stored acceptance, the balance of €70.00 and the same status as the first. Attempt four is a different request wearing a used key, and it has to fail loudly: the id is taken, the amount does not match, and something upstream is broken.
The cheap version of this is a unique index on the transaction id. It prevents the double debit and returns an error to the retry, which the game may read as a failed bet and void a round that is still live and holding the stake. Storing the response is the difference between a replay and a conflict.
Four deliveries of one debit
| Attempt | Time | Stored row | Correct response | Balance |
|---|---|---|---|---|
| First | 12:00:01 | None | Commit, 200, new balance | €70.00 |
| Retry | 12:00:04 | Accepted | 200, stored balance replayed | €70.00 |
| Retry | 12:00:09 | Accepted | 200, stored balance replayed | €70.00 |
| Same id, new amount | 12:00:31 | Accepted for €50.00 | 409, and an alert | €70.00 |
Where an idempotency key stops being one
- The key includes an attempt number or a timestamp, so every retry looks like new work to the index.
- Debits, credits and rollbacks share one id table, and a credit collides with a debit's key and returns a debit's result.
- The id is stored but the response is not, so a replay has to guess what happened to the money.
- Keys expire after minutes and a next-day dispute finds the player with a second stake and no evidence of the first.
- A cache in front of the wallet absorbs duplicates for a minute and then passes the retry straight through.
FAQ
Questions operators ask
Is a unique id enough if we do not store the response?
No. You also store the decision. Otherwise a retry after a success that you forgot will be treated as new work.
Should the player id be part of the idempotency key?
The transaction id should already be unique. Adding the player id is a useful safety check, not a replacement. Reject a retry that arrives with the same id and a different player.
Should a duplicate return 200 or an error?
Return the original result with its original status. A game that receives an error for a debit that already succeeded may void the round or refuse to continue, and the player sees a failure on a bet that took their money. Save the error for the case where the same key arrives with different content.
How long should the keys be kept?
Longer than any retry, any support window and any dispute you are prepared to lose. Months rather than minutes. The storage is cheap beside a duplicated credit, and the stored row is also the evidence that answers the ticket. Purge on a schedule you can explain to an auditor, not on a cleanup job somebody wrote once.
Keep reading
Related pages
- Guide · WalletIdempotent debitsA repeated debit with the same transaction id must take the stake once and return the answer you already stored, every time.Read
- Guide · WalletCallback timeoutsA wallet timeout is a missing answer, not a refusal: a late debit gets voided and a late credit gets retried by the studio.Read
- Product · WalletWalletBalance, bet, win and rollback on one seamless wallet: idempotent transaction ids shared by casino games and sportsbook alike.Read
- GlossarySettlementSettlement turns a round or a market into a win, a loss or a void, then credits the win or releases the reserved stake, once, on the record.Read
Get a written quote and sandbox access
Tell us your licence, target markets and products. You get the GGR rate in writing, the studio list for your markets and sandbox credentials.