Signature Validation

Game Transaction Security Header

Overview

The Transaction API supports an optional security feature using HMAC-SHA256 cryptographic signatures to ensure request authenticity and prevent tampering. When enabled, all transaction requests must include a valid signature in the X-Groove-Signature header.

Supported Endpoints

The signature validation applies to all transaction endpoints:

• GetAccount - Validate player session
• GetBalance - Retrieve player balance
• Wager - Process bet placement
• Result - Process game outcome
• WagerAndResult - Combined bet and result
• Jackpot - Process jackpot wins
• Rollback - Reverse transactions
• ReverseWin - Reverse win transactions
• RollbackRollback - Reverse rollback operations
• WagerByBatch - Process batch betting (POST request)

Setup

1. Security Key Provision

Your account manager will provide a unique security key for generating HMAC-SHA256 signatures. This key must be kept secure and never exposed in client-side code.

2. Header Inclusion

All requests must include the signature in the request header:

X-Groove-Signature: <generated_signature>

Hash Creation Process

Step 1: Parameter Concatenation

Concatenate all query parameter values (not names) in lexicographical order based on the parameter names:

Step 2: Generate HMAC-SHA256

Use the concatenated string and your security key to generate the HMAC-SHA256 signature:

signature = HMAC_SHA256(concatenated_values, security_key)

Signature Validation Flow

Error Response

If signature validation fails, the server returns:

{
    "code": 1001,
    "status": "Invalid signature",
    "message": "invalid signature"
}

Implementation Examples

Python

import hmac
import hashlib
from urllib.parse import urlparse, parse_qs

def generate_signature(url, security_key):
    # Parse URL and extract query parameters
    parsed = urlparse(url)
    params = parse_qs(parsed.query)
    
    # Create parameter dictionary (handle single values)
    param_dict = {}
    for key, value_list in params.items():
        # Skip 'request' parameter
        if key == 'request':
            continue
        # Treat 'nogsgameid' as 'gameid' for sorting
        sort_key = 'gameid' if key == 'nogsgameid' else key
        param_dict[sort_key] = value_list[0] if value_list else ''
    
    # Sort parameters alphabetically and concatenate values
    sorted_params = sorted(param_dict.items())
    concatenated = ''.join([value for key, value in sorted_params])
    
    # Generate HMAC-SHA256
    signature = hmac.new(
        security_key.encode('utf-8'),
        concatenated.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return signature

# Example usage
security_key = "test_key"
url = "/groove?request=wager&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&apiversion=1.2&betamount=10.0&roundid=nc8n4nd87&transactionid=trx_id"
signature = generate_signature(url, security_key)
print(f"X-Groove-Signature: {signature}")

Golang

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "net/url"
    "sort"
    "strings"
)

func generateSignature(requestURL string, securityKey string) string {
    // Parse URL
    u, _ := url.Parse(requestURL)
    params := u.Query()
    
    // Create parameter map for sorting
    paramMap := make(map[string]string)
    for key, values := range params {
        // Skip 'request' parameter
        if key == "request" {
            continue
        }
        // Treat 'nogsgameid' as 'gameid' for sorting
        sortKey := key
        if key == "nogsgameid" {
            sortKey = "gameid"
        }
        if len(values) > 0 {
            paramMap[sortKey] = values[0]
        }
    }
    
    // Sort keys alphabetically
    var keys []string
    for k := range paramMap {
        keys = append(keys, k)
    }
    sort.Strings(keys)
    
    // Concatenate values in sorted order
    var concatenated strings.Builder
    for _, key := range keys {
        concatenated.WriteString(paramMap[key])
    }
    
    // Generate HMAC-SHA256
    h := hmac.New(sha256.New, []byte(securityKey))
    h.Write([]byte(concatenated.String()))
    signature := hex.EncodeToString(h.Sum(nil))
    
    return signature
}

// Example usage
func main() {
    securityKey := "test_key"
    url := "/groove?request=wager&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&apiversion=1.2&betamount=10.0&roundid=nc8n4nd87&transactionid=trx_id"
    signature := generateSignature(url, securityKey)
    fmt.Printf("X-Groove-Signature: %s\n", signature)
}

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URLDecoder;
import java.nio.charset.StandardCharsets;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.TreeMap;

public class GrooveSignature {
    
