Gift Spins

Gift Spins (free rounds) let the casino grant a player a number of rounds on a given game. Only games with has_freespins: 1 in the Gamelist support them.

Rounds played from a Gift Spin session are reported through the normal bet and win callbacks, carrying the freespins_id of the grant, and freespins_finished on the last one.

Create Gift Spin

Request


[POST] {PROVIDER_URL}/v2/create-freespins

Parameter	Type	Required	Description
casino_id	integer	yes	provided by the game provider
game_id	integer	yes	unique game id
user_id	integer	yes	user’s ID at the casino
currency	string(3)	yes	currency code in ISO 4217 format
count	integer	yes	number of rounds granted, must be greater than `0`
freespins_id	string	no	your own handle for this grant. Generated when you omit it, and always returned — you need it to cancel
username	string	no	user’s username, defaults to `player_{user_id}`
valid_until	string	no	expiry, format `Y-m-d H:i:s`. Defaults to 7 days from now
start_at	string	no	start of the session, format `Y-m-d H:i:s`. Defaults to now
country	string(2-3)	no	player’s country in ISO format, used to pick the game source
source_id	integer	no	grant the rounds on one specific game source instead of letting us choose
bet	integer	no	fixed stake in cents per payline for the session. Left out, the game’s own minimum bet is used
line_number	integer	no	fixed number of paylines for the session

Request body:


{
    "casino_id": 1,
    "game_id": 19773,
    "user_id": 10000,
    "currency": "USD",
    "count": 20,
    "freespins_id": "gs-2024-0001",
    "username": "user123",
    "valid_until": "2024-09-30 23:59:59"
}

bet is an integer in cents, unlike the amount of the bet and win callbacks, which is a decimal in the major currency unit. bet: 25 means 0.25 USD. Only send it when you really want a fixed stake: a value below the game’s minimum is refused by some games and silently ignored by others.

start_at, bet and line_number shape the session where the game supports it, and are ignored where it does not. count and valid_until always apply.

Response

Successful response will be returned as a json object.


{
    "code": 200,
    "message": "OK",
    "freespins_id": "gs-2024-0001",
    "source_id": 24124
}

Parameter	Type	Description
code	integer	`200` on success
message	string	`OK`, or the confirmation text of the grant
freespins_id	string	the handle of this grant — store it, `cancel-freespins` needs it
source_id	integer	the game source the rounds were granted on

Keep source_id and pass it to Game launch when the player opens the game. A title can reach us through several game sources, and the rounds exist only on the one that granted them — launched on another, the player spins for real money instead.

A Gift Spin that is no longer valid is rejected with error 1011 when the player opens the game.

Cancel Gift Spin

Cancels a Gift Spin that has been created but not yet played out.

Request


[POST] {PROVIDER_URL}/v2/cancel-freespins

Parameter	Type	Required	Description
casino_id	integer	yes	provided by the game provider
game_id	integer	yes	unique game id
user_id	integer	yes	user’s ID at the casino
currency	string(3)	yes	currency code in ISO 4217 format
freespins_id	string	yes	the handle returned when the grant was created
source_id	integer	no	the source the grant was made on, as returned by `create-freespins`

Request body:


{
    "casino_id": 1,
    "game_id": 19773,
    "user_id": 10000,
    "currency": "USD",
    "freespins_id": "gs-2024-0001",
    "source_id": 24124
}

Response

Same shape as the create response.


{
    "code": 200,
    "message": "OK",
    "freespins_id": "gs-2024-0001",
    "source_id": 24124
}

Not every game can have a grant cancelled — where it cannot, the grant simply runs out at valid_until. Cancelling still works after the game itself has been switched off, so a grant is never stranded.

Errors

Both calls answer with HTTP 400 and the reason in message when the grant cannot be made: missing parameters, a count of zero or less, an unknown or switched-off game, a source_id that does not belong to the game, no game source that supports Gift Spins, or a refusal from the game itself, passed through as it arrived.