JRGS Casino API
Wallet (seamless)

Balance

Reading a player's balance. Moves no money.

POST {baseURL}/balance returns the player's current balance in one currency. It moves no money, so whatever it answers, nothing has to be undone.

When the RGS calls it

  • When the game client opens a session (its authenticate call): the balance is shown in the game. If the call fails, the game does not start and the player sees the error.
  • When the game client asks for the balance again.

The RGS does not read the balance before a debit: the debit itself decides whether the player can pay.

Request

FieldRequiredTypeMeaning
playerIdyesstringThe casino's own player id, as sent in the launch request.
currencyyesstringISO 4217 code of the session.
POST /rgs/balance HTTP/1.1
Host: wallet.casino.example
Content-Type: application/json
X-Key-Id: rgs-1
X-Timestamp: 1793700000
X-Signature: <hex HMAC-SHA256, see /docs/authentication>

{"playerId":"p-1001","currency":"GBP"}

Response

{ "status": "ok", "balance": 100000000 }

balance is in micro-units: 100000000 is 100.00 GBP. Sign the response with X-Timestamp and X-Signature like every other answer (see the overview). operatorTxId and alreadyProcessed mean nothing here and may be left out.

What each answer causes

No money moves, so every failure answered by the wallet is shown to the player with the money state not_charged.

AnswerThe player sees
okThe balance.
SESSION_EXPIREDERR_IS, session is invalid.
LIMIT_EXCEEDED, PLAYER_BLOCKEDERR_GLE, player is limited.
LOCATIONERR_LOC, game is not available in this location.
Any other code, 401/403, or an unknown outcomeERR_GEN, wallet is unavailable. Marked retryable when the outcome was unknown.

Your reason and message travel with the error to the game client in every case. See Errors and money states.

Pitfalls

  • balance must be a JSON integer in micro-units. A decimal (100.00) or a string ("100.00") makes the whole answer unreadable, which is an unknown outcome: the balance read fails.
  • A balance in another currency is shown as it is. A negative balance is shown as 0.
  • INSUFFICIENT_FUNDS makes no sense on a balance read and is shown as a general error.
  • A failed balance read at session start keeps the game from opening, so it needs the same availability as the debit.

On this page