    public static String generateSignature(String url, String securityKey) throws Exception {
        // Parse query parameters
        String query = url.substring(url.indexOf("?") + 1);
        Map<String, String> params = new LinkedHashMap<>();
        
        for (String param : query.split("&")) {
            String[] keyValue = param.split("=");
            String key = URLDecoder.decode(keyValue[0], StandardCharsets.UTF_8.name());
            String value = keyValue.length > 1 ? 
                URLDecoder.decode(keyValue[1], StandardCharsets.UTF_8.name()) : "";
            
            // Skip 'request' parameter
            if (!key.equals("request")) {
                // Treat 'nogsgameid' as 'gameid' for sorting
                String sortKey = key.equals("nogsgameid") ? "gameid" : key;
                params.put(sortKey, value);
            }
        }
        
        // Sort parameters alphabetically
        Map<String, String> sortedParams = new TreeMap<>(params);
        
        // Concatenate values
        StringBuilder concatenated = new StringBuilder();
        for (String value : sortedParams.values()) {
            concatenated.append(value);
        }
        
        // Generate HMAC-SHA256
        Mac mac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKey = new SecretKeySpec(
            securityKey.getBytes(StandardCharsets.UTF_8), 
            "HmacSHA256"
        );
        mac.init(secretKey);
        byte[] hash = mac.doFinal(concatenated.toString().getBytes(StandardCharsets.UTF_8));
        
        // Convert to hex string
        StringBuilder hexString = new StringBuilder();
        for (byte b : hash) {
            String hex = Integer.toHexString(0xff & b);
            if (hex.length() == 1) hexString.append('0');
            hexString.append(hex);
        }
        
        return hexString.toString();
    }
    
    // Example usage
    public static void main(String[] args) throws Exception {
        String securityKey = "test_key";
        String url = "/groove?request=wager&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&apiversion=1.2&betamount=10.0&roundid=nc8n4nd87&transactionid=trx_id";
        String signature = generateSignature(url, securityKey);
        System.out.println("X-Groove-Signature: " + signature);
    }
}

Example Signatures

Using security key: "test_key"

Security Best Practices

1. Key Management

   • Store security keys in secure configuration management systems
   • Never hardcode keys in source code
   • Rotate keys periodically
   • Use different keys for different environments (staging, production)

2. Implementation Security

   • Always validate signatures server-side
   • Implement request timeout mechanisms
   • Log all signature validation failures for security monitoring
   • Use HTTPS for all API communications

3. Error Handling

   • Never expose security keys in error messages
   • Log detailed errors server-side for debugging
   • Return generic error messages to clients

4. Testing

   • Test with the provided example signatures
   • Verify parameter sorting logic thoroughly
   • Test edge cases (empty values, special characters)
   • Validate handling of the nogsgameid to gameid conversion

Troubleshooting

Common Issues

Debugging Steps

1. Log the concatenated string before hashing
2. Verify the security key is correct
3. Check parameter extraction and sorting
4. Ensure proper character encoding (UTF-8)
5. Validate the HMAC-SHA256 implementation

Migration Guide

If you’re migrating from an unsecured implementation:

1. Phase 1: Implement signature generation in your application
2. Phase 2: Test with provided examples in staging environment
3. Phase 3: Enable signature validation with your account manager
4. Phase 4: Deploy to production with monitoring
5. Phase 5: Monitor error rates and adjust as needed

Get Account

Get Account

Overview

The Get Account method is typically the first transaction API call made when a player launches a game. It verifies the player’s session and returns essential player details needed for the game to function correctly. Game providers use this information to configure the game session, set currency display, and initialize the player’s balance.

Flow Diagram

Casino Responsibilities

The casino platform must perform the following operations when processing a Get Account request:

1. Session Validation

   • Confirm the incoming game session ID is valid
   • Verify the session is associated with the provided account ID
   • Reject the request if validation fails

2. Player Data Retrieval

   • Return consistent player identifiers for the same player across sessions
   • Provide accurate player location information
   • Return the current player balances (real money and bonus)
   • Include the correct currency setting for the player

3. Consistency Requirements

   • The account ID must be unique per player and consistent across sessions
   • This is particularly important for retry and rollback operations

Request Details

Endpoint

{casino_endpoint}?request=getaccount&[parameters]

