Guide · Wallet
A repeated debit moves money once
Networks retry. A debit your wallet already applied will arrive again after a lost response. If you apply it again, the player pays twice for one stake. Idempotency means the second call returns the first answer.
7 min readUpdated By the Turnkeyxgaming team
Store the decision, not only the balance
The key is the transaction id the aggregator sends, not a hash you invent from the amount and the timestamp. Two genuine bets can share an amount and a second. They will not share an id. The row you store is: this id, this player, this amount, this result. When the same id returns, you reply with the stored result even if the player's balance has since changed.
Idempotency has a scope. A debit id and a credit id are different keys even if a careless implementation uses one column. A rollback refers to the debit id. It is not a third debit. If your unique index is only on (player, amount), you will block a legitimate second bet and you will still double-charge a retry that changed shape slightly.
Insert the idempotency row in the same database transaction as the balance movement. A handler that commits the id first and updates the balance second can answer a retry from the insert while the money change is still uncommitted. The opposite order moves the money and then loses the insert, so the retry is free to move it again. One transaction holds the id, the outcome and the balance change, or it holds none of them.
Fields the stored reply needs
A replay should return the first answer without recomputing it. Any field you leave out will be invented from the live account, which has already moved on.
- The transaction id exactly as it arrived, including any brand prefix, so a trimmed copy becomes a different key.
- Player id and brand id beside it. Two brands will both issue an id that looks identical if you let the studios share a sequence.
- Amount and currency actually applied. A retry whose body was corrupted in transit still has to echo the original money.
- Whether you accepted or refused, plus the balance figure you sent the first time, not the balance now.
- A support timestamp stored off to the side. Time is not part of the key. Two real bets can share a second.
A safe debit handler
- 01
Insert first
Write the transaction id in a unique column before you change the balance.
- 02
Return the stored row
On a conflict, read the original result and return it unchanged.
- 03
Separate types
Keep debit, credit and rollback ids from collapsing into one namespace.
A unique-index clash is the retry's success path
When the insert conflicts, load the original row and answer with it. Rewriting that row to the player's latest balance, because the conflict handler felt helpful, destroys the evidence the studio is replaying to recover.
Two real bets and one retry in disguise
The two failures below are illustrative shapes, not sourced case reports. They show why the dedupe key has to come from the contract rather than from a convenient column.
Live roulette, €25 on red. The player taps repeat twice inside a second because the first press gave no feedback. Two genuine bets, two transaction ids, same amount, same second, same table. A wallet with a unique index on player, amount and second refuses the second bet, and the player is told they cannot stake with €400 in the account. That is the first failure: a dedupe key broad enough to reject real play.
The second failure came from the same table a month later. A proxy between the aggregator and the wallet trimmed a brand prefix from the transaction id, so `pk_88213` arrived as `88213` on retries routed the other way. The index on the full id never saw a clash. The stake left twice at €25, and support found it only when the player disputed a balance €25 lower than history with no matching round.
Both failures share a cause: the key was chosen for convenience rather than from the contract. The id that has to survive is the one the studio generated, byte for byte, prefix included, in a column nothing else writes to. A repeat tap is legitimate play, so it produces two ids and two rows that both belong. Nothing about the player, the amount or the clock is allowed to stand in for that id, and a proxy that rewrites it is a change to the wallet's primary key.
Keys people try, and what each one gets wrong
| Candidate key | Legitimate case it blocks | Retry it lets through |
|---|---|---|
| Player, amount and second | A double tap, a repeat bet, two side bets on one table | A retry that arrives in the next second |
| Round id only | Split bets, a gamble feature, a second cash-out in one round | A credit retried under the round, which needs its own key |
| A hash of the request body | Nothing, until a field is reordered or a timestamp is added in transit | A retry with any field changed, which is what a broken client sends |
| The studio id trimmed to fit a column | Nothing, until the prefix matters | The retry carrying the full id, which looks new |
| The studio id stored whole | Nothing legitimate; it is the contract's own key | Only a reused id, which is the case you want to catch |
FAQ
Questions operators ask
How long do we keep idempotency keys?
Longer than the studio retries, and long enough for a next-day dispute. A key you delete after ten minutes will be spent twice when a delayed retry arrives.
What if the same debit id comes back with a different amount?
Do not apply the new figure. Return the stored result and raise an alert. One id with two amounts means the body changed in flight or a client rebuilt the request. It is not a second stake.
Is the round id enough to make a debit idempotent?
Only when that studio truly posts one debit per round. Splits, live side bets and a second crash cash-out can each carry their own debit under one round. Key the debit on its transaction id.
Do balance reads need idempotency keys?
No, because they move no money. They do need a timestamp and a session reference, since a balance answer arriving after the player has staked is worth nothing to the client. Answer from the current commit and let the client discard a stale reply rather than replaying an old one.
What do we do with a debit id that arrives in a different currency?
Return the stored result and raise it for a human. One id recorded twice in two currencies means the body changed in flight or two wallets share a namespace. Applying the new currency is the one action that cannot be undone quietly, because round history will then disagree with the ledger about the stake.
Keep reading
Related pages
- Product · WalletWalletBalance, bet, win and rollback on one seamless wallet: idempotent transaction ids shared by casino games and sportsbook alike.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
- GlossaryIdempotencyAn idempotent wallet call can be repeated: the same transaction id returns the first result and never moves money twice.Read
- Guide · ArchitectureHow a casino API worksOne casino round traced end to end: catalogue, launch, wallet callbacks, settlement and the report line the next morning.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.