Skip to main content

Rewards System Overview

The Rewards system allows merchants to grant promotional bonuses to players.

Rewards are created from predefined Reward Configurations and assigned to individual players.

Key Concepts​

Reward Configuration​

A Reward Configuration defines the template used when creating rewards.

It defines the rules and limitations that apply when rewards are created from this configuration, such as:

  • eligible games
  • bet amount
  • number of free bets
  • supported currencies
  • maximum win
  • reward duration

Each reward configuration belongs to a specific Merchant and can be identified using:

  • internal reward configuration ID (generated by the platform)
  • external reward configuration ID provided by the Merchant (must be unique per Merchant)

Configuration Rules​

  • name must be unique per Merchant
  • startDate and endDate are optional and define the period during which rewards can be assigned using this configuration
  • maxWin is optional and limits the maximum possible win from a single free bet (configured per currency). If not configured, no maximum win limit is applied.

Reward​

A Reward is an instance of a reward configuration assigned to a specific Player.

A reward contains:

  • assigned Player
  • reference to the reward configuration
  • remaining free bets
  • expiration date
  • status

Each reward can be identified using:

  • internal reward ID (generated by the platform)
  • external reward ID provided by the Merchant (must be unique per Merchant)

Reward Types​

Currently supported reward type:

  • Free Bet

Reward Lifecycle​

The typical reward flow consists of the following steps.

Reward Sequence Diagram

1. Create Reward Configuration​

The Merchant creates a reward configuration defining the reward rules.

Reward configurations are reusable and can be assigned to many Players.

2. Assign Reward​

A reward is created by assigning a reward configuration to a Player.

When assigning a reward:

  • the Merchant may provide an external reward ID
  • if not provided, the system generates one

Reward Start Time​

A reward can start in two ways:

  • Immediately after assignment (default)
  • At a scheduled time if scheduledStartDate is provided

3. Reward Usage​

Players consume rewards automatically while placing bets in eligible games.

4. Reward Completion​

A reward finishes when one of the following occurs:

  • all free bets are consumed (status becomes CLOSED)
  • the reward expires (status becomes EXPIRED)
  • the Merchant cancels the reward (status becomes CANCELLED)

Reward Status​

StatusDescription
IN_PROGRESSReward is active and can be used
CLOSEDAll free bets have been consumed
EXPIREDReward expired before being fully used
CANCELLEDReward was cancelled by the Merchant

Reward Cancellation​

Rewards can be cancelled by the Merchant using available cancel methods.

Cancellation behavior depends on whether the reward has already started.

  • If the reward has not started, it becomes CANCELLED and cannot be used.
  • If the reward has already started, the Player may finish using the remaining free bets.

Identifiers​

Both Reward Configurations and Rewards can be identified using either an internal system identifier or a merchant-provided identifier.

  • id – system-generated UUID
  • externalId – identifier provided by the Merchant system

Depending on the endpoint, either id or externalId must be provided.

If both are provided, externalId takes precedence.

The externalId must be unique per Merchant.

Request Verification​

All reward requests must include the following fields:

  • merchantId
  • timestamp
  • hash

Hash Fields​

The following fields are included in the hash calculation:

  • merchantId
  • timestamp

Fields are concatenated without separators.

For details on how the hash is generated, see the Hash Algorithm.