Operator API

Overview

In this design, we will provide some details about how Game Aggregator (hereinafter referred to as Aggregator) will work with Operator and Game Provider (hereinafter referred to as Provider). See the diagram below.

Aggregator provides unified interface for Operator to integrate games from multiple Providers into its system.

Core API

Please note: if not stated, all the parameters in http body will be in json format.

Get Providers

Get Providers API request will be triggered by Operator to get list of providers.

Operator -> Aggregator -> Operator

GET /providers?operator_id={operator_id}&page_no={page_no}&page_size={page_size}

Reqeust Parameters

Parameter	Type	Example Value	Mandatory	Description
operator_id	string	aa80a9a8-d1b4-4f73-b1c4-548fe688258c	Mandatory	Operator id
page_no	int	4	Optional	Page number
page_size	int	20	Optional	Page size.

Response Parameters

Parameter	Type	Example Value	Mandatory	Description
id	string	pragmaticplay	Mandatory	Provider id
enabled	bool
name	string	Platinum Lightning	Mandatory	Provider name
locales	[]string		Mandatory	locales supported by the provider.
resources	[]string	{"cdn":{"logo_default_black":"https://resources.speedix.io/providers/logo/default/black/evolution.svg","logo_default_color":"https://resources.speedix.io/providers/logo/default/color/evolution.svg","logo_default_white":"https://resources.speedix.io/providers/logo/default/white/evolution.svg","logo_small_black":"https://resources.speedix.io/providers/logo/small/black/evolution.svg","logo_small_color":"https://resources.speedix.io/providers/logo/small/color/evolution.svg","logo_small_white":"https://resources.speedix.io/providers/logo/small/white/evolution.svg"}}	Mandatory	The provider resources.

Get Games

Get Games API request will be triggered by Operator to get list of authorised games from Aggregator.

Operator -> Aggregator -> Operator

GET /games?operator_id={operator_id}&page_no={page_no}&page_size={page_size}

Aggregator has a completed list of games from all Providers , but games returned to specific Operator rely on the configurations.

Reqeust Parameters

Parameter	Type	Example Value	Mandatory	Description
operator_id	string	aa80a9a8-d1b4-4f73-b1c4-548fe688258c	Mandatory	Operator id
page_no	int	4	Optional	Page number
page_size	int	20	Optional	Page size.

Response Parameters

