Reward API¶

The Reward API offers methods for retrieving information or manipulating rewards. All requests, except /free-bet where the communication is established via the OPTIONS HTTP method, are passed from the operator to VeliGames using the POST HTTP method with the content type application/json.

The signature parameter in the header is mandatory for all requests. The only exception is making a request for free bet options. In this case, the signature parameter is omitted from the header.

API Method: free-bet¶

The operator makes a request to the free-bet endpoint to retrieve the free bet options for each provider. This request does not require any additional request parameters.

Path:: https://VELIGAMES_API_URL/reward-api/public/free-bet
HTTP Method:: OPTIONS

JSON Response (HTTP 200 OK)

An example of the free-bet API method¶

curl -X 'POST' \
'https://VELIGAMES_API_URL/reward-api/public/free-bet' \
-H 'accept: */*' \
-H 'signature:OPERATOR_ID:tapm5+EvNZ5dCCN...N5CdDx0GCfUspxw==' \
-H 'Content-Type: application/json' \
-d '{
     "freeBetOptions": {
        "provider1": {
           "betAmount": [{ "fieldName": "betAmount", "required": true }],
           "betPerLineAmount": [
              { "fieldName": "betPerLineAmount", "required": true },
              { "fieldName": "lines", "required": false }
           ]
        },
        "provider2": {
           "betLevel": [{ "fieldName": "betLevel", "required": true }]
        },
        "provider3": {
           "betAmount": [{"fieldName": "betAmount", "required": true}]
        }
      }
    }'

Tip

If a provider offers multiple options at the same level, you can specify either one group of parameters or another.

For example, in the scenario above, provider1 can choose to set either the betAmount group with one required field or the betPerLineAmount group, which contains one required and one optional field.

API Method: free-bet/assign¶

The operator can use this endpoint to assign free bets to a selected player.

Path:: https://VELIGAMES_API_URL/reward-api/public/free-bet/assign
HTTP Method:: POST

The following parameters are required. A request is only valid if it contains all of these parameters.

Parameter	Type	Description
freeBetId	string	One-time unique identifier generated by OPERATOR
providerId	string	Identifier of the game provider
gameId	string	The unique identifier of the game
playerId	string	The player’s unique identifier
currency	string	The player’s currency code
brandId	string	The identifier of the casino brand
endDate	string	The end date of the free bets end date (in UTC time zone)
quantity	string	The total quantity of free bets assigned to the player

Some parameters are specific to providers. If additional information is required it is placed in the config object. To see which provider specific parameters must be included, make a call to the /free-bet endpoint.

Parameter	Type	Purpose
config.betAmount	number	Bet amount per spin
config.betLevel	number	Bet Level
config.betPerLineAmount	number	Amount of bet per line (Relevant for some slot games)
config.lines	number	The total bet is calculated by other fields * lines. For example, *betPerLineAmount lines**. The default value is 1.
config.denomination	number	The bet denomination, If omitted, the default denomination is based on the selected game.
config.coins	number	The number of coins. The value of this parameter must match the number of coins available in the selected game. If omitted, the effective default number of coins is used.

Successful response

Parameter	Type	Purpose
acknowledged	boolean	Reward request is added to the queue and will callback assignment status to operator.

Tip

When assigning a free bet to a player, VeliGames sends asynchronous requests to the provider. According to the pre-provider validation protocol, a successful response does not guarantee you will not get an error status response.

Error response

Parameter	Type	Purpose
error	enum	See Error types below.
details	object [fieldName]: ‘error description’	Optional description

Error Types

Error type	HTTP code	Description
UNKNOWN_ERROR	500	A generic error or an internal server error that can be retried
BAD_REQUEST	400	The parameters are either missing or invalid
UNAUTHORIZED	401	Invalid signature
FREE_BET_EXISTS	409	Free bet already exists

An example of using the assign API method¶

curl 'https://VELIGAMES_API_URL/reward-api/public/free-bet/assign' \
 --header 'signature: OPERATOR_ID:4asd1CCN...N5CdDx0GCfUspxw==' \
 --header 'Content-Type: application/json' \
 --data '{
     "freeBetId": "33ee9a8112....5653966725a",
     "providerId": "provider1",
     "gameId": "463",
     "playerId": "642ef1f2...3a4a091ef",
     "currency": "EUR",
     "brandId": "someBrandId",
     "endDate": "2024-12-21T12:12:14Z",
     "quantity": "10",
     "config": {
         "betAmount": "50"
     }
 }'

A success response for the assign API method¶

