Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Transactions

THNDR calls this endpoint to notify the Operator of a transaction request, instructing them to either debit or credit the player’s balance.

Endpoint

POST {operatorURL}/thndr/transactions

Bet Transaction

The BET Transaction is sent by THNDR to notify the Operator of a wager placed by a player.

The Operator must process this request to debit the player’s balance (and optionally record a potential reward).

{
   "type": "BET",
   "transactionId": "a395479b-7d31-406e-abab-2dd66a61d5ee-BET",
   "requestedAt": "2025-08-21T14:30:00.123Z",
   "userId": "{USER_ID}",
   "sessionId": "{SESSION_ID}",
   "roundId": "a395479b-7d31-406e-abab-2dd66a61d5ee",
   "currency": "USD",
   "amount": 120,
   "gameId": "solitaire",
   "reward": 200,
   "serviceFee": 20
}

  • transactionId - Unique transaction identifier. Must be persisted by the Operator for idempotency and rollback handling.

  • requestedAt - The date and time when the request was initially made, in ISO 8601 format (e.g., 2025-08-21T14:30:00.123Z).

  • userId - Player identifier on the Operator’s platform.

  • sessionId - The session identifier provided by the Operator when the game was launched.

  • roundId - Identifier of the game round this transaction belongs to.

  • currency - Player's wallet currency provided by the Operator when the game was launched (read more in Currencies).

  • amount - Bet amount, in the smallest unit of the currency (e.g., cents for USD, pence for GBP).

  • usdAmount - Optional. Transaction amount in USD cents; present only when the match currency is USD, carrying the original pre-conversion USD value (may differ from amount).

  • gameId - Game identifier. Possible values: solitaire, blocks, twentyone, blackjack, slots, plinko , videopoker, marbles, and hilo.

  • reward - The possible payout in the smallest unit of the currency if this bet wins (shown for info, do not credit yet).

  • serviceFee - Service fee portion included in amount (info-only); Operator must debit only amount, not amount + serviceFee.

For tournament entries, reward and serviceFee are not included in the BET payload. Instead, tournamentId and tournamentBetsCloseAt fields are included to identify the tournament the round belongs to and the cut-off after which it accepts no new bets.

  • tournamentId - Identifier of the tournament this round belongs to. Present only when the entry was made via a tournament flow; absent for regular duels.

  • tournamentBetsCloseAt - The cut-off after which no new bets are accepted for this tournament, in ISO 8601 format (e.g., 2025-08-21T15:00:00.000Z). Sent alongside tournamentId on tournament entries; absent for regular duels.

Error Handling

If the player does not have sufficient funds, the Operator must return:

You must pass "isClientSafe": true in the response for it to be passed to the client.

Win Transaction

The WIN transaction is sent by THNDR to notify the Operator that a player has won a round.

The Operator must process this request to credit the player’s balance.

  • transactionId - Unique transaction identifier. Must be persisted by the Operator for idempotency and rollback handling.

  • requestedAt - The date and time when the request was initially made, in ISO 8601 format (e.g., 2025-08-21T14:30:00.123Z).

  • userId - Player identifier on the Operator’s platform.

  • sessionId - The session identifier provided by the Operator when the game was launched.

  • roundId - Identifier of the game round this transaction belongs to.

  • currency - Player's wallet currency provided by the Operator when the game was launched (read more in Currencies).

  • amount - Win amount, in the smallest unit of the currency (e.g., cents for USD, pence for GBP).

  • usdAmount - Optional. Transaction amount in USD cents; present only when the match currency is USD, carrying the original pre-conversion USD value (may differ from amount).

  • gameId - Game identifier. Possible values: solitaire, blocks, twentyone, blackjack, slots, plinko , videopoker, marbles and hilo.

  • roomId - Identifier for the game room. Players sharing the same roomId are participating in the same PvP match.

  • playerScore - Final score of the player identified by userId. Absent if this player never submitted a score.

  • opponentScore - Final score of this player's opponent in the same roomId. Absent if the opponent never submitted a score.

  • tournamentId (optional) - Identifier of the tournament this round belongs to. Present only for tournament rounds.

Match scores. playerScore and opponentScore are the final scores of the two players in the match identified by roomId, from the perspective of the player in userId. Both players receive the same pair of scores with the fields swapped. Either field is omitted when that player did not submit a score - for example when they ran out of time - so treat both as optional. Scores are informational and never affect the amount to credit or debit.

Lose Transaction

The LOSE transaction is sent by THNDR to notify the Operator that a player has lost a round.

The Operator might process this request to record a loss.

  • transactionId - Unique transaction identifier. Must be persisted by the Operator for idempotency.

  • requestedAt - The date and time when the request was initially made, in ISO 8601 format (e.g., 2025-08-21T14:30:00.123Z).

  • userId - Player identifier on the Operator’s platform.

  • sessionId - The session identifier provided by the Operator when the game was launched.

  • roundId - Identifier of the game round this transaction belongs to.

  • currency - Player's wallet currency provided by the Operator when the game was launched (read more in Currencies).

  • gameId - Game identifier. Possible values: solitaire, blocks, twentyone, blackjack, slots, plinko , videopoker, marbles and hilo.

  • roomId - Identifier for the game room. Players sharing the same roomId are participating in the same PvP match.

  • playerScore - Final score of the player identified by userId. Absent if this player never submitted a score.

  • opponentScore - Final score of this player's opponent in the same roomId. Absent if the opponent never submitted a score.

  • tournamentId - Identifier of the tournament this round belongs to. Present only for tournament rounds.

