Free Round Bonuses

Info

Free Round Bonuses (FRBs) are promotional tools that allow casino operators to offer free spins to players. This section covers the complete lifecycle of Free Round Bonuses within the Tech Fusion platform.

Overview

Free Round Bonuses are a powerful marketing tool that allow casinos to:

Attract new players with risk-free gameplay offers
Re-engage existing players with promotional incentives
Reward loyal players with bonus gameplay
Promote specific games or game providers

The Tech Fusion API provides a comprehensive set of endpoints to manage the entire Free Round Bonus lifecycle, from template creation to player redemption and reporting.

FRB Lifecycle

graph TD A[Create FRB Template] -->|Define bonus parameters| B[Configure Template] B -->|Set game, wager, max win| C[Ready for Assignment] C -->|Assign to players| D[Grant FRB to Players] D -->|Bonus activation| E[Player Uses Bonus] E -->|Track usage| F[Monitor Status] F -->|Optional| G[Cancel Unused FRB] style A fill:#e6f7ff,stroke:#333,stroke-width:2px style B fill:#f0f0f0,stroke:#333,stroke-width:1px style C fill:#f0f0f0,stroke:#333,stroke-width:1px style D fill:#e6f7ff,stroke:#333,stroke-width:2px style E fill:#f0f0f0,stroke:#333,stroke-width:1px style F fill:#e6f7ff,stroke:#333,stroke-width:2px style G fill:#ffe6e6,stroke:#333,stroke-width:1px

Free Round Bonus Process Flow

The following sequence diagram illustrates how Free Round Bonuses are processed through the Tech Fusion platform:

sequenceDiagram participant Casino as Casino Operator participant Tech Fusion as Tech Fusion Platform participant Game as Game Provider participant Player Casino->>Tech Fusion: Create FRB Template Tech Fusion->>Casino: Template ID Response Casino->>Tech Fusion: Grant FRB to Player Tech Fusion->>Casino: FRB Assignment Confirmation Player->>Casino: Login & Launch Game Tech Fusion->>Game: Initialize Game with FRB Parameters Game->>Player: Display Game with Free Spins Available rect rgb(240, 240, 240) Note over Player,Casino: Free Spin Usage Player->>Game: Use Free Spin Game->>Tech Fusion: Wager Request (amount=0) Tech Fusion->>Casino: Forward Wager Request Casino->>Tech Fusion: Wager Response Tech Fusion->>Game: Forward Response Game->>Player: Display Spin Outcome Game->>Tech Fusion: Result Request (win amount) Tech Fusion->>Casino: Forward Result Request Casino->>Tech Fusion: Result Response Tech Fusion->>Game: Forward Response Game->>Player: Display Win & Updated Balance end Casino->>Tech Fusion: Get FRB Status Request Tech Fusion->>Casino: FRB Status Response alt Unused FRB Expiration Casino->>Tech Fusion: Cancel FRB Request Tech Fusion->>Casino: Cancel FRB Confirmation end

Key FRB Components

FRB Template

A template defines the parameters of a Free Round Bonus offer, including:

Eligible games
Number of free spins
Bet amount for each spin
Maximum win amount
Validity period

FRB Grant

The process of assigning a template-based bonus to a specific player or group of players.

FRB Status

Tracking mechanism for monitoring the usage and status of bonuses granted to players.

FRB Cancellation

Method for revoking unused bonuses when needed (e.g., expired offers).

Available FRB Operations

The Tech Fusion API provides the following endpoints for managing Free Round Bonuses:

Operation	Description	Endpoint
Create FRB Template	Define bonus parameters	`/frb/create/{version}/template`
Grant FRB to Players	Assign bonus to players	`/frb/grant/{version}/players`
Get FRB Status	Check bonus usage status	`/frb/{version}/bonus?operator_id=XXXXX&template_id=XXXXX&player_id=XXXXX`
FRB Metadata	Retrieve bonus information	`/frb/games/{version}/metadata`
Cancel FRB	Revoke unused bonuses	`/frb/{version}/bonus?operator_id=XXXXX&template_id=XXXXX&player_id=XXXXX`

Implementation Guidelines

When implementing Free Round Bonuses, follow these best practices:

