GetAccount

GetAccount

Returns player details, such as unique ID, currency, and language.

Responsibilities of the casino platform

The casino platform must confirm the validity of incoming game sessions and account IDs and return the user data relevant for the session. If a retry or rollback request is sent regarding a request that the casino already responded to, the account ID that is returned must be unique per player, and identical.

Request Parameters

Request Example

/groove?request=getaccount&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&apiversion=1.2

Response Parameters

Response Example

Success Response

{
  "code": 200,
  "status": "Success",
  "accountid": 8877,
  "city": "aaa",
  "country": "IL",
  "currency": "EUR",
  "gamesessionid": "aaaaa",
  "real_balance": 100,
  "bonus_balance": 50,
  "game_mode": 1,
  "order": "cash_money, bonus_money",
  "apiversion": "1.2"
}

Error Codes

GetBalance

GetBalance

Returns the current balance in the specific player account.

Responsibilities of the casino platform

The casino platform must confirm the validity of the incoming game session ID and that it is connected to the given account ID. The casino platform must also return the player’s current balance, both the bonus balance and the real balance.

Request Parameters

Request Example

/groove?request=getbalance&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&nogsgameid=80102&apiversion=1.2

Response Parameters

Response Examples

Success Response

{
    "code": 200,
    "status": "Success",
    "balance": 100,
    "bonus_balance": 50,
    "real_balance": 50,
    "game_mode": 1,
    "order": "cash_money, bonus_money",
    "apiversion": "1.2"
}

Error Response

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

Error Codes

Wager

Wager

The Wager method wagers, or bets, for a player and updates the player’s wallet balance on the casino’s platform. Idempotency must be provided.

Responsibilities of the casino platform

The casino platform must:

• Confirm that the incoming game session ID is valid and is connected with the given account ID. If this validation fails, refuse the wager.
• Check that the transaction can be approved. Checks should include:
  • Sufficient funds are available
  • The player is within responsible gaming limits
• Determine whether the transactions have already been processed or not
• Check if a request with the same transactionid has been performed before:
  • If any of the essential fields transactionid, accountid, or betamount mismatch, the error Transaction parameter mismatch is returned
  • If there are no mismatches, the original response with the status 200 Success - duplicate request is returned. The only values that may change are the balance related parameters, since the player’s balance may have changed
• In order to handle future Result and Rollback calls, you must store the following parameters: gamesessionid, accountid, roundid, transactionid and betamount

Request Parameters

Request Examples

Regular Wager (No Free Rounds)

/groove?request=wager&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&apiversion=1.2&betamount=10.0&roundid=nc8n4nd87&transactionid=trx_id

Free Round Wager

/groove?request=wager&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&apiversion=1.2&betamount=0&roundid=nc8n4nd87&transactionid=trx_id&frbid=123abc456

Response Parameters

Response Example

Success Response

{
    "code": 200,
    "status": "Success",
    "accounttransactionid": "aaaaaaa",
    "balance": 100,
    "bonusmoneybet": 0,
    "realmoneybet": 10,
    "bonus_balance": 50,
    "real_balance": 50,
    "game_mode": 1,
    "order": "cash_money, bonus_money",
    "apiversion": "1.2"
}

Error Codes

Result

Result

The game server uses this method to inform that the wager round is complete. The result 0 indicates that the player lost. Idempotency must be provided.

Responsibilities of the casino platform

The casino platform must:

• Confirm that the incoming game session ID is valid and is connected with the given account ID
• Check if a request with the same transactionid has been performed before:
  • If any of the essential fields transactionid, accountid, or betamount mismatch, the error Transaction parameter mismatch is returned
  • If there are no mismatches, the original response with the status 200 Success - duplicate request is returned. The only values that may change are the balance related parameters, since the player’s balance may have changed
