JRGS Casino API
Wallet (seamless)

Wallet (seamless) overview

The seamless wallet the casino implements and the RGS calls: the contract on one page.

The player's money stays in the casino's wallet. The RGS never holds a balance: to take a bet, pay a win or return a bet it calls an HTTP API that the casino implements. This page is the contract on one page. Each call has its own page: balance, debit, credit, rollback and the optional operations export.

The contract

Who callsThe RGS calls the casino. The casino never calls these endpoints on the RGS.
Base URLOne per casino, for example https://wallet.casino.example/rgs. The RGS appends the call's path to it: /balance, /debit, /credit, /rollback, /operations. A trailing / on the base URL is ignored.
Method and bodyPOST, Content-Type: application/json, a JSON object.
AnswerHTTP 2xx with a signed JSON body, for success and for a business refusal, each field of its documented JSON type. See Answers.
AmountsIntegers in micro-units of the currency: 1000000 = 1.00, 200000 = 0.20. Never decimals, never floats.
CurrencyISO 4217 code, the currency of the player's session, for example GBP.
SigningEvery request and every 2xx response is signed with HMAC-SHA256 under a secret shared with the casino. See Signing.
TimeoutOne call has 5 seconds unless a different timeout is agreed for the casino (1 to 15 seconds). A call that runs out of time is an unknown outcome.
IdempotencyEvery money call carries a transactionId. A repeat of the same id must not move money twice.

The wallet must keep a debit's p99 latency under 2 seconds. A debit is on the player's path: the spin does not start until the casino answers.

Did money move: yes, no or unknown

The RGS judges every answer by one question: did the money move?

The RGS readsWhenMoney
Success2xx, a valid response signature, "status": "ok"Moved (or had already moved, with alreadyProcessed: true)
Definite refusal2xx, a valid response signature, "status": "error" and one of the codes INSUFFICIENT_FUNDS, LIMIT_EXCEEDED, SESSION_EXPIRED, LOCATION, PLAYER_BLOCKED, NOT_FOUND, BET_REJECTEDDid not move
Refused for configurationHTTP 401 or 403, signed or notDid not move. The problem is the key, not the transaction.
UnknownEverything else: no answer, a timeout, any other non-2xx status (400, 404, 500, 502 …), a missing or wrong response signature, a body that is not JSON or has a field of the wrong type (a balance sent as "99.00" or 99.00), a status other than ok or error, the code DUPLICATE, or a code not in the list aboveUnknown

What the RGS does next depends on the call:

AnswerDebitCreditRollback
SuccessThe round plays.The round is closed.The bet is returned; the round is closed.
Definite refusalThe round is void; the player sees why. No rollback.Retries stop; the round waits for a person in the RGS attention queue.Same as credit, except NOT_FOUND, which counts as done (but see Rollback).
401 / 403The round is void; the player sees a general error.The round goes to the attention queue at once and the RGS stops retrying until an operator retries it, once the keys are fixed.Same as credit.
UnknownThe RGS rolls the debit back.The RGS repeats the same call until it gets a final answer.Same as credit.

So a casino that refuses something must answer 2xx with a signed body and a listed code. A refusal sent as HTTP 400 or 500, or with a code of its own, is an unknown outcome: on a debit it leads to a rollback and the player sees a general error instead of the casino's reason.

Answers

Every call except the export answers with the same body.

{ "status": "ok", "balance": 99000000, "operatorTxId": "w-77812", "alreadyProcessed": false }
{ "status": "error", "code": "INSUFFICIENT_FUNDS", "message": "Not enough funds" }
FieldTypeMeaning
status"ok" or "error"Required. Anything else is an unknown outcome.
balanceintegerThe player's balance after the call, in micro-units. Send it with every ok: the RGS shows it to the player, and a missing value is read as 0.
operatorTxIdstringThe casino's own id of the operation. Optional. The RGS stores it with jackpot payouts.
alreadyProcessedbooleantrue when this transactionId was already applied and nothing moved now. The RGS treats it as success.
codestringWith "status": "error": one of the codes in Errors and money states.
reasonstringOptional, an open list: why, in a word, such as bonus_max_bet or a responsible-gaming reason. At most 64 bytes are kept.
messagestringOptional. Shown to the player as text, as is. At most 512 bytes are kept.
detailsobjectComes with BET_REJECTED. Flat, string values only; see Debit.

In reason and message the RGS replaces control characters with spaces and drops invalid UTF-8 before it stores them.

Signing

Both directions are signed with HMAC-SHA256 under the secret the casino and the RGS share. The secret is used as the bytes of the agreed string, not decoded from hex or base64. Full rules and key rotation are in Authentication and signing.

HeaderOnValue
X-Key-IdrequestThe id of the key the RGS signs with.
X-Timestamprequest and responseUnix time in seconds.
X-Signaturerequest and responseLower-case hex HMAC-SHA256 of the canonical string.

The canonical string has four lines joined by \n, with no trailing newline:

request:   {X-Timestamp}\nPOST\n{path}\n{sha256 hex of the body}
response:  {X-Timestamp}\n{HTTP status}\n{path}\n{sha256 hex of the body}

{path} is the path of the URL the RGS called, base URL path included and with no host or query: /rgs/debit for the base URL above. The response is signed over the same path as its request and over the status code actually sent, as a decimal number (200). Both sides refuse a timestamp more than 60 seconds away from their own clock: the casino should answer 401 to such a request, and the RGS treats such a response as an unknown outcome.

