JRGS Casino API

Conformance and going live

The checks your wallet must pass before a real market opens, how a run is made, and the go-live checklist.

Before your casino can take rounds on a real market, your wallet must pass the RGS wallet conformance suite. The suite calls a test wallet of yours with the real protocol and checks the behaviours that keep money safe: idempotency, rollbacks, the late debit, and refusals that mean what they say.

Until your wallet passes, your real markets take no new sessions; running rounds finish. Whether you can try the launch flow on a market before then is agreed at onboarding. See Environments and limits.

The gate

The suite has a version; it is 2 today. Your casino is certified when its latest run passed at the current version.

  • Without a current pass, starting a session on a real market is refused with ERR_WALLET_NOT_CERTIFIED (400, details.reason: wallet, retryable: false). See Launching a game.
  • A new round on a real market is refused as well, for a session that was already open: the game client gets ERR_MAINTENANCE, "game is not available". No money moves.
  • A round already running always finishes, and a player with a running round in a game can still open a session to finish it.
  • When a check is added or made stricter, the version goes up, and every casino on a real market has to pass again before it can start new sessions and rounds there. A check of something optional is skipped where it does not apply, and adding one does not raise the version.
  • The latest run counts, not the best one. A run that fails after an earlier pass closes your real markets to new sessions until a run passes again.

What a run does

The suite moves real balances on your test wallet. Run it on test players.

The checks run in this order. Each one has 15 seconds, each HTTP call 10 seconds, and the whole run 3 minutes. Redirects are not followed.

#CheckWhat it does, and what passes
1debit and credit move the balanceDebit amount, credit 2 × amount on the same round. The balance ends amount higher.
2a zero credit is acceptedDebit, then a credit of 0. The credit answers ok.
3a repeated debit charges onceThe same debit twice. The second answers alreadyProcessed: true; the balance fell by amount once.
4a repeated credit pays onceThe same credit twice, on a round with no debit. Both answer ok; the balance rose by amount once.
5a second debit in a round is a separate charge{roundId}:debit:1 and {roundId}:debit:2. The balance fell by 2 × amount.
6rollback returns a debit onceDebit, then the same rollback twice. The balance is back where it started.
7a late debit after its rollback is refusedA rollback of a debit you never saw answers ok; then that debit arrives and must be refused with a listed code, not an unknown outcome. The balance is unchanged.
8insufficient funds is a final refusalDebit amount for the poor player. Answer INSUFFICIENT_FUNDS.
9credit does not depend on the player's stateCredit amount to the blocked player, with no debit. Answer ok.
10a blocked player cannot be chargedDebit the blocked player. Answer PLAYER_BLOCKED.
11rollback does not depend on the player's stateRoll back an unseen debit of the blocked player. Answer ok.
12a bet rejection is a final refusalDebit amount for the bet-rejected player. Answer BET_REJECTED. Skipped if you give no such player.
13the export lists what the wallet appliedDebit, then page through POST /operations for the last and next five minutes. The debit is listed as type: debit with its amount. Skipped unless your casino has the export turned on.

Every id the suite sends starts with conformance- and is unique to the run, for example conformance-{uuid}-r3:debit:1, with gameId: conformance. Reconciliation leaves those ids out, so the suite may run against your live wallet as long as it uses test players. Checks 1–7 and 13 use the main player: give it a balance of at least 3 × amount, and expect each run to leave it up to 3 × amount lower. The blocked player gains amount per run.

A check that fails reports why, usually the wallet's code or "timeout".

The free rounds group

One more group of checks is optional: it is not part of the version, so adding it did not make any casino pass again. It has one check.

CheckWhat it does, and what passes
a free round credit with no debitA credit with a freeRounds object and no debit before it. The credit answers ok, and the balance rose by amount once.

The group is run after the checks above and has its own verdict, shown next to the run's. A failure there does not fail the run. But to award free rounds on a real market your latest run must have passed the group too; otherwise POST /free-rounds is refused with ERR_WALLET_NOT_CERTIFIED (details.reason: free_rounds). Demo and internal markets are exempt.

How a run is made

Running the suite opens a real market, so it is done by the RGS team, not from a casino account. You give us:

Field
Test wallet URLhttp or https; the base the protocol paths are appended to
Key id and secretthe pair the RGS signs with for this wallet; the secret is sealed when stored and never shown again
Playera test player with enough balance (see above)
Poor playera player whose balance is below the amount
Blocked playera blocked player
Bet-rejected playeroptional: a player whose debit of the amount you refuse with BET_REJECTED
Currencythe currency of all three or four players
Amounta positive amount in integer micro-units

Your casino's accounts with the See the casino permission can see the results: the required version, whether you are current, and the last ten runs with each check's result, who ran it and against which URL.

Testing against our wallets

We test the RGS against two wallets of our own, and their behaviour is the model for yours. Neither is published with these docs.

  • A minimal in-memory wallet used in the RGS's own tests. It applies an id once, answers repeats with alreadyProcessed: true, remembers every rollback's target, and refuses a debit whose rollback came first with NOT_FOUND.
  • A test casino that integrates the RGS as a real operator does, and passes the suite. All its state is in Postgres: transactionId is the primary key of its transactions, every debit, credit and rollback is one database transaction holding the player's row lock, and a table of rollbacks by debit id refuses the late debit. The RGS never reuses a transactionId with a different body; should one arrive with a changed player or amount, the test casino answers DUPLICATE, deliberately an unknown outcome. That is a guard, not a model to copy: answer a repeat with its first result. It serves the export, and can be made to time out (with or without moving the money), refuse with any listed code, or answer slowly, which is how we exercise the paths described in Retries, idempotency and reconciliation.

Go-live checklist

The protocol. Your wallet serves balance, debit, credit and rollback, verifies the RGS's signature, and signs every answer. See Wallet and Authentication and signing.

Idempotency and the late debit. A repeated transactionId answers alreadyProcessed: true and moves nothing, whatever the player's state now. A rollback of an unseen debit succeeds and is remembered; that debit, if it arrives, is refused with a listed code. See Retries, idempotency and reconciliation.

Credits always land. Credits and rollbacks are accepted with an expired session, for a blocked or self-excluded player, and for a round with no debit. So are credits with an amount of 0, and a second credit on a closed round for a jackpot win. Your wallet does not refuse a credit.

Refusals are definite. Every refusal of yours uses a listed code (see Errors and money states). Anything else is read as an unknown outcome: a debit is then rolled back, and a credit retried.

Speed. Keep the p99 of your debits, measured over 5-minute windows from our side, under 2 seconds: the player waits on every debit. We alert when it stays above 2 s for 10 minutes, and when more than 5 % of your calls time out over 5 minutes while you take more than about 6 calls a minute. The debit and settlement times of every round are kept and shown in round history.

Timeout. Agree with us the timeout of one call to your wallet. See Environments and limits.

Reconciliation. Serve the export, POST /operations, and have it turned on, so your ledger is compared with the journal every period. It is optional, and recommended. See Operations.

Conformance. Give us your test wallet's details and test players, and get a pass at the current version. Run again whenever the version goes up.

People. Name who on your side handles a refused credit or a reconciliation difference, and give your support staff backoffice accounts with See round history. See Jackpots, history and replay.

On this page