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.

Create Bonus

Create Bonus Template

This endpoint receives bonus template creation requests from Groove. When casino operators want to set up free spin campaigns for your games, Groove sends the template details to your platform.

Request Details (From Groove to Your Platform)

• Method: POST
• Endpoint: https://{your_domain}/frb/create (or your specified endpoint)
• Content-Type: application/json; charset=UTF-8
• Direction: Groove → Your Platform

Request Parameters (What You’ll Receive from Groove)

Request Example

{
    "providerName": "Provider Name",
    "operatorId": 11,
    "transactionId": "292c8dbb-e00d-4807-a754-0b9ae5297c1j",
    "numberOfRounds": 10,
    "availableFromDate": "2023-06-19 14:56:56",
    "availableDuration": 90,
    "expirationDate": "2025-01-15 11:24:38",
    "balanceTypeId": 1,
    "messageFirstLine": "You got a Free Round Bonus",
    "messageSecondLine": "It's your lucky day",
    "offerName": "2e10691304314db08244f8c730055af73781878195",
    "gameInfoList": [
        {
            "gameId": "provider_game_id",
            "betAmount": 1
        }
    ]
}

Response Examples

Success Response

{
    "status": "Success",
    "code": 200,
    "templateId": "123456789",
    "exceptionResponses": null
}

Error Responses

General Error

{
    "status": "General Error",
    "code": 400,
    "templateId": null,
    "exceptionResponses": "Invalid Parameters"
}

Wrong Game ID

{
    "status": "Wrong Game ID",
    "code": 443,
    "templateId": null,
    "exceptionResponses": "Game id 123 is not valid"
}

Invalid Parameters

{
    "status": "Invalid Parameters",
    "code": 449,
    "templateId": null,
    "exceptionResponses": "Expiration Date is already Expired"
}

Internal Error

{
    "status": "Internal Error",
    "code": 500,
    "templateId": null,
    "exceptionResponses": null
}

Alternative Internal Error format:

{
    "status": "Internal Error",
    "errorCode": 500,
    "description": "Wrong info received"
}

Implementation Requirements

1. Template ID Generation: Your system must generate and return a unique templateId in the response
2. Storage: Store the template details for future player assignments from Groove
3. Currency: All bet amounts are in EUR - convert when assigning to players
4. Multi-Game Support: A template can include multiple games from your portfolio
5. Offer Tracking: Store the offerName as a unique identifier from Groove
6. Date Validation: Verify expiration date is after available from date
7. Idempotency: If Groove resends the same transactionId, return the original response

Processing the Request (Your Implementation)

// Example of how to process the incoming request from Groove
app.post('/frb/create', (req, res) => {
    const {
        providerName,
        operatorId,
        transactionId,
        numberOfRounds,
        gameInfoList,
        expirationDate,
        // ... other parameters
    } = req.body;
    
    // Validate the request
    if (!validateGameIds(gameInfoList)) {
        return res.status(443).json({
            status: "Wrong Game ID",
            code: 443,
            templateId: null,
            exceptionResponses: "Invalid game ID provided"
        });
    }
    
    // Generate unique template ID
    const templateId = generateUniqueTemplateId();
    
    // Store template in your database
    storeTemplate({
        templateId,
        transactionId,
        operatorId,
        gameInfoList,
        // ... other fields
    });
    
    // Return success response to Groove
    res.json({
        status: "Success",
        code: 200,
        templateId: templateId,
        exceptionResponses: null
    });
});

Validation Checklist

When processing requests from Groove, validate:

• ✅ All required fields are present in the request
• ✅ Game IDs match games available on your platform
• ✅ Dates are in correct UTC format (YYYY-MM-DD HH:MM:SS)
• ✅ Expiration date is after available from date
• ✅ Bet amounts are positive numbers
• ✅ Transaction ID hasn’t been processed before (idempotency check)

Assign Bonus

Assign Bonus to Players

This endpoint receives player bonus assignment requests from Groove. When casino operators want to grant free spins to specific players on your games, Groove sends the assignment details to your platform.

Request Details (From Groove to Your Platform)

• Method: POST
• Endpoint: https://{your_domain}/frb/assign (or your specified endpoint)
• Content-Type: application/json; charset=UTF-8
• Direction: Groove → Your Platform

Request Parameters (What You’ll Receive from Groove)

Request Example

