Product · Wallet
Casino wallet API: one seamless wallet for every game
The casino wallet API is the contract between our servers and your ledger.
- balance
- debit
- credit
- rollback
- idempotency
- retries
Concepts
Seamless wallet vs transfer wallet
With a seamless wallet the player's money never leaves your system: every stake is a debit request to your endpoint, every win is a credit, and your response is the final word on the balance. It is a single wallet API for every studio and for sportsbook.
In a seamless wallet the player's balance lives only in your ledger. In a transfer wallet the player moves money into a game or provider sub-wallet, plays there, and moves it back afterwards. The transfer wallet casino model is easier for a provider to build but harder for players and finance: balances split, transfers fail half-way, and support tickets follow. Turnkeyxgaming integrates as an operator seamless wallet by default. The seamless vs transfer wallet guide compares the two in detail.
The practical result is a unified wallet across aggregated games. A player who wins on a slot can join a live table straight away and then bet on football, because an aggregator with sportsbook on the same wallet settles both. There is one balance, one history and one place to apply limits. That is what a single wallet for casino and sportsbook means in daily operation. The unit those calls belong to is a game round.
Calls
Bet, win and rollback API calls
Every money movement is one of four calls. The bet, win and rollback API calls carry a transaction UUID, and that UUID is how duplicates are detected.
{
"transaction_id": "5d1c9a8e-2f3b-4c7a-9e61-0b8f2a7c4d11",
"round_id": "rnd_4471920",
"player_id": "p_82731",
"game_id": "pg_fortune_tiger",
"amount": "2.00",
"currency": "EUR"
}
200 OK
{ "status": "ok", "balance": "148.00", "currency": "EUR" }The four wallet calls
| Call | When it fires | Your responsibility |
|---|---|---|
| Balance | Game load and periodic refresh | Return the spendable balance for the session currency |
| Debit (bet) | Before a round or a bet is accepted | Reject on insufficient funds; never go negative |
| Credit (win) | When a round settles, including zero-win settlements | Credit exactly once per transaction UUID |
| Rollback | When a debit must be reversed (void, timeout, studio error) | Refund the original debit once; treat an unknown original as already reversed |
Reliability
Idempotency, retries and duplicate handling
Networks fail, and wallets have to assume that every request may arrive twice. An idempotent casino wallet API stores each transaction UUID with its result; in a transaction-UUID casino wallet, that stored result is the source of truth. If the same UUID arrives again, you return the stored result instead of moving money again. That one rule handles almost all casino duplicate transaction handling.
Casino callback retry rules follow from it. If your endpoint times out on a credit, we retry the same request with the same UUID until you acknowledge it or the retry window in your agreement expires, so a win is not lost to one dropped packet. If a debit times out, the round is not started and a casino transaction rollback is sent for that UUID, so a stake is never kept without a game. Persist a cancellation marker when a rollback names a debit that has not committed yet; the debit reads that marker at commit and refuses to settle, rather than depending on a later retry that may never arrive. Log every casino wallet callback with its UUID, round and response. When a player disputes a balance, that log is your evidence.
The retry window is a contract term, not an unlimited promise. Your agreement states how long each side keeps retrying, after which the open item moves to reconciliation with a named owner. That is why the wallet test suite includes a rollback that lands before its debit commits: the state machine, not the retry count, is what makes the outcome deterministic.
Seamless wallet integration checklist
Casino wallet integration is finished when your seamless wallet API passes these checks in sandbox:
- The same transaction UUID twice returns the same result and the balance moves once
- A rollback for an unknown transaction returns success without changing the balance
- A rollback that arrives before an in-flight debit commits leaves a cancellation marker, and the debit cannot settle afterwards
- A debit larger than the balance is rejected with the documented error code
- Responses stay well inside the timeout under burst load from live and crash games
- Every callback decrypts cleanly and passes the freshness check before the body is trusted
- Player balance API casino responses use the session currency and the agreed decimal precision
Multi-currency casino wallets
A multi-currency casino wallet holds balances per currency, and each game session runs in one currency only. A EUR/GBP casino wallet, for example, should open a EUR session for a EUR balance and must never convert silently mid-round. Studios publish the currencies each game supports, and the catalogue exposes that, so your lobby can hide titles that do not support the player's currency.
The igaming wallet API does not set exchange rates or move money between currencies. That remains your ledger's job, along with deposits and withdrawals. The casino payment API page explains how payments sit next to the wallet without passing through it.
FAQ
Questions operators ask
Do you offer a transfer wallet option?
Some studios only support a transfer wallet. Where that applies we explain the trade-offs during onboarding, but the default integration is the seamless one-wallet casino API described here.
What happens if my wallet is down?
New rounds cannot start because debits fail. Pending credits are retried on the same transaction UUID inside the retry window set in your agreement, so a win is not lost to one dropped callback. When that window closes, the open item moves to reconciliation with a named owner instead of being retried indefinitely.
Is the unified wallet casino API the same for sportsbook?
Yes, with one addition: sport bets stay open for hours or days, so credits arrive long after the debit. Your ledger should track open bets accordingly.
Keep reading
Related pages
- DocumentationAPI docsAuthentication, the game list, demo and real launch, AES-encrypted wallet callbacks and error handling, with test keys to start.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
- GlossarySeamless walletA seamless wallet keeps the balance on the operator's ledger and posts every bet and win as a live callback, per round, in the session currency.Read
- Guide · WalletsSeamless vs transfer walletA seamless wallet debits your ledger per round. A transfer wallet moves a balance into the game and back, and that split shows.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 · 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
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.