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.

json
{
  "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"
  }
}
FieldRequiredNotes
sessionTokenyesFrom POST /v1/partner/sessions.
betIdyesYour unique id for this Extra Bet, max 64 chars. Unique per Partner for at least 7 days; never reuse it.
betCreatedAtyesWhen 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).
levelyesInteger. 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.
amountyesDecimal 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.
currencyyesMust match the session and be a currency the Operator offers; otherwise the bet is refused with 1202 currencyNotSupported.
triggernoThe slot spin or casino bet that caused this play (see below). Optional context.

Trigger

trigger describes what caused the play.

FieldNotes
betThe bet of the slot spin or casino bet that caused the play, as a decimal string, in the session currency.
gameRefYour reference for the game it came from (the slot, or the casino game).
betRefYour 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 amount is 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 betId with a different trigger is refused with 1400 betIdReuse, 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:

  1. The player's casino bet is accepted and your trigger rule says it triggers a play.
  2. The player has opted in and a level is confirmed by your backend.
  3. Only now debit the Extra Bet, then send POST /v1/partner/bets.
  4. 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:

json
{
  "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:

json
{
  "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 that betId. Retry-After is the seconds until maintenanceUntil.
  • Send new plays, with new betIds, only after maintenanceUntil. Hide the side game until then; GET /v1/partner/games and /levels report maintenance up to 24 hours ahead (see 09-games.md).
  • Order of checks: a betId we already accepted is answered first, so a retry of an accepted bet still finishes and returns its result even during a window. Only a new betId gets 1506. Look-ups, cancels, history links, reconciliation and session close keep working.
  • Maintenance is for planned work. An engine emergency stop returns 1502 gameUnavailable instead.

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:

json
{
  "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's ready event carries enabled and optInChanged reports 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 new betIds, once enabled is true again.
  • Order of checks: a betId we 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:

json
{
  "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 no Retry-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 new betIds, only after that.
  • Order of checks: a betId we 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:

json
{
  "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"
}
FieldMeaning
statuscommitted (credit win), voided or cancelled (refund the bet amount; nothing was won).
roundIdPass to your client for reveal (reveal mode 2), and keep it for support and reconciliation.
baseWinFixed wins from the game maths, including Reel Triple Mini/Minor bonuses paid at card end.
progressiveWinA 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, poolOwnerTypeThe jackpot pool this bet fed (Operator, Group, Partner or Network); null for fixed-prize games.
bonusIdSet when a Reel Triple bonus is paid at the end of this card, otherwise null.
carriedBonusA Reel Triple bonus from an earlier card that timed out, paid now (see below), otherwise null.
winThe total to credit: baseWin + progressiveWin + carriedBonus.amount. Always credit win.
committedAtWhen 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 getMeaningDo
200 with statusDefinite.Credit win (committed) or refund (voided, cancelled). Stop.
4xx errorDefinite: the bet was not played.Refund the bet amount. Fix the cause before the next bet.
503 with 1506 maintenanceDefinite: the bet was not played (retryable: false).Refund the bet amount. Send new plays only after maintenanceUntil.
403 with 1508 sideGameOffDefinite: 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 settlementSuspendedDefinite: 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 serviceUnavailableNot 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 errorNot definite.Retry the same request (same betId and body) with backoff, honouring Retry-After.

The retry rule: send the bet, then credit or refund on a definite answer, retry while within your retry horizon, and cancel when the horizon has passed

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 /levels again after a change, and a bet still sent at the old price gets 1201 priceMismatch.
  • 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 betId with a different body (level, amount, currency, time, trigger) is refused with 1400 betIdReuse; 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.

ResultMeaningDo
200 status: cancelledThe bet was never committed. It is now void; a late copy of the bet will be refused.Refund.
200 status: committedToo late: the round was already committed. The stored result is returned.Credit win.
200 status: voidedWe 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 carriedBonus and is included in win. 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/bets for 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.