• Confirm that the incoming accountid and roundid match up with a previously placed wager. If this confirmation fails, refuse the result
• A result must be accepted even if the game session has expired, since a result can be reported by the game server later. Groove provides the game session for you as information in this call
• The only expected return code for a valid result call is success. All other return codes are unexpected and will result in the result attempt being resent. Return code 1000 Not logged on is never a valid response to a result call. The casino platform must accept the result even if the session has expired

Request Parameters

Request Examples

Regular Result (After Wager)

/groove?request=result&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&apiversion=1.2&result=10.0&roundid=nc8n4nd87&transactionid=trx_id&gamestatus=completed

Free Round Result (No Prior Wager)

/groove?request=result&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&apiversion=1.2&result=10.0&roundid=nc8n4nd87&transactionid=trx_id&gamestatus=completed&frbid=123abc456

Response Parameters

Response Example

Success Response

{
    "code": 200,
    "status": "Success",
    "walletTx": "aaaaaaa",
    "balance": 100,
    "bonusWin": 0,
    "realMoneyWin": 10,
    "bonus_balance": 50,
    "real_balance": 50,
    "game_mode": 1,
    "order": "cash_money, bonus_money",
    "apiversion": "1.2"
}

Error Codes

Rollback

Rollback

This method either rolls back a wager or a wager that did not result in a result. For example, if a player places a wager and the Result request fails, you can send a Rollback request to roll back the original wager.

Responsibilities of the casino platform

The casino platform must confirm that the incoming accountid, roundid, and transactionid are identical to the latest wager in the game round and not included in a result that has been issued for the relevant game round.

The casino platform may, but is not required to, verify that the bet amount in the relevant wager request is identical to the rollback amount.

The casino platform must refuse the rollback if any of these assertions fail.

• Check if a request with the same transactionid has been performed before:
  • If any of the essential fields transactionid, accountid, or betamount mismatch, the error Transaction parameter mismatch is returned
  • If there are no mismatches, the original response with the status 200 Success - duplicate request is returned. The only values that may change are the balance related parameters, since the player’s balance may have changed
• A rollback can be issued by the game server later. Therefore, a rollback must be accepted even if the game session has expired. Groove provides the game session for you as information in this call
• The only expected return code for a valid rollback call is 0 success
• If no matching wager is found, the code 102 Wager not found is returned
• If the rollback is incorrect, code 110 Operation not allowed is returned
• Return code 1000 Not logged on is never a valid response to a rollback call. The casino platform must accept the rollback even if the session has expired
• All other return codes result in a resending of the rollback attempt
• The Casino must refund the player only if a successful wager was found. Do not refund the player in the case of a failed wager or any other error

Request Parameters

Request Example

/groove?request=rollback&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&apiversion=1.2&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,
    "order": "cash_money, bonus_money",
    "apiversion": "1.2"
}

Error Codes

Wager And Result

Wager And Result

Places a wager and sets the result amount at the same time. Idempotency must be provided, which means equal requests should only be processed once. If a request is duplicated, that is, the requests have the same transactionid, the original response must be sent with the status 200, Success - duplicate request status.

Responsibilities of the casino platform

The same as in the separate Wager and Result requests.

Request Parameters

Request Examples

Regular Wager and Result (No Free Rounds)

/groove?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

Free Round Wager and Result

/groove?request=wagerAndResult&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&apiversion=1.2&result=10.0&betamount=0&roundid=nc8n4nd87&transactionid=trx_id&gamestatus=completed&frbid=123abc456

Response Parameters

Response Example

Success Response

{
  "code": 200,
  "status": "Success",
  "walletTx": "aaaaaaa",
  "balance": 100,
  "bonusWin": 0,
  "realmoneyWin": 0,
  "bonusmoneybet": 0,
  "realmoneybet": 5,
  "bonus_balance": 50,
  "real_balance": 50,
  "game_mode": 1,
  "order": "cash_money, bonus_money",
  "apiversion": "1.2"
}

Error Codes

The error codes are the same that are used in separate Wager and Result requests.

Jackpot

Jackpot