{
    "templateId": "fe06efeb-b7fd-4249-a58d-717226507d5f",
    "providerName": "Provider Name",
    "operatorId": 11,
    "transactionId": "292c8dbb-e00d-4807-a754-0b9ae5297c1j",
    "numberOfRounds": 10,
    "availableFromDate": "2023-06-19 14:56:56",
    "availableDuration": 90,
    "expirationDate": "2025-01-15 11:24:38",
    "balanceTypeId": 1,
    "messageFirstLine": "You got a Free Round Bonus",
    "messageSecondLine": "It's your lucky day",
    "offerName": "2e10691304314db08244f8c730055af73781878195",
    "gameInfoList": [
        {
            "gameId": "provider_game_id",
            "betAmount": 1
        }
    ],
    "players": [
        {
            "playerId": "12345678",
            "playerCurrency": "EUR",
            "playerCountry": "IRL"
        }
    ]
}

Response Examples

Success Response

{
    "code": 200,
    "status": "Success",
    "templateId": "assign_unique_456xyz",  // Unique ID for THIS assignment (different from create templateId)
    "players": [
        {
            "playerId": 793918407,
            "playerCurrency": "EUR",
            "playerCountry": "IRL"
        },
        {
            "playerId": 793918408,
            "playerCurrency": "EUR",
            "playerCountry": "IRL"
        }
    ],
    "exceptionResponses": null
}

Partially Success Response

When some players are assigned successfully but others fail:

{
    "code": 200,
    "status": "Partially Succeeded",
    "templateId": "123abc456",
    "players": [
        {
            "playerId": 793918407,
            "playerCurrency": "EUR",
            "playerCountry": "IRL"
        }
    ],
    "exceptionResponses": null
}

Error Responses

General Error

{
    "status": "General Error",
    "code": 400,
    "templateId": null,
    "players": [
        {
            "playerId": 793918407,
            "playerCurrency": "EUR",
            "playerCountry": "IRL"
        }
    ],
    "exceptionResponses": "Invalid Parameters"
}

Wrong Game ID

{
    "status": "Wrong Game ID",
    "code": 443,
    "templateId": null,
    "players": [
        {
            "playerId": 793918407,
            "playerCurrency": "EUR",
            "playerCountry": "IRL"
        }
    ],
    "exceptionResponses": "Game id 123 is not valid"
}

Wrong Player ID

{
    "status": "Wrong Player Id",
    "code": 444,
    "templateId": null,
    "players": [
        {
            "playerId": 793918407,
            "playerCurrency": "EUR",
            "playerCountry": "IRL"
        }
    ],
    "exceptionResponses": ""
}

Internal Error

{
    "status": "Internal Error",
    "code": 500,
    "templateId": null,
    "players": [
        {
            "playerId": 793918407,
            "playerCurrency": "EUR",
            "playerCountry": "IRL"
        }
    ],
    "exceptionResponses": null
}

Implementation Requirements

1. Template Validation: Verify the templateId in the request matches a template previously created by Groove
2. Generate Unique Assignment ID: Create a new unique templateId for each assignment (different from the create templateId)
3. Currency Conversion: Your system must convert bet amounts from EUR to each player’s currency
4. Bet Value Mapping: After currency conversion, use the closest bet value supported by your game for that currency
5. Bulk Processing: Handle multiple player assignments in a single request from Groove
6. Partial Success Handling: Support partial success - some players may succeed while others fail
7. Player Validation: Check if player IDs from Groove exist in your system
8. Assignment Tracking: Store each unique assignment with its generated templateId for transaction reference
9. Idempotency: If Groove resends the same transactionId, return the original response with the same unique templateId

Processing the Request (Your Implementation)

