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.

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

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

Response Fields

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

Debit

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

Request Fields

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

Response Fields

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

Credit

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

The RGS always sends a credit callback, even when the player loses — the amount will be "0". A round is always closed by either a credit or a rollback, never by a debit alone. Check roundClosed to determine if the round has ended.

Request Fields

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

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

Balance

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

Request Fields

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

Response Fields

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

Request Fields

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

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

Response Status Codes

All callback responses must include a status field. Return "OK" on success, or one of these error codes:

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.

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