Parameter	Type	Example Value	Mandatory	Description
id	string	aa80a9a8-d1b4-4f73-b1c4-548fe688258c	Mandatory	Game id
name	string	Platinum Lightning	Mandatory	Game name
assets	string	{ "background_1": "https://resources.speedix.io/games/background/1/pragmaticplay_AutoRoulette.jpg", "landscape_1": "https://resources.speedix.io/games/landscape/1/pragmaticplay_AutoRoulette.png", "square_1": "https://resources.speedix.io/games/square/1/pragmaticplay_AutoRoulette.png" }	Mandatory	The assets for the game in json format.
category	string	slots	Mandatory	Game's category. Available categories: slots, scratch, roulette, card, casual, lottery, poker, craps, crash, fishing, mines, video_poker, virtual_sports
languages	[]string	{“en“, “de“, “fr“}	Mandatory	The languages supported by the game.
currencies	[]string	{“USD“, “BRL“, ”IDR(K)”}	Mandatory	The currencies supported by the game.
theme	string	ancient_civilizations	Optional	The genre of a slot. Available themes: africa, ancient_civilizations, asia, book_off, branded, easter, egypt, fantasy, food, fruits, girls, halloween, horrors, joker, luxury_life, military, other, party, pirates, retro, space, sport, st_patrick_day, st_valentines_day, sweets, underwater_world, western, x_mas_and_new_year.
fee_group	string	basic	Mandatory	Assigns a group for each game due to different financial conditions
customised	bool	false	Mandatory	Shows whether the game is custom-made. Custom-made games are designed specifically for one casino.
devices	array of strings	["mobile"]	Mandatory	Devices on which the game can be launched. Available options: mobile, desktop
licenses	array of strings	MT	Mandatory	License that the provider partners with. 'No License' indicates casinos operating under no license to which games of the specific game provider relate.
has_jackpot	bool	true	Optional	Marks which games support jackpot feature
jackpot_type	string	In game	Mandatory	Indicates the type of the jackpot. Can be ‘Network’, ‘Local’, ‘In game’ or 'Not Available' if the jackpot type isn’t specified.
forbid_bonus_play	bool	true	Mandatory	Indicates games without an opportunity to place bets on bonus funds.
has_freespins	bool	true	Optional	Marks which games support freespins bonus feature (bonuses issued via API)
payout	float	98	Optional	Game's RTP
hit_rate	float	7.9	Optional	Frequency of wins per 100 bets. The higher the hit rate, the lower the volatility rating, and vice versa. Positive value. For slots only.
volatility_rating	string	medium-high	Optional	Game's volatility. Available levels are: low, medium-low, medium, medium-high, high, very-high, low-medium
lines	int	25	Optional	Number of paylines
ways	int	243	Optional	Also can mark the number of paylines
description	string		Optional	Game's description
has_live	bool	true	Optional	Marks which games are live ones
hd	bool	false	Optional	HD games are those with aspect ratio 16:9
accumulating	bool	true	Mandatory	Indicates games with accumulating bonuses.
multiplier	float	2000.0	Optional	The maximum coefficient the bet can be multiplied by.
released_at:		2018-06-05	Optional	Date of release. Game can't be launched before this date.
recalled_at:		2019-02-13	Optional	Date of recall. Game can't be launched after this date.
bonus_buy	bool	true	Mandatory	Indicates games with purchasable bonuses.
restrictions			Optional	Marks the territories blacklisted or/and whitelisted for the game
restricted_countries	array of strings	[“US“, “SG“]	Mandatory	List of countries game is restricted
recalled	bool	true	Mandatory	Indicates if game has been recalled
demo_enabled	bool	true	Mandatory	Indicates if game support demo play

Get Round Detail

Get Round Detail API request will be triggered by Operator to get detail of specified round from Aggregator.

Operator -> Aggregator -> Operator

GET /round-detail?round_id={round_id}

Reqeust Parameters

Parameter	Type	Example Value	Mandatory	Description
round_id	string	aa80a9a8-d1b4-4f73-b1c4-548fe688258c	Mandatory	Round id

Response Parameters

Response of /round-detail varies for different game providers, it might be a URL with which you can open up a page or json object representing the round detail.

Create Session

Create Session API request will be sent by Operator to Provider to start the game.

Operator -> Aggregator -> Provider → Aggregator → Operator

POST /sessions

Request