// Example of how to process the incoming assignment request from Groove
app.post('/frb/assign', (req, res) => {
    const {
        templateId,
        transactionId,
        players,
        gameInfoList,
        // ... other parameters
    } = req.body;
    
    // Check if template exists (created earlier by Groove)
    const template = getTemplate(templateId);
    if (!template) {
        return res.status(400).json({
            status: "General Error",
            code: 400,
            templateId: null,
            players: players,
            exceptionResponses: "Template not found"
        });
    }
    
    // Generate a UNIQUE assignment ID for this specific assignment
    // This is different from the templateId in the request
    const uniqueAssignmentId = generateUniqueAssignmentId();
    // Example: "assign_" + uuid() or "assign_" + timestamp + "_" + randomId
    
    // Process each player
    const successfulPlayers = [];
    const failedPlayers = [];
    
    for (const player of players) {
        // Validate player exists in your system
        if (!validatePlayer(player.playerId)) {
            failedPlayers.push(player);
            continue;
        }
        
        // Convert EUR bet amounts to player's currency
        // and map to closest supported bet value
        const convertedBets = convertBetAmounts(
            gameInfoList,
            player.playerCurrency
        );
        
        // Map to closest supported bet values for the game
        const supportedBets = mapToSupportedBetValues(
            convertedBets,
            player.playerCurrency
        );
        
        // Assign bonus to player with the unique assignment ID
        assignBonusToPlayer({
            playerId: player.playerId,
            originalTemplateId: templateId,  // Store original for reference
            assignmentId: uniqueAssignmentId,  // Unique ID for this assignment
            convertedBets: supportedBets,
            expirationDate: req.body.expirationDate
        });
        
        successfulPlayers.push(player);
    }
    
    // Return appropriate response to Groove with UNIQUE assignment ID
    if (successfulPlayers.length === players.length) {
        res.json({
            code: 200,
            status: "Success",
            templateId: uniqueAssignmentId,  // Return the UNIQUE assignment ID
            players: successfulPlayers,
            exceptionResponses: null
        });
    } else if (successfulPlayers.length > 0) {
        res.json({
            code: 200,
            status: "Partially Succeeded",
            templateId: uniqueAssignmentId,  // Return the UNIQUE assignment ID
            players: successfulPlayers,
            exceptionResponses: null
        });
    } else {
        res.status(444).json({
            status: "Wrong Player Id",
            code: 444,
            templateId: null,
            players: failedPlayers,
            exceptionResponses: "No valid players found"
        });
    }
});

Validation Checklist

When processing assignment requests from Groove:

• ✅ Template ID exists in your system (from previous create request)
• ✅ All player IDs are validated against your player database
• ✅ Currency codes are in ISO3 format and supported
• ✅ Bet amounts are converted from EUR to player currencies
• ✅ Transaction ID hasn’t been processed before (idempotency)
• ✅ Expiration date hasn’t passed

Parameter Mismatch Handling

If the assignment parameters from Groove don’t match the stored template (except availableFromDate), return an error response:

{
    "status": "General Error",
    "code": 400,
    "templateId": null,
    "players": [...],
    "exceptionResponses": "Transaction parameter mismatch"
}

Currency Conversion Example

When Groove sends a template with EUR bet amounts, convert for each player:

Important: After converting the EUR amount to the player’s currency, use the closest bet value supported by your game for that currency. For example, if the conversion results in 1.13 USD but your game only supports 1.00 or 1.25 USD bets, use the closest supported value.

Get FRB Status

Get FRB Status

This endpoint allows Groove to query the status of a specific free round bonus assignment for a player on your platform.

Request Details (From Groove to Your Platform)

• Method: GET
• Endpoint: https://{your_domain}/frb/{version}/bonus?operator_id={operator_id}&template_id={template_id}&player_id={player_id}
• Direction: Groove → Your Platform

Request Parameters (What You’ll Receive from Groove)

Request Example

GET /frb/1.0/bonus?operator_id=11&template_id=assign_456xyz&player_id=12345678

Response Parameters (What You Must Return)

Available Statuses

All FRB endpoints must use these exact status values:

Response Examples

Success Response - Active Bonus

{
    "player_id": "12345678",
    "player_currency": "EUR",
    "operator_id": 11,
    "provider_id": 123,
    "status": "active",
    "template_id": "assign_456xyz",
    "left_rounds": 10,
    "total_rounds": 50,
    "expiration_date": "2025-02-11T12:00:00Z",
    "games": [
        {
            "game_id": "game001",
            "bet_amount": [1.0, 2.0],
            "currency": "EUR"
        },
        {
            "game_id": "game002",
            "bet_amount": [1.0, 2.0],
            "currency": "EUR"
        }
    ],
    "error_message": ""
}

Success Response - Completed Bonus

{
    "player_id": "12345678",
    "player_currency": "EUR",
    "operator_id": 11,
    "provider_id": 123,
    "status": "completed",
    "template_id": "assign_456xyz",
    "left_rounds": 0,
    "total_rounds": 50,
    "expiration_date": "2025-02-11T12:00:00Z",
    "games": [],
    "error_message": ""
}

Error Response

{
    "player_id": "12345678",
    "player_currency": "EUR",
    "operator_id": 11,
    "provider_id": 123,
    "template_id": "assign_456xyz",
    "expiration_date": "2025-02-11T12:00:00Z",
    "error_message": "Bonus not found"
}

HTTP Response Codes

