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. hizi uses hashesProcessed in your response to decide the result of each credit. The HTTP status code does not decide it.
- Processed: Return the credit hash in
hashesProcessedwithout anerrorCode. hizi books the credit as paid. - Result unknown: Do not return the credit hash in
hashesProcessed. A timeout or an empty response body has the same effect. hizi keeps the credit pending and the gameround open. hizi sends the credit again later. See Retry Logic / Error handling. - Final error: Return the credit hash with an
errorCode. hizi does not send the credit again. hizi does not void the debit. hizi marks the gameround as stranded.
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 |
Void of the first debit
A void always refers to the hash of a debit. A void never refers to a credit.
A void always has the hash of the debit that it voids. For games on the native hizi game studio protocol, the first debit (isFirstDebit is true) uses the gameRound hash as its hash. So for these games, a void with the gameRound hash is a void of the first debit. It is not a void of a credit. Games on other game studio protocols can use a different hash for the first debit. Identify the debit by the hash of the void, not by the gameRound hash.
A void of the first debit cancels the whole gameround. After the void, the gameround must have a net result of 0 for the player:
- Reverse the first debit. If you did not process the debit, do not process it later.
- If you booked a credit for this gameround, reverse the credit too. This occurs when your wallet processed a call, but the reply did not get to hizi in time.
- Do not expect an end transaction. hizi marks the gameround as cancelled.
- Answer all later transactions for this gameround with HTTP status code 400.
hizi does not send a void of the first debit after you confirmed a credit of the same gameround in hashesProcessed. In that case, hizi treats the gameround as crashed. Reconcile the gameround.
hizi can send the transaction type in upper case (VOID). Compare transaction types without case sensitivity.
For a sample, see Scenario 3: a doTransactions call times out.
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 operation, or a debit with a ticket supplied. A void that hizi sends after a failed debit has the amount of that debit. Add this amount) 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 operation, or a debit with a ticket supplied. A void that hizi sends after a failed debit has the amount of that debit. Add this amount) | |||
| 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 immediately if it does not get HTTP 200. This applies to all other HTTP status codes and to network errors. hizi makes up to 5 retries, with no delay between them. hizi does not queue a credit for retries at increasing intervals.
After the last attempt, hizi uses hashesProcessed to decide the result of each credit. See Error handling for credit transactions in doTransactions:
- The hash has no
errorCode: hizi books the credit as paid. - The hash has an
errorCode: hizi marks the gameround as stranded. hizi does not send the credit again. - The hash is missing: the credit stays pending, and the gameround stays open.
hizi sends a pending credit again in these cases:
- The player launches the same game again. hizi sends the credit after your getGameURL call returns, before the game starts. The call has the
externalSessionIdof the new launch. Accept the credit at that time. If you return an error for the credit, hizi marks the gameround as stranded, and the game does not start. - The RGS janitor process retries open gamerounds. The janitor is a background job that runs every hour. It sends pending credits of gamerounds that are older than a configured age. The call can come without an
externalSessionId. When the gameround reaches the maximum gameround age, the janitor stops the retries and closes the gameround.
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 a credit call, hizi does not send a void transaction for the debit. See Error handling for credit transactions in doTransactions and Retry Logic / Error handling.
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. |
Scenario 3: a doTransactions call times out
hizi waits a limited time for the reply to doTransactions. If the call contains a debit and your wallet does not reply in time, hizi does not retry the call. hizi sends a void of the first debit, and cancels the gameround. Your wallet can still process the first call after hizi stopped to wait. In that case, reverse the debit and the credit of that call. See Void of the first debit.
All calls assume the player's initial balance is EUR 10. The game uses the native hizi game studio protocol, so the gameRound hash and the hash of the first debit have the same value.
| Step 1 POST /doTransactions | hizi submits a one shot gameround with a win |
| Sample payload | Description |
| { "playerId": "sampleplayer", "gameCode": "testgame", "gameRound": "5417dcd79e964235bd8e112e29c23dd9", "transactions": [ { "type": "debit", "isFirstDebit": true, "amount": 100, "currency": "EUR", "hash": "5417dcd79e964235bd8e112e29c23dd9" }, { "type": "credit", "amount": 50, "currency": "EUR", "hash": "1937bafe0dde4a118b010f21d8d35cc5" }, { "type": "end", "hash": "4fead761e38d4b08b62d64fab690fa74" } ], "transactionCount": 3 } | The player spins for EUR 1 and wins EUR 0.50. |
| Sample response | Description |
| no reply in time | hizi stops to wait and records a network error. hizi does not retry a call that contains a debit. |
| Step 2 POST /doTransactions | hizi voids the first debit |
| Sample payload | Description |
| { "playerId": "sampleplayer", "gameCode": "testgame", "gameRound": "5417dcd79e964235bd8e112e29c23dd9", "transactions": [ { "hash": "5417dcd79e964235bd8e112e29c23dd9", "type": "VOID", "amount": 100, "currency": "EUR" } ], "transactionCount": 1 } | The void has the hash of the first debit. In this sample, this hash is also the gameRound hash. The void cancels the whole gameround. |
| void example of fields to sign for transaction [ "5417dcd79e964235bd8e112e29c23dd9", 100 ] | Append these fields to the fields used to calculate the signature |
| Sample response (success) | Description |
| { "balances": [{ "type": "real", "amount": 1000, "currency": "EUR" }], "hashesProcessed": [{ "hash": "5417dcd79e964235bd8e112e29c23dd9" }] } | The balance is EUR 10 again. If your wallet processed Step 1, it reversed the debit of EUR 1 and the credit of EUR 0.50. If your wallet did not process Step 1, it booked nothing. |
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 submit a gameround report | 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 submit a gameround result | 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).
Use case:
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 | Report that the animation of a closed gameround finished | ||
| 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 report the end of an animation
Fields marked in red must be part of the signature.
| Sample call to report the end of an animation | 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 |