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: false and keep the round open — further debits (double/split/insurance) and the closing credit for the same roundId will follow.
  • Apply the usual transactionId idempotency 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_CLOSED is 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.