Draw Transaction

The DRAW transaction is sent by THNDR to notify the Operator that a player has tied a round.

The Operator must process this request to credit the player’s balance.

  • transactionId - Unique transaction identifier. Must be persisted by the Operator for idempotency and rollback handling.

  • requestedAt - The date and time when the request was initially made, in ISO 8601 format (e.g., 2025-08-21T14:30:00.123Z).

  • userId - Player identifier on the Operator’s platform.

  • sessionId - The session identifier provided by the Operator when the game was launched.

  • roundId - Identifier of the game round this transaction belongs to.

  • currency - Player's wallet currency provided by the Operator when the game was launched (read more in Currencies).

  • amount - Win amount, in the smallest unit of the currency (e.g., cents for USD, pence for GBP).

  • usdAmount - Optional. Transaction amount in USD cents; present only when the match currency is USD, carrying the original pre-conversion USD value (may differ from amount).

  • gameId - Game identifier. Possible values: solitaire, blocks, twentyone, blackjack, slots, plinko , videopoker, marbles and hilo.

  • roomId - Identifier for the game room. Players sharing the same roomId are participating in the same PvP match.

  • playerScore - Final score of the player identified by userId. Absent if this player never submitted a score.

  • opponentScore - Final score of this player's opponent in the same roomId. Absent if the opponent never submitted a score.

Rollback Transaction

The ROLLBACK transaction is sent by THNDR to request the Operator to reverse a previously processed BET transaction, in cases of error, cancellation, or game rollback.

The Operator must ensure that the original transaction is undone and the player’s balance is correctly updated.

  • transactionId - Unique transaction identifier. Must be persisted by the Operator for idempotency.

  • requestedAt - The date and time when the request was initially made, in ISO 8601 format (e.g., 2025-08-21T14:30:00Z).

  • originalTransactionId - The transactionId of the original BET transaction being rolled back.

  • userId - Player identifier on the Operator’s platform.

  • sessionId - The session identifier provided by the Operator when the game was launched.

  • roundId - Identifier of the game round this transaction belongs to.

  • currency - Player's wallet currency provided by the Operator when the game was launched (read more in Currencies).

  • gameId - Game identifier. Possible values: solitaire, blocks, twentyone, blackjack, slots, plinko , videopoker, marbles and hilo.

Important: If a system crash occurs before receiving a response from the BET transaction, you may receive rollback requests for transaction ids that were never persisted in your database (i.e., the user was not credited). These requests must be ignored, and a 200 status code must be returned.

Promo Transaction

The PROMO transaction is sent by THNDR once per free match grant, to report the combined result of every free match on it.

The Operator must process this request to credit the player's balance.

It is sent when either:

  • every match on the grant has been played, or

  • the grant expires with at least one match played.

A grant that is cancelled, or expires with no match played, sends nothing.

  • transactionId - Unique transaction identifier, stable across retries. Must be persisted by the Operator for idempotency.

  • requestedAt - The date and time when the request was initially made, in ISO 8601 format (e.g., 2026-10-02T14:30:00.123Z).

  • userId - Player identifier on the Operator's platform.

  • sessionId - The session in which the last match on the grant was played.

  • roundId - Identifier of the last match played on the grant.

  • currency - The currency sent on the grant (read more in Currencies).

  • amount - Total the player won across every match on the grant, in the smallest unit of the currency (e.g., cents for USD, pence for GBP). Credit this amount. May be 0.

  • usdAmount - Optional. amount in USD cents before conversion; present only when the match currency is USD.

  • gameId - Game identifier of the last match played on the grant. Possible values: solitaire, blocks, twentyone, blackjack, slots, plinko , videopoker, marbles and hilo.

  • grantId - The grantId the Operator sent when granting the free matches.

  • cost - Total entry fees waived across every match played on the grant, in the smallest unit of the currency (info-only). Do not debit it; use it to report the cost of the promotion.

  • usdCost - Optional. cost in USD cents before conversion; present only when the match currency is USD.

  • isTest - Present and true when the player is a test player.

Each match is converted at the exchange rate of the session it was played in, and the converted amounts are summed, so amount and cost can differ slightly from converting usdAmount and usdCost at a single rate. See What each outcome adds to the grant for how each result contributes.

A free match sends no BET, WIN, LOSE, DRAW or ROLLBACK, and a PROMO is never rolled back. Do not look up a previous BET for its roundId: the Operator's wallet has never seen that round. A PROMO for a transactionId you have already processed must return 2XX without crediting the player again.

Signature Verification

Verify the request signature using raw request body as the request payload. More in the Request Signing section.

PreviousAnalytics Events
NextBalance

Last updated