Parameter	Type	Mandatory	Description
operator_id	string	Mandatory	Operator Id
game_id	string	Mandatory	Game Id
currency	string	Mandatory	3 or 4 letters identifier of currency in upper case (https://en.wikipedia.org/wiki/ISO_4217 )
locale	string	Mandatory	2 letters identifier of language in lower case (https://en.wikipedia.org/wiki/ISO_639-1 ). Default locale is "en".
session_id	string	Optional	session_id in UUID format. For Provider only
ip	string	Mandatory	Player's IP address (IPv4)
client_type	string	Mandatory	Player's device type: mobile/desktop
balance	string	Optional	Initial balance. Is used to reduce balance requests.
urls	object	Mandatory	Parameters to redirect player. See description below. Your server should accept requests to these urls via any HTTP method (GET, POST etc.)
user	object	Mandatory	Player's attributes. Parameters are described below
jurisdiction	string	Optional	Identifier of the license. Two-letters identifier of country or combination of two-letters identifiers if applying to country's region (CA-ON for Ontario, Canada) (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 )
payload	string	Optional	Field to transfer the game stream session's identifier from casino to Livespins provider
extra_info	object	Optional	Provider specific parameters.

Parameters of object urls

Parameter	Type	Mandatory	Description
return_url	string	Mandatory	URL to redirect user after session is finished.
deposit_url	string	Mandatory	URL to redirect user to deposit page.
lobby_url	string	Mandatory	URL to redirect user to Operator’s page.

Parameters of object user

Parameter	Type	Mandatory	Description
wallet_user_id	string	Mandatory	Unique wallet_user_id on Operator side. wallet_user_id is created for each wallet / currency of the user.
user_id	string	Mandatory	unique user_id in Operator.
email	string	Optional	player's email
firstname	string	Optional
lastname	string	Optional
nickname	string	Optional	may be displayed in the game
city	string	Optional
date_of_birth	string	Optional	dates in format YYYY-MM-DD
registered_at	string	Optional	dates in format YYYY-MM-DD
gender	string	Optional	gender - m - for male, f - for female
country	string	Mandatory	2 letters identifier of country (https://en.wikipedia.org/wiki/ISO_3166-1 )

Parameters of object extra_info

extra_info provides the flexibility to assign some provider specific parameters.

Parameter	Type	Mandatory	Description
min_amount	string	Optional	Minimum bet amount. Default to 0.1 if not provided.
max_amount	string	Optional	Maximum bet amount. Default to 1000 if not provided.
exchange_rate	string	Optional	Exchange rate
balance_type	string	Optional	Balance type for the bet.

Please note: the above parameters are just example. extra_info varies for different providers and can be empty if not needed.

Response

Parameter	Type	Mandatory	Description
launch_options	object	Mandatory	Parameters for starting the game

Parameters of object launch_options

Parameter	Type	Mandatory	Description
game_url	string	Mandatory	game_url should include GA user_id in query parameter.
strategy	string	Mandatory

Demo

Demo API request will be sent by Operator to Provider to start demo game session.

Operator -> Aggregator -> Provider → Aggregator → Operator

POST /demo

Request

Parameter	Type	Mandatory	Description
game_id	string	Mandatory	Game Id
locale	string	Mandatory	2 letters identifier of language in lower case (https://en.wikipedia.org/wiki/ISO_639-1 ). Default locale is "en".
session_id	string	Optional	session_id in UUID format. For Provider only
ip	string	Mandatory	Player's IP address (IPv4)
client_type	string	Mandatory	Player's device type: mobile/desktop
urls	object	Mandatory	Parameters to redirect player. See description below. Your server should accept requests to these urls via any HTTP method (GET, POST etc.)
user	object	Mandatory	Player's attributes. Parameters are described below
jurisdiction	string	Optional	Identifier of the license. Two-letters identifier of country or combination of two-letters identifiers if applying to country's region (CA-ON for Ontario, Canada) (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 )
payload	string	Optional	Field to transfer the game stream session's identifier from casino to Livespins provider

Parameters of object urls

Parameter	Type	Mandatory	Description
return_url	string	Mandatory	URL to redirect user after session is finished.
lobby_url	string	Mandatory	URL to redirect user to Operator’s page.

Parameters of object user

Parameter	Type	Mandatory	Description
wallet_user_id	string	Mandatory	Unique wallet_user_id on Operator side. wallet_user_id is created for each wallet / currency of the user.
user_id	string	Mandatory	unique user_id in Operator.
email	string	Optional	player's email
firstname	string	Optional
lastname	string	Optional
nickname	string	Optional	may be displayed in the game
city	string	Optional
date_of_birth	string	Optional	dates in format YYYY-MM-DD
registered_at	string	Optional	dates in format YYYY-MM-DD
gender	string	Optional	gender - m - for male, f - for female
country	string	Mandatory	2 letters identifier of country (https://en.wikipedia.org/wiki/ISO_3166-1 )

Response

Parameter	Type	Mandatory	Description
launch_options	object	Mandatory	Parameters for starting the game

Parameters of object launch_options

Parameter	Type	Mandatory	Description
game_url	string	Mandatory	game_url should include GA user_id in query parameter.
strategy	string	Mandatory

Balance

Balance API request will be triggered by Provider to Operator to get the user balance.

Provider -> Aggregator -> Operator → Aggregator → Provider

POST /balance

Request

Parameter	Type	Mandatory	Description
session_id	string	Optional	Session Id
user_id	string	Mandatory	user_id on Operator side
currency	string	Mandatory	3 or 4 letters identifier of currency in upper case (https://en.wikipedia.org/wiki/ISO_4217 )
game_id	string	Optional	Game's identifier. If game_id is not set in the request, get the user balance instead.
round_id	string	Optional	game round_id on Provider side.
finished	bool	Optional	Whether the game round is finished

Response

Parameter	Type	Mandatory	Description
balance	string	Mandatory	Player's balance
bonus	string	Optional	Player’s bonus balance
round_id	string	Optional	Game round_id on Operator side. This field is presented in the case of closing a round.

Error Handling

• Message format should be validated and error bad request is expected if validation fails.

• The message should be validated as per Message-Signing-and-Verification and error message validation failed is expected if validation fails.

• The existence of user should be checked and error user not found is expected if not.

Play

Play API request will be triggered by Provider to Operator during the game.

Provider -> Aggregator -> Operator → Aggregator → Provider

POST /play

Request

Parameter	Type	Mandatory	Description
user_id	string	Mandatory	user_id on Operator side
currency	string	Mandatory	3 or 4 letters identifier of currency in upper case (https://en.wikipedia.org/wiki/ISO_4217 )
game_id	string	Mandatory	game_id
round_id	string	Mandatory	game round_id on Operator side
finished	bool	Mandatory	Whether the game round is finished (if not sent, should be considered by casino as "false" by default)
sm_result	string	Optional	The details of game (slot machine) result. For Portugal license only.
actions	array of objects of type either bet or win	Mandatory	Each object in array has the list of parameters.

Parameters for object actions

Parameter	Type	Mandatory	Description
action	string	Mandatory	bet, win, adjust, debit, credit and end
bet_id	string	Mandatory	bet identifier
txn_id	string	Mandatory	Transaction id from Provider
ext_txn_id	string	Optional	External transaction id from Provider when the Provider is an integration of Aggregator and Provider. Otherwise, it’s ““.
update_balance	bool	Mandatory	update_balance flag indicate if user balance needs to be updated as per the action.
take_all	bool	Optional	For debit action only.
is_refund	bool	Optional	For credit action only.
finished	bool	Mandatory	Indicate if the bet has finished.
amount	string	Mandatory	Non-negative amount
jackpot_contribution	string	Optional	Jackpot contribution of the bet.
jackpot_win	string	Optional	Non-negative amount.
bet_time	int64	Optional	Unix timestsamp in milli seconds.
settle_time	int64	Optional	Unix timestsamp in milli seconds.
provider_timestamp	int64	Mandatory	Timestamp from Providerin unix timestsamp in milli seconds.

Operator shoule make sure actions with the same round_id, bet_id and txn_id should be processed only once.

Response

Parameter	Type	Mandatory	Description
balance	string	Mandatory	Player’s balance in subunits
round_id	string	Mandatory	Game round_id on Operator side
transactions	array of objects	Mandatory	Each item in txs corresponds to action in request (bet, win, rollback). Parameters are described below

Parameters of object transactions

Parameter	Type	Mandatory	Description
txn_id	string	Mandatory	Transaction id from Provider
operator_txn_id	string	Optional	Transaction id from Operator
processed_at	string	Optional	Unix timestamp in milliseconds when the transaction was processed.
bonus_amount	string	Optional	The amount of bonus money a player placed a bet on. Bonus amount is received from the casino. It could be any value from 0 to the bet amount

Actions

User balance should be updated by the actions below if update_balance flag is true.

Action	Purpose	User Balance Update
bet	user places a bet.	User balance should be deducted by action.amount. User balance should be checked and return insufficient funds error if not enough.
win	User wins a bet.	User balance should be added by action.amount. The existence of bet should be checked and return bet not found error if not exists.
adjust	Adjust the previous bet result.	User balance should be added by action.amount which can be a positive or negative number. If action.amount is negative number, user balance should be checked and return insufficient funds error if not enough. The existence of bet should be checked and return bet not found error if not exists.
debit	Topup when starting the game.	User balance should be deducted by action.amount after checking if enough. Otherwise return insufficient funds error.
credit	Adjust user balance after the game has finished.	User balance should be added by action.amount.

Actions bet, win and end with update_balance as false serve as historical records only and should be used to maintain a complete audit trail of gaming transaction history. No wallet balance update should be trigged by any of these actions.

end action indicates the end of the bet if bet_id is not empty or the whole round otherwise.

Error Handling

• Message format should be validated and error bad request is expected if validation fails.

• The message should be validated as per Message-Signing-and-Verification and error message validation failed is expected if validation fails.

• The existence of user should be checked and error user not found is expected if not.

• If there is any action deducting the user balance in the request, user balance should be no less than the deducted amount, otherwise return insufficient funds error and keep the user balance intact.

• On action adjust, the existence of round should be checked and error round not found is expected if not.

• On action win and end, the existence of bet should be checked and error bet not found is expected if not.

Rollback

Rollback API is triggered by Provider to Operator.

Provider -> Aggregator -> Operator -> Aggregator -> Provider

POST /rollback

Request

Parameter	Type	Mandatory	Description
user_id	string	Mandatory	user_id in Operator
currency	string	Mandatory	3 or 4 letters identifier of currency in upper case (https://en.wikipedia.org/wiki/ISO_4217 )
game_id	string	Mandatory	game_id
round_id	string	Mandatory	Game round_id on Provider side.
finished	bool	Optional	Whether the game is finished
sm_result	string	Optional	The details of game (slot machine) result. For Portugal license only.
actions	array of objects of type rollback	Mandatory	Rollback action is described below

Parameters for object actions

Parameter	Type	Mandatory	Description
action	string	Mandatory	"rollback"
bet_id	string	Mandatory	Identifier of bet for rollback.
txn_id	string	Mandatory	Transaction id of the rollback action from Provider.
ext_txn_id	string	Mandatory	External transaction id of rollback action from Provider.
original_txn_id	string	Mandatory	Transaction id of the action to rollback from Provider.
original_ext_txn_id	string	Mandatory	External transaction id of action to rollback from Provider.
provider_timestamp	int64	Mandatory	Action timestamp on Provider in unix timestsamp in milli seconds.

Response

Parameter	Type	Mandatory	Description
balance	string	Mandatory	Player's balance.
round_id	string	Optional	Game round_id on Operator side. Can be omitted if original action was not processed.
transactions	array of objects	Mandatory	Each item in txs corresponds to action in request (rollback). Parameters are described below

Parameters for object transactions

Parameter	Type	Mandatory	Description
txn_id	string	Mandatory	transaction id from Provider in the request.
operator_txn_id	string	Optional	Transaction id from Operator.
processed_at	string	Optional	Action timestamp on Provider in unix timestsamp in milli seconds.

The action with empty original_txn_id means rolling back the whole bet indicated by bet_id.

The existence of the original transaction indicated by original_txn_id or the original bet indicated by bet_id should be checked and return transaction not found or bet not found error if not exists.

Error handling

• Message format should be validated and error bad request is expected if validation fails.

• The message should be validated as per Message-Signing-and-Verification and error message validation failed is expected if validation fails.

• The existence of user should be checked and error user not found is expected if not.

• The existence of bet should be checked and error bet not found is expected if not.

• The existence of original transaction indicated by original_txn_id should be checked and error transaction not found is expected if not.

Freespin

Issue Freespin

Issue Freespin API request is triggered by Operator to Provider to add user to specified freespin. Freespin will be created if doesn’t exist.

Operator -> Aggregator -> Provider → Aggregator → Operator

POST /freespins/issue

Request

Parameter	Type	Mandatory	Description
operator_id	string	Mandatory	Operator Id
freespin_id	string	Mandatory	Unique freespin id in operator system.
user	object	Mandatory	User information
request_id	string	Optional	request_id is used when the user needs to be added to the same freespin multiple times.
games	[]object
quantity	int	Mandatory	The number of free spin rounds.
start_at	int	Mandatory	Unix timestamp in seconds when the freespin starts.
expire_at	int	Mandatory	Unix timestamp in seconds when the freespin expires / end.
valid_until	int	Optional	Unix timestamp in seconds after which the freespin will be unavailable for the user. The valid time duration should be less than 30 days.

Parameters of object user:

Parameter	Type	Mandatory	Description
wallet_user_id	string	Mandatory	Unique wallet_user_id on Operator side. wallet_user_id is created for each wallet / currency of the user.
user_id	string	Mandatory	unique user_id in Operator.
email	string	Optional	player's email
firstname	string	Optional
lastname	string	Optional
nickname	string	Optional	may be displayed in the game
city	string	Optional
date_of_birth	string	Optional	dates in format YYYY-MM-DD
registered_at	string	Optional	dates in format YYYY-MM-DD
gender	string	Optional	gender - m - for male, f - for female
country	string	Mandatory	2 letters identifier of country (https://en.wikipedia.org/wiki/ISO_3166-1 )

Parameter of object games:

Parameter	Type	Mandatory	Description
game_id	string	Mandatory	Game id
bet_levels	[]object	Mandatory	Specify the bet levels placed in the freespin rounds.

Parameters of object bet_values:

Parameter	Type	Mandatory	Description
currency	string	Mandatory	Currency
bet_level	int	Mandatory	Specify the value of bet level in the freespin rounds.

Please note:

1. freespin_id should be unique in the system and can’t be reused even if the previous freespin has expired or cancelled.

2. Either bet_per_line or total_bet needs to be specified on each item in bet_values array.

3. All the items in the array should be with the same configuration, either bet_per_line or total_bet.

Response

On success, the response body will be empty with status code 200.

Cancel Freespin

Cancel Freespin API request is triggered by Operator to Provider to cancel the existing freespin.

Operator -> Aggregator -> Provider → Aggregator → Operator

POST /freespins/cancel

Request

Parameter	Type	Mandatory	Description
operator_id	string	Mandatory	Operator id
freespin_id	string	Mandatory	The unique freespin id to cancel.

Response

On success, the response body will be empty with status code 200.

Freespin Win

Freespin win API request is triggered by Provider to Operator to notify the winning of freespin round.

Provider -> Aggregator -> Operator → Aggregator → Provider

POST /freespins/win

Request

Parameter	Type	Mandatory	Description
freespin_id	string	Mandatory	Freespin id
txn_id	string	Mandatory	Transaction id from provider.
user_id	string	Mandatory	The id of user who wins the freespin round.
request_id	string	Optional	request_id works for the scenaro when one user is added to the same freespin for multiple times.
game_id	string	Mandatory	Game id where the freespin win happens.
round_id	string	Optional	Round id of the freespin win round.
currency	string	Mandatory	The currency of freespin win.
amount	string	Mandatory	The amount of freespin win.
timestamp	int	Mandatory	The unix timestmap in milliseconds when the freespin win round happens.

Response

Parameter	Type	Mandatory	Description
txn_id	string	Optional	Transaction id from operator side.
balance	string	Mandatory	User balance updated after the freespin win.
bonus	string	Optional	Bonus updated after the freespin win.
timetsamp	int	Optional	The unix timestmap in milliseconds when the freespin win is processed on operator side.

Services

Aggregator is mainly a message broker between Provider and Operator which converts and forwards the messages which provides the Restful APIs described above. For this, we will setup a web service with go-gin.