Bets
The bet call, the trigger, the response, retries until a definite answer, cancel, and the carried-over bonus.
On this page
The bet call
POST /v1/partner/bets — signed, no nonce (idempotent by betId)
This one call plays an Extra Game in both streams. A game integration sends it for a base spin; a casino integration sends it for a casino bet its trigger rule selected.
{
"sessionToken": "st_7f3a9c",
"betId": "b-000123",
"betCreatedAt": "2027-03-01T12:00:00.000Z",
"level": 2,
"amount": "1.00",
"currency": "EUR",
"trigger": {
"bet": "2.00",
"gameRef": "slot-gold-rush",
"betRef": "spin-8841"
}
}| Field | Required | Notes |
|---|---|---|
sessionToken | yes | From POST /v1/partner/sessions. |
betId | yes | Your unique id for this Extra Bet, max 64 chars. Unique per Partner for at least 7 days; never reuse it. |
betCreatedAt | yes | When you created the bet, UTC (Coordinated Universal Time), from an NTP-synced clock. Must not be in the future (beyond 60 s) and must be younger than the bet age limit (just under 24 hours). |
level | yes | Integer. The Bet Level the player selected. It selects the player's card. A level that isn't one of the levels offered to this Operator (GET /v1/partner/games/{gameId}/levels lists them) is refused with 1200 validationFailed, and the message names the level. |
amount | yes | Decimal string. The amount you actually bet, which is what you debited from the player. It must equal the current price of level for this Operator and currency. The price of a level is calculated from the level, the Operator's base bet and the currency's factor (see 09-games.md), and GET /v1/partner/games/{gameId}/levels returns the offered levels and their current prices. If it differs, the bet is refused with 1201 priceMismatch before anything is played. The error returns the level and the current price: refund, then send a new bet with a new betId at that price. Jackpot contributions are calculated from amount. |
currency | yes | Must match the session and be a currency the Operator offers; otherwise the bet is refused with 1202 currencyNotSupported. |
trigger | no | The slot spin or casino bet that caused this play (see below). Optional context. |
Trigger
trigger describes what caused the play.
| Field | Notes |
|---|---|
bet | The bet of the slot spin or casino bet that caused the play, as a decimal string, in the session currency. |
gameRef | Your reference for the game it came from (the slot, or the casino game). |
betRef | Your reference for that spin or bet. |
- Game integration: the base spin. Casino integration: the casino bet the trigger rule selected.
- The trigger is context only. The Extra Bet
amountis still the price of a level chosen by the player and is never derived from the trigger bet. - The trigger is part of the idempotency check. A retry must repeat the same trigger; the same
betIdwith a differenttriggeris refused with1400betIdReuse, like any other changed field. - We store it with the round and show it in reconciliation and support. We never check it against a limit: keeping the combined bet (the Extra Bet plus the triggering bet) within a jurisdiction's cap is your responsibility.
Casino integration: when to debit
Order your steps like this:
- The player's casino bet is accepted and your trigger rule says it triggers a play.
- The player has opted in and a level is confirmed by your backend.
- Only now debit the Extra Bet, then send
POST /v1/partner/bets. - If we reject the play with a 4xx error, refund the Extra Bet (the play was not made).
Rapid casino bets can come faster than the Operator's minimum round interval. The interval applies per
player across all sessions and both streams. A play that comes too soon is refused with 1505 roundTooSoon
and a nextPlayAt time:
{
"code": 1505,
"error": "roundTooSoon",
"message": "Next play allowed at 2027-03-01T12:00:03.000Z.",
"retryable": false,
"nextPlayAt": "2027-03-01T12:00:03.000Z",
"serverTime": "2027-03-01T12:00:01.100Z",
"requestId": "req_5b1e..."
}Keep the last nextPlayAt per player and skip the play before you debit while it is in the future. If you
do get 1505, refund the Extra Bet. Don't retry the same betId after a 1505: a play that is still wanted
needs a new betId once nextPlayAt has passed. Skipping a play is always allowed: the casino bet itself is not
affected.
Planned maintenance
During a planned maintenance window for the game (set per Site, per Operator or per game), a new play is refused with
1506 maintenance, HTTP 503:
{
"code": 1506,
"error": "maintenance",
"message": "reel-triple is under planned maintenance until 2027-03-01T14:00:00.000Z.",
"retryable": false,
"maintenanceUntil": "2027-03-01T14:00:00.000Z",
"serverTime": "2027-03-01T12:00:00.184Z",
"requestId": "req_5b1e..."
}- It is a definite answer even though the status is
503: the bet was not played. Refund it and don't retry thatbetId.Retry-Afteris the seconds untilmaintenanceUntil. - Send new plays, with new
betIds, only aftermaintenanceUntil. Hide the side game until then;GET /v1/partner/gamesand/levelsreportmaintenanceup to 24 hours ahead (see09-games.md). - Order of checks: a
betIdwe already accepted is answered first, so a retry of an accepted bet still finishes and returns its result even during a window. Only a newbetIdgets1506. Look-ups, cancels, history links, reconciliation and session close keep working. - Maintenance is for planned work. An engine emergency stop returns
1502gameUnavailableinstead.
Side game switched off
While the player has switched the side game off in the widget, or the widget is hidden, new plays of that game are refused with 1508 sideGameOff, HTTP 403:
{
"code": 1508,
"error": "sideGameOff",
"message": "The side game is switched off for this player.",
"retryable": false,
"serverTime": "2027-03-01T12:00:00.184Z",
"requestId": "req_5b1e..."
}- ReelXtra decides this, not your backend: the on/off switch in the widget (and
rx.hide()) stops play (see the on/off switch section of the Sessions and widget chapter). The widget'sreadyevent carriesenabledandoptInChangedreports each change, so you can stop sending before you debit. - It is a definite answer: no Round was made. Refund the bet amount and don't retry that
betId. Send new plays, with newbetIds, onceenabledistrueagain. - Order of checks: a
betIdwe already accepted is answered first, so a retry of an accepted bet still finishes and returns its result, even if the switch was turned off meanwhile.
Settlement suspended
If ReelXtra has suspended an Operator (or its Group) for non-payment, new plays into its Network Pools are refused with 1507 settlementSuspended, HTTP 403:
{
"code": 1507,
"error": "settlementSuspended",
"message": "New plays into this Operator's Network Pools are suspended.",
"retryable": false,
"serverTime": "2027-03-01T12:00:00.184Z",
"requestId": "req_5b1e..."
}- It is a definite answer: the bet was not played. Refund it and don't retry that
betId. There is noRetry-After: ReelXtra staff suspend and lift a suspension by hand, and a change takes effect on the next configuration publication. Your account manager will tell you when it is lifted. Send new plays, with newbetIds, only after that. - Order of checks: a
betIdwe already accepted is answered first, so a retry of an accepted bet still finishes and returns its result. Look-ups, cancels, history links and reconciliation keep working. - It only affects games that play into a Network Pool. Fixed-prize games and Operator-owned Pools are not affected.
Game integration: when to debit
Take the Extra Bet from the player's balance before calling us, together with the base bet. Refund it if we reject the play.
The response
200 with a definite result:
{
"status": "committed",
"betId": "b-000123",
"roundId": "rnd_9QxL...",
"gameId": "reel-triple",
"level": 2,
"currency": "EUR",
"amount": "1.00",
"baseWin": "0.00",
"progressiveWin": "0.00",
"poolId": "pool_7",
"poolOwnerType": "Network",
"bonusId": null,
"carriedBonus": {
"bonusId": "bon_31",
"amount": "35.00",
"originRoundId": "rnd_8Hb2..."
},
"win": "35.00",
"committedAt": "2027-03-01T12:00:00.171Z",
"serverTime": "2027-03-01T12:00:00.184Z"
}| Field | Meaning |
|---|---|
status | committed (credit win), voided or cancelled (refund the bet amount; nothing was won). |
roundId | Pass to your client for reveal (reveal mode 2), and keep it for support and reconciliation. |
baseWin | Fixed wins from the game maths, including Reel Triple Mini/Minor bonuses paid at card end. |
progressiveWin | A jackpot hit: the seed plus all the growth in the pool. "0.00" (zero) when there is no hit or the game is fixed-prize. |
poolId, poolOwnerType | The jackpot pool this bet fed (Operator, Group, Partner or Network); null for fixed-prize games. |
bonusId | Set when a Reel Triple bonus is paid at the end of this card, otherwise null. |
carriedBonus | A Reel Triple bonus from an earlier card that timed out, paid now (see below), otherwise null. |
win | The total to credit: baseWin + progressiveWin + carriedBonus.amount. Always credit win. |
committedAt | When the round was committed (UTC); null unless status is committed. |
Every field is always present, whatever the game or status, so every response has the same shape. Money
fields that don't apply are zero in the currency's precision (for example "0.00"). References that don't apply
(roundId and committedAt on a bet that wasn't committed, poolId, poolOwnerType, bonusId, carriedBonus) are null.
The response never carries lockedByPartner; that field is only on reconciliation lines (see Reconciliation).
All wins are whole minimal units of the currency. Jackpot payouts are never capped by the max-win limit; other wins respect the Operator's and the jurisdiction's limits.
Retries: always get a definite answer
Network problems happen. The rule is simple: if you didn't get a definite answer, send exactly the same
request again with the same betId. We will never play the game twice for one betId; a retry returns the
result we already have.
| You get | Meaning | Do |
|---|---|---|
200 with status | Definite. | Credit win (committed) or refund (voided, cancelled). Stop. |
4xx error | Definite: the bet was not played. | Refund the bet amount. Fix the cause before the next bet. |
503 with 1506 maintenance | Definite: the bet was not played (retryable: false). | Refund the bet amount. Send new plays only after maintenanceUntil. |
403 with 1508 sideGameOff | Definite: the bet was not played; no Round was made. | Refund the bet amount. Don't retry that betId; send new plays only while the widget is on (ready.enabled, optInChanged). |
403 with 1507 settlementSuspended | Definite: the bet was not played. | Refund the bet amount. Don't retry that betId; send new plays only once the suspension is lifted. |
503 with 9001 serviceUnavailable | Not definite: we could not confirm the bet (for example a server left the cluster mid-bet). | Retry the same request (same betId and body) with backoff, honouring Retry-After. We finish the bet we stored and never play it again, so it is paid once. |
429, other 5xx, timeout, connection error | Not definite. | Retry the same request (same betId and body) with backoff, honouring Retry-After. |
How to read it: a 200 and the definite errors (a 4xx other than 429, or 503 with 1506) end the bet: credit or refund by status, or refund because the bet was not played. A 429, any other 5xx or a timeout is not definite: if you are still within your retry horizon, send the same request again; if not, cancel the bet, which always gives a definite answer.
- Retry with exponential backoff (for example 0.5 s, 1 s, 2 s, 4 s … capped at 10 s) for up to the retry
horizon: 2 minutes from the first attempt. After 5 minutes an unfinished jackpot bet is voided
on our side, so retries after the horizon may get
voided. - If the horizon passes without a definite answer, cancel the bet (below). Cancel always gives a definite answer.
- After a price change: a level's price can change when we publish a new configuration. A price change applies
from the next bet; your player's card continues. Read
/levelsagain after a change, and a bet still sent at the old price gets1201priceMismatch. - During planned maintenance: a retry of a bet we already accepted still returns its result. A new bet gets
1506(definite, refund; see Planned maintenance). - Sending the same
betIdwith a different body (level, amount, currency, time, trigger) is refused with1400betIdReuse; nothing is played. - A bet that is still being finished on our side after a server failure is either completed by your retry or
voided automatically a few minutes later. If the player's next bet arrives first, the unfinished bet is
voided at once; your retry of it then gets
voided, so refund it.
Cancel
POST /v1/partner/bets/{betId}/cancel — signed, no nonce (idempotent)
Send the same fields as the original bet (session token, level, amount, currency, betCreatedAt, trigger) so the
cancel reaches the same game state.
| Result | Meaning | Do |
|---|---|---|
200 status: cancelled | The bet was never committed. It is now void; a late copy of the bet will be refused. | Refund. |
200 status: committed | Too late: the round was already committed. The stored result is returned. | Credit win. |
200 status: voided | We had already voided it. | Refund. |
You can cancel a betId we have never seen; it is recorded so that a delayed copy of that bet is refused.
Look up a bet
GET /v1/partner/rounds/{betId} returns the stored result of any bet, of any age, in the same shape as the bet
response. Use it for support cases and reconciliation, not instead of retrying. Bets older than 30 days are
forwarded by our silo to an internal history reader on the Reporting side; your call is the same.
To show a player the history of one round, use POST /v1/partner/rounds/{betId}/history (see Reconciliation).
Carried-over bonus (Reel Triple)
In Reel Triple a player locks a Mini or Minor bonus by completing rows; it is paid when the card ends. If the card times out (30 minutes once few cells remain) with a bonus locked, the bonus is not lost: it is paid in the response to the player's next bet on the same game, level and currency, through any session, any day.
- It appears as
carriedBonusand is included inwin. The widget shows the bonus first, then the new card's first spin, under the same reveal. - It can be paid by a play from the other stream: a bonus locked through a Provider's slot is paid in the player's next overlay play, and the other way round, if both Partners send the Operator's own player id. The Partner whose bet pays it credits it; the locking Partner is shown on reconciliation (see Reconciliation).
- Its amount was fixed when it locked, so later limit or configuration changes don't reduce it.
- It is paid exactly once: only by a bet that commits. If that bet is refused, cancelled or voided, the bonus stays owed for the next one.
Free spins, bonus rounds and your own features
- Provider: only call
POST /v1/partner/betsfor spins where the player actually placed an Extra Bet. Don't call us for your free spins or bonus rounds unless the player is charged an Extra Bet for them. A Provider never sends them as triggers. - Operator: you decide with your trigger rule whether free spins, bonus rounds, or any other casino bet triggers a play. Each play still needs an Extra Bet the player is charged.