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)

Parameter Type Mandatory Description
providerName string Yes Provider’s name
operatorId int Yes Operator’s ID
transactionId string Yes Transaction’s ID
numberOfRounds int Yes Amount of free bets
availableFromDate string Yes Date and time from which the bonus becomes available in UTC
Format: YYYY-MM-DD HH:MM:SS
availableDuration int Yes How long the rounds will be available (in days)
expirationDate string Yes Date and time until which the bonus is available in UTC
Format: YYYY-MM-DD HH:MM:SS
balanceTypeId int Yes Defines if the money goes to bonus/real
messageFirstLine string Yes Text message 1
messageSecondLine string Yes Text message 2
offerName string Yes Name of the offer
gameInfoList array Yes Array with the game details
gameInfoList.gameId string Yes Identifies specific game
gameInfoList.betAmount decimal Yes Bet value for each free bet

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)