A worked example, secret example-secret, X-Timestamp: 1793700000, base URL https://wallet.casino.example/rgs. The request body, exactly as sent:

{"transactionId":"01a1a0d9-f100-7d2e-8f30-4a5b6c7d8e9f:debit:1","roundId":"01a1a0d9-f100-7d2e-8f30-4a5b6c7d8e9f","playerId":"p-1001","gameId":"slots","gameVersion":"1.0.0","variant":"957","currency":"GBP","amount":1000000}
sha256(body)  cda7a374b60bc03fa8e967c167a1a27c2e5872fc5738172b05396cf36c78bb44
signed        1793700000\nPOST\n/rgs/debit\ncda7a374b60bc03fa8e967c167a1a27c2e5872fc5738172b05396cf36c78bb44
X-Signature   ab9c8a92f61d4df3464816effa9f24ad47d09ead9ddb21c0b634eda553d8718b

The casino answers 200 with the body {"status":"ok","balance":99000000,"operatorTxId":"w-77812","alreadyProcessed":false}, sent with the same X-Timestamp. A response carries your own clock's time; this one happens to be signed in the same second:

sha256(body)  ffc51ac63ba19839e1175c46b247a73f06c81c117d5a1448a2d4c63e1cd4c832
signed        1793700000\n200\n/rgs/debit\nffc51ac63ba19839e1175c46b247a73f06c81c117d5a1448a2d4c63e1cd4c832
X-Signature   f854c0c69ebbf29a0d9650209056392590e78c383a943a55933829ff35ce1fbf

Hash and sign the body bytes as they travel. Parsing and re-serialising the JSON changes the bytes and breaks the signature. The RGS reads at most 1 MiB of a response.

Transaction ids

Each money call names its operation with a transactionId built from the round id. The RGS never changes a round's ids, and reconciliation matches the casino's ledger by them.

OperationtransactionIdSent by
Debit of the bet{roundId}:debit:1the RGS
Credit of the round's payout{roundId}:creditthe RGS
Rollback of the bet{roundId}:rollback:1, naming {roundId}:debit:1 in targetTransactionIdthe RGS
Credit of a jackpot win{roundId}:jackpot:{pool}:{level}:{index}the jackpot service

Rounds use UUIDs, for example 01a1a0d9-f100-7d2e-8f30-4a5b6c7d8e9f, but treat roundId and transactionId as opaque strings: the conformance suite sends ids such as conformance-…-r1. Today a round has exactly one debit. Treat every transactionId as its own operation all the same: the conformance suite checks that {roundId}:debit:2 would be a separate charge.

A round, call by call

  1. Session start. When the player opens the game, the RGS reads the balance to show it. The game client may read it again later.
  2. Bet. The RGS sends a debit of the stake, {roundId}:debit:1.
    • success: the outcome is drawn and shown;
    • definite refusal: the round is void and the player sees the reason; nothing else follows;
    • unknown: the RGS sends a rollback, {roundId}:rollback:1, and repeats it until the casino gives a final answer. The round ends there.
  3. Payout. When the round ends the RGS sends a credit, {roundId}:credit, also when the win is 0. A one-step spin is credited right after its debit. A round with player decisions (a bonus game, a gamble) is credited when the player finishes it, or, if the player leaves, when the RGS closes it automatically some time after the player was last seen (an hour in the shipped configuration).
  4. Jackpot. If the round won a jackpot, the jackpot service sends its own credit, {roundId}:jackpot:{pool}:{level}:{index}, apart from the round's credit. See Jackpots, history and replay.

A credit and a rollback are never both sent for one round: a round that was debited is either credited or rolled back.

There is one more case: when a game's new version settles a player's saved progress from an older version (for example, collected bonus symbols), the RGS opens a round of its own that only credits the settled amount, {roundId}:credit, with no debit before it.

What the wallet must guarantee

  • Idempotency by transactionId. A repeat of an applied operation moves nothing and answers ok with alreadyProcessed: true and the current balance.
  • Credit and rollback always succeed. They settle money that is already decided. Accept them for an expired session, a blocked or self-excluded player, and a closed game session. Accept a credit for a round whose debit you do not have.
  • A rollback of an unknown debit is remembered. Answer it ok with the current balance, return nothing, and record that the debit is cancelled. If that debit arrives later, refuse it with a listed code, for example NOT_FOUND, and do not charge.
  • A refusal is 2xx, signed, with a listed code. Anything else is an unknown outcome.
  • Calls arrive in order only within a round. A round's debit comes before its credit or rollback; nothing orders one round's calls against another's. The player's next round can start as soon as the previous round's outcome is recorded, or as soon as its debit is recorded as unknown, while that round's credit or rollback is still being retried in the background. The RGS waits up to 2 seconds for a pending credit of the same game before the next debit; other games of the player are not waited for, and neither is a pending rollback. After those 2 seconds the debit goes out anyway. So accept a credit or rollback of one round after the debit of the player's next round. Until that credit lands your balance lacks the win, and refusing the next debit with INSUFFICIENT_FUNDS is correct: the player sees ERR_IPB. One exception: while the RGS credits the settlement of a player's saved progress, it holds the player's new round of that game and stake for up to 2 seconds, then refuses it with ERR_GEN, reason state_settling, money not_charged, retryable. Nothing is debited.

On this page