Groove Gaming sends this request as a Result call when the player wins a jackpot. Idempotency must be provided, which means the same request should only be processed once. If a request is duplicated, the original response must be sent with status 200, Success - duplicate request status.

Request Parameters

Request Example

/groove?request=jackpot&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&apiversion=1.2&amount=2000.0&roundid=nc8n4nd87&transactionid=trx_id&gamestatus=completed

Response Parameters

Response Example

Success Response

{
    "code": 200,
    "status": "Success",
    "walletTx": "aaaaaaa",
    "balance": 2100,
    "bonusWin": 0,
    "realMoneyWin": 2000,
    "bonus_balance": 50,
    "real_balance": 2050,
    "game_mode": 1,
    "order": "cash_money, bonus_money",
    "apiversion": "1.2"
}

Error Codes

Signature Validation

Signature Validation

Overview

For enhanced security, Groove can sign transaction API requests using HMAC-SHA256. Your platform should validate these signatures to ensure requests are authentic and haven’t been tampered with.

Prerequisites

Before validating signatures, you’ll need:

1. Access Key Value: Provided by Groove during integration setup
2. Secret: Base64 decoded version of the Access Key Value

Secret = base64_decode(<Access Key Value>)

Note: The Access Key is a pseudo-random HS512 secret provided by Groove.

Authorization Header

Each signed request from Groove includes an Authorization header with the following format:

Authorization: HMAC-SHA256 Signature={Signature}

Header Syntax

Signature Calculation

The signature is calculated using:

Signature = base64_encode(HMACSHA256(Path-And-Query, Secret))

Where:

• Path-And-Query: The canonical representation of the request path and query string
• Secret: The base64 decoded Access Key Value

Path-And-Query Format

The Path-And-Query is the concatenation of:

1. The request’s absolute URI path
2. The query string (including the ?)

Example

For a request to:

https://your-domain.com/groove?request=getbalance&gamesessionid=123&accountid=456

The Path-And-Query would be:

/groove?request=getbalance&gamesessionid=123&accountid=456

Implementation Example

PHP Implementation

function validateGrooveSignature($request, $accessKeyValue) {
    // Get the Authorization header
    $authHeader = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
    
    // Extract signature from header
    if (!preg_match('/HMAC-SHA256\s+Signature=(.+)/', $authHeader, $matches)) {
        return false;
    }
    
    $providedSignature = $matches[1];
    
    // Decode the secret
    $secret = base64_decode($accessKeyValue);
    
    // Build Path-And-Query
    $pathAndQuery = $_SERVER['REQUEST_URI'];
    
    // Calculate expected signature
    $hash = hash_hmac('sha256', $pathAndQuery, $secret, true);
    $expectedSignature = base64_encode($hash);
    
    // Compare signatures (constant-time comparison)
    return hash_equals($expectedSignature, $providedSignature);
}

// Usage
$accessKeyValue = "your_base64_access_key_from_groove";
if (validateGrooveSignature($_REQUEST, $accessKeyValue)) {
    // Process the valid request
    processTransaction();
} else {
    // Reject invalid signature
    http_response_code(401);
    echo json_encode([
        "code" => 401,
        "status" => "Unauthorized",
        "message" => "Invalid signature"
    ]);
}

Node.js Implementation

const crypto = require('crypto');

function validateGrooveSignature(req, accessKeyValue) {
    // Get the Authorization header
    const authHeader = req.headers['authorization'] || '';
    
    // Extract signature from header
    const match = authHeader.match(/HMAC-SHA256\s+Signature=(.+)/);
    if (!match) {
        return false;
    }
    
    const providedSignature = match[1];
    
    // Decode the secret
    const secret = Buffer.from(accessKeyValue, 'base64');
    
    // Build Path-And-Query
    const pathAndQuery = req.originalUrl;
    
    // Calculate expected signature
    const hash = crypto
        .createHmac('sha256', secret)
        .update(pathAndQuery)
        .digest('base64');
    
    // Compare signatures (constant-time comparison)
    return crypto.timingSafeEqual(
        Buffer.from(hash),
        Buffer.from(providedSignature)
    );
}

