JRGS Casino API

Retries, idempotency and reconciliation

Which transaction ids repeat, what your wallet must do with a repeat, how the RGS retries, and how the two ledgers are compared.

Every wallet call can be lost on the way: the request may never reach you, or your answer may never reach the RGS. Neither side can tell those two cases apart. The protocol stays safe because every money movement has a fixed transactionId, the RGS sends the same id every time it repeats a call, and your wallet applies an id at most once.

This page covers what the RGS repeats and when, what your wallet must guarantee in return, what happens when a credit cannot be paid, and how your ledger is compared with the RGS journal afterwards. The individual calls are described under Wallet, and the codes your wallet may answer under Errors and money states.

Transaction ids

A round's ids are built from its roundId and never change, not across retries, restarts or a move of the round to another server:

CalltransactionIdSent by
Debit of the bet{roundId}:debit:1the RGS
Credit of the win{roundId}:creditthe RGS
Rollback of the bet{roundId}:rollback:1 (its targetTransactionId is {roundId}:debit:1)the RGS
Credit of a jackpot win{roundId}:jackpot:{pool}:{level}:{index}the RGS jackpot service, see Jackpots

Treat the id as an opaque string. Do not parse it, and do not assume a roundId is a UUID: the conformance suite sends ids such as conformance-…-r1:debit:1.

Every round whose debit you did not refuse ends with exactly one of its own credit or rollback, unless the RGS team marks it settled by hand, and a credit is sent even when the win is zero. A round whose debit you refused with a listed code gets neither.

What your wallet must guarantee

The same transactionId has the same effect, once. A second call with an id you have already applied moves no money and answers status: ok, alreadyProcessed: true, and the balance. Check a debit in this order: first whether a rollback already named its id (then refuse it, see below), then whether you already know the id (then answer alreadyProcessed: true), and only then the player and the balance. A repeated debit for a player who has since been blocked, or whose balance has since dropped, must still answer alreadyProcessed: true, because the money was already taken. Refusing it would tell the RGS the bet was never taken.

A rollback of a debit you never saw succeeds, and is remembered. Answer status: ok (it returns nothing), and record that the debit's id is now cancelled.

A debit that arrives after its rollback is refused, definitely. The late debit is the original request, delayed in the network. Refuse it with a listed code that means "nothing moved". NOT_FOUND is what our own test wallets use. Do not answer DUPLICATE: the RGS reads DUPLICATE as "the outcome is unknown", and the conformance suite fails it. Never answer with a timeout or a non-2xx status.

Credit and rollback do not depend on the player. They settle money that is already decided. Accept them with an expired session, for a blocked or self-excluded player, and for a round you have no debit for: a round that pays out a carried player state is a credit with no debit, and a jackpot credit can arrive after the round's own credit.

The conformance suite checks each of these against your test wallet before a real market opens; see Conformance and going live.

A simple way to get them right is the one our own test wallet uses: make transactionId the primary key of your transactions table, apply each debit, credit and rollback in one database transaction that locks the player's row, and keep a table of rollbacks by the debit id they cancelled, which a debit checks before it applies.

What the RGS guarantees

  • One id per movement, on every attempt. A retry, a restart of an RGS server, or the round moving to another server sends the same transactionId and the same body.
  • A debit is sent once. If its outcome is unknown (a timeout, a network error, a non-2xx status other than 401/403, a bad signature on your answer, an unknown code, or DUPLICATE), the RGS does not repeat it: it records the debit as uncertain and starts a rollback of it. The player gets their money back either way. The one exception is recovery: an RGS server that stopped after recording a round's start and before recording the debit's outcome sends the debit again with the same id, and expects alreadyProcessed: true if it went through.
  • Credits and rollbacks are never given up. An unknown outcome is retried with the same id, with a backoff that starts at 200 ms and doubles up to 30 s between attempts, for as long as it takes. The retries survive a restart of an RGS server.
  • A definite refusal is not repeated automatically. See below.
  • Order only within a round. A round's debit comes before its credit or rollback. The player's next round of the same game waits up to 2 seconds for the previous round's credit before its debit, and not for a rollback, so either can still reach you after the next round's debit; see What the wallet must guarantee.

How long one call may take is set per casino; see Environments and limits.

When a credit or rollback does not finish

A credit or rollback that has not succeeded goes to the RGS operators' attention queue, Problem rounds:

What happenedWhat the RGS does
Unknown outcome, under 10 attempts and under 5 minutesRetries with backoff. Nothing is raised yet.
Unknown outcome, 10 attempts or 5 minutes reached (defaults)Raises the round in the attention queue once, and keeps retrying. When an attempt succeeds, the entry clears itself.
401 or 403 from your walletRaises the round as refused at once and stops, as for a definite refusal. Fix the keys, then the RGS operators retry the round. While the wallet secret rotates, accept both secrets until we confirm the switch (Rotating the wallet secret), so no round stops.
A definite refusal: status: error with a listed code (other than DUPLICATE, and NOT_FOUND on a rollback)Raises the round as refused and stops. Nothing is retried until a person acts.
NOT_FOUND on a rollbackDone: there was nothing to return.

