Appearance
Appendix D - Freeplays
Basics
These calls allow the operator to grant freeplays to a player. A freeplay is like a free spin in slot games. The operator account must have this feature enabled. Contact customer support to check if the feature is enabled.
The operator grants freeplays for a specific game and stake (amount and currency). The operator can set an expiry date. After this date, the granted freeplays are not available. Each time the operator grants a package to a player, the operator must provide a unique serial for the package. Calls with the same serial are idempotent. This means repeated assignPlayerFreerounds calls with the same serial do not change or assign information linked to that serial twice.
When a player uses a freeplay, the doTransactions call includes additional information. The operator side needs no further changes when a player uses freeplays. The operator must accept debit transactions with an amount of zero and a serial. This serial must be known to the operator from a previous assignPlayerFreerounds call.
assignPlayerFreerounds - assign a package of freeplays to a player
The operator sends this call to hizi.io to grant freeplays for a given stake and game to a player.
| POST /assignPlayerFreerounds | Assign a package of freeplays for a game and 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 game ID of the game for which the operator grants the freeplays |
| serial | string | YES | A unique identifier for this package. This call is idempotent for this parameter. The operator must generate a unique serial. The operator should use a UUID. If the player uses the freeplay in a later debit transaction, hizi.io sends this serial as a reference. |
| currency | currency | YES | Currency for which the operator grants the freeplay |
| stake | amount | YES | Stake in the game for which the operator grants the freeplay |
| count | number | YES | Number of freeplays that the operator grants in this package |
| expires | timestamp | NO | If set, the freeplay expires after this date. If not set, the expiry date defaults to 180 days after the call. |
| returned attributes | |||
| attribute | type | mandatory | notes |
| serial | string | YES | Serial of the created package (the same value the operator passed) |
| errorCode | errorCode | NO | If an error occurs, the HTTP status is not 200. hizi.io can return additional error information. |
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" } | This call creates 4 freeplays. They are not valid after 7-Dec-2020. The signature must include the fields shown in red. |
| Sample response (success) | Description |
| { "serial": "unique-value", "internalid": "4596dbe02be2483598f261b7f8c853cd", "count": 4, "used": 0, "expires": "2020-12-07T00:00:00.000Z" } | Information about the created package |
revokePlayerFreerounds - delete freeplays from a player
The operator sends this call to hizi.io to revoke (delete) previously granted freeplay packages. This call is idempotent. It always returns the same result when the operator sends it 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 game ID of the game for which the operator granted the freeplay. The operator must supply this ID so hizi.io transmits the correct information. |
| serial | string | YES | A unique identifier for this package. The operator must have used this serial in a previous assignPlayerFreerounds call with the same gameCode and playerId. |
| returned attributes | |||
| attribute | type | mandatory | notes |
| serialRevoked | string | YES | Serial that hizi.io revoked (the same serial the operator passed in the body of this call) |
| errorCode | errorCode | NO | If an error occurs, the HTTP status is not 200. hizi.io can return additional error information. |
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" } | This call revokes a package with the given information |
| Sample response (success) | Description |
| { "serialRevoked": "dbf8907c-8002-4bdc-8804-3b1ec00d21be" } | hizi.io revoked the package |
getPlayerFreerounds - query freeplays granted to a player
The operator sends this call to hizi.io to query available freeplay packages. hizi.io does not report used or expired packages.
| 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 game ID of the game for which the operator queries the freeplays |
| currency | currency | YES | Currency for which the operator queries the freeplays |
| returned attributes | |||
| attribute | type | mandatory | notes |
| tickets | Array of ticket structure | YES | Returns the available packages, with serial, currency, stake, and count for each |
| errorCode | errorCode | NO | If an error occurs, the HTTP status is not 200. hizi.io can return additional error information. |
Sample call to query available freeplay packages
| Sample call | Description |
| GET /getPlayerFreerounds?playerId=141ad0ffab554ba8b9022db6dfdc05ad&gameCode=game-oddoreven¤cy=EUR | Queries the freeplays available for a game, player, and 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 } ] } | hizi.io returns three packages. Two packages have a stake of 100 (1 EUR). One package has a stake of 5 EUR. In total, 6 freeplays are available for spins with a stake of 1 EUR. 1 freeplay is available for spins 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]