Template Management
- Create templates with clear identification and purpose
- Set appropriate limits on maximum wins
- Define reasonable validity periods
Player Assignment
- Target specific player segments for maximum effectiveness
- Provide clear terms and conditions
- Implement proper validation before granting
Monitoring and Reporting
- Regularly check bonus usage status
- Analyze performance of different bonus offers
- Maintain audit trails for all bonus activities
Error Handling
- Implement comprehensive error handling for all FRB operations
- Handle edge cases like attempting to use expired bonuses

Warning

Free Round Bonuses must comply with relevant gambling regulations in your jurisdiction. Ensure your implementation meets all regulatory requirements regarding bonus offers and promotions.

Next Steps

Explore the specific FRB operations in the following sections to implement a complete Free Round Bonus system for your casino.

Retrieve game provider FRB metadata

Retrieves FRB metadata from the game providers.

Request endpoint: /frb/games/{version}/metadata

Request Method: GET

Usage information for QuickFire

Game provider QuickFire requires a parameter named balanceTypeId. This parameter is not used by any other game provicer.

The valid values of the balanceTypeId parameter are:

0: Real money
1: Bonus money

Request parameters:

Parameter	Data type	Description
version	String required	The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0. Example: 1.0

Response Parameters:

None.

Example Response:

{
  "Quickfire": {
    "providerId": "27",
    "fieldsToDefine": {
      "numberOfRounds": {
        "type": "Integer",
        "maxValue": 2147483647,
        "minValue": 0
      },
      "availableFromDate": {
        "type": "Date",
        "format": "yyyy-MM-dd HH:mm:ss"
      },
      "availableDuration": {
        "type": "Integer"
      },
      "expirationDate": {
        "type": "Date",
        "format": "yyyy-MM-dd HH:mm:ss"
      },
      "balanceTypeId": {
        "type": "Integer",
        "allowedValues": [
          0,
          1
        ]
      },
      "messageFirstLine": {
        "type": "String",
        "optional": false
      },
      "messageSecondLine": {
        "type": "String",
        "optional": false
      },
      "offerName": {
        "type": "String",
        "optional": false
      }
    },
    "gameInfoList": [
      {
        "gameId": "83400088",
        "betAmount": [
          0
        ]
      },
      {
        "gameId": "83400091",
        "betAmount": [
          0
        ]
      },
      {
        "gameId": "83400161",
        "betAmount": [
          0
        ]
      }
    ]
  },
  "Playson": {
    "providerId": "7",
    "fieldsToDefine": {
      "numberOfRounds": {
        "type": "Integer",
        "maxValue": 2147483647,
        "minValue": 0
      },
      "availableFromDate": {
        "type": "Date",
        "format": "yyyy-MM-dd HH:mm:ss"
      },
      "availableDuration": {
        "type": "Integer"
      },
      "expirationDate": {
        "type": "Date",
        "format": "yyyy-MM-dd HH:mm:ss"
      },
      "balanceTypeId": {
        "type": "Integer",
        "allowedValues": [
          0,
          1
        ]
      },
      "messageFirstLine": {
        "type": "String",
        "optional": false
      },
      "messageSecondLine": {
        "type": "String",
        "optional": false
      },
      "offerName": {
        "type": "String",
        "optional": false
      }
    },
    "gameInfoList": [
      {
        "gameId": "80700000",
        "betAmount": [
          0
        ]
      },
      {
        "gameId": "80700023",
        "betAmount": [
          0
        ]
      }
    ]
  },
  "Evoplay Entertainment": {
    "providerId": "23",
    "fieldsToDefine": {
      "numberOfRounds": {
        "type": "Integer",
        "maxValue": 2147483647,
        "minValue": 0
      },
      "availableFromDate": {
        "type": "Date",
        "format": "yyyy-MM-dd HH:mm:ss"
      },
      "availableDuration": {
        "type": "Integer"
      },
      "expirationDate": {
        "type": "Date",
        "format": "yyyy-MM-dd HH:mm:ss"
      },
      "balanceTypeId": {
        "type": "Integer",
        "allowedValues": [
          0,
          1
        ]
      },
      "messageFirstLine": {
        "type": "String",
        "optional": false
      },
      "messageSecondLine": {
        "type": "String",
        "optional": false
      },
      "offerName": {
        "type": "String",
        "optional": false
      }
    },
    "gameInfoList": [
      {
        "gameId": "82500000",
        "betAmount": [
          0
        ]
      },
      {
        "gameId": "82500037",
        "betAmount": [
          0
        ]
      }
    ]
  }
}

