Data types and definitions
Basic types
Basic types are scalar types which are used in objects.
| type | description | format | sample value |
| string | representing a string value | UTF-8 encoded string | test |
| number | representing a number | any valid number notation with or without decimals | 180.1 |
| amount | a value representing a “money” value, always given in 1/100 units of base currency without fractions | any positive (greater or equal 0) integer value, 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 | a ISO-3166-2 2 letter country code, see https://en.wikipedia.org/wiki/ISO_3166-2 | 2 letter string (uppercase) | GB |
| hash | UUID identifying transactions or other unique values Hashes are used 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 | ISO_8601 timestamp see https://en.wikipedia.org/wiki/ISO_8601 as an example you can use the following to generate an ISO string in javascript: console.log(new Date().toISOString()); | represented as string it is recommended to always use UTC time | 2020-01-21T14:48:04Z |
| array | an array of any basic or object types | json array notation | [1,2] |
| boolean | indicating a binary value | true false "true" "false" | true |
| jsondata | a valid json object | json object notation | { "test": "ok" } |
Object types
The following objects complex data type which are used in request and/or response payloads. Attributes have 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 | any positive (greater or equal 0) integer value, no fractions | YES | balance in 1/100 units of base currency without 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 hash identifying the gameround will always be included in either the request or response body.
| attribute | type | allowed values | mandatory | notes |
| type | string | “end” “debit” “credit” “void” | YES | determines type of transaction |
| isFirstDebit | boolean | true or false | YES if type = "debit", if sent with other types should be ignored. If YES is received this indicates the start of a new gameround | in case of a debit transaction this indicates the first bet that is needed to start the game |
| amount | amount | any positive (greater or equal 0) integer value, no fractions Amount can be 0 if a granted freeplay is used. | only for debit and credit transactions | the value of the transaction in 1/100 of the base currency |
| discountAmount | amount | Optional discount to be applied to amount | Only for debit transactions | The value of the discount in 1/100 of the base currency |
| discountCampaignId | string | Optional campaignId to be 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 the transaction is be performed in |
| hash | hash | any valid value | only for debit credit and void transactions | identifies a transaction, all calls have to be idempotent on this value |
| timestamp | timestamp | any valid value | NO | timestamp of the transaction, only transmitted in reporting transactions back to operator |
| reason | string | any valid value | NO | optional reason of this transaction |
| T**he following attributes are used when a freeplay is consumed instead of an amount to be debited. In that case the amount attribute is set to 0. See Appendix D**for details of freeplay processing | ||||
| freePlayStake | amount | If a freeplay is used (amount = 0) this value indicates the stake used for that gameround | NO | |
| freePlayUsed | boolean | If a freeplay is used this value is set to “true” | NO | |
| serial | string | Serial of the freeplay package used | NO | Serial used in assignPlayerFreerounds call |
Notes
A transaction always has a type which can be any of the following. Multiple transactions can be linked using the gameround hash.
The following transaction types are allowed
| value | description | notes |
| debit | a player placed a wager (bet), if isFirstDebit is set to true this indicates the start of a new gameround | It is the operator responsibility to determine if real or bonus money should be used. |
| credit | a winning should be added to the players account | |
| void | a debit transaction should be voided | please note that the void command might be received before the actual debit transaction is received, in this case the debit should be voided (that means no deduction from the players account). The transaction to be voided is identified by the transaction hash |
| end | the gameround is finished | this will always be sent when the gameround is finished (also in case of a void transaction). |
| Samples | Description |
| { "type": "debit", "isFirstDebit": "true", "amount": 200, "currency": "EUR", "hash": "62848922-da8b-46af-b7b3-7cf10190cd25" } | a gameround is started. user placed an initial wager of 2 EUR. Call should be idempotent. |
| { "type": "debit", "isFirstDebit": "false", "amount": 100, "currency": "EUR", "hash": "39ab89c2-f722-405e-a2e1-c96fedbfd586" } | user placed a continuation bet of 1 EUR. Call should be idempotent. |
| { "type": "credit", "amount": 1000, "currency": "EUR", "hash": "5b1ba0fc-6040-478e-9a19-58bd4786ca23" } | user won 10 EUR in that gameround. Call should be idempotent. |
| { "type": "void", "hash": "62848922-da8b-46af-b7b3-7cf10190cd25", "reason": "game had a malfunction" } | the game had a malfunction, so the debit transaction above should be voided. Call should be idempotent. |
| { "type": "end" } | the gameround is finished, should be closed. Call should be 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" } | Instead of a debit a free ticket with a value of 1 EUR is used |
errorCode
This structure is used to return an error as result to an API call.
| attribute | type | allowed values | mandatory | notes |
| id | number | ID of error that occurred (0 represents no error / successful operation) | YES | see list of known errors |
| msg | string | optional explanation | NO | not displayed in client, useful to give hints in log files. |
| clientmsg | string | optional message to be displayed in game client | NO | this message will be displayed without further interpretation in game client |
| Samples | Description |
| { "id": 1, "msg": "player id unknown" } | sample of an error when a player was not found |
| { "id": 0 } | sample of errorCode meaning no error (successful operation). |
| { "id": 11, "msg": "betlimit reached", "clientmsg": "You reached your daily betting limit!" } | sample of an error when bet limit was reached with a text that should be displayed in game client. |
clientMessage
This structure is used to trigger a dialog that should be rendered in the game client. This could be used to pass a message about a switch from bonus to real money usage or to control betting limits or reality checks. Additional flags allow the operator to interrupt any autoplays.
| attribute | type | content | mandatory | notes |
| title | string | title of the message box | YES | |
| msg | string | message to be displayed in a message box in game client | YES | |
| buttons | array of jsondata | optional list of buttons that should be displayed see notes for details | NO | If not present a standard "OK" button which closes the dialog box without any action will be shown |
| stopAutoPlay | boolean | true false | NO | if present and set to true any running autoplay features will be interrupted and have to be resumed by player manually |
Structure of button data in a client message
The following object is used to define buttons to be displayed in a client message box.
| attribute | type | allowed values | mandatory | notes |
| label | string | text on button | YES | |
| url | string | URL to be called when button is clicked | NO | if not present 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 player choice to continue or exit. |
tickets
This structure is used to return information of tickets and/or freeplays which are assigned / available for a player. See Appendix D for details of freeplays
| attribute | type | allowed values | mandatory | notes |
| serial | string | Serial assign to this package | YES | Unique for each operator |
| stake | amount | any positive non zero, 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 | Positive non zero integer | 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 |