Appendix D - Free plays
Basics
These calls allow operators to grant freeplays to a player. A freeplay can be considered as a free spin in slot games. This feature has to be enabled for the operator account. Please contact customer support if you want to make sure if that feature is enabled.
Freeplays are granted for a specific game and stake (amount and currency). An expiry date can be set, after the granted freeplays will not be available. Each time a package should be granted to a player, the operator has to provide a unique serial for this package. Calls with the same serial are idempotent, meaning that no information linked to that serial will be changed / assigned twice by repeated assignPlayerFreerounds calls with the same serial.
Please note that you will receive additional information in doTransactions call when a free play is used by a player. No further changes on the operator side are necessary when freeplays are used except accepting debit transactions with an amount of zero and a serial known to the operator and used in assignPlayerFreerounds before.
assignPlayerFreerounds - assign a package of freeplays to a player
This call is sent from the operator to hizi.io to grant a number of freeplays for a given stake and game to a player
| POST /assignPlayerFreerounds | Assign a package of freeplays for a game / stake to a player | ||
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + playerId + gameCode + serial + currency + stake + count | |||
| mandatory request header fields | |||
| X-H-AUTH-ID, X-H-AUTH-SIG, X-H-TIMESTAMP | |||
| request Parameters (json payload) | |||
| attribute | type | mandatory | notes |
| playerId | string | YES | ID that identifies the player at the operator site |
| gameCode | string | YES | the gameid of the game for which the freeplays should be granted |
| serial | string | YES | A unique identifier for this package. This call is redundant on this parameter. The operator has to take care of generating a unique serial, recommended is the usage of a UUID. If freeplay will be used in later debit transactions, this serial will be sent as reference. |
| currency | currency | YES | currency for which the freeplay should be granted |
| stake | amount | YES | Stake in game for which the freeplay should be granted |
| count | number | YES | Count of freeplays to be granted within this package |
| expires | timestamp | NO | If set freeplay will expire after that date, if not set will default to an expiry date of 180 days after submitting the call |
| returned attributes | |||
| attribute | type | mandatory | notes |
| serial | string | YES | Serial of the package created (same as passed by operator) |
| 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 grant a freeplay package
| Sample call grant a freeplay package | Description |
| POST /assignPlayerFreerounds | Assign a package of freeplays |
| Sample payload | Description |
| { "playerId": "141ad0ffab554ba8b9022db6dfdc05ad", "gameCode": "game-oddoreven", "serial": "unique-value", "currency": "EUR", "stake": "100", "count": "4", "expires": "2020-12-07T00:00:00Z" } | We create 4 freeplay which should not be valid after 7-Dec-2020 Fields that have to be included in the signature are red! |
| Sample response (success) | Description |
| { "serial": "unique-value", "internalid": "4596dbe02be2483598f261b7f8c853cd", "count": 4, "used": 0, "expires": "2020-12-07T00:00:00.000Z" } | Information of package created |
revokePlayerFreerounds - delete freeplays from a player
This call is sent from the operator to hizi.io to revoke (delete) previously granted freeplay packages. This call is idempotent and will always return the same result when transmitted more than once.
| POST /revokePlayerFreerounds | revoke a package of freeplays granted to a player | ||
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + playerId + gameCode + serial | |||
| mandatory request header fields | |||
| X-H-AUTH-ID, X-H-AUTH-SIG, X-H-TIMESTAMP | |||
| request Parameters (json payload) | |||
| attribute | type | mandatory | notes |
| playerId | string | YES | ID that identifies the player at the operator site |
| gameCode | string | YES | the gameid of the game for which the freeplay were granted, has to be supplied to ensure correct information is transmitted |
| serial | string | YES | A unique identifier for this package. This serial must have been used in a previous assignPlayerFreerounds call with the same gameCode and playerId |
| returned attributes | |||
| attribute | type | mandatory | notes |
| serialRevoked | string | YES | Serial that was revoked (must be the same as the serial passed in the body of this 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 revoke a freeplay package
| Sample call | Description |
| POST /revokePlayerFreerounds | Revoke a previously granted package of freeplays |
| Sample payload | Description |
| { "playerId": "141ad0ffab554ba8b9022db6dfdc05ad", "gameCode": "game-oddoreven", "serial": "dbf8907c-8002-4bdc-8804-3b1ec00d21be" } | We revoke a package with the given information |
| Sample response (success) | Description |
| { "serialRevoked": "dbf8907c-8002-4bdc-8804-3b1ec00d21be" } | The package was revoked |
getPlayerFreerounds - query freeplays granted to a player
This call is sent from the operator to hizi.io to query available free play packages. Packages used or expired will not be reported.
| GET /getPlayerFreerounds | Query freeplay packages | ||
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + playerId + gameCode + currency | |||
| mandatory request header fields | |||
| X-H-AUTH-ID, X-H-AUTH-SIG, X-H-TIMESTAMP | |||
| request Parameters (URI parameters) | |||
| attribute | type | mandatory | notes |
| playerId | string | YES | ID that identifies the player at the operator site |
| gameCode | string | YES | the gameid of the game for which the freeplays should be queried |
| currency | currency | YES | currency for which the freeplays should be queried |
| returned attributes | |||
| attribute | type | mandatory | notes |
| tickets | Array of ticket structure | YES | Returns available packages with serial, currency, stake and count information |
| 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 available freeplay packages
| Sample call | Description |
| GET /getPlayerFreerounds?playerId=141ad0ffab554ba8b9022db6dfdc05ad&gameCode=game-oddoreven¤cy=EUR | queries freeplays available for a game/player/currency |
| Sample response (success) | Description |
| { "tickets": [ { "serial": "unique-value", "currency": "EUR", "stake": 100, "availableTickets": 4 }, { "serial": "959e3491-4d90-429b-be21-d5bde520982c", "currency": "EUR", "stake": 100, "availableTickets": 2 }, { "serial": "dbf8907c-8002-4bdc-8804-3b1ec00d21be", "currency": "EUR", "stake": 500, "availableTickets": 1 } ] } | Three packages are returned, two for a stake of 100 (= 1 EUR) and one for a stake of 5 EUR. Which totals in 6 freeplays available for spins with a stake of 1 EUR and 1 freeplay available with a stake of 5 EUR |
registerFreeroundTemplate
[WORK IN PROGRESS - CONTACT SUPPORT FOR DETAILS]
getFreeroundTemplate
[WORK IN PROGRESS - CONTACT SUPPORT FOR DETAILS]
removeFreeroundTemplate
[WORK IN PROGRESS - CONTACT SUPPORT FOR DETAILS]