Error Response:

{
  "errMsg": "unauthorized"
}

Response codes:

Code	Status	Message
200	success	200 success Got games providers FRB metadata successfully
400	bad request	bad request
500	internal server error	internal server error

Create FRB template

Creates a new FRB template.

Request endpoint: /frb/create/{version}/template

Request Method: POST

Usage information

The request body includes the FRB templates to create.

Note

Starting of 2025-12-01, authorization token is required for this request. The authorization token must be Base64-encoded as follows:
This request requires an authorization token: Bearer authorization token.
Token Format: The authorization token must be Base64-encoded as follows:
AuthorizationToken = encode(back_office_email:back_office_password)

Note

The specified parameters ‘operatorId’ and ‘providerName’ must already be configured in Sinatra.
For Playson, the template must contain only one game.
For Pragmatic Play, the expiration date of the template must be no more than 30 days from the template start date

Info

For QuickFire, parameter balanceTypeId is required. This parameter is not used by any other game provider. Valid values are:

0: Real money
1: Bonus money

Note

Bet amount definition is in EUR cents, so for other currencies, we have conversion rates defined in the Sinatra service.
Bet amount definition is in cents, so if the bet amount is 1.00, the value should be 100.
By default we will use the value of 0.01 as the minimum bet amount.
If any other value is required, please contact us and we will configure it, it should be defined in the betAmount array.
Amount set in game might be different than the amount set in the template(As different games might have different bet amounts set in them), we will use the closes bet amount to the bet amount set in the template.

Request parameters:

Parameter	Data type	Description
version	String required	The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0. Example: 1.0
Authorization	Yes (Header)	Sinatra back office user

Request Body

[
  {
    "providerName": "string",
    "operatorId": 0,
    "numberOfRounds": 0,
    "availableFromDate": "YYYY-MM-DD HH:mm:ss",
    "availableDuration": 0,
    "expirationDate": "YYYY-MM-DD HH:mm:ss",
    "balanceTypeId": [
      0
    ],
    "messageFirstLine": "string",
    "messageSecondLine": "string",
    "offerName": "string",
    "gameInfoList": [
      {
        "gameId": "string",
        "betAmount": [
          0
        ]
      }
    ]
  }
]

Note

betAmount value should be as cents.

The response body include the id parameter, which is used to get the template collection ID in the main object, which in turn is used to grant FRB.

Response Parameters:

None.

Example Response:

Success response:

{
  "createdBy": "string",
  "lastModifiedBy": "string",
  "version": 0,
  "id": "created_id",
  "done": true,
  "succeeded_insertion": [
    {
      "createdBy": "string",
      "lastModifiedBy": "string",
      "version": 0,
      "id": "string",
      "templateId": "string",
      "providerName": "string",
      "providerId": 0,
      "operatorId": 0,
      "currencyData": [
        {
          "name": "string",
          "bet_value": 0
        }
      ],
      "numberOfRounds": 0,
      "availableFromDate": "string",
      "availableDuration": 0,
      "expirationDate": "string",
      "balanceTypeId": [
        0
      ],
      "messageFirstLine": "string",
      "messageSecondLine": "string",
      "offerName": "string",
      "gameInfoList": [
        {
          "gameId": "string",
          "betAmount": [
            0
          ],
          "mobileGamePlatformInfo": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
          },
          "desktopGamePlatformInfo": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
          },
          "extraData": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
          }
        }
      ],
      "exceptionResponses": [
        "string"
      ],
      "players": [
        {
          "playerId": "string",
          "playerCurrency": "string",
          "playerCountry": "string"
        }
      ],
      "status": "string",
      "koalaRequest": {
        "requestUri": "string",
        "requestBody": "string",
        "responseStatus": "string",
        "responseBody": "string"
      }
    }
  ]
}

Info

If the request is successful, the response will contain a list of successfully created templates ( succeeded_insertion).
Upon assigning the FRB template, the template id that should be sent is the “id” field of the template object in the response (root object), in this example it is “created_id”.

Error Response:

{
  "errMsg": "bad request"
}

Response codes:

