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.

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.

{
  "requestId": "unique-request-id",
  "playerId": "player-1",
  "currency": "USD",
  "gameCode": "dice-alpha"
}

{
  "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"
}

Only requestId, status, and balance are required in the response. All other fields (accountCurrency, name, countryCode, languageCode, birthDate, registrationDate, address) are optional and used to enrich the player profile.

If accountCurrency is provided, it must match the currency sent in the request. A mismatch will cause the launch to fail.

Debit

POST /callback/debit — Deduct the bet amount from the player's balance.

{
  "requestId": "unique-request-id",
  "playerId": "player-1",
  "transactionId": "unique-transaction-id",
  "roundId": "round-uuid",
  "gameCode": "dice-alpha",
  "amount": "1.50",
  "metadata": "{}"
}

The optional metadata field is a JSON string with extra transaction details.

{
  "requestId": "unique-request-id",
  "status": "OK",
  "balance": "98.50"
}

You may include a customUserError string in the response — this message will be displayed to the player.

Credit

POST /callback/credit — Credit the player's balance with winnings.

Check roundClosed to determine if the round has ended. A round can produce multiple credit callbacks before closing (e.g., multi-action games like Mines).

A credit with amount: "0" and roundClosed: true signals the round ended with no payout (the player lost). Always respond with OK and the current balance.

{
  "requestId": "unique-request-id",
  "playerId": "player-1",
  "transactionId": "unique-transaction-id",
  "roundId": "round-uuid",
  "roundClosed": true,
  "gameId": "dice-alpha",
  "amount": "3.00",
  "metadata": "{}"
}

{
  "requestId": "unique-request-id",
  "status": "OK",
  "balance": "101.50"
}

sessionToken is not included in credit callbacks — payouts must succeed even after session expiry.

Balance

POST /callback/balance — Return the player's current balance (e.g., when loading the game UI).

{
  "requestId": "unique-request-id",
  "playerId": "player-1"
}

{
  "requestId": "unique-request-id",
  "status": "OK",
  "balance": "100.00"
}

Rollback

POST /callback/rollback — Reverse a previously placed bet (e.g., if an error occurs after debit but before the round completes). 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.

{
  "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": "{}"
}

{
  "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:

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_INVALID_SIGNATURE`	HMAC verification failed
`ERROR_WRONG_SYNTAX`	Malformed request
`ERROR_UNKNOWN`	Any other error

Idempotency

The transactionId field serves as an idempotency key in /callback/debit, /callback/credit, and /callback/rollback. A single round can produce multiple callbacks (e.g., multi-action games). Your server should use transactionId to detect and safely deduplicate retried requests — return the same successful response if a transactionId has already been processed.

sequenceDiagram
    participant RGS as RGS
    participant Op as Your Server

    RGS->>Op: POST /callback/debit (txn-1)
    Note over Op: Network timeout
    RGS->>Op: POST /callback/debit (txn-1, retry)
    Op-->>RGS: { status: "OK", balance: "98.50" }
    Note over Op: Same txn-1 → return cached response

Authentication

Sessions