{ "acknowledged": true }

An example of an error response for the assign API method¶

{ "error": "BAD_REQUEST", "details": { "brandId": "field is required" } }

API Method: free-bet/assign (VeliSports)¶

When assigning free bets for the velisports provider, use the same free-bet/assign endpoint with a specific set of parameters. Unlike the standard free bet flow, quantity is not expected for sports free bets, it is configured in advance in velisports backoffice at the moment. Additionally, the operator can optionally override the template’s claimable setting, claim period, and end date by providing claimable, claimPeriod, and endDate parameters in the request.

Path:: https://VELIGAMES_API_URL/reward-api/public/free-bet/assign
HTTP Method:: POST

Request body

Parameter	Type	Description
freeBetId	string	One-time unique identifier generated by the operator.
providerId	string	Must be `velisports`.
gameId	string	The unique identifier of the game.
playerId	string	The player’s unique identifier.
currency	string	The player’s currency code.
brandId	string	The identifier of the casino brand.
config	object	Provider-specific configuration. See /free-bet for available options.
providerCampaignId	string	The campaign template identifier on the provider side. Available values can be retrieved via sportsbook/templates.

The following parameters are optional and can be used to override the template’s default settings.

Parameter	Type	Description
claimable	boolean	Override the template’s claimable setting.
claimPeriod	number	Override the template’s claim period (days).
endDate	string	The end date of the free bets end date (in UTC time zone).

An example of using free-bet/assign for velisports¶

curl 'https://VELIGAMES_API_URL/reward-api/public/free-bet/assign' \
 --header 'signature: OPERATOR_ID:4asd1CCN...N5CdDx0GCfUspxw==' \
 --header 'Content-Type: application/json' \
 --data '{
     "freeBetId": "33ee9a8112....5653966725a",
     "providerId": "velisports",
     "gameId": "1000",
     "playerId": "642ef1f2...3a4a091ef",
     "currency": "EUR",
     "brandId": "someBrandId",
     "config": {},
     "providerCampaignId": "campaign-abc123",
     "claimable": true,
     "claimPeriod": 7
 }'

Response and errors

The response and error codes are identical to the standard free-bet/assign endpoint.

API Method: free-bet/cancel¶

By sending a request to this endpoint, you cancel an existing free bet.

Path:: https://VELIGAMES_API_URL/reward-api/public/free-bet/cancel
HTTP Method:: POST

Request body

Parameter	Type	Description
freeBetId	string	Unique identifier generated by OPERATOR on /assign that should be cancelled.
brandId	string	The identifier of the casino brand

JSON Response

Parameter	Type	Purpose
acknowledged	boolean	Cancel request is added to the queue and will callback cancellation status to operator.

Error response

VeliGames makes an asynchronous request to the provider to cancel the assigned free bets. According to the applied pre-provider validation protocol, a successful response does not guarantee that you will not get an error status response.

Parameter	Type	Purpose
error	enum	See error types below.
details	object [fieldName]: ‘error description’	Optional description

Error Types

Error type	Status code	Description
UNKNOWN_ERROR	500	A generic error or an internal server error that can be retried
BAD_REQUEST	400	The parameters are either missing or invalid
UNAUTHORIZED	401	Invalid signature
FREE_BET_NOT_FOUND	404	Free bet not found (Cancel/Info)
NOT_ALLOWED	405	Indicates that the requested operation is not allowed, such as canceling a free bet in the STARTED status.

An example of using the cancel API method¶

curl 'https://VELIGAMES_API_URL/reward-api/public/free-bet/cancel' \
 --header 'signature: OPERATOR_ID:4asd1CCN...N5CdDx0GCfUspxw==' \
 --header 'Content-Type: application/json' \
 --data '{
     "freeBetId": "33ee9a8112....5653966725a",
     "brandId": "someBrandId"
 }'

A success response for the cancel API method¶

{ "acknowledged": true }

An example of an error response for the cancel API method¶

{ "error": "BAD_REQUEST", "details": { "brandId": "field is required" } }

API Method: free-bet/info¶

A request to the this endpoint returns basic information and the current status of an existing free bet.

Path:: https://VELIGAMES_API_URL/reward-api/public/free-bet/info
HTTP Method:: POST

Request body

Parameter	Type	Description
freeBetId	string	Unique identifier generated by OPERATOR on /assign.
brandId	string	The identifier of the casino brand

JSON Response

The JSON response to the /free-bet/info request contains the essential information about the requested free bet. All parameters are of the string type.