Request Parameters

Example Request

GET {casino_endpoint}?request=getaccount&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&apiversion=1.2

Response Details

Response Parameters

Example Success Response

{
  "code": 200,
  "status": "Success",
  "accountid": "8877",
  "city": "London",
  "country": "GB",
  "currency": "EUR",
  "gamesessionid": "11_99d71938-c2d9-4844-b950-d598c2es",
  "real_balance": 100.00,
  "bonus_balance": 50.00,
  "game_mode": 1,
  "order": "cash_money",
  "apiversion": "1.2"
}

Error Handling

Common Error Codes

Implementation Notes

1. Player Identification:

   • The accountid must be consistent for the same player across different sessions
   • This consistency is crucial for transaction reconciliation and player tracking

2. Location Information:

   • The country parameter uses ISO 3166-1 alpha-2 country codes (e.g., US, GB, DE)
   • Location data is used for regulatory compliance and localization

3. Currency Handling:

   • The currency parameter uses ISO 4217 currency codes (e.g., EUR, USD, GBP)
   • Cryptocurrency support varies by game provider
   • Games will display monetary values in the specified currency format

4. CMA Compliance:

   • For UK Gambling Commission (UKGC) regulated operators, game_mode and order parameters are required
   • These parameters control how funds are consumed for wagers (real money vs. bonus money)

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=getaccount&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&apiversion=1.2

Query parameters for signature (alphabetically sorted):

• accountid: “111”
• apiversion: “1.2”
• device: “desktop”
• gamesessionid: “123_jdhdujdk”

Concatenated values: 1111.2desktop123_jdhdujdk

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

X-Groove-Signature: be426d042cd71743970779cd6ee7881d71d1f0eb769cbe14a0081c29c8ef2a09

Related Endpoints

• Get Balance - Retrieves current player balance
• Wager - Places a bet and updates player balance
• Result - Updates player balance after a game round completes

Get Balance

Get Balance

Overview

The Get Balance method allows game providers to request the current balance for a specific player. This is typically called at various points during gameplay to ensure the player’s displayed balance is accurate. The casino returns both the real money balance and any bonus funds available to the player.

Flow Diagram

Casino Responsibilities

The casino platform must perform the following operations when processing a Get Balance request:

1. Session Validation

   • Confirm the incoming game session ID is valid
   • Verify the session is associated with the provided account ID
   • Reject the request if validation fails

2. Balance Retrieval

   • Retrieve the player’s current real money balance
   • Retrieve the player’s current bonus balance (if applicable)
   • Calculate the total balance (real + bonus)

3. Response Formatting

   • Return all balance values with consistent decimal precision
   • Include any required CMA-compliance parameters if applicable

Request Details

Endpoint

{casino_endpoint}?request=getbalance&[parameters]

Request Parameters

Example Request

GET {casino_endpoint}?request=getbalance&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&nogsgameid=80102&apiversion=1.2

Response Details

Response Parameters

Example Success Response

{
  "code": 200,
  "status": "Success",
  "balance": 100.00,
  "bonus_balance": 50.00,
  "real_balance": 50.00,
  "game_mode": 1,
  "order": "cash_money",
  "apiversion": "1.2"
}

Example Error Response

{
  "code": 1,
  "status": "Technical error",
  "message": "Technical error",
  "apiversion": "1.2"
}

Error Handling

Common Error Codes

Implementation Notes

1. Balance Calculation:

   • The balance value must equal the sum of real_balance and bonus_balance
   • For casinos that don’t use bonus balances, set bonus_balance to 0.00

2. Frequency of Calls:

   • Games typically call Get Balance after every significant player action
   • Balance may be polled periodically during gameplay
   • Balance should always be refreshed after financial transactions (wagers, results)

3. Error Handling:

   • If a player’s session has expired, return code 1000 Not logged on
   • This allows the game to prompt the player to log in again if needed

4. Balance Fields:

   • All balance fields should be returned (balance, bonus_balance, real_balance)

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. Remember to treat nogsgameid as gameid for sorting purposes
4. See Signature Validation for detailed implementation

Signature Example

For the request:

GET {casino_endpoint}?request=getbalance&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&nogsgameid=80102&apiversion=1.2

Query parameters for signature (alphabetically sorted, treating nogsgameid as gameid):

