Debit
Taking a bet from the player's balance: request, answers, idempotency and refusals.
POST {baseURL}/debit takes the stake of a round from the player's balance. It is the only call that
may be refused for the player's sake: not enough money, a limit, a blocked account, a bonus rule.
When the RGS calls it
Once per round, when the player places a bet, after the RGS has checked the stake against the session's bet levels and limits. The outcome is drawn after the debit succeeds, so the player waits for your answer before the spin starts. Keep the debit's p99 latency under 2 seconds.
The call has 5 seconds unless a different timeout (1 to 15 seconds) was agreed for the casino. A debit that times out is an unknown outcome and is rolled back.
A debit can arrive before the credit or rollback of the player's previous round: the next round starts
once the previous one's outcome is recorded, and its settlement may still be retrying. Answer the debit
against the balance you have. If it is too low because the previous win has not been credited yet,
INSUFFICIENT_FUNDS is the right answer, and the player sees ERR_IPB. See
What the wallet must guarantee.
Request
| Field | Required | Type | Meaning |
|---|---|---|---|
transactionId | yes | string | {roundId}:debit:1. The idempotency key. |
roundId | yes | string | The round. A UUID today; treat it as an opaque string. |
playerId | yes | string | The casino's own player id. |
gameId | yes | string | The game, for example slots. |
gameVersion | yes | string | The game's version, for example 1.0.0. |
variant | yes | string | The game's variant (its RTP configuration), for example 957. |
currency | yes | string | ISO 4217 code of the session. |
amount | yes | integer | The stake in micro-units. |
POST /rgs/debit HTTP/1.1
Host: wallet.casino.example
Content-Type: application/json
X-Key-Id: rgs-1
X-Timestamp: 1793700000
X-Signature: ab9c8a92f61d4df3464816effa9f24ad47d09ead9ddb21c0b634eda553d8718b
{"transactionId":"01a1a0d9-f100-7d2e-8f30-4a5b6c7d8e9f:debit:1","roundId":"01a1a0d9-f100-7d2e-8f30-4a5b6c7d8e9f","playerId":"p-1001","gameId":"slots","gameVersion":"1.0.0","variant":"957","currency":"GBP","amount":1000000}The signature above is real for the secret example-secret; the
overview shows how it is built.
Response
A debit applied now:
{ "status": "ok", "balance": 99000000, "operatorTxId": "w-77812", "alreadyProcessed": false }The same transactionId again, already applied:
{ "status": "ok", "balance": 99000000, "operatorTxId": "w-77812", "alreadyProcessed": true }balance is the balance after the debit. The game shows it to the player while the round plays.
What each answer causes
| Answer | Money | What the RGS does | The player sees |
|---|---|---|---|
ok (alreadyProcessed either way) | taken | Draws the outcome; the round goes on to its credit. | The round. |
INSUFFICIENT_FUNDS | not taken | Voids the round. | ERR_IPB |
LIMIT_EXCEEDED | not taken | Voids the round. | ERR_GLE with your reason |
PLAYER_BLOCKED | not taken | Voids the round. | ERR_GLE, reason yours or blocked |
SESSION_EXPIRED | not taken | Voids the round. | ERR_IS |
LOCATION | not taken | Voids the round. | ERR_LOC |
BET_REJECTED | not taken | Voids the round. | ERR_BET_REJECTED with your reason, message, details |
NOT_FOUND | not taken | Voids the round and logs it as an error. | ERR_GEN |
HTTP 401 / 403 | not taken | Voids the round and logs it as an error. | ERR_GEN |
Unknown: timeout, other non-2xx, bad signature, DUPLICATE, a code not listed | unknown | Sends a rollback and repeats it until it is final. | ERR_GEN, money pending, then refunded |
A voided round sends nothing more to the wallet: no rollback, no credit. In every refusal the casino's
message reaches the game client as operatorMessage. The money states are explained in
Errors and money states.
BET_REJECTED
BET_REJECTED refuses a bet by the casino's own rules, most often a bonus that caps the stake. It means
definitely not debited; do not retry.
{
"status": "error",
"code": "BET_REJECTED",
"reason": "bonus_max_bet",
"message": "Your bonus allows a bet of up to 5.00 GBP",
"details": { "max_bet": "5.00", "currency": "GBP", "bonus_id": "b-81" }
}reasonis an open list. The first known value isbonus_max_bet, whosedetailsaremax_bet(a decimal string such as"5.00"),currencyandbonus_id.detailsis a flat object of strings. At most 16 entries are kept; a key over 64 bytes, a value over 256 bytes, and a value that is not a string are left out without failing the refusal. Which entries are kept when there are more than 16 is not defined.detailsandmessagereach the player's screen. The game shows them as text, never as markup.
Idempotency
- A repeat of a
transactionIdyou have applied moves nothing and answersok,alreadyProcessed: true, with the current balance. The RGS repeats a debit with the same id when it recovers a round whose debit it sent but whose answer it did not record. - A debit whose
transactionIdwas named by a rollback you already received is refused for certain, with a listed code (the reference wallet answersNOT_FOUND), and charges nothing. See Rollback.
The reference test wallet does exactly this, in this order:
- the id was rolled back before:
NOT_FOUND; - the id is known:
ok,alreadyProcessed: true, current balance; - the player is blocked:
PLAYER_BLOCKED; - the balance is below
amount:INSUFFICIENT_FUNDS; - otherwise take
amount, remember the id, answerok.
Pitfalls
-
balancemust be a JSON integer. A decimal or a string makes the answer unreadable: an unknown outcome, so the debit is rolled back. -
A refusal sent as HTTP 4xx/5xx is not a refusal.
INSUFFICIENT_FUNDSwith status400is an unknown outcome: the RGS rolls back and the player sees a general error instead of "top up". -
Your own error codes are unknown outcomes. Map them to a listed code, usually
BET_REJECTEDwith yourreason. -
DUPLICATEis not success. It says the transaction exists but not what happened to it, so the RGS rolls the debit back. Answer a repeat withokandalreadyProcessed: true. -
An unsigned or wrongly signed
okis not success. The RGS rolls it back, so the bet is returned even if you took it.