Code	Status	Message
200	success	200 success Got games providers FRB metadata successfully
400	bad request	bad request
422	Invalid parameters	One of: • bet amount should be an integer • no metadata fields for this provider • Available date is empty • Available date should be with format yyyy-MM-dd HH:mm:ss • Available date should be a future date • Expiration date is empty • Expiration date should be with format yyyy-MM-dd HH:mm:ss • Expiration date should be a future date • Number of rounds is empty • Balance type id is empty • Balance type id allowed values are 0 or 1 • Wrong balance type id size - values are 0 or 1 • Offer name can not be more than 255 characters • Game info list is empty • Game id not exist in this provider • provider supports only single game
500	internal server error	internal server error

Grant FRB to players

Grant a free round bonus to a player.

Request endpoint: /frb/grant/{version}/players

Request Method: POST

Usage information:

The request body includes the FRB template to granted to the specified players.

Note

For Playson and Evoplay Entertainment, only one player can be sent in the array.

Note

Template ID should be the ID of the FRB template created in the Create FRB template endpoint.

In the response body, parameter templateId is used to get the FRB templates granted successfully to players from the succeededAwarded parameter list under the FrbTemplatesAwardedCollections object.

Request parameters:

Parameter	Data type	Description
version	String required	The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0. Example: 1.0
Authorization	Yes (Header)	Sinatra back office user

Request body:

body includes FRB template to be granted to specific players.

{
  "templateId": "string",
  "players": [
    {
      "playerId": "string",
      "playerCurrency": "EUR",
      "playerCountry": "USA"
    }
  ]
}

Note

Currency - ISO 4217 currency code, should be the same as the currency of the player, which is used to play the game.
Country - alpha-3 country code, should be the same as the country (alpha-2) of the player, which is used to play the game.

Response parameters:

None

Example Response

Success response

{
  "id": "string",
  "templateId": "string",
  "players": [
    {
      "playerId": "string",
      "playerCurrency": "string",
      "playerCountry": "string"
    }
  ],
  "status": "string",
  "templatesAwardedCollections": {
    "failed_frb_awarded": [],
    "succeeded_frb_awarded": [
      {
        "templateId": "success_template_id",
        "providerName": "string",
        "players": [
          {
            "playerId": "string",
            "playerCurrency": "string",
            "playerCountry": "string"
          }
        ],
        "status": "string"
      }
    ],
    "partially_frb_awarded": []
  }
}

Info

For transactions(wager/result), the frbid which will be sent in request is the template id within succeeded_frb_awarded, in this case “success_template_id”.

Info

For Get / Cancel FRB requests, the id which should be sent is the template id within succeeded_frb_awarded, in this case “success_template_id”.

Error Response:

{
  "errMsg": "bad request"
}

Response codes:

Code	Status	Message
200	success	200 success Got games providers FRB metadata successfully
400	bad request	bad request
422	Invalid parameters	One of: • bet amount should be an integer • no metadata fields for this provider • Available date is empty • Available date should be with format yyyy-MM-dd HH:mm:ss • Available date should be a future date • Expiration date is empty • Expiration date should be with format yyyy-MM-dd HH:mm:ss • Expiration date should be a future date • Number of rounds is empty • Balance type id is empty • Balance type id allowed values are 0 or 1 • Wrong balance type id size - values are 0 or 1 • Offer name can not be more than 255 characters • Game info list is empty • Game id not exist in this provider • provider supports only single game
500	internal server error	internal server error

Get FRB Status

Get the free round bonus information granted to a player for the supported providers.

Request endpoint: /frb/{version}/bonus?operator_id=XXXXX&template_id=XXXXX&player_id=XXXXX

Request Method: GET

Usage information:

The request query parameters includes the operator ID, template ID, and Player ID.

Note

This request requires an authorization token: Bearer authorization token.
Token Format: The authorization token must be Base64-encoded as follows:
AuthorizationToken = encode(back_office_email:back_office_password)

Request parameters:

Parameter	Mandatory	Description
version	Yes	The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0. Example: 1.0
operator_id	Yes	Tech Fusion operator id
template_id	Yes	FRB grant template id.
player_id	Yes	The granted player id.
Authorization	Yes (Header)	Sinatra back office user

Example Response

Success response

