Appearance
Operator → hizi.io
This section describes the calls the operator can make to launch games and get information about game status and rounds. The operator must implement getGameURL. The operator uses this call to launch games. All other calls are optional. These calls give the operator more control over games and players. IP whitelisting might apply.
getGameURL - get a game launch URL for a player for a game
The operator uses this call to launch a game for a player. The call returns a URL. Direct the player to this URL (for example, in an iframe). The call creates the necessary sessions and starts the game with the passed parameters. The system accepts the returned URL only once within 60 seconds. If the operator needs a reload, or does not call the URL within 50 seconds, the operator must submit a new getGameURL call.
If the player ID is unknown, the system registers the player with an implicit registerPlayer call. If the operator passes playerdetails, the system updates the record with these values.
The operator can launch the game in three modes.
REAL - a normal real money game. The Operator API debits bets and credits winnings.
DEMO - the game launches in demo (fun) mode. The system makes no calls to the Operator API. The system does not record demo games. playerId is not mandatory. The system generates a temporary user 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. Omit this field if mode=DEMO, unless the operator has a strong reason to persist demo balances. |
| currency | currency | YES | currency used to start the game |
| gameCode | string | YES | ID of the game to start |
| language | language | YES | language to use. Fallbacks might apply if a game does not support the language code. |
| mode | string | YES | mode of the game to use. One of the following: REAL, DEMO, HISTORY |
| gameround | hash | NO mandatory when mode= HISTORY | gameround to replay. Used only when mode=history. Note: only real money gamerounds can be replayed. |
| playerdetails | jsondata | NO | optional additional information about the player. See the registerPlayer call for the structure of this data. |
| profile | string | NO | a set of predefined game parameters. If not present, the system uses default settings. See Appendix C for available profiles. To use multiple profiles, separate them with commas. |
| options | jsondata | NO | additional game settings to use to launch the game. See Appendix C for available settings. These settings override any settings 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. The system passes this reference back in doTransactions 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 for redirecting the player. |
| errorCode | errorCode | NO | If an error occurs, the HTTP status is not 200. The response can include additional error information. |
| isNew | boolean | NO | True if the player was not known before. False if the system updated existing information. Returned only if mode = "REAL" |
| internalPlayerId | string (max 32 characters) | NO | the internal player ID (for reference). Returned only if mode = "REAL" |
Sample 1: start a real money game
This sample starts a real money game. The signature must include the fields 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, using British Pound. Uses the 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
This sample starts a demo money game. The signature must include the fields 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, using British Pound. |
| Sample response (success) | Description |
| { "url": "http://testgame?token=cfc62f2b-45ca-4444-8f62-5e87c5fb5273" } | returns a game URL |
registerPlayer - register a player (optional)
The operator uses this call to register a player in the hizi.io database. This call is optional. If a getGameURL call includes a playerId the system does not know, the system makes this call implicitly. The operator can pass additional data for better statistics and for targeting users with freeplay templates. The system does not link this data to a name. It links the data only to the ID on the operator's side. The operator does not need to submit any data. However, we recommend submitting country, gender, and birthday.
This call is idempotent. The operator can call it multiple times. Each call updates the information linked to the player account with the submitted information.
If freeplay templates are associated with the passed playerdetails, the system grants them to the user when it creates a new record (isNew = true in the response).
Use the getPlayerDetails call to query all stored information.
| 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 to store. 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 the system updated existing information. |
| internalPlayerId | string (max 32 characters) | YES | the internal player ID (for reference) |
| errorCode | errorCode | NO | If an error occurs, the HTTP status is not 200. The response can include additional error information. |
Structure of player details
Pass playerdetails as a one-level JSON object in the following format:
{ "attribute 1": "value", "attribute 2": "value", … }
The operator can pass any attribute name. Use each attribute name only once.
The following attributes are predefined. Use them to store the corresponding information. The operator can use all attributes to target a group of users for freeplays.
| attribute | description | format | sample value |
| displayName | the player's nickname (some games can display this nickname) | string (max 80 characters) | TheBoss |
| country | The player's country of residence. This can have legal implications, depending on the jurisdiction. | countrycode | GB |
| affiliate | code or channel that identifies the affiliate that referred the player. If the operator submits this information, the system can award the player free rounds supported by the game. | string (max 80 characters) | IncomingChannel |
| promotionCode | code that lets the operator grant a bonus to the player. If the operator submits this information, the system can award the player free rounds supported by the game. | string (max 80 characters) | thebestpromoever |
| gender | the player's gender. Accepted values: M (male), F (female), O (other) | string length 1 character (uppercase) | M |
| birthDate | the player's birth date. Format: YYYY-MM-DD | string (length 10 characters) | 1978-05-12 |
| isTestPlayer | true if the operator wants to exclude the player from billing reports | boolean | Optional, default is false |
Sample: register a player with full details
This sample registers a player. The signature must include the fields 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. Submits standard attributes and two custom attributes. |
| Sample response (success) | Description |
| { isNew: true, internalPlayerId: "acfbf7980c4d4add8688c944c9c2a22a" } | The system created a player account because the player was not known before. |
getPlayerDetails - query information linked to a player
The operator uses this call to query all information linked to a player ID submitted by registerPlayer or getGameURL calls. The call also returns whether the player is blocked.
| 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 the system has stored. See here for details. |
| isBlocked | boolean | YES | true if the operator blocked the player in the hizi.io database with a setPlayerBlock call |
| blockReason | string | NO | optional reason for the player block, if the operator passed one in the setPlayerBlock call |
| errorCode | errorCode | NO | If an error occurs, the HTTP status is not 200. The response can include additional error information. |
Sample call to query player details
This sample retrieves player details. The signature must include the fields 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
The operator uses this call to block or unblock a player for all hizi.io games. Use this call when the operator also blocks the player.
Use the getPlayerDetails call to query the status of the player.
| 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 | indicates whether the operator blocks or unblocks the player |
| blockReason | string | NO | optional reason why the operator blocks this player |
| 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 | If an error occurs, the HTTP status is not 200. The response can include additional error information. |
Sample: block a player
This sample blocks a player. The signature must include the fields 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
The operator uses this call to query open gamerounds for a player.
| GET /getOpenGameRounds | query any open real money gamerounds 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 gameround IDs. Use these IDs in the getGameRoundDetails call to retrieve more details. |
getOpenGameRoundsByGame- get open gamerounds by game
The operator uses this call to query open gamerounds for a game code.
| GET /getOpenGameRoundsByGame | query any open real money gamerounds for a game code | ||
| request Parameters (URI parameters) | |||
| attribute | type | mandatory | notes |
| gameCode | string | YES | code that identifies the game (for example, as received from 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 gameround IDs. Use these IDs in the getGameRoundDetails call to retrieve more details. |
getGameRoundDetails - get information for a gameround
The operator uses this call to query open gamerounds for a 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. The system can return this ID from 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 the gameround, including: hash player mode game operator status language currency environment timestamp totalBetAmount totalWinAmount (both amount type, in 1/100 of the base currency) transactions (a list of debits, credits, and voids), as defined in the gameTransaction structure |
getGameRoundReport - get a list of gamerounds for a player / game
The operator uses this call to query open gamerounds for a 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 (for example, as received from getGameList or submitted to getGameURL) |
| daysBack | number | NO | number of days back to retrieve. This parameter defaults to the maximum days stored (7 days). |
| currency | currency | NO | Optional currency to filter for |
| gameRound | hash | NO | Optional gameround hash (or hash prefix) to filter by |
| 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
The operator uses this call to query open gamerounds for a 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, the call returns a URL valid for 10 minutes to display the game result. If false or not present, the call returns 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 operator sets the getURL request parameter to true, the call returns a URL that displays the game result. This URL is valid for only 10 minutes. |
| msg | string | If the operator sets the getURL request parameter to false, or omits it, the call returns HTML code to display the game result. |
| gameCode | string | If the operator sets the getURL request parameter to false, or omits it, the call returns the name of the game for the requested gameround. |
reconcileTransactions - request of replaying a gameround
The operator uses this call to request a replay of all transactions from a gameround. The gameround must already be closed. The system supports only real money gamerounds. The operator receives a doTransactions call with all transactions processed in that gameround in the payload. The submitted hashes are the same as in the original call. Therefore, the doTransactions endpoint must support idempotence for this call. If the gameround is open, the system also closes it automatically.
Note: Use the getGameRoundDetails call to query the status of the gameround. Use the getOpenGameRoundsByGame call to retrieve open rounds per game.
| 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. The system can return this ID from 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 the gameround, including: hash player mode game operator status language currency environment timestamp totalBetAmount totalWinAmount (both amount type, in 1/100 of the base currency) transactions (a list of debits, credits, and voids), as defined in the gameTransaction structure |
| hashesProcessed | array of json objects | YES | array of transaction hashes and the result of processing. The response includes this array even if an error occurs. The system treats transaction hashes not in this list as not processed, and therefore as an error. For details, see here. |
| balance | number | YES | balance returned by the operator, in 1/100 units of the base currency |
| currency | currency | YES | currency of balance |
| mode | string | YES | mode of the round. Only REAL is supported here. |
| errorCode | errorCode | NO | If an error occurs, the HTTP status is not 200. The response can include additional error information. |
voidGameRound - void a debit of a gameround
The operator uses this call to void (revert) a previously submitted debit call. The operator receives a doTransactions call with a void operation for the initial debit. This call fails and returns an error if the gameround is not open, or if the system already processed a credit successfully.
Note: Use the getGameRoundDetails call to query the status of the gameround. Use the getOpenGameRoundsByGame call to retrieve open rounds per game.
| 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. The system can return this ID from 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 | If an error occurs, the HTTP status is not 200. The response can include additional error information. |
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]