• accountid: “111”
• apiversion: “1.2”
• device: “desktop”
• gameid (from nogsgameid): “80102”
• gamesessionid: “123_jdhdujdk”

Concatenated values: 1111.2desktop80102123_jdhdujdk

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

X-Groove-Signature: 434e2b4545299886c8891faadd86593ad8cbf79e5cd20a6755411d1d3822abba

Related Endpoints

• Get Account - Retrieves player account information
• Wager - Updates player balance when placing a bet
• Result - Updates player balance after a game round completes

Wager

Wager Transaction

Overview

The Wager method represents a player placing a bet in a game. When a player initiates a betting action, the game provider sends a Wager request to the Groove platform, which then forwards it to the casino operator. The casino processes the request by validating the player’s session, checking available funds, and updating the player’s balance accordingly.

Flow Diagram

Casino Responsibilities

The casino platform must perform the following operations when processing a Wager request:

1. Session Validation

   • Confirm the incoming game session ID is valid
   • Verify the session is associated with the provided account ID
   • Reject the wager if validation fails

2. Transaction Validation

   • Verify sufficient funds are available
   • Check that the player is within responsible gaming limits
   • Determine if the transaction has already been processed

3. Idempotency Check

   • Check if a request with the same transactionid has been processed before
   • If any essential fields mismatch (transactionid, accountid, or betamount), return “Transaction parameter mismatch”
   • If no mismatches, return the original response with status “200 Success - duplicate request”

4. Transaction Storage

   • Store transaction details to handle future Result and Rollback calls
   • Important fields to store: gamesessionid, accountid, roundid, transactionid, and betamount

Request Details

Endpoint

{casino_endpoint}?request=wager&[parameters]

Request Parameters

Example Request

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

Response Details

Response Parameters

Example Success Response

{
  "code": 200,
  "status": "Success",
  "accounttransactionid": "aaaaaaa",
  "balance": 100.00,
  "bonusmoneybet": 0.00,
  "realmoneybet": 10.00,
  "bonus_balance": 50.00,
  "real_balance": 50.00,
  "game_mode": 1,
  "order": "cash_money",
  "apiversion": "1.2"
}

Error Handling

Common Error Codes

Implementation Notes

1. Idempotency Handling:

   • Always store transaction IDs to identify duplicate requests
   • Return the original response for duplicate transactions with the same transaction ID
   • Only the balance fields may change in duplicate responses (as player balance may have changed due to other transactions)

2. Transaction Storage:

   • Store wager details to validate future Result and Rollback calls
   • Key data includes: session ID, account ID, round ID, transaction ID, and bet amount

3. Error Handling:

   • Return appropriate error codes based on validation results
   • Include detailed error messages for troubleshooting

4. Free Round Bonuses:

   • If the wager is part of a Free Round Bonus, include the frbid parameter
   • For FRB wagers, the bet amount is typically 0 in real money mode

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. Include frbid parameter if present (for free round bonuses)
4. See Signature Validation for detailed implementation

Signature Example

For the request:

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

Query parameters for signature (alphabetically sorted):

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

Concatenated values: 1111.210.0desktop80102123_jdhdujdknc8n4nd87trx_id

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

X-Groove-Signature: f6d980dfe7866b6676e6565ccca239f527979d702106233bb6f72a654931b3bc

Related Endpoints

• Result - Used after a wager to add winnings to the player’s balance
• Wager and Result - Combined operation for immediate bet and win
• Rollback - Used to reverse a wager transaction if needed

Result

Result Transaction

Overview

The Result method is called by the game provider to inform the casino that a game round has completed and to report the outcome. If the player wins, the Result transaction adds the winning amount to the player’s balance. If the player loses, a result value of 0 is sent, indicating no additional funds should be added to the player’s balance.

Flow Diagram

Casino Responsibilities

The casino platform must perform the following operations when processing a Result request:

1. Session Validation

   • Confirm the incoming game session ID is valid
   • Verify the session is associated with the provided account ID

2. Idempotency Check

   • Check if a request with the same transactionid has been processed before
   • If any essential fields mismatch (transactionid, accountid, or result), return “Transaction parameter mismatch”
   • If no mismatches, return the original response with status “200 Success - duplicate request”

