Appearance
hizi.io -> Operator
This section describes the calls that the hizi.io backend can make to the operator backend. IP whitelisting might apply.
Amounts are always 1/100 of base currency
Every amount you receive (debits, credits) is an integer. Every balance you return here is also an integer. Each integer represents 1/100 of the base currency (a fixed x100 factor). It is never a decimal. For example, a debit amount of 200 is EUR 2.00. A returned balance of 12000 is EUR 120.00.
This is a fixed 1/100 convention. It is not the currency's ISO minor unit. For example, JPY and CLP have no minor unit. A few other 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.
getBalance - get a player’s balance
This call queries a player's balance at the operator. The operator may return two balances: real and bonus. Returning a bonus balance is optional. Some legislation requires it. If the operator returns a bonus balance, it must also return the attribute "useBonusFirst". The game frontend uses this attribute to show the use of bonus or real money, when legislation requires this.
| GET /getBalance | Get the balance of a player. | ||
| request Parameters (URI parameters) | |||
| attribute | type | mandatory | notes |
| playerId | string | YES | ID that identifies the player at the operator's site |
| currency | currency | YES | Currency of the requested balance |
| gameCode | string | NO | If the request includes a game code, return freeplays or tickets allocated to that game and player. This is the ID that identifies the game (same code as in the getGameUrl call). See the ticket and freeplay documentation in Appendix D - freeplays and game tickets |
| externalSessionId | string | NO | Reference to a session ID passed in the getGameURL call |
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + playerId + currency + gameCode (if present) | |||
| mandatory request header fields | |||
| X-H-AUTH-ID, X-H-AUTH-SIG, X-H-TIMESTAMP | |||
| returned attributes | |||
| attribute | type | mandatory | notes |
| balances | array of playerBalance objects | YES | The response can include one or two entries. One entry must be “real” money. The response may optionally include “bonus” money |
| discountInfo | discountInfo structure | NO | Optional information about discounts. See Appendix E for details |
| useBonusFirst | boolean | NO (defaults to true) | true if the player must use bonus funds first. false if the player must use real money first. This field is informational. The game frontend displays it only when regulations require it |
| errorCode | errorCode | NO | If an error occurs, the HTTP status code must not be 200. The response can include additional error information |
| clientMessage | clientmessage | NO | Defines a message box that appears in the game client. This field can also appear when an error occurs |
Sample call to query a player's balance
| Fields marked in red must be part of the signature | Description |
| **GET /getBalance?playerId=1234567¤cy=**EUR | Request a EUR balance |
| Sample response (success) | Description |
| { "useBonusFirst": "true", "balances": [{ "type": "real", "amount": 12000, "currency": "EUR" }, { "type": "bonus", "amount": 8010, "currency": "EUR" }] } | The response returns a real money balance of EUR 120.00. It also returns a bonus money balance of EUR 80.10. The player must use bonus money first, so the game displays the message “you are using bonus funds” when legislation requires it. |
| Sample response (error) | Description |
| { "errorCode": { "id": 1, "msg": "player id unknown" } } | Returns an error because the operator did not find the player ID. This call must not return HTTP code 200. |
doTransactions - submit game transactions
Use this call to submit one or more transactions from a game. All transactions refer to a gameround. A unique hash identifies the gameround. You can submit multiple transactions in one call. You can also submit multiple calls. A unique hash identifies each transaction. This call must be idempotent on these hashes.
Process transactions in the order you receive them. A void operation for a debit transaction can arrive before the debit transaction it refers to. In that case, treat the debit transaction as voided, even if you receive it after the void.
If an error occurs in a debit transaction, decline subsequent credit transactions. Do this for the same request and for later requests. Do not process these declined transactions. If at least one operation fails, the HTTP return code must not be 200.
If you receive an initial debit request (isFirstDebit set to true) and it generates an error, for example insufficient funds, treat the gameround as closed. Do not accept further debit or credit transactions.
If you receive a follow-up debit request (isFirstDebit set to false) and it generates an error, for example insufficient funds, do not perform the debit transaction. Keep the gameround open. Accept further debit and credit requests. You will never receive a debit request after an end command in the same call.
Return the player's balance after you process the transactions.
If you receive debit or credit transactions for a closed gameround, and you have not processed them before, report an error.
Process void calls regardless of the gameround's state.
Error handling for credit transactions
A credit transaction must never fail with a 5xx error. If a credit transaction fails with a 5xx error, hizi retries it immediately. If further requests fail, hizi queues the transaction and retries it at increasing intervals. As long as you do not accept the credit call, the player cannot play the game, because the gameround stays open. If you answer a credit transaction with a non-repeatable error, hizi voids the previous debit transactions. hizi then treats the gameround as voided.
If a previous credit transaction succeeded, do not void any debit or credit transactions. Treat the gameround as crashed. Reconcile the gameround.
List of actions that can be submitted
The following actions can appear in a transaction. You always receive at least one debit transaction and one end transaction.
| action | notes | mandatory during lifetime of a gameround |
| debit | A player placed a wager (bet). If isFirstDebit is true, this indicates the start of a new gameround | YES |
| credit | A player won an amount | NO |
| void | If you receive a void call for a gameround, do not process or accept further calls for that gameround. Do not expect an end transaction. hizi automatically marks the round as cancelled. If you receive a transaction for a gameround that has been voided, respond with HTTP status code 400. | NO |
| end | The gameround is closed. Do not accept further transactions, except void operations. If you already sent a VOID action, the end action is not mandatory. You can still send an end action together with a debit action in one combined call | YES unless a VOID was sent |
Flows for transactions
The following diagrams explain the handling of transactions.
Flow of a debit operation
Flow of a credit operation
| POST /doTransactions | Submit an array of gameTransactions | ||
| request Parameters (JSON payload) | |||
| attribute | type | mandatory | notes |
| playerId | string | YES | ID that identifies the player at the operator's site |
| gameCode | string | YES | ID that identifies the game played (same code as in the getGameUrl call) |
| gameRound | hash | YES | Gameround that brackets all transactions |
| transactions | array of gameTransactions | YES | List of transactions to process. This array must hold at least one entry |
| transactionCount | number | YES | Count of transactions in the payload. This count must match the length of the submitted transactions array. If the count differs, reject the call with error code 400 and error id 16 |
| serialUsed | string | NO | Contains the serial of the ticket / freeplay package used for the first deposit in this gameround. hizi sets this field only when there is no first deposit transaction in the call, because the field “serial” in the transactions data contains the information instead. This field is for information only. It links credit + end transactions to a serial, when you send these in separate calls. Note: To activate this field, set the flag “addSerialToTransactions” in the operator settings |
| ticketInformation | Object (see below) | NO | If a package of tickets / freeplays finishes in that gameround, this field contains information about the ticket / freeplay, for example the total amount won Note: To activate this field, set the flag “addSerialToTransactions” in the operator settings |
{ serial: string; stake: number; won: number; isFinal: boolean; used: number; } | |||
| externalSessionId | string | NO | Reference to a session id passed in the getGameURL call Note: hizi sends this property only when the getGameURL call originally included it and the session is still active. If the RGS's built-in janitor process auto-closes the round, no session might be active. In that case, hizi does not send externalSessionID. Process the call whether or not it includes an externalSessionId |
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + playerId + gameCode + gameRound + all transaction hashes and if applicable amounts submitted Sign the fields for transactions in the same sequence as you submit them in the transactions payload. See an example here for a debit/end transaction, and here for a debit/credit/end transaction For example: Hash of the first transaction Amount of the first transaction (do not add an amount if there is no amount, or the amount is 0 (zero), for example an end or void operation, or a debit with a ticket supplied) Hash of the second transaction (do not add an amount if there is no amount, or the amount is 0 (zero), for example an end or void operation, or a debit with a ticket supplied) | |||
| mandatory request header fields | |||
| X-H-AUTH-ID, X-H-AUTH-SIG, X-H-TIMESTAMP | |||
| returned attributes | |||
| attribute | type | mandatory | notes |
| balances | array of playerBalance objects | YES | The response can include one or two entries. One entry must be “real” money. The response may optionally include “bonus” money. The balances must reflect the balance after you process the transactions. |
| discountInfo | discountInfo structure | NO | Optional information about discounts. See Appendix E for details |
| useBonusFirst | boolean | NO (defaults to true) | true if the player must use bonus funds first. false if the player must use real money first. This field is informational. The game frontend displays it only when regulations require it |
| errorCode | errorCode | NO / YES (in case of error) | If an error occurs, the HTTP status code must not be 200. Return this error information. If you did not process any of the transmitted hashes correctly, this field is mandatory. The game frontend uses this information to display error messages |
| clientMessage | clientmessage | NO | Defines a message box that appears in the game client. This field can also appear when an error occurs |
| hashesProcessed | array of json objects | YES | Array of transaction hashes and the result of processing each one. Return this field also when an error occurs. hizi assumes that transaction hashes missing from this list were not processed, and treats them as an error. See the structure below for details. hizi logs the errorCode structure that hashesProcessed returns |
Structure of hashesProcessed
| attribute | type | allowed values | mandatory | notes |
| hash | hash | a transaction hash submitted in the call | YES | |
| errorCode | errorCode | the result of processing the transaction | NO | If this field is not present, the call was processed successfully |
Retry Logic / Error handling
If a doTransactions call with debits returns an HTTP 5xx code, or if a network error occurs, hizi does not retry the call. hizi sends a VOID transaction. hizi marks the gameround as “canceled”.
If a doTransactions call with debits returns an HTTP 4xx code, hizi does not retry the call. hizi marks the gameround as “canceled”.
If the payload of a doTransactions call contains a credit but no debit, hizi retries the call on all error conditions. hizi keeps retrying until the call succeeds, or until you manually mark the gameround as stranded.
Scenarios and samples
The following sections describe example scenarios and sample calls.
Scenario 1: single shot gamerounds
In a single shot gameround, the game determines the outcome after the player's initial bet, for example a normal spin. In this case, hizi transmits all transactions in a single call. The call has 2 transactions if there is no win, or 3 transactions if there is a win. Treat the initial debit as the start of a new gameround. If an error occurs on the debit, for example no balance available, forfeit any possible credit call. Mark the gameround as closed and failed.
If an error occurs on credit and the HTTP error code is 500 or higher, hizi retries the call a few times. If the error persists, or if the HTTP error code is between 400 and 500, hizi sends a void transaction for the debit. hizi marks the gameround as closed and failed.
The following sample calls show two cases: with a win, and without a win. All calls assume the player's initial balance is EUR 10. Fields marked in red must be part of the signature.
Sample for a one shot game without a win
| Sample call for a one shot game without a win | Description |
| POST /doTransactions | Submit a list of transactions |
| Sample payload | Description |
| { "playerId": "sampleplayer", "gameCode: "testgame", "gameRound": "04d4e7fc-092b-459e-bd32-c41343b4af2a", "transactions": [ { "type": "debit", "isFirstDebit": true, "currency": "EUR", "hash": "13536977-5cfa-430b-a019-18430d61b48f", "amount": 200, "timestamp": "2020-01-21T14:48:04Z", "reason": "spin" }, { "type": "end", "hash": "b92f866a-5fe9-4ac1-ae0d-9f403dfe1a12", "timestamp": "2020-01-21T14:48:04Z" } ], "transactionCount": 2 } | The player spins for EUR 2 and does not win anything. Because there is no gameround yet, the first debit indicates the start of a new round. hizi immediately closes the gameround. |
| debit / end example of fields to sign for transaction [ "13536977-5cfa-430b-a019-18430d61b48f", 200, "b92f866a-5fe9-4ac1-ae0d-9f403dfe1a12" ] | Append these fields to the fields used to calculate the signature |
| Sample response (success) | Description |
| { "balances": [{ "type": "real", "amount": 800, "currency": "EUR" }], "hashesProcessed": [{ "hash": "13536977-5cfa-430b-a019-18430d61b48f" } ,{ "hash": "b92f866a-5fe9-4ac1-ae0d-9f403dfe1a12" }] } | The response returns a real money balance of EUR 8. |
Sample for a one shot game with a single win
| Sample call for a one shot game with a win | Description |
| POST /doTransactions | Submit a list of transactions |
| Sample payload | Description |
| { "playerId": "sampleplayer", "gameCode: "testgame", "gameRound": "04d4e7fc-092b-459e-bd32-c41343b4af2a", "transactions": [ { "type": "debit", "isFirstDebit": true, "amount": 200, "currency": "EUR", "hash": "13536977-5cfa-430b-a019-18430d61b48f", "timestamp": "2020-01-21T14:48:04Z", "reason": "spin" }, { "type": "credit", "amount": 150, "currency": "EUR", "hash": "4fac9a5d-3662-4f85-88ad-8301681d4b61", "timestamp": "2020-01-21T14:48:04Z", "reason": "3 symbols in line 1" }, { "type": "end", "hash": "b92f866a-5fe9-4ac1-ae0d-9f403dfe1a12", "timestamp": "2020-01-21T14:48:04Z" } ], "transactionCount": 3 } | The player spins for EUR 2 and wins EUR 1.50. Because there is no gameround yet, the first debit indicates the start of a new round. hizi immediately closes the gameround. |
| debit/credit/end example of fields to sign for transaction [ "13536977-5cfa-430b-a019-18430d61b48f", 200, "4fac9a5d-3662-4f85-88ad-8301681d4b61", 150, "b92f866a-5fe9-4ac1-ae0d-9f403dfe1a12" ] | Append these fields to the fields used to calculate the signature |
| Sample response (success) | Description |
| { "balances": [{ "type": "real", "amount": 950, "currency": "EUR" }], "hashesProcessed": [{ "hash": "13536977-5cfa-430b-a019-18430d61b48f" } ,{ "hash": "4fac9a5d-3662-4f85-88ad-8301681d4b61" } ,{ "hash": "b92f866a-5fe9-4ac1-ae0d-9f403dfe1a12" }] } | The response returns a real money balance of EUR 9.50 |
Scenario 2: multiple transaction calls for a gameround
Use multiple doTransactions calls when the game cannot determine the outcome after the player's initial bet, for example when the player enters a bonus round or wins in-game free spins. In this case, hizi transmits all transactions in multiple calls. Each call has 1 or 2 transactions. The first call is always an initial debit call. hizi transmits wins and additional bets in separate calls. At the end of the gameround, hizi transmits an end action, or appends it to the last credit call. If an error occurs on the initial debit, for example no balance available, mark the gameround as closed and failed. Do not accept further calls for this gameround, except an end action.
If an error occurs on credit and the HTTP error code is 500 or higher, hizi retries the call a few times. If the error persists, or if the HTTP error code is between 400 and 500, hizi sends a void transaction for the debit. hizi marks the gameround as closed and failed.
If an error occurs when you submit an additional bet (isFirstDebit is false), take no further action. The game can continue with a smaller stake. In this case, hizi sends a new debit transaction.
If you receive a second initial bet for the same gameround hash, always respond with an error, because the gameround has already started. Take no further action.
The following example shows a multi transaction call flow. All calls assume the player's initial balance is EUR 10. Fields marked in red must be part of the signature.
Sample for a gameround with multiple calls (6 calls in this example)
| Sample call sequence for multiple calls in a gameround (a basic game plus a bonus round with an additional wager) | Description |
| Sample payload | Description |
| Sample response (success) | Description |
| Step 1 POST /doTransactions | Submit the initial debit to start a new gameround |
| Sample payload | Description |
| { "playerId": "sampleplayer", "gameCode: "testgame", "gameRound": "04d4e7fc-092b-459e-bd32-c41343b4af2a", "transactions": [ { "type": "debit", "isFirstDebit": true, "amount": 200, "currency": "EUR", "hash": "13536977-5cfa-430b-a019-18430d61b48f", "timestamp": "2020-01-21T14:48:04Z", "reason": "spin" } ], "transactionCount": 1 } | The player bets an initial EUR 2 |
| Sample response (success) | Description |
| { "balances": [{ "type": "real", "amount": 800, "currency": "EUR" }], "hashesProcessed": [{ "hash": "13536977-5cfa-430b-a019-18430d61b48f" }] } | The response returns a real money balance of EUR 8. |
| Step 2 POST /doTransactions | The player wins on the basic spin |
| Sample payload | Description |
| { "playerId": "sampleplayer", "gameCode: "testgame", "gameRound": "04d4e7fc-092b-459e-bd32-c41343b4af2a", "transactions": [ { "type": "credit", "amount": 150, "currency": "EUR", "hash": "4fac9a5d-3662-4f85-88ad-8301681d4b61", "timestamp": "2020-01-21T14:48:04Z", "reason": "3 symbols in line 1" }, ], "transactionCount": 1 } | The player wins EUR 1.50 from the basic spin |
| Sample response (success) | Description |
| { "balances": [{ "type": "real", "amount": 950, "currency": "EUR" }], "hashesProcessed": [{ "hash": "4fac9a5d-3662-4f85-88ad-8301681d4b61" }] } | The response returns a real money balance of EUR 9.50. |
| Step 3 POST /doTransactions | The player places a continuation bet |
| Sample payload | Description |
| { "playerId": "sampleplayer", "gameCode: "testgame", "gameRound": "04d4e7fc-092b-459e-bd32-c41343b4af2a", "transactions": [ { "type": "debit", "isFirstDebit": false, "amount": 170, "currency": "EUR", "hash": "2f1e3eeb-4330-4d26-87d8-4a72b3fdc4d6", "timestamp": "2020-01-21T14:48:04Z", "reason": "get more scatters bet for bonus round" } ], "transactionCount": 1 } | The player bets EUR 1.70 for additional scatters in a bonus game |
| Sample response (success) | Description |
| { "balances": [{ "type": "real", "amount": 780, "currency": "EUR" }], "hashesProcessed": [{ "hash": "2f1e3eeb-4330-4d26-87d8-4a72b3fdc4d6" }] } | The response returns a real money balance of EUR 7.80. |
| Step 4 POST /doTransactions | The player wins in a bonus game |
| Sample payload | Description |
| { "playerId": "sampleplayer", "gameCode: "testgame", "gameRound": "04d4e7fc-092b-459e-bd32-c41343b4af2a", "transactions": [ { "type": "credit", "amount": 950, "currency": "EUR", "hash": "02ab706a-749a-4851-894b-ba48bec74ec4", "timestamp": "2020-01-21T14:48:04Z", "reason": "win in bonus game" }, ], "transactionCount": 1 } | The player wins EUR 9.50 in the bonus game |
| Sample response (success) | Description |
| { "balances": [{ "type": "real", "amount": 1730, "currency": "EUR" }], "hashesProcessed": [{ "hash": "02ab706a-749a-4851-894b-ba48bec74ec4" }] } | The response returns a real money balance of EUR 17.30. |
| Step 5 POST /doTransactions | This call closes the gameround |
| Sample payload | Description |
| { "playerId": "sampleplayer", "gameCode: "testgame", "gameRound": "04d4e7fc-092b-459e-bd32-c41343b4af2a", "transactions": [ { "type": "end", "hash": "b92f866a-5fe9-4ac1-ae0d-9f403dfe1a12", "timestamp": "2020-01-21T14:48:04Z" } ], "transactionCount": 1 } | The gameround is finished. Do not accept further debits or credits |
| Sample response (success) | Description |
| { "balances": [{ "type": "real", "amount": 1730, "currency": "EUR" }], "hashesProcessed": [{ "hash": "b92f866a-5fe9-4ac1-ae0d-9f403dfe1a12" }] } | The response returns a real money balance of EUR 17.30. |
| Step 4a (replaces 4+5) POST /doTransactions | This is an alternative to steps 4 and 5. Here, the last credit call also closes the gameround |
| Sample payload | Description |
| { "playerId": "sampleplayer", "gameCode: "testgame", "gameRound": "04d4e7fc-092b-459e-bd32-c41343b4af2a", "transactions": [ { "type": "credit", "amount": 950, "currency": "EUR", "hash": "02ab706a-749a-4851-894b-ba48bec74ec4", "timestamp": "2020-01-21T14:48:04Z", "reason": "win in bonus game" }, ], [ { "type": "end", "hash": "b92f866a-5fe9-4ac1-ae0d-9f403dfe1a12", "timestamp": "2020-01-21T14:48:04Z" } ], "transactionCount": 2 } | The player wins EUR 9.50 in the bonus game. The gameround is now finished. Do not accept further debits or credits |
| Sample response (success) | Description |
| { "balances": [{ "type": "real", "amount": 1730, "currency": "EUR" }], "hashesProcessed": [{ "hash": "02ab706a-749a-4851-894b-ba48bec74ec4" },{ "hash": "b92f866a-5fe9-4ac1-ae0d-9f403dfe1a12" }] } | The response returns a real money balance of EUR 17.30. |
logEvent (optional)
hizi uses this call to inform the operator of events. Log in to the hizi.io backoffice with your credentials to turn this call on or off. An event is always bound to a player. An event is optionally bound to a gameround. Events can include big wins or other events during a game, for example free spins won or a bonus level entered. See Appendix A for details on events.
The operator is responsible for storing this data. We recommend that you expose these events to the operator's helpdesk, because they can contain information about big wins or big stakes.
| POST /logEvent | Submit an event | ||
| request Parameters (JSON payload) | |||
| attribute | type | mandatory | notes |
| playerId | string | YES | ID that identifies the player at the operator's site |
| gameRound | hash | NO | Gameround that the event is bound to |
| eventType | string | YES | A string describing the event |
| eventData | jsondata | NO | A JSON structure describing the event. See Appendix A for the possible values |
| reason | string | NO | Optional reason for this call |
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + playerId + (gameround if present in payload) | |||
| 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 code must not be 200. The response can include additional error information |
Sample call to submit an event
Fields marked in red must be part of the signature.
| Sample call to report a bonus win | Description |
| POST /logEvent | Report a bonus win |
| Sample payload | Description |
| { "playerId": "sampleplayer", "gameRound": "04d4e7fc-092b-459e-bd32-c41343b4af2a", "eventType": "BONUSROUND", "eventData": { "credit": { "amount": 950, "currency": "EUR" }, "freespins": 10 }, "reason": "Player got 10 freespins" } | The player receives 10 in-game free spins and wins EUR 9.50 |
| Sample response (success) | Description |
| { } | Empty response |
doGameRoundReport (optional)
hizi sends this call with gameround details only after the round is closed. The payload includes the most important details of a gameround. You can use these details for reporting and historical records.
The operator must request that hizi enable this endpoint. Otherwise, hizi does not send requests.
| POST /doGameRoundReport | Submit gameround details (for a closed gameround) | ||
| request Parameters (JSON payload) | |||
| attribute | type | mandatory | notes |
| gameRoundDetail | jsondata | YES | Gameround payload |
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP | |||
| 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 code must not be 200. The response can include additional error information |
Sample call to submit a gameround
Fields marked in red must be part of the signature.
| Sample call to report a bonus win | Description |
| POST /doGameRoundReport | Sends a gameround's payload |
| Sample payload | Description |
| { "gameRoundDetail": { "hash": "789b5513cb1a499dba181c6091c57d36", "mode": "REAL", "game": "bg-olympus-gold-96", "operator": "internal_testoperator", "status": "closed", "player": "acfbf7980c4d4add8688c944c9c2a22a", "language": "EN", "currency": "EUR", "environment": "gmzp", "timestamp": "2025-07-08T13:22:01.874+00:00", "baseStake": 10, "totalBetAmount": 10, "totalPayedAmount": 10, "totalWinAmount": 15, "dataStored": {}, "ticketUsed": false, "balanceAfter": 9075, "transactions": [ { "hash": "789b5513cb1a499dba181c6091c57d36", "type": "debit", "amount": 10, "payed": 10, "isFirstDebit": true, "currency": "EUR", "timestamp": "2025-07-08T13:21:44.599Z", "balanceAfter": 9060 }, { "hash": "3ef71295e3924915aec018ee32d10e17", "type": "credit", "amount": 15, "payed": 15, "currency": "EUR", "timestamp": "2025-07-08T13:22:01.555Z", "balanceAfter": 9075 }, { "hash": "637310141d1c4fdf8dc8579e0b8dec21", "type": "end", "currency": "EUR", "timestamp": "2025-07-08T13:22:01.855Z", "balanceAfter": 9075 } ] } } | Gameround payload |
| Sample response (success) | Description |
| { } | Empty response |
doGameRoundResult (optional)
hizi sends this call with the gameround result only after the round is closed. The payload includes an HTML representation of the game result. The operator must request that hizi enable this endpoint. Otherwise, hizi does not send requests.
| POST /doGameRoundResult | Submit a gameround result (for a closed gameround) | ||
| request Parameters (JSON payload) | |||
| attribute | type | mandatory | notes |
| gameCode | string | YES | Game code |
| msg | string | YES | Base64-encoded HTML that you can use to display the gameround. Buffer.from(body.msg,'base64').toString('utf-8'); |
| gameRound | hash | YES | Gameround ID |
| playerId | string | YES | Player ID |
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP + gameRound + gameCode + playerId + msg | |||
| 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 code must not be 200. The response can include additional error information |
Sample call to submit a gameround result
Fields marked in red must be part of the signature.
| Sample call to report a bonus win | Description |
| POST /doGameRoundResult | Sends a gameround's HTML result |
| Sample payload | Description |
| { "gameRound": "789b5513cb1a499dba181c6091c57d36", "playerId": "acfbf7980c4d4add8688c944c9c2a22a", "gameCode": "bg-olympus-gold-96", "msg": "<html>...</html>" } | Gameround payload |
| Sample response (success) | Description |
| { } | Empty response |
reportAnimationEnd (optional)
hizi sends this call to the operator when the animation of the current gameround finishes. At this point, the spin or play button is active again, and the player can start a new game. This call must never fail. It must always report HTTP 200 (success).
Usecase:
A gameround can consist of a single transaction. hizi closes the gameround immediately in one doTransactions call. Client-side animations can still be running. From the player's point of view, the game is still running. Some legal frameworks require game start and end events to go to a safe server for the regulator. Use this call to report correct game start and end events for these frameworks. This call is mostly useful for German regulations.
The operator must request that hizi enable this endpoint. Otherwise, hizi does not send requests.
| POST /reportAnimationEnd | Submit gameround details (for a closed gameround) | ||
| request Parameters (JSON payload) | |||
| attribute | type | mandatory | notes |
| gameRound | hash | YES | Gameround to report as finished |
| 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 code must not be 200. The response can include additional error information |
Sample call to submit a gameround
Fields marked in red must be part of the signature.
| Sample call to report a bonus win | Description |
| POST /reportAnimationEnd | Gameround is finished (animation stopped) |
| Sample payload | Description |
| { "gameRound": "8a73676f4e5c4b4d8507b526f48b4f4d" } | Gameround payload |
| Sample response (success) | Description |
| { } | Empty response |
ping
hizi uses this call to test the availability of the operator's service. hizi can call this endpoint at any time. The endpoint must return HTTP status code 200 to confirm operation. The response can include additional performance data for extended monitoring.
If this call receives repeated errors, the hizi.io Backoffice notifies you.
| GET /ping | Call the operator to confirm operation | ||
| request Parameters (URI parameters) | |||
| attribute | type | mandatory | notes |
| NONE | |||
| fields to sign (order is important) | |||
| secret + X-H-AUTH-ID + X-H-TIMESTAMP | |||
| mandatory request header fields | |||
| X-H-AUTH-ID, X-H-AUTH-SIG, X-H-TIMESTAMP | |||
| returned attributes | |||
| attribute | type | mandatory | notes |
| performanceData | jsondata | NO | Additional data that you can use for monitoring |
| errorCode | errorCode | NO | If an error occurs, the HTTP status code must not be 200. The response can include additional error information |
Sample call to test availability of operator service
| Fields marked in red must be part of the signature | Description |
| GET /ping | Get the operational status |
| Sample response (success) | Description |
| { "performanceData": { "status": "operational" } } | The response indicates success and returns an optional status |