Parameter	Type	Purpose
freeBetId	string	The unique identifier of the requested free bet
brandId	string	The identifier of the casino brand
status	enum	The current status of the requested free bet: CREATED ASSIGNED CANCELLED STARTED PLAYED ERROR
reason	string (optional)	More information in case the free bet status is set to ERROR.

API Method: free-bet/bet-levels¶

Warning

It currently works only with in-house studios. The only supported providerId values are heavenof7 and veliplay. Requests for any other provider are not supported.

Please only pass a single currency or the list you actually require per request, to avoid large payloads.

The operator makes a request to this endpoint to retrieve the available bet levels and their stake values for a given game, broken down per currency. The returned betLevel can be used as config.betLevel when assigning a free bet.

Path:: https://VELIGAMES_API_URL/reward-api/public/free-bet/bet-levels
HTTP Method:: POST

Request body

The following parameters are required.

Parameter	Type	Description
brandId	string	The identifier of the casino brand.
providerId	string	Identifier of the game provider. Must be `heavenof7` or `veliplay`.
gameId	string	The unique identifier of the game.

The following parameter is optional.

Parameter	Type	Description
currencies	array	Filter the response to the listed currency codes. If omitted, all currencies configured for the brand and provider are returned.

JSON Response

Returns the available bet levels grouped per currency.

Parameter	Type	Description
currencies	array	The list of per-currency bet levels. See the object fields below.

Currency object fields

Parameter	Type	Description
currency	string	The currency code the bet levels apply to.
levels	array	The list of available bet levels for this currency. See the object fields below.

Level object fields

Parameter	Type	Description
betLevel	number	The 1-based bet level index. Use this value as `config.betLevel` when assigning a free bet.
amount	number	The stake value for this bet level, in the given currency.

An example of using the bet-levels API method¶

curl 'https://VELIGAMES_API_URL/reward-api/public/free-bet/bet-levels' \
 --header 'signature: OPERATOR_ID:4asd1CCN...N5CdDx0GCfUspxw==' \
 --header 'Content-Type: application/json' \
 --data '{
     "brandId": "someBrandId",
     "providerId": "heavenof7",
     "gameId": "DiamondStrike",
     "currencies": ["GC", "SC"]
 }'

A success response for the bet-levels API method¶

{
    "currencies": [
        {
            "currency": "GC",
            "levels": [
                { "betLevel": 1, "amount": 0.5 },
                { "betLevel": 2, "amount": 1 },
                { "betLevel": 3, "amount": 2 }
            ]
        },
        {
            "currency": "SC",
            "levels": [
                { "betLevel": 1, "amount": 0.2 },
                { "betLevel": 2, "amount": 0.5 }
            ]
        }
    ]
}

Error Types

Error type	HTTP code	Description
BAD_REQUEST	400	The parameters are either missing or invalid.
UNAUTHORIZED	401	Invalid signature.
GAME_NOT_FOUND	404	No game matches the requested `gameId` on the provider side.
CURRENCY_NOT_FOUND	404	None of the requested `currencies` are available for the game.
UNKNOWN_ERROR	502	A generic error or an internal server error that can be retried

API Method: sportsbook/templates¶

The operator makes a request to this endpoint to retrieve the list of available campaign templates from the VeliSports provider. The returned id values are used as the providerCampaignId when assigning a sports free bet.

Path:: https://VELIGAMES_API_URL/reward-api/public/free-bet/sportsbook/templates
HTTP Method:: POST

Request body

The following parameters are required.

Parameter	Type	Description
brandId	string	The identifier of the casino brand.
providerId	string	Must be `velisports`.
currency	string	The player’s currency code.

The following parameters are optional and can be used to filter and paginate the results.

Parameter	Type	Description
bonusTypes	array	Filter by bonus types. Possible values: `BONUS`, `INSURANCE`, `FREE_BET`, `EARLY_PAYOUT`.
page	number	The page number for pagination. Default is `1`.
size	number	The number of items per page. Default is `25`.
search	string	A search term to filter templates by name.
fieldNameToOrderBy	string	The field name to sort results by. Default is `id`.
orderByDescending	boolean	Whether to sort in descending order. Default is `true`.

An example of using the sportsbook/templates API method¶

curl 'https://VELIGAMES_API_URL/reward-api/public/free-bet/sportsbook/templates' \
 --header 'signature: OPERATOR_ID:4asd1CCN...N5CdDx0GCfUspxw==' \
 --header 'Content-Type: application/json' \
 --data '{
     "brandId": "someBrandId",
     "providerId": "velisports",
     "currency": "EUR",
     "bonusTypes": ["FREE_BET"],
     "page": 1,
     "size": 25
 }'