Implementation Example

app.get('/frb/:version/bonus', (req, res) => {
    const { operator_id, template_id, player_id } = req.query;
    const { version } = req.params;
    
    // Validate parameters
    if (!operator_id || !template_id || !player_id) {
        return res.status(400).json({
            player_id: player_id || "",
            player_currency: "",
            operator_id: parseInt(operator_id) || 0,
            provider_id: 123,
            template_id: template_id || "",
            expiration_date: "",
            error_message: "Missing required parameters"
        });
    }
    
    // Look up the bonus assignment
    const assignment = getAssignment(template_id, player_id);
    
    if (!assignment) {
        return res.status(404).json({
            player_id: player_id,
            player_currency: "EUR",
            operator_id: parseInt(operator_id),
            provider_id: 123,
            template_id: template_id,
            expiration_date: "",
            error_message: "Bonus not found"
        });
    }
    
    // Determine status
    let status = 'active';
    if (assignment.canceled) {
        status = 'canceled';
    } else if (new Date(assignment.expiration_date) < new Date()) {
        status = 'expired';
    } else if (assignment.left_rounds === 0) {
        status = 'completed';
    }
    
    // Build response
    res.json({
        player_id: player_id,
        player_currency: assignment.player_currency,
        operator_id: parseInt(operator_id),
        provider_id: 123,
        status: status,
        template_id: template_id,
        left_rounds: assignment.left_rounds,
        total_rounds: assignment.total_rounds,
        expiration_date: assignment.expiration_date,
        games: status === 'active' ? assignment.games : [],
        error_message: ""
    });
});

Important Notes

1. Template ID: The template_id in the request is the unique assignment ID your platform generated during the /assign request
2. Status Logic: Determine status based on cancellation, expiration, and remaining rounds
3. Games Array: Only include games array when status is active
4. Bet Amounts: Return the converted bet amounts in the player’s currency
5. Error Handling: Always return a structured response even for errors

Best Practices

1. Cache Assignment Data: Keep assignment data readily available for quick status checks
2. Track Round Usage: Accurately track remaining rounds as players use them
3. Update Status: Automatically update status based on expiration and usage
4. Validate Operator: Ensure the operator_id matches the assignment
5. Log Requests: Keep audit logs of all status check requests

Cancel FRB

Cancel FRB

This endpoint allows Groove to cancel an active free round bonus assignment for a player on your platform.

Request Details (From Groove to Your Platform)

• Method: DELETE
• Endpoint: https://{your_domain}/frb/{version}/bonus?operator_id={operator_id}&template_id={template_id}&player_id={player_id}
• Direction: Groove → Your Platform

Request Parameters (What You’ll Receive from Groove)

Request Example

DELETE /frb/1.0/bonus?operator_id=11&template_id=assign_456xyz&player_id=12345678

Response Parameters (What You Must Return)

The response structure is identical to the Get FRB Status endpoint, but should reflect the actual status of the bonus.

Available Statuses

All FRB endpoints must use these exact status values:

Response Examples

Success Response - Bonus Canceled

{
    "player_id": "12345678",
    "player_currency": "EUR",
    "operator_id": 11,
    "provider_id": 123,
    "status": "canceled",
    "template_id": "assign_456xyz",
    "left_rounds": 10,
    "total_rounds": 50,
    "expiration_date": "2025-02-11T12:00:00Z",
    "games": [],
    "error_message": ""
}

Error Response - Bonus Not Found

{
    "player_id": "12345678",
    "player_currency": "EUR",
    "operator_id": 11,
    "provider_id": 123,
    "template_id": "assign_456xyz",
    "expiration_date": "",
    "error_message": "Bonus not found"
}

Response - Already Completed (Cannot Cancel)

{
    "player_id": "12345678",
    "player_currency": "EUR",
    "operator_id": 11,
    "provider_id": 123,
    "status": "completed",
    "template_id": "assign_456xyz",
    "left_rounds": 0,
    "total_rounds": 50,
    "expiration_date": "2025-02-11T12:00:00Z",
    "games": [],
    "error_message": ""
}

HTTP Response Codes

Implementation Example

