Guide · Wallet
What a wallet timeout actually means
A timeout is not a no. It means the caller did not get an answer in time, so it does not know whether the wallet moved money. Treating a timeout as a clean rejection is how players lose stakes or get paid twice.
7 min readUpdated By the Turnkeyxgaming team
Debit timeouts and credit timeouts are different problems
On a debit, the studio cannot leave the round open forever while your wallet thinks. If the response is late, the studio voids the round and sends a rollback. Your wallet must refund if it did take the stake, and must do nothing if it did not. That is only possible if the original debit is stored under an id you can look up. A timeout handler that 'just refunds' will invent money when the debit never landed.
A credit timeout is the opposite risk. The player has a win and your wallet has not confirmed it. The credit is retried with the same id until you acknowledge it. Do not generate a new id on the retry. Do not answer 'rejected' to a credit because the player has since spent the balance. The win belongs to the round that produced it.
Time the callback from the send, not from a log line after the handler returns. A debit that has moved the balance and then waits on a bonus recalculation is still late. Reply with the stored decision, including the balance it produced, before that work. A retry repeats those bytes without reading the live balance.
What each silent callback is asking
Recovery depends on which call went quiet.
| Call that went quiet | What the studio does next | What your row must already say |
|---|---|---|
| Debit | Voids the round and sends a rollback. A late commit still has to be reversible. | Debit id, whether money moved, and the balance you would have returned. |
| Credit | Retries the same id until you acknowledge it. A fresh id on that retry pays the win twice. | Credit id and the exact acknowledgement. Refuse only if the first attempt truly refused. |
| Rollback after a debit timeout | Retries until you confirm. A debit you never took is a no-op, not an error. | The debit id it names, and a marker that this reversal has already been applied. |
Timeout rules worth writing down
- 01
Store every id
Persist the debit or credit id before you move money, not after.
- 02
Rollback is a question
On rollback, look up the debit. Refund only if that debit succeeded.
- 03
Retry credits
Acknowledge a repeated credit with the original result. Do not pay it again and do not refuse it.
A socket timeout is not an insufficient-funds code
Mapping a dropped connection onto the response you use when the player cannot afford the stake tells the studio the round was refused. If the database then commits, the player has paid for a round that is already being voided. Stay silent until you know, and let the rollback ask whether money moved.
A cash-out credit that arrived three times
The timeline below is a worked example built from common retry shapes, not a reported incident at a named operator. Use it to rehearse the failure, and substitute your own timings.
Crash game, 60-second rounds, 4,000 players in one round on a Saturday. A player cashes out at 1.8x on a €100 stake, so the credit is €180. The request reaches the wallet, the handler opens a transaction, updates the balance and waits on a bonus recalculation queued behind the evening's reporting. The studio's retry timer is two seconds and it fires twice before the first response leaves.
Both retries carry the same credit id, but the handler deduped on round id and amount, and the first transaction had not committed. Three handlers, three transactions, one balance credited three times: €540 where €180 was due. The recalculation finished, all three committed, and the player withdrew €360 that did not belong to them. The daily file the next morning showed three credits with the same round id and identical amounts, which is how it was found.
The repair has two halves and both are required. The dedupe key becomes the studio's credit id, written inside the same transaction as the balance change. And nothing slow stays in the handler: the bonus recalculation moves to an event published after the commit, so the response is the stored decision rather than a wait. A retry arriving while the first call is open should block briefly on the key and return the first answer, not start its own work. The stuck round escalation guide picks up the case where the retry itself never arrives.
Where the response time goes, and what to move out of the handler
Decide a total budget for the callback and allocate it across these steps. The allocation is yours; the order below is what keeps the number achievable.
| Step in the handler | Can it leave the request? | What it costs when it stays |
|---|---|---|
| Decryption and key check before the handler | No | Cheap, and the first thing to keep |
| Idempotency lookup and balance update | No | This is the transaction; everything else is optional |
| Bonus or wagering recalculation | Yes, as an event after commit | The commonest cause of a retry storm at peak |
| Fraud or velocity scoring | Usually, once the stake is accepted. Limits that must block a stake stay in front of the commit | A model on the hot path turns a busy round into timeouts |
| Write to a reporting or analytics store | Yes | A second write inside the handler doubles the failure surface |
| Player notification | Yes | Push and email belong behind the commit, never in front of it |
FAQ
Questions operators ask
What response time should the wallet aim for?
Fast enough that a live betting window and a crash cash-out do not expire while you are still in the database. Measure under concurrency, not with a single curl.
Should we open a second debit when the first callback feels slow?
No. Finish the transaction you started. If the studio has already disconnected, the stored debit id is what the rollback will look up. A second debit under a new id takes the stake twice for one round.
Can live betting windows and crash cash-outs share one database timeout?
They should not wait on the same downstream job. A cash-out that arrives after the multiplier has crashed is the studio's decision to accept or ignore. Your handler still owes a stored answer quickly. Neither call should sit behind a report query or a bonus rebuild.
Should we ask for a longer retry interval so the wallet has more time?
You can ask, but the studio's retry window is not yours to set, and a longer interval does not help while the handler waits on a job. Fix the hot path first. Then agree the interval in writing, because a retry landing after your own transaction timed out is a duplicate you answer from the stored row anyway.
What should we log when a callback times out and we never answered?
The request id, the round id, and the moment the handler started and committed, even when the response never left. That row is what proves whether money moved when the studio asks. A log line written only after the response is sent says nothing about the call that went quiet.
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 · 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 · ArchitectureHow a casino API worksOne casino round traced end to end: catalogue, launch, wallet callbacks, settlement and the report line the next morning.Read
- IntegrationIntegrationSandbox keys, AES-encrypted wallet callbacks and the four wallet endpoints, then a 24–72 hour go-live once decryption and retries pass.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.