JRGS Casino API
Wallet (seamless)

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

FieldRequiredTypeMeaning
transactionIdyesstring{roundId}:debit:1. The idempotency key.
roundIdyesstringThe round. A UUID today; treat it as an opaque string.
playerIdyesstringThe casino's own player id.
gameIdyesstringThe game, for example slots.
gameVersionyesstringThe game's version, for example 1.0.0.
variantyesstringThe game's variant (its RTP configuration), for example 957.
currencyyesstringISO 4217 code of the session.
amountyesintegerThe 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

AnswerMoneyWhat the RGS doesThe player sees
ok (alreadyProcessed either way)takenDraws the outcome; the round goes on to its credit.The round.
INSUFFICIENT_FUNDSnot takenVoids the round.ERR_IPB
LIMIT_EXCEEDEDnot takenVoids the round.ERR_GLE with your reason
PLAYER_BLOCKEDnot takenVoids the round.ERR_GLE, reason yours or blocked
SESSION_EXPIREDnot takenVoids the round.ERR_IS
LOCATIONnot takenVoids the round.ERR_LOC
BET_REJECTEDnot takenVoids the round.ERR_BET_REJECTED with your reason, message, details
NOT_FOUNDnot takenVoids the round and logs it as an error.ERR_GEN
HTTP 401 / 403not takenVoids the round and logs it as an error.ERR_GEN
Unknown: timeout, other non-2xx, bad signature, DUPLICATE, a code not listedunknownSends 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" }
}
  • reason is an open list. The first known value is bonus_max_bet, whose details are max_bet (a decimal string such as "5.00"), currency and bonus_id.
  • details is 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.
  • details and message reach the player's screen. The game shows them as text, never as markup.

Idempotency

  • A repeat of a transactionId you have applied moves nothing and answers ok, 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 transactionId was named by a rollback you already received is refused for certain, with a listed code (the reference wallet answers NOT_FOUND), and charges nothing. See Rollback.

The reference test wallet does exactly this, in this order:

  1. the id was rolled back before: NOT_FOUND;
  2. the id is known: ok, alreadyProcessed: true, current balance;
  3. the player is blocked: PLAYER_BLOCKED;
  4. the balance is below amount: INSUFFICIENT_FUNDS;
  5. otherwise take amount, remember the id, answer ok.

Pitfalls

  • balance must 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_FUNDS with status 400 is 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_REJECTED with your reason.

  • DUPLICATE is not success. It says the transaction exists but not what happened to it, so the RGS rolls the debit back. Answer a repeat with ok and alreadyProcessed: true.

  • An unsigned or wrongly signed ok is not success. The RGS rolls it back, so the bet is returned even if you took it.

On this page