Operator → hizi.io
This section describes calls the operator can make to launch games and get information of game status / rounds. The only call that has to be implemented is getGameURL as this is used to launch games. All other calls are optional to use but enable a greater control over control of games and players to the operator. Please note that IP whitelisting might be in place.
getGameURL - get a game launch URL for a player for a game
This call is used to launch a game for a player. It returns a URL to which the player should be directed (e.g. in an iframe). It creates the necessary sessions and starts the game with the passed parameters. The URL returned call only be called once within 60 seconds, if a reload has to be made or the URL is not called in 50 seconds, a new getGameURL call has to be submitted.
If the player ID is unknown it will be registered with an implicit registerPlayer call. If playerdetails are passed the appropriate record will be updated with these values.
Game can be launched in three modes
REAL - a normal real money game, operator API will be used to debit bets and credit winnings.
DEMO - game will be launched in demo (fun) mode. No calls to operator API will be made, demo games will not be recorded. playerId is not mandatory as a temporary user will be generated for demo games.
| POST /getGameURL | get a URL to launch a game | ||
| request Parameters (json payload) | |||
| attribute | type | mandatory | notes |
| playerId | string | YES for mode= REAL or mode= HISTORY NO if mode= DEMO | ID that identifies the player at the operator site, SHOULD be omitted if mode=DEMO unless there is a strong reason to persist demo balances. |
| currency | currency | YES | currency for which the game should be started |
| gameCode | string | YES | the gameid of the game to be started |
| language | language | YES | language that should be used, note that fallbacks might apply if the language code is not supported by a game. |
| mode | string | YES | mode of the game that should be used, one of the following: REAL DEMO HISTORY |
| gameround | hash | NO mandatory when mode= HISTORY | gameround to replay, only used when mode=history Note that only real money gamerounds can be replayed! |
| playerdetails | jsondata | NO | optional additional player information, refer to registerPlayer call for structure of this data |
| profile | string | NO | a set of predefined game parameters, if not present default settings will be used. See Appendix C for available profiles. Multiple profiles can be used by comma separating them |
| options | jsondata | NO | additional game settings that should be used to launch the game, see Appendix C for available settings. These override any settings which might be defined in the profile. |
| variables | jsondata | NO | Optional game variables. For a list of allowed variables see Appendix C |
| externalSessionId | string | NO | Optional reference to a session which will be proxied / passed back in doTransactions and and getBalance calls |
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + playerId (if present) + currency + gameCode + mode | |||
| mandatory request header fields | |||
| X-H-AUTH-ID, X-H-AUTH-SIG, X-H-TIMESTAMP | |||
| returned attributes | |||
| attribute | type | mandatory | notes |
| url | string | YES | URL to which the user should be redirected. |
| errorCode | errorCode | NO | in case an error occurred HTTP status should not be 200 and an additional error information can be returned |
| isNew | boolean | NO | true if the player was not known before, false if information was updated, only returned if mode = "REAL" |
| internalPlayerId | string (max 32 characters) | NO | the internal playerid (for reference), only returned if mode = "REAL" |
Sample 1: start a real money game
Start a real money game. Fields that have to be included in the signature are highlighted in red.
| Sample call to start a real money game | Description |
| POST /getGameURL | start a real money game |
| Sample payload | Description |
| { "playerId": "sampleplayer", "currency": "GBP", "gameCode": "testgame", "language": "en", "mode": "real", "playerdetails": { "country": "GB" }, "profile": "jurisidiction-de,customProfileName", "options": { "homeURL": "https://myhome.com/example" } } | starts a real money game in English language and currency British Pound using jurisdiction setting for germany and a custom Profile created earlier. Passes a home URL |
| Sample response (success) | Description |
| { "url": "http://testgame?token=f264e73f-5aa4-4858-bf6e-3d02bcfa5e2d" } | returns a game URL |
Sample 2: start a demo game
Start a demo money game. Fields that have to be included in the signature are highlighted in red.
| Sample call to start a demo game | Description |
| POST /getGameURL | start a demo money game |
| Sample payload | Description |
| { "currency": "GBP", "gameCode": "testgame", "language": "en", "mode": "demo" } | starts a demo game in English language and currency British Pound. |
| Sample response (success) | Description |
| { "url": "http://testgame?token=cfc62f2b-45ca-4444-8f62-5e87c5fb5273" } | returns a game URL |
registerPlayer - register a player (optional)
This call is used to register a player within the hizi.io database. This call is optional as if a playerId is received in a getGameURL call which is not known this call will be made implicit. You may pass additional data to get better statistics and targeting of users for granting free play templates. Note that all data is not linked to a name , just to the ID on the operator's side. It is not necessary to submit any data, however we recommend to submit country, gender and birthday.
This call is idempotent and can therefore be called multiple times, where the information linked to the player account will always be updated with the submitted information.
If any free play templates are associated with any of the playerdetails passed they will be granted to the user if a new record was created (isNew = true) on return.
All stored information can be queried by using the getPlayerDetails call
| POST /registerPlayer | register a player with the hizi.io database | ||
| request Parameters (json payload) | |||
| attribute | type | mandatory | notes |
| playerId | string | YES | ID that identifies the player at the operator site |
| playerdetails | jsondata | NO | player information that should be stored,see here for details |
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + playerId | |||
| mandatory request header fields | |||
| X-H-AUTH-ID, X-H-AUTH-SIG, X-H-TIMESTAMP | |||
| returned attributes | |||
| attribute | type | mandatory | notes |
| isNew | boolean | YES | true if the player was not known before, false if information was updated |
| internalPlayerId | string (max 32 characters) | YES | the internal playerid (for reference) |
| errorCode | errorCode | NO | in case an error occurred HTTP status should not be 200 and an additional error information can be returned |
Structure of player details
Playerdetails can be passed as a one level JSON object following the format
{ "attribute 1": "value", "attribute 2": "value", … }
As attribute any value can be passed, make sure that every attribute is used only once.
The following attributes are predefined and should be used if according information should be stored. All attributes can be used to target a group of users to grant free plays.
| attribute | description | format | sample value |
| displayName | player’s nickname (could be displayed in some games) | string (max 80 characters) | TheBoss |
| country | The country of residence of the player, this might have some implications according to legislation. | countrycode | GB |
| affiliate | code/channel identifying the affiliate from which the player is coming from. By submitting that information players can be awarded free rounds which are supported by the games | string (max 80 characters) | IncomingChannel |
| promotionCode | code allowing operator to grant bonus to player. By submitting that information players can be awarded free rounds which are supported by the games | string (max 80 characters) | thebestpromoever |
| gender | player’s gender. Accepted values: M (male), F (female), O (other) | string length 1 character (uppercase) | M |
| birthDate | player’s birthdate. Format YYYY-MM-DD | string (length 10 characters) | 1978-05-12 |
| isTestPlayer | True when player should be excluded from billing reports | boolean | Optional, default is false |
Sample: register a player with full details
Registers a player. Fields that have to be included in the signature are marked in red.
| Sample call for registering a player | Description |
| POST /registerPlayer | registers a player |
| Sample payload | Description |
| { "playerId": "sampleplayer", "playerdetails": { "displayName": "TheBoss", "country": "GB", "affilate": "Affilate No. 1", "promotionCode": "promonewyear2020", "gender": "F", "birthDate": "1985-05-10", "custom Attribute 1": "some information", "custom Attribute 2": "other information" } } | registers a player and submits some standard attributes along with 2 custom ones |
| Sample response (success) | Description |
| { isNew: true } | player account was created as the player was not know before |
getPlayerDetails - query information linked to a player
This call is used to query all information linked to a player id submitted by registerPlayer or getGameURL calls. Also returns if the player is blocked or not.
| GET /getPlayerDetails | query stored player details | ||
| request Parameters (URI parameters) | |||
| attribute | type | mandatory | notes |
| playerId | string | YES | ID that identifies the player at the operator site |
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + playerId | |||
| mandatory request header fields | |||
| X-H-AUTH-ID, X-H-AUTH-SIG, X-H-TIMESTAMP | |||
| returned attributes | |||
| attribute | type | mandatory | notes |
| playerdetails | jsondata | YES | player information that is stored,see here for details |
| isBlocked | boolean | YES | true if the player is blocked in the hizi.io database via a setPlayerBlock call |
| blockReason | string | NO | holds an optional reason for the player block if that was passed in a setPlayerBlock call |
| errorCode | errorCode | NO | in case an error occurred HTTP status should not be 200 and an additional error information can be returned |
Sample call to query player details
Retrieves player details. Fields that have to be included in the signature are highlighted in red.
| Sample call to query a players details | Description |
| **GET /getPlayerDetails?playerId=**sampleplayer | Ask for stored player details |
| Sample response (success) | Description |
| { "isBlocked": false, "playerdetails": { "displayName": "TheBoss", "country": "GB", "affilate": "Affilate No. 1", "promotionCode": "promonewyear2020", "gender": "F", "birthDate": "1985-05-10", "custom Attribute 1": "some information", "custom Attribute 2": "other information" } } | Returns player details |
setPlayerBlock - block or unblock a player
This call is used to block or unblock a player for all hizi.io games. Use of this call is recommended when a player is also blocked by the operator.
The status of the player can be queried by using the getPlayerDetails call
| POST /setPlayerBlock | block or unblock a player | ||
| request Parameters (json payload) | |||
| attribute | type | mandatory | notes |
| playerId | string | YES | ID that identifies the player at the operator site |
| isBlocked | boolean | YES | indicating whether a player should be blocked or unblocked. |
| blockReason | string | NO | optional a reason why this player is blocked |
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + playerId | |||
| mandatory request header fields | |||
| X-H-AUTH-ID, X-H-AUTH-SIG, X-H-TIMESTAMP | |||
| returned attributes | |||
| attribute | type | mandatory | notes |
| errorCode | errorCode | NO | in case an error occurred HTTP status should not be 200 and an additional error information can be returned |
Sample: block a player
Blocks a player. Fields that have to be included in the signature are highlighted in red.
| Sample call for blocking a player | Description |
| POST /setPlayerBlock | blocks a player |
| Sample payload | Description |
| { "playerId": "sampleplayer", "isBlocked": true, "blockReason": "Credit card fraud" } | blocks a player and sets a reason |
| Sample response (success) | Description |
| { } | empty response |
getOpenGameRounds - get open gamerounds for a player
This call is used to query open gamerounds for a given player.
| GET /getOpenGameRounds | query any open real money game rounds for a player | ||
| request Parameters (URI parameters) | |||
| attribute | type | mandatory | notes |
| playerId | string | YES | ID that identifies the player at the operator site |
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + playerId | |||
| mandatory request header fields | |||
| X-H-AUTH-ID, X-H-AUTH-SIG, X-H-TIMESTAMP | |||
| returned attributes | |||
| attribute | type | mandatory | notes |
| gameRoundList | array of gameround hashes | YES | list of open gamerounds ids, these can be used in getGameRoundDetails call to retrieve further details |
getOpenGameRoundsByGame- get open gamerounds by game
This call is used to query open game rounds for a given game code.
| GET /getOpenGameRoundsByGame | query any open real money game rounds for a game code | ||
| request Parameters (URI parameters) | |||
| attribute | type | mandatory | notes |
| gameCode | string | YES | code that identifies the game (as e.g. received by getGameList or submitted to getGameURL ) |
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + gameCode | |||
| mandatory request header fields | |||
| X-H-AUTH-ID, X-H-AUTH-SIG, X-H-TIMESTAMP | |||
| returned attributes | |||
| attribute | type | mandatory | notes |
| gameRoundList | array of gameround hashes | YES | list of open gamerounds ids, these can be used in getGameRoundDetails call to retrieve further details |
getGameRoundDetails - get information for a gameround
This call is used to query open game rounds for a given player.
| GET /getGameRoundDetails | query gameround details | ||
| request Parameters (URI parameters) | |||
| attribute | type | mandatory | notes |
| playerId | string | YES | ID that identifies the player at the operator site |
| gameRound | hash | YES | ID (hash) that identifies the gameround, as returned e.g. could be getOpenGameRounds or getGameRoundReport |
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + playerId + gameRound | |||
| mandatory request header fields | |||
| X-H-AUTH-ID, X-H-AUTH-SIG, X-H-TIMESTAMP | |||
| returned attributes | |||
| attribute | type | mandatory | notes |
| gameRound | JSON Data | YES | details of gameround including hash player mode game operator status language currency environment timestamp totalBetAmount totalWinAmount transactions (= list of debit / credits / voids) as defined in gameTransaction structure |
getGameRoundReport - get a list of gamerounds for a player / game
This call is used to query open gamerounds for a given player.
| GET /getGameRoundReport | get a list of real money gamerounds for a player / game | ||
| request Parameters (URI parameters) | |||
| attribute | type | mandatory | notes |
| playerId | string | YES | ID that identifies the player at the operator site |
| gameCode | string | YES | code that identifies the game (as e.g. received by getGameList or submitted to getGameURL ) |
| daysBack | number | NO | number of days back which should be retrieved, this parameter defaults to the maximum days stored (7 days) |
| currency | currency | NO | Optional currency to filter for |
| gameRound | hash | NO | Optional gameround hash(prefix) to filter for |
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + playerId + gameCode | |||
| mandatory request header fields | |||
| X-H-AUTH-ID, X-H-AUTH-SIG, X-H-TIMESTAMP | |||
| returned attributes | |||
| attribute | type | mandatory | notes |
| gameRounds | array of JSON Data | YES | array of records that identify a gameround hash mode game status timestamp bet win |
getGameRoundResult - get a HTML representation of a result of a gameround
This call is used to query open gamerounds for a given player.
| GET /getGameRoundResult | get a HTML representation of a game result | |
| request Parameters (URI parameters) | ||
| attribute | type | notes |
| playerId | string | ID that identifies the player at the operator site |
| gameRound | hash | gameround hash to get data for |
| getURL | boolean | If true return a URL valid for 10 minutes to display the gameresult, if false or not present return HTML code |
| fields to sign (order is important) | ||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + playerId + gameRound | ||
| mandatory request header fields | ||
| X-H-AUTH-ID, X-H-AUTH-SIG, X-H-TIMESTAMP | ||
| returned attributes | ||
| attribute | type | notes |
| resultURL | string | If the getURL request parameter is set to true, return a URL which displays the game result. This URL is only valid for 10 minutes |
| msg | string | If the getURL request parameter is set to false or not existing, returns HTML code which can be used to display the HTML code |
| gameCode | string | If the getURL request parameter is set to false or not existing, returns the name of the game of the requested gameround |
reconcileTransactions - request of replaying a gameround
This call is used to request a replay of all transactions from a gameround. The gameround has to be closed already and only real money game rounds are supported. The operator will receive a doTransactions call with all transactions processed in that game round in the payload. Hashes submitted will be the same as with the original call, so the doTransactions endpoint has to support idempotence on this call. If the gameround is open they will also be automatically closed.
Note: The status of the game round can be queried by using the getGameRoundDetails call. Open rounds per game could be retrieved by the getOpenGameRoundsByGame call.
| POST /reconcileTransactions | request resending of all transactions of a closed real money gameround | ||
| request Parameters (json payload) | |||
| attribute | type | mandatory | notes |
| gameRound | hash | YES | ID (hash) that identifies the gameround, as returned e.g. be getOpenGameRounds or getGameRoundReport |
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + gameRound | |||
| mandatory request header fields | |||
| X-H-AUTH-ID, X-H-AUTH-SIG, X-H-TIMESTAMP | |||
| returned attributes | |||
| attribute | type | mandatory | notes |
| gameRound | JSON Data | YES | details of gameround including hash player mode game operator status language currency environment timestamp totalBetAmount totalWinAmount transactions (= list of debit / credits / voids) as defined in gameTransaction structure |
| hashesProcessed | array of json objects | YES | array of transaction hashes and the result of processing. This should also be returned in case an error occurred. Transaction hashes not in that list will be assumed to not processed and therefore be treated as an error. For details see here. |
| balance | number | YES | balance returned by operator in 1/100 units of base currency |
| currency | currency | YES | currency of balance |
| mode | string | YES | mode of round (only REAL supported here) |
| errorCode | errorCode | NO | in case an error occurred HTTP status should not be 200 and additional error information can be returned |
voidGameRound - void a debit of a gameround
This call is used to void (revert) a previously submitted debit call. The operator will receive a doTransactions call with a void operation for the initial debit. Note this call won’t work if the gameround is not open or any credit was already processed successfully and return an error.
Note: The status of the game round can be queried by using the getGameRoundDetails call. Open rounds per game could be retrieved by the getOpenGameRoundsByGame call.
| POST /voidGameRound | Request voiding the initial debit of a gameround | ||
| request Parameters (json payload) | |||
| attribute | type | mandatory | notes |
| gameRound | hash | YES | ID (hash) that identifies the gameround, as returned e.g. be getOpenGameRounds or getGameRoundReport |
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + gameRound | |||
| mandatory request header fields | |||
| X-H-AUTH-ID, X-H-AUTH-SIG, X-H-TIMESTAMP | |||
| returned attributes | |||
| attribute | type | mandatory | notes |
| errorCode | errorCode | NO | in case an error occurred HTTP status should not be 200 and additional error information can be returned |
getGameHealth ping / availability of game
[WORK IN PROGRESS - CONTACT SUPPORT FOR DETAILS]
getGameRoundState for given player / game / currency (or session)
[WORK IN PROGRESS - CONTACT SUPPORT FOR DETAILS]
forceCloseGameRound for a given gameRound
[WORK IN PROGRESS - CONTACT SUPPORT FOR DETAILS]