JRGS Casino API
Wallet (seamless)

Rollback

Returning a bet whose debit had an unknown outcome, or whose round could not be played.

POST {baseURL}/rollback cancels a named debit: if the casino took the money, it gives it back; if the debit never arrived, the casino remembers that it is cancelled. Like a credit, it settles money that is already decided and must not be refused.

When the RGS calls it

The RGS sends a rollback of {roundId}:debit:1 when:

  • the debit's outcome is unknown: a timeout, no answer, a non-2xx status other than 401/403, a bad response signature, DUPLICATE, or an unlisted code;
  • the debit succeeded but the round could not be played: the game failed, or its outcome could not be used. The player gets the bet back;
  • in rare recovery cases, for a round the RGS cannot finish: then the rollback may name a debit that was never sent.

It is never sent after a debit you refused with a listed code, and never for a round that was credited.

The rollback runs in the background, right after the debit. The player's answer waits for it up to 2 seconds and shows the money as refunded once it is done, pending until then.

The player can start the next round meanwhile, so a rollback can arrive after the debit of the player's next round. Accept it then as at any other time; calls are ordered only within one round.

Request

FieldRequiredTypeMeaning
transactionIdyesstring{roundId}:rollback:1. The idempotency key of the rollback.
targetTransactionIdyesstringThe debit to cancel, {roundId}:debit:1.
roundIdyesstringThe round.
playerIdyesstringThe casino's own player id.
currencyyesstringThe round's currency.

There is no amount: return what the debit named by targetTransactionId took, or nothing if it took nothing.

POST /rgs/rollback HTTP/1.1
Host: wallet.casino.example
Content-Type: application/json
X-Key-Id: rgs-1
X-Timestamp: 1793700006
X-Signature: <hex HMAC-SHA256>

{"transactionId":"01a1a0d9-f100-7d2e-8f30-4a5b6c7d8e9f:rollback:1","targetTransactionId":"01a1a0d9-f100-7d2e-8f30-4a5b6c7d8e9f:debit:1","roundId":"01a1a0d9-f100-7d2e-8f30-4a5b6c7d8e9f","playerId":"p-1001","currency":"GBP"}

Response

The debit had taken 1.00, now returned:

{ "status": "ok", "balance": 100000000, "operatorTxId": "w-77820", "alreadyProcessed": false }

The debit never arrived (or you refused it); nothing is returned, the cancellation is recorded, and the answer is the same ok:

{ "status": "ok", "balance": 100000000, "operatorTxId": "w-77820", "alreadyProcessed": false }

What each answer causes

AnswerWhat the RGS does
okThe round ends as refunded. alreadyProcessed: true is recorded as a duplicate; nothing else differs.
NOT_FOUNDCounts as done: there was nothing to return. The round ends as refunded.
Unknown: timeout, non-2xx other than 401/403, bad signature, DUPLICATE, an unlisted codeRepeats the same call with backoff from 200 ms doubling to 30 s, without end. After 10 attempts or 5 minutes the round also appears in the RGS attention queue; the retries go on.
HTTP 401 / 403Stops after this one attempt: attention queue as refused, until the keys are fixed and an RGS operator retries the round or marks it settled.
Any other listed codeA definite refusal: retries stop and the round waits for an RGS operator to retry it or mark it settled after the casino has fixed the money by hand. Do not answer one.

Accept a rollback for an expired session and for a blocked or self-excluded player, as for a credit.

A rollback before its debit

The debit and its rollback can cross. The RGS gives up waiting for a debit, sends the rollback, and the debit, delayed somewhere on the way, reaches the casino after it. The wallet must handle that order:

  1. A rollback arrives for a debit you do not have. Record that targetTransactionId is cancelled and answer ok with the current balance. A debit you refused counts as one you do not have: answer ok, return nothing. The RGS would also accept NOT_FOUND here, but the conformance suite requires ok.
  2. The debit arrives later. Refuse it for certain with a listed code, for example NOT_FOUND, and charge nothing.

If the wallet forgets step 1, the late debit takes the player's money in a round the RGS has already closed as refunded, and nothing will ever return it. The conformance suite checks exactly this.

Idempotency

A repeat of a rollback you have applied returns nothing more and answers ok, alreadyProcessed: true, with the current balance. The reference test wallet:

  1. the rollback's id is known: ok, alreadyProcessed: true, current balance;
  2. otherwise remember the rollback's id and mark targetTransactionId cancelled;
  3. if that debit was applied, give its amount back and forget the debit;
  4. answer ok with the balance.

Pitfalls

  • Answering NOT_FOUND to a rollback of a debit you never saw fails conformance; answer ok.
  • Forgetting the cancellation: the late debit must still be refused.
  • Expecting an amount in the request.
  • Refusing a rollback because the player is blocked or the session has ended.

On this page