3. Round Validation

   • Confirm that the incoming accountid and roundid match a previously placed wager
   • For FRB or tournament payouts, a Result may be received without a previous Wager

4. Session Expiry Handling

   • A Result must be accepted even if the game session has expired
   • Return code 1000 Not logged on is never a valid response to a Result call

5. Game Status Processing

   • If gamestatus is “completed”, mark the round as closed
   • If gamestatus is “pending”, the round remains open for additional Result transactions

Request Details

Endpoint

{casino_endpoint}?request=result&[parameters]

Request Parameters

Example Request

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

Response Details

Response Parameters

Example Success Response

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

Error Handling

Common Error Codes

Implementation Notes

1. Game Status Handling:

   • pending - Indicates that the round is still in progress and more Result transactions may follow
   • completed - Indicates the round is finished and should be closed
   • A round can have multiple pending Results but only one completed Result

2. Idempotency Handling:

   • Always store transaction IDs to identify duplicate requests
   • Return the original response for duplicate transactions with the same transaction ID
   • Only the balance fields may change in duplicate responses (as player balance may have changed due to other transactions)

3. Session Expiry:

   • Result transactions MUST be processed even if the player’s session has expired
   • This is crucial as Results may arrive significantly after the player has disconnected
   • Never return 1000 Not logged on for Result transactions

4. Free Round Bonus Results:

   • For FRB games, a Result may be received without a matching Wager
   • Include the frbid parameter to identify which bonus the Result belongs to

5. Multiple Results in a Round:

   • Some games (particularly live games) may send multiple Result transactions for a single round
   • Only the final Result with gamestatus=completed closes the round

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. Include frbid parameter if present (for free round bonuses)
4. See Signature Validation for detailed implementation

Signature Example

For the request:

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

Query parameters for signature (alphabetically sorted):

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

Concatenated values: 1111.2desktop80102123_jdhdujdk10.0nc8n4nd87trx_id

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

X-Groove-Signature: d9655083f60cfd490f0ad882cb01ca2f9af61e669601bbb1dcced8a5dca1820f

Related Endpoints

• Wager - Used before a Result to place a bet
• Wager and Result - Combined operation for immediate bet and win
• Rollback on Result - Used to reverse a Result transaction if needed

Wager And Result

Wager And Result Transaction

Overview

The Wager And Result method is an optimization that allows game providers to perform both a wager and a result operation in a single transaction. This is particularly useful for instant games where the outcome is determined immediately after the player places a bet, such as scratch cards or simple slot spins.

By combining these operations, the game can reduce latency and network traffic, resulting in a smoother player experience. Like individual Wager and Result transactions, Wager And Result implements idempotency controls to prevent duplicate processing.

Flow Diagram

Casino Responsibilities

The casino platform must perform the following operations when processing a Wager And Result request:

1. Session Validation

   • Confirm the incoming game session ID is valid
   • Verify the session is associated with the provided account ID

2. Transaction Validation

   • Verify sufficient funds are available for the wager
   • Check that the player is within responsible gaming limits
   • Determine if the transaction has already been processed

3. Idempotency Check

   • Check if a request with the same transactionid has been processed before
   • If any essential fields mismatch, return “Transaction operator mismatch”
   • If no mismatches, return the original response with status “200 Success - duplicate request”

4. Transaction Processing

   • Process the wager (deduct the bet amount from player balance)
   • Process the result (add the win amount to player balance)
   • Calculate the final player balance

Request Details

Endpoint

/groove?request=wagerAndResult&[parameters]

Request Parameters

Example Request

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

Response Details

Response Parameters

Example Success Response

{
  "code": 200,
  "status": "Success",
  "walletTx": "de73550e-0612-4a1b-8a0d-a5a3745b",
  "balance": 105.00,
  "bonusWin": 0.00,
  "realMoneyWin": 10.00,
  "bonusmoneybet": 0.00,
  "realmoneybet": 5.00,
  "bonus_balance": 50.00,
  "real_balance": 55.00,
  "game_mode": 1,
  "order": "cash_money",
  "apiversion": "1.2"
}

Error Handling

Common Error Codes

The error codes for Wager And Result are the same as those used in the individual Wager and Result transactions.

Implementation Notes

1. Use Cases:

   • Instant win games (scratch cards, simple slots)
   • Games where the outcome is determined immediately after the bet
   • Optimizations to reduce latency and improve player experience