{
  "player_id": "12345",
  "player_currency": "EUR",
  "operator_id": 67890,
  "provider_id": 123,
  "status": "active",
  "template_id": "template567",
  "left_rounds": 10,
  "total_rounds": 50,
  "expiration_date": "2025-02-11T12:00:00Z",
  "games": [
    {
      "game_id": "game001",
      "bet_amount": [
        10.5,
        20
      ],
      "currency": "EUR"
    },
    {
      "game_id": "game002",
      "bet_amount": [
        10.5,
        20
      ],
      "currency": "EUR"
    }
  ],
  "error_message": ""
}

Error Response:

 {
  "player_id": "12345",
  "player_currency": "EUR",
  "operator_id": 67890,
  "provider_id": 123,
  "template_id": "template567",
  "expiration_date": "2025-02-11T12:00:00Z",
  "error_message": "Internal Server Error"
}

Status Index:

Status	Description
active	The FRB is active, and the player can play.
canceled	The FRB is inactive; the operator requested to cancel the bonus.
expired	The FRB is inactive. The expiration date has passed.
completed	The player has finished playing; no available rounds remain for this bonus.

Response codes:

Code	Status	Message
200	success	200 success Got FRB status successfully
400	bad request	bad request
403	forbidden access	forbidden access
500	internal server error	internal server error

Cancel FRB

Cancel an active free round bonus granted to a player for the supported providers.

Request endpoint: /frb/{version}/bonus?operator_id=XXXXX&template_id=XXXXX&player_id=XXXXX

Request Method: DELETE

Usage information:

The request query parameters includes the operator ID, template ID, and Player ID.

Note

Request parameters:

Parameter	Mandatory	Description
version	Yes	The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0. Example: 1.0
operator_id	Yes	Tech Fusion operator id
template_id	Yes	FRB grant template id.
player_id	Yes	The granted player id.
Authorization	Yes (Header)	Sinatra back office user

Example Response

Success response

{
  "player_id": "12345",
  "player_currency": "EUR",
  "operator_id": 67890,
  "provider_id": 123,
  "status": "active",
  "template_id": "template567",
  "left_rounds": 10,
  "total_rounds": 50,
  "expiration_date": "2025-02-11T12:00:00Z",
  "games": [
    {
      "game_id": "game001",
      "bet_amount": [
        10.5,
        20
      ],
      "currency": "EUR"
    },
    {
      "game_id": "game002",
      "bet_amount": [
        10.5,
        20
      ],
      "currency": "EUR"
    }
  ],
  "error_message": ""
}

Error Response:

 {
  "player_id": "12345",
  "player_currency": "EUR",
  "operator_id": 67890,
  "provider_id": 123,
  "template_id": "template567",
  "expiration_date": "2025-02-11T12:00:00Z",
  "error_message": "Internal Server Error"
}

Status Index:

Status	Description
active	The FRB is active, and the player can play.
canceled	The FRB is inactive; the operator requested to cancel the bonus.
expired	The FRB is inactive. The expiration date has passed.
completed	The player has finished playing; no available rounds remain for this bonus.

Http response codes:

Code	Status	Description
200	success	200 success status update
400	bad request	bad request
403	forbidden access	forbidden access
500	internal server error	internal server error

Free Round Bonuses

Free Round Bonuses

Overview

FRB Lifecycle

Free Round Bonus Process Flow

Key FRB Components

FRB Template

FRB Grant

FRB Status

FRB Cancellation

Available FRB Operations

Implementation Guidelines

Next Steps

Subsections of Free Round Bonuses

Retrieve game provider FRB metadata

Retrieve game provider FRB metadata

Usage information for QuickFire

Request parameters:

Response Parameters:

Example Response:

Error Response:

Response codes:

Create FRB template

Create FRB template

Usage information

Request parameters:

Request Body

Response Parameters:

Example Response:

Success response:

Error Response:

Response codes:

Grant FRB to players

Grant FRB to players

Usage information:

Request parameters:

Request body:

Response parameters:

Example Response

Success response

Error Response:

Response codes:

Get FRB Status

Get FRB Status

Usage information:

Request parameters:

Example Response

Success response

Error Response:

Status Index:

Response codes:

Cancel FRB

Cancel FRB

Usage information:

Request parameters:

Example Response

Success response

Error Response:

Status Index:

Http response codes: