Wallet Callbacks
When a player launches a game or places a bet, the RGS calls your backend to authenticate the player, debit, or credit the player's balance. You must implement these five endpoints at the callback URL registered during onboarding.
All callbacks are POST requests with a JSON body, signed with HMAC-SHA256 via X-Timestamp and X-HMAC-SHA256 headers. See Authentication for verification details.
Currencies & Amounts
Amounts in all callbacks are represented as decimal strings (e.g., "1.50") to avoid floating-point precision issues. Use GET /operator/currencies to fetch the current list of supported currency codes.
RMB is accepted as an alias for CNY. If you need a currency not listed, contact us during onboarding.
Authenticate
POST /callback/authenticate — Verify the player and return their balance when a session is launched.
The RGS calls this endpoint during POST /operator/launch to confirm that the player exists and is allowed to play.
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
requestId |
string | Yes | Unique identifier for this request |
playerId |
string | Yes | The player ID provided in the launch request |
currency |
string | Yes | Currency code for the session (e.g., "USD") |
gameCode |
string | Yes | Game code being launched (e.g., "dice-alpha") |
{
"requestId": "unique-request-id",
"playerId": "player-1",
"currency": "USD",
"gameCode": "dice-alpha"
}
Response Fields
| Field | Type | Required | Description |
|---|---|---|---|
requestId |
string | Yes | Echo back the requestId from the request |
status |
string | Yes | "OK" on success, or an error code |
balance |
string | Yes (if OK) | Player's current balance as a decimal string (e.g., "100.00") |
accountCurrency |
string | No | Player's wallet currency — must match the request currency if provided |
name |
string | No | Player's display name |
countryCode |
string | No | Player's country (ISO 3166-1 alpha-2) |
languageCode |
string | No | Player's language preference (ISO 639-1) |
birthDate |
string | No | Player's date of birth (YYYY-MM-DD) |
registrationDate |
string | No | When the player registered (YYYY-MM-DD) |
address |
string | No | Player's address |
excluded |
boolean | No | true if the player is self-excluded — the launch is refused |
excludedUntil |
string | No | Optional exclusion end date (YYYY-MM-DD), recorded for auditing |
{
"requestId": "unique-request-id",
"status": "OK",
"balance": "100.00",
"accountCurrency": "USD",
"name": "John Doe",
"countryCode": "US",
"languageCode": "en",
"birthDate": "1990-01-01",
"registrationDate": "2024-01-15",
"address": "123 Main St"
}
If accountCurrency is provided, it must match the currency sent in the request. A mismatch will cause the launch to fail.
Return excluded: true to refuse launch for a self-excluded player. The launch fails with player_self_excluded and the event is audited. See Responsible Gaming.
Debit
POST /callback/debit — Deduct the bet amount from the player's balance.
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
requestId |
string | Yes | Unique identifier for this request |
playerId |
string | Yes | The player placing the bet |
transactionId |
string | Yes | Unique transaction ID — use as idempotency key |
roundId |
string | Yes | The game round this debit belongs to |
gameCode |
string | Yes | Game code (e.g., "dice-alpha") |
amount |
string | Yes | Bet amount as a decimal string (e.g., "1.50") |
metadata |
string | No | JSON string with extra transaction details |
{
"requestId": "unique-request-id",
"playerId": "player-1",
"transactionId": "unique-transaction-id",
"roundId": "round-uuid",
"gameCode": "dice-alpha",
"amount": "1.50",
"metadata": "{}"
}
Response Fields
| Field | Type | Required | Description |
|---|---|---|---|
requestId |
string | Yes | Echo back the requestId from the request |
status |
string | Yes | "OK" on success, or an error code |
balance |
string | Yes (if OK) | Player's balance after the debit |
customUserError |
string | No | Message displayed to the player when the debit is rejected |
{
"requestId": "unique-request-id",
"status": "OK",
"balance": "98.50"
}
Credit
POST /callback/credit — Credit the player's balance with winnings.
The RGS sends a credit callback for every round, also when the player loses. For a loss, the amount is "0".
A credit or a rollback closes each round. A debit alone never closes a round.
Check roundClosed when a callback arrives. A round can include several credits, and only the final credit closes it.
A credit with amount: "0" and roundClosed: true signals the round ended with no payout. Always respond with OK and the current balance.
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
requestId |
string | Yes | Unique identifier for this request |
playerId |
string | Yes | The player receiving the credit |
transactionId |
string | Yes | Unique transaction ID — use as idempotency key |
roundId |
string | Yes | The game round this credit belongs to |
roundClosed |
boolean | Yes | true if this credit closes the round |
gameId |
string | Yes | Game code (e.g., "dice-alpha") |
amount |
string | Yes | Payout amount as a decimal string — "0" for losses |
metadata |
string | No | JSON string with extra transaction details |
{
"requestId": "unique-request-id",
"playerId": "player-1",
"transactionId": "unique-transaction-id",
"roundId": "round-uuid",
"roundClosed": true,
"gameId": "dice-alpha",
"amount": "3.00",
"metadata": "{}"
}
Response Fields
| Field | Type | Required | Description |
|---|---|---|---|
requestId |
string | Yes | Echo back the requestId from the request |
status |
string | Yes | "OK" on success, or an error code |
balance |
string | Yes (if OK) | Player's balance after the credit |
{
"requestId": "unique-request-id",
"status": "OK",
"balance": "101.50"
}
sessionToken is not included in credit callbacks — payouts must succeed even after session expiry.
Non-Closing Credits
Some games settle part of a round before it ends. In multiplayer blackjack, two kinds of winnings are decided the moment the cards are dealt: side bets (Perfect Pairs, 21+3), and a player's natural blackjack when the dealer's upcard is neither an ace nor a ten-value card (a dealer natural is then impossible, so the 3:2 win is guaranteed). The RGS credits both immediately after the deal in a single credit with roundClosed: false, while the remaining hands play on. The round's final credit arrives later with roundClosed: true and excludes the amount already paid.
Your implementation must:
- Accept a credit with
roundClosed: falseand keep the round open — further debits (double/split/insurance) and the closing credit for the sameroundIdwill follow. - Apply the usual
transactionIdidempotency to every credit independently. - Handle a credit arriving after the round closed (a retried early credit can be overtaken by the closing credit). Accepting it is preferred; rejecting it with
ERROR_ROUND_CLOSEDis also valid but moves the payout to manual reconciliation.
A round can therefore contain several debits and up to two credits, and it is always the credit (or rollback) with roundClosed: true that ends it. The integration tester certifies this pattern under Multi-Credit Rounds (tests 46-48).
Balance
POST /callback/balance — Return the player's current balance (e.g., when loading the game UI).
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
requestId |
string | Yes | Unique identifier for this request |
playerId |
string | Yes | The player whose balance to return |
{
"requestId": "unique-request-id",
"playerId": "player-1"
}
Response Fields
| Field | Type | Required | Description |
|---|---|---|---|
requestId |
string | Yes | Echo back the requestId from the request |
status |
string | Yes | "OK" on success, or an error code |
balance |
string | Yes (if OK) | Player's current balance |
{
"requestId": "unique-request-id",
"status": "OK",
"balance": "100.00"
}
Rollback
POST /callback/rollback — Reverse a previously placed bet. The RGS sends this when a debit callback fails (500 response, timeout, etc.) to ensure the player doesn't lose money if the debit was applied on your side. The reverseTransactionId identifies which debit transaction to reverse.
Your server must handle rollbacks that arrive before the corresponding debit — or for debits your server never acknowledged. If a debit call times out from the RGS side, the RGS may issue a rollback even though your server never confirmed the debit. Treat a rollback for an unknown reverseTransactionId as successful (return OK) since the original debit was never applied.
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
requestId |
string | Yes | Unique identifier for this request |
playerId |
string | Yes | The player whose bet is being reversed |
transactionId |
string | Yes | Unique transaction ID for this rollback — use as idempotency key |
reverseTransactionId |
string | Yes | The transactionId of the original debit being reversed |
roundId |
string | Yes | The game round this rollback belongs to |
roundClosed |
boolean | Yes | true if this rollback closes the round |
gameId |
string | Yes | Game code (e.g., "dice-alpha") |
metadata |
string | No | JSON string with extra transaction details |
{
"requestId": "unique-request-id",
"playerId": "player-1",
"transactionId": "rollback-transaction-id",
"reverseTransactionId": "original-bet-transaction-id",
"roundId": "round-uuid",
"roundClosed": true,
"gameId": "dice-alpha",
"metadata": "{}"
}
Response Fields
| Field | Type | Required | Description |
|---|---|---|---|
requestId |
string | Yes | Echo back the requestId from the request |
status |
string | Yes | "OK" on success, or an error code |
balance |
string | Yes (if OK) | Player's balance after the rollback |
{
"requestId": "unique-request-id",
"status": "OK",
"balance": "100.00"
}
sessionToken is not included in rollback callbacks — reversals must succeed even after session expiry.
Response Status Codes
All callback responses must include a status field. Return "OK" on success, or one of these error codes:
Answer every callback you process with HTTP 200, including errors: put the error in status. The RGS treats any other HTTP status as a failed call, whatever the body says. It rolls back a debit answered that way (the player sees a generic error instead of, say, insufficient funds) and keeps retrying a credit or rollback until it gets a 200. Requests that fail signature verification may be refused either way.
| Status | Meaning |
|---|---|
OK |
Success |
ERROR_NOT_ENOUGH_MONEY |
Insufficient funds to place the bet |
ERROR_PLAYER_DISABLED |
Player account is locked or disabled |
ERROR_INVALID_SESSION |
Session token is unknown |
ERROR_SESSION_EXPIRED |
Session has expired |
ERROR_INVALID_GAME |
Game is unknown or disabled |
ERROR_WRONG_CURRENCY |
Currency mismatch with player's wallet |
ERROR_DUPLICATE_TRANSACTION |
transactionId already processed with different parameters |
ERROR_TRANSACTION_DOES_NOT_EXIST |
Rollback target bet was never processed (treat as success) |
ERROR_ROUND_CLOSED |
Credit rejected because the round is already closed (see Non-Closing Credits) |
ERROR_INVALID_SIGNATURE |
HMAC verification failed |
ERROR_WRONG_SYNTAX |
Malformed request |
ERROR_UNKNOWN |
Any other error. On a debit, the RGS treats it as ambiguous and sends a rollback |
Idempotency
Every /callback/debit, /callback/credit, and /callback/rollback request includes a unique transactionId. Your server should use this as an idempotency key — if you receive a request with a transactionId you've already processed, return the same successful response without applying the transaction again.
The RGS retries callbacks on transient failures (timeouts, 5xx responses). Each retry sends the same transactionId, so deduplication ensures transactions are only applied once.
Most games produce one debit and one credit per round, but your callback implementation must support multiple transactions per roundId: blackjack issues mid-round debits (double, split, insurance), and multiplayer blackjack can additionally send a non-closing credit for winnings already decided at the deal (side bets, natural blackjacks) before the closing credit.
Tap Trading
Tap Trading uses the existing callback endpoints and signature verification.
Its game code is tap_trading_3s.
Each accepted bet has a separate roundId and debit transaction, even if several bets share one column.
Each bet ends with a credit that has roundClosed: true. A loss sends a credit with amount: "0".
A refund sends a rollback with the original debit's reverseTransactionId.
An unknown debit result can also require a rollback.
Handle a rollback for an unknown debit as described in Rollback.
A failed credit or rollback can arrive again with the same transactionId.
Apply each transaction once. Return the successful response for a repeated transaction.
Accept credits and rollbacks after session expiry or player disconnect.
These callbacks do not require an active player session.
Crash and Take Off
Crash and Take Off use the existing callback endpoints and signature verification.
Their game codes are crash and takeoff.
Each bet has a separate roundId and debit transaction. In Take Off, the two bets of one player in one flight have two roundId values.
The RGS sends the debit when the betting countdown ends. A bet that the player cancels before then produces no callback.
Each bet ends with one credit that has roundClosed: true, sent after the crash. A loss sends a credit with amount: "0".
Many bets settle at the same crash, so expect a burst of credits after each round.
A refused debit removes the bet from the round, and no rollback follows. A debit with an unknown result sends a rollback. Handle it as described in Rollback. A debit that is approved after the flight starts also sends a rollback, because the bet cannot play.
A failed credit or rollback can arrive again with the same transactionId.
Apply each transaction once. Return the successful response for a repeated transaction.
Accept credits and rollbacks after session expiry or player disconnect.
These callbacks do not require an active player session.