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-
2xxstatus other than401/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
| Field | Required | Type | Meaning |
|---|---|---|---|
transactionId | yes | string | {roundId}:rollback:1. The idempotency key of the rollback. |
targetTransactionId | yes | string | The debit to cancel, {roundId}:debit:1. |
roundId | yes | string | The round. |
playerId | yes | string | The casino's own player id. |
currency | yes | string | The 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
| Answer | What the RGS does |
|---|---|
ok | The round ends as refunded. alreadyProcessed: true is recorded as a duplicate; nothing else differs. |
NOT_FOUND | Counts 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 code | Repeats 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 / 403 | Stops 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 code | A 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:
- A rollback arrives for a debit you do not have. Record that
targetTransactionIdis cancelled and answerokwith the current balance. A debit you refused counts as one you do not have: answerok, return nothing. The RGS would also acceptNOT_FOUNDhere, but the conformance suite requiresok. - 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:
- the rollback's id is known:
ok,alreadyProcessed: true, current balance; - otherwise remember the rollback's id and mark
targetTransactionIdcancelled; - if that debit was applied, give its amount back and forget the debit;
- answer
okwith the balance.
Pitfalls
- Answering
NOT_FOUNDto a rollback of a debit you never saw fails conformance; answerok. - 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.