// Usage in Express.js
app.get('/groove', (req, res) => {
    const accessKeyValue = process.env.GROOVE_ACCESS_KEY;
    
    if (!validateGrooveSignature(req, accessKeyValue)) {
        return res.status(401).json({
            code: 401,
            status: "Unauthorized",
            message: "Invalid signature"
        });
    }
    
    // Process valid request
    processTransaction(req, res);
});

Python Implementation

import hmac
import hashlib
import base64
from flask import request, jsonify

def validate_groove_signature(access_key_value):
    # Get the Authorization header
    auth_header = request.headers.get('Authorization', '')
    
    # Extract signature from header
    import re
    match = re.search(r'HMAC-SHA256\s+Signature=(.+)', auth_header)
    if not match:
        return False
    
    provided_signature = match.group(1)
    
    # Decode the secret
    secret = base64.b64decode(access_key_value)
    
    # Build Path-And-Query
    path_and_query = request.full_path
    if path_and_query.endswith('?'):
        path_and_query = path_and_query[:-1]
    
    # Calculate expected signature
    hash_obj = hmac.new(
        secret,
        path_and_query.encode('utf-8'),
        hashlib.sha256
    )
    expected_signature = base64.b64encode(hash_obj.digest()).decode('utf-8')
    
    # Compare signatures (constant-time comparison)
    return hmac.compare_digest(expected_signature, provided_signature)

# Usage in Flask
@app.route('/groove')
def handle_groove_request():
    access_key_value = os.environ.get('GROOVE_ACCESS_KEY')
    
    if not validate_groove_signature(access_key_value):
        return jsonify({
            'code': 401,
            'status': 'Unauthorized',
            'message': 'Invalid signature'
        }), 401
    
    # Process valid request
    return process_transaction()

Testing Signature Validation

Test Example

Given:

• Access Key Value: dGVzdF9zZWNyZXRfa2V5XzEyMw==
• Request URL: /groove?request=getbalance&accountid=123
• Expected Path-And-Query: /groove?request=getbalance&accountid=123

Steps:

1. Decode secret: base64_decode("dGVzdF9zZWNyZXRfa2V5XzEyMw==")
2. Calculate HMAC-SHA256 of Path-And-Query with secret
3. Base64 encode the hash
4. Compare with provided signature

Security Best Practices

1. Always validate signatures in production environments
2. Use constant-time comparison to prevent timing attacks
3. Store Access Key securely (environment variables, secure vault)
4. Log validation failures for security monitoring
5. Reject requests with invalid or missing signatures
6. Rotate Access Keys periodically as per security policy
7. Use HTTPS for all communications

Common Issues and Solutions

Issue 1: Signature Mismatch

Cause: Incorrect Path-And-Query construction Solution: Ensure you’re using the exact request URI including all query parameters

Issue 2: Encoding Problems

Cause: Incorrect base64 decoding of Access Key Solution: Verify the Access Key is properly base64 decoded before use

Issue 3: Missing Authorization Header

Cause: Header not properly forwarded by proxy/load balancer Solution: Configure your infrastructure to forward Authorization headers

Issue 4: Query Parameter Order

Cause: Parameters reordered by framework Solution: Use the raw request URI as received, not reconstructed

Response for Invalid Signatures

When signature validation fails, return:

{
    "code": 401,
    "status": "Unauthorized",
    "message": "Invalid signature",
    "apiversion": "1.2"
}

Integration Checklist

• Receive Access Key Value from Groove
• Implement signature validation in your chosen language
• Test with sample requests from Groove
• Handle both signed and unsigned requests (during transition)
• Configure proper error responses
• Set up monitoring for validation failures
• Document your validation endpoint

Note on Optional Implementation

While signature validation is highly recommended for production environments, it may be optional during initial integration and testing phases. Coordinate with Groove to determine when signature validation should be enabled for your integration.