Jackpot

Jackpot Transactions

Info

A jackpot transaction occurs when a player wins a special prize pool. This documentation explains how Groove Gaming processes jackpot wins.

Overview

When a player wins a jackpot during gameplay, Groove Gaming sends a Jackpot request to the casino operator. This functions similarly to a Result call but is specifically for jackpot prizes.

Warning

**Important:** Jackpot requests implement idempotency controls. This means the same request should only be processed once. If a duplicate request is received, the system must return the original response with status code 200 and the " Success - duplicate request" status.

Flow Diagram

sequenceDiagram participant Game as Game Provider participant Groove as Groove Platform participant Casino as Casino Operator Game->>Groove: Player wins jackpot Groove->>Casino: Jackpot request Casino->>Casino: Process jackpot win Casino->>Groove: Jackpot response Groove->>Game: Update player balance

Request Details

Endpoint

{casino_endpoint}?request=jackpot&[parameters]

Request Parameters

Parameter Data type Required Description
accountid String(60) - [0-9a-zA-Z] Yes Account ID
Example: 5179068
amount Decimal (32,10) Yes The jackpot win amount
Example: 2000.00
apiversion String Yes API version
Example: 1.2
gameid String Yes Groove game ID
Example: 80102
gamesessionid String(64) Yes Game session ID from start game method
Example: 11_99d71938-c2d9-4844-b950-d598c2es
gamestatus String Yes Game Status
Valid values: completed, pending
request String Yes Request method name
Value: jackpot
roundid String(255) Yes Round ID
Example: 802d1812c32686748f2afbcacfcc82114cf
transactionid String(255) Yes Transaction ID
Example: 7617edd0924c11e7abb2865556898ad0re

Example Request

GET {casino_endpoint}?request=jackpot&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&apiversion=1.2&amount=10.0&roundid=nc8n4nd87&transactionid=trx_id&gamestatus=completed

Response Details

Response Parameters

Parameter Data type Required Description
apiversion String Yes API version
Example: 1.2
balance Decimal (32,10) Yes Total player balance (real + bonus)
Example: 500.00
bonus_balance Decimal (32,10) Yes Player’s bonus balance
Example: 50.00
bonusWin Decimal (32,10) Yes Portion of win allocated to bonus funds
Example: 10.00
code Integer Yes Response code (see Appendix)
Example: 200
game_mode Integer Yes* Game mode:
1 - Real money mode
2 - Bonus mode
*Required for CMA-compliant games
order String Yes* Order type:
cash_money - Real money
bonus_money - Bonus money
*Required for CMA-compliant games
real_balance Decimal (32,10) Yes Player’s real money balance
Example: 100.00
realMoneyWin Decimal (32,10) Yes Portion of win allocated to real money
Example: 20.00
status String Yes Response status (see Appendix)
Example: Success
walletTx String(50) Yes Casino’s wallet transaction ID
Example: de73550e-0612-4a1b-8a0d-a5a3745b
Note

**Note:** The sum of `bonusWin` and `realMoneyWin` must equal the total jackpot `amount` specified in the request. If your casino does not use bonuses, set `bonusWin` to 0.

Note

**Note:** Jackpot might not be related to round, so it should be accepted even if no wager before.

Example Success Response

{
  "code": 200,
  "status": "Success",
  "walletTx": "de73550e-0612-4a1b-8a0d-a5a3745b",
  "balance": 100.00,
  "bonusWin": 2.00,
  "realMoneyWin": 8.00,
  "bonus_balance": 50.00,
  "real_balance": 50.00,
  "game_mode": 1,
  "order": "cash_money",
  "apiversion": "1.2"
}

Error Handling

Common Error Codes

Code Status Description
1 Technical error Internal server error
110 Operation not allowed This error occurs when:
• The jackpot amount is negative
• Player account not found
• Game status is invalid
400 Transaction operator mismatch Transaction belongs to a different operator
Tip

For a complete list of error codes, refer to [Appendix A: Transaction Response Status Codes](/appendix-a-transaction-response-status-codes/).

Implementation Notes

  1. Always store transaction IDs to ensure idempotency and prevent duplicate processing
  2. Validate all incoming parameters before processing
  3. The jackpot transaction should update player balances immediately
  4. Return appropriate error codes when validation fails

Security

When Signature Validation is enabled:

  1. Include the X-Groove-Signature header in your request
  2. Calculate signature using query parameters (excluding request)
  3. See Signature Validation for detailed implementation

Signature Example

For the request:

GET {casino_endpoint}?request=jackpot&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&apiversion=1.2&amount=10.0&roundid=nc8n4nd87&transactionid=trx_id

Query parameters for signature (alphabetically sorted):

  • accountid: “111”
  • amount: “10.0”
  • apiversion: “1.2”
  • device: “desktop”
  • gameid: “80102”
  • gamesessionid: “123_jdhdujdk”
  • roundid: “nc8n4nd87”
  • transactionid: “trx_id”

Concatenated values: 11110.01.2desktop80102123_jdhdujdknc8n4nd87trx_id

With security key "test_key", the signature would be:

X-Groove-Signature: d4cc7c2a2ed2f33657e2c24e0c32c5ead980f793e2ce81eb00316f0544a45048