The RGS tolerates NOT_FOUND on a rollback, but answer ok to a rollback of a debit you never saw: the conformance suite requires it.

A person at the RGS then does one of two things, both recorded in the audit log:

  • Retry now sends the same call again, with the same transactionId, and restarts the backoff.
  • Mark settled closes the round without any wallet call. It requires a reference and a comment, and is meant for when you have confirmed that the money was settled by hand.

Your users can see your casino's problem rounds in the backoffice (with the See round history permission). Retry now and Mark settled are done by the RGS team, not by casino accounts.

A definite refusal of a credit means manual work on both sides

A refused credit is a win the player has not been paid, held until people on both sides agree what to do. So your wallet should not refuse a credit. If it does:

  1. The round appears as refused in the attention queue. The player has not been paid.
  2. You find and fix the cause on your side.
  3. Either you ask us to Retry now, and the credit reaches your wallet again under the same transactionId; or you pay the player by hand and give us your reference, and we Mark settled with it.

Prefer the retry: it keeps the round's own transactionId in your ledger. A payment made by hand under another id shows up in reconciliation as missing_in_journal. If you pay by hand, do not then also ask for a retry: the retry would be a new credit to you if your manual payment did not use the round's id.

The same applies to a refused rollback, with the bet in place of the win.

Reconciliation

Reconciliation compares what the RGS journal says moved with what your wallet says it applied, by transactionId, in both directions, one period at a time. It moves no money and changes neither side.

It needs the optional export call, POST /operations, described in Operations. A casino without it is simply not reconciled; nothing else depends on it. To turn it on, switch the export on in your casino's wallet settings in the backoffice (the Manage keys permission) and tell us, so we enable it on our side. Once it is on, the next conformance run also checks the export on your test wallet, and a failure there fails the run.

How a period is compared

  • A period is one hour by default. It runs once its end plus the margin has passed.
  • The margin, one hour by default, is how far beyond the period each side looks for the other. It absorbs the two clocks and the time between your wallet applying an operation and the journal recording it.
  • The RGS asks your export for [from − margin, to + margin), in pages of up to 1000, and reads the journal for the same window.
  • An operation the journal requires in the period is looked up among everything you listed in the wider window, and an operation you list with at in the period is looked up among the journal's rounds of the wider window.
  • The first period of a casino is the last one already over (end plus margin passed) when reconciliation first runs for it. After that, each period follows the last one that finished. A period that failed (your export did not answer, for example) is recorded with its reason and compared again automatically. Any other period is compared again only when the RGS team re-runs it.

What the journal requires your export to list:

OperationRequired when
Debitthe round's debit is confirmed in the journal (the round resolved, or reached its credit)
Creditthe round's credit succeeded
Rollbackthe round was rolled back and you list its debit; its amount must equal the debit's. If you never had the debit, a rollback of amount 0, or no rollback at all, are both correct.
Jackpot creditnever required, because when it is paid is the jackpot service's; but if you list one, it is checked

A free round is a credit with no debit, and the journal expects exactly that: its credit is required in your export, and a debit for it is not. Its credit's id is the ordinary {roundId}:credit, with freeRounds in the body.

Differences

KindMeaning
missing_at_casinoThe journal requires the operation; your export does not list it.
missing_in_journalYou list an operation for a round the journal does not have, or one the journal forbids: a debit the RGS records as refused, a credit on a round that was rolled back, a rollback on a round that closed, or an id the round does not use.
amount_differsBoth sides have it, with a different amount or currency.
details_differBoth sides have it, for a different player or of a different type.

Operations whose transactionId starts with conformance- are left out, so the conformance suite may run against your live wallet with test players.

A jackpot credit ({roundId}:jackpot:…) is matched by amount, currency and player when the journal records that win, and by player and type only for a win the jackpot service found on its own. A jackpot credit for a round that was rolled back, voided, or never debited is missing_in_journal.

Rounds that began before the window are seen only in part: their amounts cannot be checked, they are counted as partial on the run, and their debit belongs to the period that saw it. A credit that kept retrying for longer than the margin shows as missing_at_casino in the period in which the RGS recorded it; the RGS team checks it against your ledger.

Where you see the result

In the backoffice, Reconciliation shows your casino's last runs (period, status, operations on each side, matched, differences, partial) and the open differences, to accounts with the See round history permission. When the RGS team compares the same period again, a difference it no longer finds is cleared. A difference closed by a person stays closed; closing one moves nothing and is done by the RGS team, with a comment.

On this page