JSON Response

Returns a paginated list of available campaign templates.

Parameter	Type	Description
meta	object	Information about the pagination. See the table below for object fields.
items	array	The list of campaign templates. See the table below for object fields.

Meta object fields

Parameter	Type	Description
totalItems	number	The total number of items in the collection that matches the request.
itemCount	number	The number of items returned in this particular response.
itemsPerPage	number	The maximum number of items from the data set that may fit in a page.
totalPages	number	The total number of pages required to deliver the whole collection.
currentPage	number	The current page number for this particular response.

Template object fields

Parameter	Type	Description
id	number	The unique identifier of the template. Used as `providerCampaignId` when assigning a sports free bet.
name	string	The name of the campaign template.
bonusType	string	The type of the bonus (e.g. `FREE_BET`, `BONUS`, `INSURANCE`, `EARLY_PAYOUT`).
expirationDate	string	The expiration date of the template (in UTC). Present when `validityType` is `0`.
validForDays	number	The number of days the free bet is valid for after assignment. Present when `validityType` is `1`.
claimable	boolean	Whether the free bet must be claimed by the player before it becomes active.
claimPeriod	number	The number of days the player has to claim the free bet. Present when `claimable` is `true`.

A success response for the sportsbook/templates API method¶

{
    "items": [
        {
            "id": 2757,
            "name": "Veligames Template 1",
            "bonusType": "FREE_BET",
            "expirationDate": "2026-03-30T20:00:00Z",
            "validForDays": null,
            "claimable": false,
            "claimPeriod": null,
        }
    ],
    "meta": {
        "totalItems": 42,
        "itemCount": 1,
        "itemsPerPage": 25,
        "totalPages": 2,
        "currentPage": 1
    }
}

Error Types

Error type	HTTP code	Description
UNKNOWN_ERROR	500	A generic error or an internal server error that can be retried
BAD_REQUEST	400	The parameters are either missing or invalid.
UNAUTHORIZED	401	Invalid signature.

API Method: sportsbook/template¶

The operator makes a request to this endpoint to retrieve the details of a single campaign template from the VeliSports provider, including its conditions and grant configuration.

Path:: https://VELIGAMES_API_URL/reward-api/public/free-bet/sportsbook/template
HTTP Method:: POST

Request body

The following parameters are required.

Parameter	Type	Description
templateId	string	The unique identifier of the template to retrieve in VeliSports’s system.
brandId	string	The identifier of the casino brand.
providerId	string	Must be `velisports`.

The following parameters are optional.

Parameter	Type	Description
currency	string	The currency of `grantAmount`.
timezone	string	The timezone offset passed to the provider. Default is `0`.

An example of using the sportsbook/template API method¶

curl 'https://VELIGAMES_API_URL/reward-api/public/free-bet/sportsbook/template' \
 --header 'signature: OPERATOR_ID:4asd1CCN...N5CdDx0GCfUspxw==' \
 --header 'Content-Type: application/json' \
 --data '{
     "templateId": "3210",
     "brandId": "someBrandId",
     "providerId": "velisports"
 }'

JSON Response

Returns the flattened details of the requested template.

Parameter	Type	Description
id	number	The unique identifier of the template.
name	string	The name of the campaign template.
bonusType	string	The type of the bonus (e.g. `FREE_BET`, `BONUS`, `INSURANCE`, `EARLY_PAYOUT`).
countryCodes	array	The list of country ISO codes the template is restricted to. Empty if the template is not country-restricted.
enabled	boolean	Whether the template is enabled.
activationDate	string	The activation date of the template (in UTC).
expirationDate	string	The expiration date of the template (in UTC).
validForDays	number	The number of days the free bet is valid for after assignment. Present for relative-validity templates.
claimable	boolean	Whether the free bet must be claimed by the player before it becomes active.
claimPeriod	number	The number of days the player has to claim the free bet. Present when `claimable` is `true`.
grantAmount	object	The fixed grant amount, with fields `amount` (number) and `currency` (string). Present for fixed-amount templates.
grantRatio	number	The grant ratio as a percentage (e.g. `80` for 80%). Present for ratio-based templates.
groupingType	string	How the conditions are combined. `ALL` means every condition must match; `ANY` means at least one must match.
conditions	array	The list of conditions attached to the template. See the table below.

Condition object fields

