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.

See also

Authentication

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}]
        }
      }
    }'
Copy code

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"
     }
 }'
Copy code

A success response for the assign API method

{ "acknowledged": true }
Copy code

An example of an error response for the assign API method

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

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"
 }'
Copy code

A success response for the cancel API method

{ "acknowledged": true }
Copy code

An example of an error response for the cancel API method

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

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.

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

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" }
Copy code