app.delete('/frb/:version/bonus', (req, res) => {
    const { operator_id, template_id, player_id } = req.query;
    const { version } = req.params;
    
    // Validate parameters
    if (!operator_id || !template_id || !player_id) {
        return res.status(400).json({
            player_id: player_id || "",
            player_currency: "",
            operator_id: parseInt(operator_id) || 0,
            provider_id: 123,
            template_id: template_id || "",
            expiration_date: "",
            error_message: "Missing required parameters"
        });
    }
    
    // Look up the bonus assignment
    const assignment = getAssignment(template_id, player_id);
    
    if (!assignment) {
        return res.status(404).json({
            player_id: player_id,
            player_currency: "EUR",
            operator_id: parseInt(operator_id),
            provider_id: 123,
            template_id: template_id,
            expiration_date: "",
            error_message: "Bonus not found"
        });
    }
    
    // Check current status and respond accordingly
    if (assignment.status === 'completed') {
        // Return the actual status (completed) - cannot cancel
        return res.json({
            player_id: player_id,
            player_currency: assignment.player_currency,
            operator_id: parseInt(operator_id),
            provider_id: 123,
            status: "completed",  // Return ACTUAL status
            template_id: template_id,
            left_rounds: 0,
            total_rounds: assignment.total_rounds,
            expiration_date: assignment.expiration_date,
            games: [],
            error_message: ""
        });
    }
    
    if (assignment.status === 'expired') {
        // Return the actual status (expired) - can still mark as canceled for records
        return res.json({
            player_id: player_id,
            player_currency: assignment.player_currency,
            operator_id: parseInt(operator_id),
            provider_id: 123,
            status: "expired",  // Return ACTUAL status
            template_id: template_id,
            left_rounds: assignment.left_rounds,
            total_rounds: assignment.total_rounds,
            expiration_date: assignment.expiration_date,
            games: [],
            error_message: ""
        });
    }
    
    if (assignment.status === 'canceled') {
        // Already canceled - return current status
        return res.json({
            player_id: player_id,
            player_currency: assignment.player_currency,
            operator_id: parseInt(operator_id),
            provider_id: 123,
            status: "canceled",  // Already canceled
            template_id: template_id,
            left_rounds: assignment.left_rounds,
            total_rounds: assignment.total_rounds,
            expiration_date: assignment.expiration_date,
            games: [],
            error_message: ""
        });
    }
    
    // Cancel the bonus
    cancelAssignment(template_id, player_id);
    
    // Return success response
    res.json({
        player_id: player_id,
        player_currency: assignment.player_currency,
        operator_id: parseInt(operator_id),
        provider_id: 123,
        status: "canceled",
        template_id: template_id,
        left_rounds: assignment.left_rounds,
        total_rounds: assignment.total_rounds,
        expiration_date: assignment.expiration_date,
        games: [],
        error_message: ""
    });
});

Important Notes

1. Template ID: The template_id in the request is the unique assignment ID your platform generated during the /assign request
2. Status Response Rules:
   • ALWAYS return the ACTUAL status of the bonus, not the requested action
   • If bonus is completed, return status: "completed" (not "canceled")
   • If bonus is expired, return status: "expired" (not "canceled")
   • If bonus is already canceled, return status: "canceled"
   • Only return "canceled" if you actually performed the cancellation
3. HTTP Response Codes:
   • Return HTTP 200 even when returning completed or expired status
   • Use HTTP 404 only when the bonus doesn’t exist
4. Player Protection: Ensure no active game rounds are using the bonus before cancellation
5. Audit Trail: Keep records of cancellation attempts, even unsuccessful ones
6. Immediate Effect: Successful cancellations should take effect immediately

Business Rules

1. Active Games: If a player is currently in a game round using this bonus, handle appropriately:

   • Option 1: Prevent cancellation until round completes
   • Option 2: Allow cancellation but let current round complete
   • Document your approach for Groove

2. Refunds: Cancellation does not imply refund - it only stops future usage

3. Notification: Consider notifying the player that their bonus has been canceled

Best Practices

1. Transaction Safety: Use database transactions to ensure atomic updates
2. Concurrent Access: Handle race conditions if player is actively using the bonus
3. Audit Logging: Log all cancellation requests with timestamp and reason
4. Status Consistency: Ensure status is consistently updated across all systems
5. Error Messages: Provide clear error messages for different failure scenarios

FAQ

Frequently Asked Questions

Template Creation & Assignment Flow

Will Groove send an /assign request without first sending a /create request?

Answer: No. Groove will always send a /create request first, and your platform must respond with a templateId. Groove then uses this templateId in subsequent /assign requests.

How do template IDs flow through the FRB process?

Answer: The template ID flow works as follows:

