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:
| Call | transactionId | Sent by |
|---|---|---|
| Debit of the bet | {roundId}:debit:1 | the RGS |
| Credit of the win | {roundId}:credit | the 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
transactionIdand the same body. - A debit is sent once. If its outcome is unknown (a timeout, a network
error, a non-
2xxstatus other than401/403, a bad signature on your answer, an unknown code, orDUPLICATE), 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 expectsalreadyProcessed: trueif 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 happened | What the RGS does |
|---|---|
| Unknown outcome, under 10 attempts and under 5 minutes | Retries 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 wallet | Raises 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 rollback | Done: 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:
- The round appears as refused in the attention queue. The player has not been paid.
- You find and fix the cause on your side.
- 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
atin 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:
| Operation | Required when |
|---|---|
| Debit | the round's debit is confirmed in the journal (the round resolved, or reached its credit) |
| Credit | the round's credit succeeded |
| Rollback | the 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 credit | never 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
| Kind | Meaning |
|---|---|
missing_at_casino | The journal requires the operation; your export does not list it. |
missing_in_journal | You 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_differs | Both sides have it, with a different amount or currency. |
details_differ | Both 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.