2. Idempotency Handling:

   • Store transaction IDs to identify duplicate requests
   • Return the original response for duplicate transactions with the same transaction ID
   • Only the balance fields may change in duplicate responses

3. Balance Calculation:

   • The final balance should reflect both the wager deduction and result addition
   • Example: Initial balance 100.00, bet 5.00, win 10.00, final balance 105.00

4. Game Status:

   • If gamestatus is “completed”, mark the round as closed
   • If gamestatus is “pending”, the round remains open for additional Result transactions

5. Free Round Bonus:

   • For FRB games, the betamount is typically 0
   • Include the frbid parameter to identify which bonus is being used

Advantages Over Separate Calls

1. Reduced Latency: Single network round-trip instead of two
2. Simplified Error Handling: One transaction to track and manage
3. Atomic Operation: Either both wager and result succeed, or neither does
4. Improved Player Experience: Faster game play with immediate results

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. Include frbid parameter if present (for free round bonuses)
4. See Signature Validation for detailed implementation

Signature Example

For the request:

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

Query parameters for signature (alphabetically sorted):

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

Concatenated values: 1111.210.0desktop80102123_jdhdujdk10.0nc8n4nd87trx_id

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

X-Groove-Signature: bba4df598cf50ec69ebe144c696c0305e32f1eef76eb32091585f056fafd9079

Related Endpoints

• Wager - Separate endpoint for placing a bet
• Result - Separate endpoint for reporting game outcome
• Rollback - Used to reverse a transaction if needed

Rollback

Rollback Transaction

Overview

The Rollback method allows game providers to reverse a previously made wager. This is commonly used in error scenarios, such as when a network issue occurs after a player places a bet but before the game round completes. By rolling back the wager, the player’s funds are returned to their account, ensuring they are not charged for a game round that did not complete properly.

Some game providers require specialized rollback implementations. For example, Sports Book providers typically require support for both Rollback on Result and Rollback on Rollback operations in addition to the standard Rollback.

Flow Diagram

Casino Responsibilities

The casino platform must perform the following operations when processing a Rollback request:

1. Transaction Validation

   • Confirm that the incoming accountid, roundid, and transactionid match the original wager
   • Verify that the wager being rolled back has not already been included in a result
   • Check that no previous rollback has been processed for this transaction

2. Idempotency Check

   • Check if a request with the same transactionid has been processed before
   • If any essential fields mismatch, return “Transaction operator mismatch”
   • If no mismatches, return the original response with status “200 Success - duplicate request”

3. Session Expiry Handling

   • A rollback must be accepted even if the game session has expired
   • Return code 1000 Not logged on is never a valid response to a rollback call

4. Balance Restoration

   • Refund the player’s balance only if a successful wager was found
   • Do not refund in case of a failed wager or any other error
   • Update both real money and bonus balances as appropriate

Request Details

Endpoint

{casino_endpoint}?request=rollback&[parameters]

Request Parameters

Example Request

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

Response Details

Response Parameters

Example Success Response

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

Error Handling

Common Error Codes

Implementation Notes

1. Rollback Eligibility:

   • A wager can only be rolled back if no result has been processed for it
   • Once a result transaction is received, the wager can no longer be rolled back
   • In case a result needs to be rolled back, use Rollback on Result instead

2. Idempotency Handling:

   • Store transaction IDs to identify duplicate rollback requests
   • Return the original response for duplicate transactions with the same transaction ID
   • Only the balance fields may change in duplicate responses (as player balance may have changed)

3. Balance Restoration:

   • The player’s balance should be restored to its state before the wager
   • If the original wager used both real money and bonus funds, both balances should be restored accordingly

4. Timing Considerations:

   • Rollbacks may be sent significantly after the original wager
   • The system must handle rollbacks even if the player’s session has expired
   • This is particularly important for games with network issues or delayed error detection

5. Transaction Record Keeping:

   • Maintain a record of rolled back transactions for auditing and reconciliation
   • Update the status of the original wager to indicate it has been rolled back

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=rollback&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&apiversion=1.2&rollbackamount=10.0&roundid=nc8n4nd87&transactionid=trx_id

Query parameters for signature (alphabetically sorted):

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

Concatenated values: 1111.2desktop80102123_jdhdujdk10.0nc8n4nd87trx_id

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

