Appearance
Data types and definitions
Amounts are always 1/100 of base currency
Every monetary value in this API is an integer expressed as 1/100 of the base currency (a fixed ×100 factor). This includes bets, wins, balances, stakes, and discounts. The API never uses a decimal. For example, the API sends €10.00 as 1000, and €1.50 as 150.
This is a fixed 1/100 convention, not the currency's ISO minor unit. Some currencies have no minor unit (for example JPY, CLP). A few currencies use 1/1000. hizi always expects 1/100 of the base currency. Do not send or expect fractions or decimals. See the amount type below.
Basic types
Basic types are scalar types. Objects use these types.
| type | description | format | sample value |
| string | represents a string value | UTF-8 encoded string | test |
| number | represents a number | any valid number notation with or without decimals | 180.1 |
| amount | a monetary value, always expressed as 1/100 of the base currency. It is an integer, never a fraction or decimal (for example €12.00 = 1200). This is a fixed ×100 factor, not necessarily the currency's ISO minor unit (see the callout above) | a positive integer, 0 or more, no fractions | 1200 |
| currency | ISO 4217 3-letter currency code. See https://en.wikipedia.org/wiki/ISO_4217 | 3 letter string (uppercase) | EUR |
| language | identifies a language. See http://www.lingoes.net/en/translator/langcode.htm | 2 or 5 letter string | en en-US |
| country | an ISO-3166-2 2-letter country code. See https://en.wikipedia.org/wiki/ISO_3166-2 | 2 letter string (uppercase) | GB |
| hash | a UUID (a 128-bit unique identifier) that identifies transactions or other unique values. The API uses hashes to identify gamerounds, transactions, and other unique objects | 128 Bit UUID represented as a 36 character string see https://en.wikipedia.org/wiki/Universally_unique_identifier | 123e4567-e89b-12d3-a456-426655440000 |
| timestamp | an ISO 8601 timestamp. See https://en.wikipedia.org/wiki/ISO_8601. Example: use the following code to generate an ISO string in JavaScript: console.log(new Date().toISOString()); | represented as a string. Always use UTC time | 2020-01-21T14:48:04Z |
| array | an array of any basic or object types | json array notation | [1,2] |
| boolean | represents a binary value | true false "true" "false" | true |
| jsondata | a valid json object | json object notation | { "test": "ok" } |
Object types
The following objects are complex data types used in request and response payloads. Each attribute has a basic type.
playerBalance
This type describes the balance of a player.
| attribute | type | allowed values | mandatory | notes |
| type | string | “real” “bonus” “demo” | YES | |
| amount | amount | a positive integer, 0 or more, no fractions | YES | balance in 1/100 of the base currency, no fractions |
| currency | currency | any 3 character currency code | YES | ISO 4217 3-letter currency code |
| Samples | Description |
| { "type": "real", "amount": 1200, "currency": "EUR" } | sample of a real money balance (12 EUR) |
| { "type": "bonus", "amount": 0, "currency": "EUR" } | sample of a bonus money balance |
gameTransaction
This object describes a transaction linked to a gameround. The request or response body always includes the hash that identifies the gameround.
| attribute | type | allowed values | mandatory | notes |
| type | string | “end” “debit” “credit” “void” | YES | determines the type of the transaction |
| isFirstDebit | boolean | true or false | YES if type = "debit". If the type is not "debit", the operator ignores this field. YES indicates the start of a new gameround | for a debit transaction, this field indicates the first bet needed to start the game |
| amount | amount | a positive integer, 0 or more, no fractions. The amount can be 0 if the operator grants a freeplay | only for debit and credit transactions | the value of the transaction in 1/100 of the base currency |
| discountAmount | amount | Optional discount applied to the amount | Only for debit transactions | The value of the discount in 1/100 of the base currency |
| discountCampaignId | string | Optional campaignId used for a discount | Only for debit transactions | campaignId received in discount information |
| currency | currency | any 3 character currency code | only for debit and credit transactions | the currency of the transaction |
| hash | hash | any valid value | only for debit, credit, and void transactions | identifies a transaction. All calls must be idempotent on this value |
| timestamp | timestamp | any valid value | NO | timestamp of the transaction. The API sends this only when reporting transactions back to the operator |
| reason | string | any valid value | NO | optional reason of this transaction |
| The following attributes apply when the operator uses a freeplay instead of debiting an amount. In that case, the amount attribute is 0. See Appendix D for details of freeplay processing | ||||
| freePlayStake | amount | If the operator uses a freeplay (amount = 0), this value indicates the stake used for that gameround | NO | |
| freePlayUsed | boolean | If the operator uses a freeplay, this value is true | NO | |
| serial | string | Serial of the freeplay package used | NO | Serial used in assignPlayerFreerounds call |
Notes
A transaction always has a type. The type can be any of the following. The gameround hash links multiple transactions.
Allowed transaction types
| value | description | notes |
| debit | a player placed a wager (bet). If isFirstDebit is true, this indicates the start of a new gameround | The operator decides whether to use real or bonus money |
| credit | the operator adds a win to the player's account | |
| void | the operator voids a debit transaction | The operator might receive the void command before the actual debit transaction. In this case, the operator voids the debit transaction. This means no deduction from the player's account. The transaction hash identifies the transaction to void |
| end | the gameround is finished | The API always sends this when the gameround finishes, including after a void transaction |
| Samples | Description |
| { "type": "debit", "isFirstDebit": "true", "amount": 200, "currency": "EUR", "hash": "62848922-da8b-46af-b7b3-7cf10190cd25" } | A gameround starts. The player places an initial wager of 2 EUR. Make this call idempotent. |
| { "type": "debit", "isFirstDebit": "false", "amount": 100, "currency": "EUR", "hash": "39ab89c2-f722-405e-a2e1-c96fedbfd586" } | The player places a continuation bet of 1 EUR. Make this call idempotent. |
| { "type": "credit", "amount": 1000, "currency": "EUR", "hash": "5b1ba0fc-6040-478e-9a19-58bd4786ca23" } | The player wins 10 EUR in that gameround. Make this call idempotent. |
| { "type": "void", "hash": "62848922-da8b-46af-b7b3-7cf10190cd25", "reason": "game had a malfunction" } | The game had a malfunction. The operator voids the debit transaction above. Make this call idempotent. |
| { "type": "end" } | The gameround finishes. The operator closes it. Make this call idempotent. |
| Sample when a freeplay is used | Description |
| { "hash": "9385ec9642034ed89ef974d0fffbdff7", "type": "debit", "isFirstDebit": true, "amount": 0, "currency": "EUR", "freePlayStake": 100, "freePlayUsed": true, "serial": "f089ec54-8e3b-40b0-92c3-e614402f5358" } | The operator uses a free ticket worth 1 EUR instead of a debit |
errorCode
The operator uses this structure to return an error as the result of an API call.
| attribute | type | allowed values | mandatory | notes |
| id | number | ID of error that occurred (0 means no error, a successful operation) | YES | see list of known errors |
| msg | string | optional explanation | NO | The game client does not display this text. Use it to give hints in log files |
| clientmsg | string | optional message to be displayed in game client | NO | The game client displays this message exactly, without further interpretation |
| Samples | Description |
| { "id": 1, "msg": "player id unknown" } | example of an error when the API cannot find a player |
| { "id": 0 } | example of errorCode for no error (a successful operation) |
| { "id": 11, "msg": "betlimit reached", "clientmsg": "You reached your daily betting limit!" } | example of an error when the player reaches the bet limit, with text for the game client to display |
clientMessage
The operator uses this structure to trigger a dialog in the game client. Use it to pass a message about a switch from bonus to real money, to control betting limits, or to show reality checks. Additional flags let the operator interrupt an autoplay.
| attribute | type | content | mandatory | notes |
| title | string | title of the message box | YES | |
| msg | string | message that the game client displays in a message box | YES | |
| buttons | array of jsondata | optional list of buttons to display. See notes for details | NO | If this field is not present, the game client shows a standard "OK" button. This button closes the dialog box without further action |
| stopAutoPlay | boolean | true false | NO | If this field is true, the game client interrupts any running autoplay. The player must resume autoplay manually |
Structure of button data in a client message
Use the following object to define buttons for a client message box.
| attribute | type | allowed values | mandatory | notes |
| label | string | text on button | YES | |
| url | string | URL that the game client calls when the player clicks the button | NO | If this field is not present, the button just closes the box |
| Sample | Description |
| { "title": "Reality check", "msg": "You are now playing for 60 minutes, do you want to continue ?", "stopAutoPlay": true, "buttons": [ { "label": "Yes" }, { "label": "No", "url": "http://gotolobby" } ] } | Displays a reality check message box. Stops autoplay. Gives the player a choice to continue or exit. |
tickets
The API uses this structure to return information about tickets and freeplays available to a player. See Appendix D for details on freeplays.
| attribute | type | allowed values | mandatory | notes |
| serial | string | Serial assign to this package | YES | Unique for each operator |
| stake | amount | a positive integer greater than 0, no fractions | YES | Stake for which the freeplay is valid |
| currency | currency | any 3 character currency code | YES | Currency for which the freeplay is valid |
| availableTickets | number | a positive integer greater than 0 | YES | Number of freeplays available |
| Samples | Description |
| { "serial": "unique-value", "currency": "EUR", "stake": 100, "availableTickets": 4 } | 4 tickets with a stake of 1 EUR available |
| { "serial": "dbf8907c-8002-4bdc-8804-3b1ec00d21be", "currency": "EUR", "stake": 500, "availableTickets": 1 } | One ticket with a stake of 5 EUR available |