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 calls | The RGS calls the casino. The casino never calls these endpoints on the RGS. |
| Base URL | One 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 body | POST, Content-Type: application/json, a JSON object. |
| Answer | HTTP 2xx with a signed JSON body, for success and for a business refusal, each field of its documented JSON type. See Answers. |
| Amounts | Integers in micro-units of the currency: 1000000 = 1.00, 200000 = 0.20. Never decimals, never floats. |
| Currency | ISO 4217 code, the currency of the player's session, for example GBP. |
| Signing | Every request and every 2xx response is signed with HMAC-SHA256 under a secret shared with the casino. See Signing. |
| Timeout | One 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. |
| Idempotency | Every 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 reads | When | Money |
|---|---|---|
| Success | 2xx, a valid response signature, "status": "ok" | Moved (or had already moved, with alreadyProcessed: true) |
| Definite refusal | 2xx, a valid response signature, "status": "error" and one of the codes INSUFFICIENT_FUNDS, LIMIT_EXCEEDED, SESSION_EXPIRED, LOCATION, PLAYER_BLOCKED, NOT_FOUND, BET_REJECTED | Did not move |
| Refused for configuration | HTTP 401 or 403, signed or not | Did not move. The problem is the key, not the transaction. |
| Unknown | Everything 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 above | Unknown |
What the RGS does next depends on the call:
| Answer | Debit | Credit | Rollback |
|---|---|---|---|
| Success | The round plays. | The round is closed. | The bet is returned; the round is closed. |
| Definite refusal | The 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 / 403 | The 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. |
| Unknown | The 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" }| Field | Type | Meaning |
|---|---|---|
status | "ok" or "error" | Required. Anything else is an unknown outcome. |
balance | integer | The 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. |
operatorTxId | string | The casino's own id of the operation. Optional. The RGS stores it with jackpot payouts. |
alreadyProcessed | boolean | true when this transactionId was already applied and nothing moved now. The RGS treats it as success. |
code | string | With "status": "error": one of the codes in Errors and money states. |
reason | string | Optional, an open list: why, in a word, such as bonus_max_bet or a responsible-gaming reason. At most 64 bytes are kept. |
message | string | Optional. Shown to the player as text, as is. At most 512 bytes are kept. |
details | object | Comes 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.
| Header | On | Value |
|---|---|---|
X-Key-Id | request | The id of the key the RGS signs with. |
X-Timestamp | request and response | Unix time in seconds. |
X-Signature | request and response | Lower-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 ab9c8a92f61d4df3464816effa9f24ad47d09ead9ddb21c0b634eda553d8718bThe 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 f854c0c69ebbf29a0d9650209056392590e78c383a943a55933829ff35ce1fbfHash 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.
| Operation | transactionId | Sent by |
|---|---|---|
| Debit of the bet | {roundId}:debit:1 | the RGS |
| Credit of the round's payout | {roundId}:credit | the RGS |
| Rollback of the bet | {roundId}:rollback:1, naming {roundId}:debit:1 in targetTransactionId | the 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
- Session start. When the player opens the game, the RGS reads the balance to show it. The game client may read it again later.
- 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.
- 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). - 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 answersokwithalreadyProcessed: trueand 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
okwith the current balance, return nothing, and record that the debit is cancelled. If that debit arrives later, refuse it with a listed code, for exampleNOT_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_FUNDSis correct: the player seesERR_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 withERR_GEN, reasonstate_settling, moneynot_charged, retryable. Nothing is debited.