X-Groove-Signature: 5ecbc1d5c6bd0ad172c859da01cb90746a61942bdf6f878793a80af7539719e5

Related Endpoints

• Wager - The transaction that may need to be rolled back
• Rollback on Result - Used to reverse a Result transaction
• Rollback on Rollback - Used to reverse a previous Rollback transaction

Jackpot

Jackpot Transactions

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.

Flow Diagram

Request Details

Endpoint

{casino_endpoint}?request=jackpot&[parameters]

Request Parameters

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

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

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

Rollback On Result

Rollback On Result

Some Game Providers send Rollback for result requests, especially in sport games where the result of a game can be changed even after sending a result request. In this case, Game Providers want to deduct the result amount from a player’s balance.

Responsibilities of the casino platform

Request parameters:

Request Example:

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

Response parameters:

Response Example:

Success Response:

{
  "code": 200,
  "status": "Success",
  "accounttransactionid": "aaaaaaa",
  "balance": 100,
  "bonus_balance": 50,
  "real_balance": 50,
  "game_mode": 1,
  "apiversion": "1.2"
}

Error Codes:

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=reversewin&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&amount=10.0&roundid=nc8n4nd87&transactionid=trx_id&wintransactionid=win_trx_id&apiversion=1.2

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”
• wintransactionid: “win_trx_id”

Concatenated values: 11110.01.2desktop80102123_jdhdujdknc8n4nd87trx_idwin_trx_id

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

X-Groove-Signature: 0e96af62a1fee9e6dfbdbda06bc068a6cf2eb18152e02e39c3af70aecb5d04d7

Rollback On Rollback

Rollback On Rollback

Some Game Providers send Rollback for refund requests, especially in sport games where the result of a game can be changed even after sending a refund request. In this case, Game Providers want to reverse the rollback request.

Responsibilities of the casino platform

Request parameters:

Request Example:

{casino_endpoint}?request=rollbackrollback&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&rollbackAmount=10.0&roundid=nc8n4nd87&transactionid=trx_id

Response parameters:

Response Example:

Success Response:

{
  "code": 200,
  "status": "Success",
  "accounttransactionid": "aaaaaaa",
  "balance": 100,
  "bonus_balance": 50,
  "real_balance": 50,
  "game_mode": 1,
  "apiversion": "1.2"
}

Error Codes:

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=rollbackrollback&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&rollbackAmount=10.0&roundid=nc8n4nd87&transactionid=trx_id&apiversion=1.2

Query parameters for signature (alphabetically sorted):

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

Concatenated values: 1111.2desktop80102123_jdhdujdk10.0nc8n4nd87trx_id

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

X-Groove-Signature: ecaeae75702f548f788c92c06804e59d11719a70302704b36ef72d607e180327

Sportsbook - Bet By Batch

Sportsbook Feature - Bet By Batch

Overview

The Bet By Batch transaction is a sportsbook-specific feature that allows processing multiple wagers in a single API call. This is particularly useful for sports betting scenarios where players need to place multiple bets simultaneously (such as parlays, accumulators, or system bets), improving performance and reducing the number of individual API calls required.

Request Format

Endpoint

POST {casino_url}?request=wagerbybatch&request_id=XXXXXXX&gamesessionid=YYYYYY&gameid=TTTTTTT&apiversion=1.2

HTTP Method

POST (Unlike other transaction endpoints that use GET)

Query Parameters

Request Body (JSON)

Bet Object Structure

Request Example

POST {casino_endpoint}?request=wagerbybatch&request_id=batch_001&gamesessionid=1501_aea2b5b4-e066-4561-a16b-a187a6435a64&gameid=82602&apiversion=1.2

{
    "account_id": "24",
    "game_id": "82602",
    "game_session_id": "1501_aea2b5b4-e066-4561-a16b-a187a6435a64",
    "device": "Desktop",
    "bets": 
    [
            {
            "frb_id": "",
            "amount": 0.01,
            "round_id": "groove_test_00000000000000008",
            "transaction_id": "groove_test_00000000000000008"
            },
            {
            "frb_id": "",
            "amount": 0.02,
            "round_id": "groove_test_00000000000000009",
            "transaction_id": "groove_test_00000000000000009"
            },
            {
            "frb_id": "",
            "amount": 0.03,
            "round_id": "groove_test_00000000000000010",
            "transaction_id": "groove_test_00000000000000010"
            }
    ]
}