1. Create: Groove sends create request → Your platform responds with templateId (e.g., “template_123”)
2. Assign: Groove sends assign request with templateId: "template_123" → Your platform generates and returns a NEW unique templateId (e.g., “assign_456”)
3. Transaction: Your game sends wager/result with frbid: "assign_456" (the unique assignment ID, not the original template ID)

This allows the same bonus template to be assigned multiple times with unique tracking for each assignment.

Why does Groove send similar data in both create and assign requests?

Answer: Both requests contain similar data for consistency and validation purposes. Your platform can ignore any fields that aren’t relevant to your processing logic.

What should we do if Groove sends an /assign request with different parameters than the original /create request for the same offerName?

Answer: This situation is a mismatch so error should be returned:

{
    "status": "General Error",
    "code": 400,
    "templateId": null,
    "players": [
        {
            "playerId": 793918407,
            "playerCurrency": "EUR",
            "playerCountry": "IRL"
        }
    ],
    "exceptionResponses": "Transaction parameter mismatch"
}

Date & Time Management

Can availableFromDate, availableDuration, and expirationDate be different for POST /create and POST /assign?

Answer:

• expirationDate - must be the same for both create and assign requests
• availableDuration - must be the same for both create and assign requests
• availableFromDate - can be different for both create and assign requests

Are dates in requests in UTC format?

Answer: Correct, all dates are in UTC format.

What does availableDuration mean in Groove’s requests?

Answer: It specifies how many days the free rounds will be available to the player after the availableFromDate.

How does expirationDate relate to availableFromDate in Groove’s requests?

Answer: The expirationDate can be independent of availableFromDate. It represents the final date when the bonus expires, regardless of when it became available.

Duplicate Handling

How should we handle duplicate offerName values from Groove?

Answer: For /create requests from Groove with duplicate offerName, this is an error - return:

{
    "status": "General Error",
    "code": 400,
    "templateId": null,
    "exceptionResponses": "OfferName already exist"
}

For /assign requests, duplicate offerName is normal - it means Groove is assigning the same template to different players, or the same player is receiving the template multiple times.

Game & Player Management

Will Groove send multiple games in the gameInfoList?

Answer: Yes, Groove can send multiple games in a single template. If the list contains only one game, the bonus applies to that specific game. If multiple games are included, the bonus can be used on any of those games.

Will Groove send multiple players in a single /assign request?

Answer: Yes, Groove can send multiple players in the players array for bulk assignments. Your platform should process each player and return appropriate success/failure status for each.

Transaction Integration

What should our game send as frbid when making wager requests to Groove?

Answer: The frbid must be the unique templateId that YOUR PLATFORM generates and returns in the assign response. This is NOT the templateId from the create request or from Groove’s assign request - it’s a new unique ID you generate for each assignment.

What exactly should our game use as the frbid when sending wager requests to Groove?

Answer: The frbid must be the unique templateId that your platform generates and returns in the assign response. Each assignment gets a new unique ID, even when the same bonus template is assigned multiple times to the same player. This allows casinos to differentiate between bonuses triggered by different events (registration, deposit, etc.).

What bet amount should our game send in wager requests for free rounds?

Answer: The betamount parameter must always be 0 (zero) for free round transactions. The actual bet value for the free round is already defined in the FRB template and converted to the player’s currency during assignment.

If a round starts before expirationDate but finishes after, should our game still send the result to Groove?

Answer: Yes, your game should send the result request to Groove. As long as the round started before the expirationDate, it’s valid.

Implementation Details

Currency Conversion

When Groove sends bonus assignments, your platform must convert the EUR base amounts to each player’s currency. This ensures players receive equivalent value in their account currency.

Multiple Assignments from Groove

• Groove may assign the same template to multiple players
• Groove may assign the same template to the same player multiple times
• Each assignment must generate a NEW unique templateId in your response
• Your platform tracks each assignment with its unique ID (e.g., remaining rounds per assignment)
• When a player has multiple active assignments, each has its own unique assignment ID for transactions
• This allows casinos to differentiate bonuses by trigger event (registration vs deposit vs promotion)

Best Practices for Handling Groove Requests

1. Validate that template exists when Groove sends /assign requests
2. Check if players exist in your system before assignment
3. Return specific error codes to help Groove understand issues
4. Support partial success when Groove sends multiple players
5. Log all requests from Groove for reconciliation

Testing Your FRB Implementation

1. Test receiving single and multiple player assignments from Groove
2. Verify EUR to player currency conversion accuracy
3. Test edge cases with date validations
4. Ensure proper error responses are returned to Groove
5. Test idempotency - return same response if Groove resends requests