Parameter	Type	Description
conditionType	string	The type of the condition (e.g. `Sport`, `Competition`).
operationType	string	The operator applied to the value (e.g. `Equals`).
value	string	The human-readable condition value. When multiple values are configured, they are joined with ``, ``.

A success response for the sportsbook/template API method¶

{
    "id": 3210,
    "name": "vg-test-007",
    "bonusType": "FREE_BET",
    "countryCodes": [],
    "enabled": true,
    "activationDate": "2026-04-22T20:00:00Z",
    "expirationDate": "2026-04-26T20:00:00Z",
    "validForDays": null,
    "claimable": false,
    "claimPeriod": null,
    "grantAmount": { "amount": 1, "currency": "USD" },
    "groupingType": "ALL",
    "conditions": [
        {
            "conditionType": "Sport",
            "operationType": "Equals",
            "value": "Football"
        },
        {
            "conditionType": "Competition",
            "operationType": "Equals",
            "value": "EAFF E-1 Football Championship, Women"
        }
    ]
}

Error Types

Error type	HTTP code	Description
TEMPLATE_NOT_FOUND	404	The requested template could not be found on the provider side.
UNKNOWN_ERROR	500	A generic error or an internal server error that can be retried
BAD_REQUEST	400	The parameters are either missing or invalid.
UNAUTHORIZED	401	Invalid signature.

API Method: sportsbook/claim¶

The operator makes a request to this endpoint to claim an assigned sports free bet on behalf of a player. This is relevant for free bets where the claimable flag is set to true either in the campaign template or overridden in the assign request.

Path:: https://VELIGAMES_API_URL/reward-api/public/free-bet/sportsbook/claim
HTTP Method:: POST

Request body

Parameter	Type	Description
freeBetId	string	The unique identifier of the free bet to claim.
brandId	string	The identifier of the casino brand.

An example of using the sportsbook/claim API method¶

curl 'https://VELIGAMES_API_URL/reward-api/public/free-bet/sportsbook/claim' \
 --header 'signature: OPERATOR_ID:4asd1CCN...N5CdDx0GCfUspxw==' \
 --header 'Content-Type: application/json' \
 --data '{
     "freeBetId": "33ee9a8112....5653966725a",
     "brandId": "someBrandId"
 }'

Successful response

Parameter	Type	Description
freeBetId	string	The unique identifier of the claimed free bet.
operationType	string	The operation type. Always `CLAIM`.
status	string	The status of the claim operation. `CLAIMED` on success.
reason	string	Additional information in case the status is set to ERROR. Otherwise, this parameter is not included.

A success response for the sportsbook/claim API method¶

{
    "freeBetId": "33ee9a8112....5653966725a",
    "operationType": "CLAIM",
    "status": "CLAIMED"
}

Error Types

Error type	HTTP code	Description
UNKNOWN_ERROR	500	A generic error or an internal server error that can be retried
BAD_REQUEST	400	The parameters are either missing or invalid.
UNAUTHORIZED	401	Invalid signature.
FREE_BET_NOT_FOUND	404	The free bet was not found.

Event: status¶

The free bet status endpoint should be implemented of operator side. This webhook is called by VeliGames to notify operator about the current status of a free bet. Initiated after processing /assign or /cancel

Path:: https://{operator-defined-freebet-status-url}/status
HTTP Method:: POST

Note

VeliGames includes the signature header in this request. The operator must validate it to confirm the request originates from a trusted source; an invalid signature is answered with 401 UNAUTHORIZED. See Authentication.

Request body

The JSON document in the body of the request contains information about a free bet along with the operation that must be run on the operator’s system

Parameter	Type	Description
freeBetId	string	One-time unique identifier
brandId	string	The unique identifier of the casino brand
operationType	enum	Either ASSIGN or CANCEL
status	string	One of ASSIGNED, CANCELLED, or ERROR
reason	string	Relevant if the status is set to ERROR. Otherwise, this parameter is not be included.

Response

The operator’s system returns the HTTP code 200 indicating the success. In case of error HTTP code or timeout, VeliGames will retry the request several times.

Error response

If the request fails, the operator’s system can return one of the predefined error codes.

Error type	HTTP Status code	Description
UNKNOWN_ERROR	500	A generic error or an internal server error that can be retried
BAD_REQUEST	400	The parameters are either missing or invalid
UNAUTHORIZED	401	Invalid signature
FREE_BET_NOT_FOUND	404	Free bet not found (Cancel/Info)

An example of an error response for the status API method¶

{ "error": "FREE_BET_NOT_FOUND" }