Response Format

Success Response

{
  "status": "Success",
  "code": 0,
  "message": "OK",
  "bets": [
    {
      "provider_transaction_id": "groove_test_00000000000000008",
      "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
      "bonus_money_bet": "0.00",
      "real_money_bet": "0.01"
    },
    {
      "provider_transaction_id": "groove_test_00000000000000009",
      "transaction_id": "123e4567-e89b-12d3-a456-426614174001",
      "bonus_money_bet": "0.00",
      "real_money_bet": "0.02"
    },
    {
      "provider_transaction_id": "groove_test_00000000000000010",
      "transaction_id": "123e4567-e89b-12d3-a456-426614174002",
      "bonus_money_bet": "0.00",
      "real_money_bet": "0.03"
    }
  ],
  "balance": "1234.51",
  "real_balance": "1234.51",
  "bonus_balance": "0.00"
}

Response Fields

Individual Bet Result Fields

Error Handling

Error Response

When the batch request fails:

{
  "code": 1006,
  "status": "Out of money",
  "message": "Insufficient funds to process batch"
}

Common Error Codes

Processing Logic

1. Batch Validation: The entire batch is validated for structure and session validity
2. Atomic Processing: All bets in the batch are processed as a single atomic transaction
3. Balance Check: Total required amount for all bets is validated against available balance
4. Transaction Recording: Each bet is recorded with its own transaction ID in the wallet system
5. Balance Updates: Player balance is updated once after all bets are processed

Idempotency

Each individual bet within the batch follows standard idempotency rules:

• If a transaction_id has been processed before, return the original response for that bet
• The batch request_id should also be unique for each batch submission
• Resubmitting the same batch with the same request_id should return the original response

Use Cases

Sports Betting Scenarios

Parlay/Accumulator Bets

Multiple selections combined into a single bet:

{
  "bets": [
    {
      "amount": 10.00,
      "round_id": "parlay_001",
      "transaction_id": "match1_home_win"
    },
    {
      "amount": 10.00,
      "round_id": "parlay_001",
      "transaction_id": "match2_over_2.5"
    },
    {
      "amount": 10.00,
      "round_id": "parlay_001",
      "transaction_id": "match3_both_score"
    }
  ]
}

System Bets

Multiple combinations from selected events:

{
  "bets": [
    {
      "amount": 5.00,
      "round_id": "system_001",
      "transaction_id": "combo_1_2"
    },
    {
      "amount": 5.00,
      "round_id": "system_001",
      "transaction_id": "combo_1_3"
    },
    {
      "amount": 5.00,
      "round_id": "system_001",
      "transaction_id": "combo_2_3"
    }
  ]
}

Multiple Single Bets

Different bets on various sporting events:

{
  "bets": [
    {
      "amount": 20.00,
      "round_id": "single_001",
      "transaction_id": "football_match_1"
    },
    {
      "amount": 15.00,
      "round_id": "single_002",
      "transaction_id": "tennis_match_1"
    },
    {
      "amount": 10.00,
      "round_id": "single_003",
      "transaction_id": "basketball_match_1"
    }
  ]
}

Security

When Signature Validation is enabled:

1. Include the X-Groove-Signature header
2. Calculate signature using query parameters (excluding request)
3. The request body is not included in signature calculation
4. See Signature Validation for detailed implementation

Signature Example

For the request:

POST {casino_url}?request=wagerbybatch&request_id=batch_001&gamesessionid=1501_xyz&gameid=82602&apiversion=1.2

Query parameters for signature (alphabetically sorted):

• apiversion: “1.2”
• gameid: “82602”
• gamesessionid: “1501_xyz”
• request_id: “batch_001”

Concatenated values: 1.282602gamesessionid_valuebatch_001

Best Practices

1. Batch Size: Keep batch sizes reasonable (typically < 100 bets)
2. Transaction IDs: Use meaningful, unique transaction IDs
3. Error Recovery: Implement proper error handling for partial failures
4. Logging: Log both the batch request_id and individual transaction_ids
5. Validation: Pre-validate bet amounts and balance before submission
6. Timeout Handling: Set appropriate timeouts for larger batches