Credit
Paying a round's win, zero included. A credit must always be accepted.
POST {baseURL}/credit pays the result of a round to the player and closes the round on the casino's
side. The money is already decided when it is sent, so a credit must not be refused.
When the RGS calls it
- Every round that was debited and played ends with exactly one credit,
{roundId}:credit, even when the win is 0. A losing round is closed by a credit ofamount: 0. - A one-step round (a spin) is credited right after its debit.
- A round with player decisions is credited when the player finishes it, or, when the player leaves, after the RGS closes it automatically (an hour after the player was last seen, in the shipped configuration). By then the player's session may have expired.
- A round that only settles saved progress of an older game version is credited with no debit before it.
- A round whose debit was refused is never credited. A round that was rolled back is never credited.
The credit runs in the background. The player's answer waits for it up to 2 seconds; if it is not done by then, the game gets the result without a balance and shows the balance as pending until it is.
The player can start the next round meanwhile. Its debit waits up to 2 seconds for this credit if the
round is of the same game, then goes out anyway, so a credit can arrive after the debit of the player's
next round, while it is still being retried. Accept it then as at any other time; calls are ordered
only within one round. Until it lands your balance lacks the win, and a next debit refused with
INSUFFICIENT_FUNDS is correct. The settlement of saved progress is the exception: the RGS holds the
player's new round of that game and stake for up to 2 seconds while it is credited, then refuses the
round with ERR_GEN, reason state_settling, money not_charged, retryable, and nothing is debited.
The jackpot service sends a separate credit for a jackpot win, with its own id; see below.
Request
The same fields as a debit.
| Field | Required | Type | Meaning |
|---|---|---|---|
transactionId | yes | string | {roundId}:credit. The idempotency key. |
roundId | yes | string | The round. |
playerId | yes | string | The casino's own player id. |
gameId | yes | string | The game. |
gameVersion | yes | string | The game's version. |
variant | yes | string | The game's variant. |
currency | yes | string | The round's currency. |
amount | yes | integer | The win in micro-units, 0 or more. |
POST /rgs/credit HTTP/1.1
Host: wallet.casino.example
Content-Type: application/json
X-Key-Id: rgs-1
X-Timestamp: 1793700002
X-Signature: <hex HMAC-SHA256>
{"transactionId":"01a1a0d9-f100-7d2e-8f30-4a5b6c7d8e9f:credit","roundId":"01a1a0d9-f100-7d2e-8f30-4a5b6c7d8e9f","playerId":"p-1001","gameId":"slots","gameVersion":"1.0.0","variant":"957","currency":"GBP","amount":2500000}Response
{ "status": "ok", "balance": 101500000, "operatorTxId": "w-77813", "alreadyProcessed": false }For a losing round, amount is 0 and the answer is an ordinary ok with the unchanged balance.
balance after the credit is the balance the game shows at the end of the round.
What each answer causes
| Answer | What the RGS does |
|---|---|
ok | Closes the round. With alreadyProcessed: true it records the credit as a duplicate; nothing else differs. |
Unknown: timeout, non-2xx other than 401/403, bad signature, DUPLICATE, an unlisted code | Repeats the same call, same transactionId, 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 and puts the round in the attention queue as refused. Nothing is retried until the keys are fixed and an RGS operator retries the round, or marks it settled. |
A listed code (PLAYER_BLOCKED, SESSION_EXPIRED, NOT_FOUND, …) | A definite refusal. The RGS stops and the round waits in the attention queue until an RGS operator retries it, or marks it settled with a reference after the casino has paid the player by hand. |
A definite refusal of a credit means manual work on both sides and a player waiting for a win. Do not answer one. In particular:
- accept a credit for an expired or closed session;
- accept a credit for a blocked, self-excluded or limited player;
- accept a credit with
amount: 0; - accept a credit for a round whose debit you do not have.
The conformance suite checks a zero credit and a credit to a blocked player.
Idempotency
A repeat of a transactionId you have applied pays nothing and answers ok, alreadyProcessed: true,
with the current balance. Expect repeats: every unknown outcome is repeated until it is final, also
after an RGS restart. The reference test wallet:
- the id is known:
ok,alreadyProcessed: true, current balance; - otherwise add
amount, remember the id, answerok.
It checks nothing else: not the session, not the player's state, not a matching debit.
Jackpot credits
A jackpot win is paid by the jackpot service, not by the round, with the same request shape:
| Field | Value |
|---|---|
transactionId | {roundId}:jackpot:{pool}:{level}:{index}, for example 01a1a0d9-f100-7d2e-8f30-4a5b6c7d8e9f:jackpot:mega:grand:0 |
roundId, playerId, gameId, gameVersion, variant | Those of the round that won |
currency, amount | The round's currency and the amount won |
So one round can have two credits: {roundId}:credit and the jackpot's. Treat them as separate
operations. The jackpot service repeats an unknown outcome with backoff from 1 s doubling to 5 minutes;
any refusal, 401 and 403 included, stops it and leaves the payout to a person, as for the round's own credit. See
Jackpots, history and replay.
Free round credits
A free round is paid by the casino and has no debit. Its credit is the ordinary
{roundId}:credit with one more field, freeRounds:
"freeRounds": { "bonusId": "welcome-2026-11", "awardId": "019a4b5e-6f70-7c3d-8e9f-0a1b2c3d4e5f", "index": 3, "rounds": 10, "bet": 200000 }The object is present only on a free round, so its presence is how you tell one. Accept the credit like any
other: it moves the balance by amount once, and a repeat answers ok, alreadyProcessed: true. There is no
call for the end of an award; see Free rounds.
Pitfalls
- Linking a credit to a debit and refusing the credit when the debit is missing. Settlement rounds and jackpot credits have no debit of their own id.
- Skipping a zero credit, or answering it with an error. It is how a losing round closes.
- Answering
DUPLICATEto a repeat. That is an unknown outcome and is repeated forever; answerokwithalreadyProcessed: true.