Calls provided by API V2

Introduction

API V2 supports simple operations like gamestart, win, and end. It also provides more complex endpoints. These endpoints let you wager wins. They also track game spin events, for example free spins in a gameround. They prevent the game from consuming more spins than it awarded.

API V2 also provides an interface to the hizi.io certified RNG (random number generator).

Game front ends use these calls to start communication with hizi.io. Game engines and third-party RGS also use these calls.

The following tables summarize the calls. More details and the structure of each call appear below.

Frontend Calls (GET)


Endpoint	Method	Required	Description
/status	GET	Optional	Check API status
/connect	GET	Mandatory	Establish connection, get long-lived token
/reconnect	GET	Optional	Re-establish connection using long-lived token
/disconnect	GET	Optional	Signal game close/leave to operator

Game Engine / RGS Calls (POST)


Endpoint	Method	Required	Description
/testPing	POST	Optional	Test communication and payload signature
/startGameRound	POST	Mandatory	Start round, debit bet, optionally credit win and close
/endGameRound	POST	Mandatory	Close a gameround
/getGameRoundInfo	POST	Optional	Get info about an open gameround
/getGameRoundHistoryInfo	POST	Optional	Get historical info about a closed gameround
/voidGameRound	POST	Optional	Void a debit for an open gameround
/collectWin	POST	Optional	Collect part or all of open winnings
/addWin	POST	Mandatory	Add a win to a gameround
/wagerWin	POST	Optional	Wager part or all of open winnings
/getUncollectedAmount	POST	Optional	Get amount of uncollected winnings
/addSpinCounterGameState	POST	Optional	Track spin events (for example free spins), not needed for RGS-to-RGS
/getAvailableSpinCounter	POST	Optional	Get available spin counter, not needed for RGS-to-RGS
/getTokenForGameRound	POST	Optional	Get token for a gameround
/getTokenData	POST	Optional	Get token data
/getLastGameRounds	POST	Optional	Get last gamerounds
/getRandomResult	POST	Conditional¹	Get certified RNG result
/getOperatorSettings	GET	Optional	Get operator-specific settings
/getBalance	POST	Optional	Get player balance

¹ /getRandomResult is not required for a classic RGS-to-RGS integration. If your RGS runs on your own infrastructure and already uses your own certified RNG (the typical RGS-to-RGS case), do not call /getRandomResult. Keep using your certified RNG. Pass its results in the rngResult fields as usual. The hizi.io certified RNG is required only when the game logic runs inside the hizi.io RGS and must get randomness from hizi.io for compliance. This applies to direct game engine integrations hosted by hizi.io, and to a partner RGS hosted within the hizi.io RGS ("RGS inception"). See /getRandomResult below.

Game frontend calls

All calls use the GET method. Each call needs a valid token, except status calls. There are two types of token. The game launcher passes a short-lived token as a URL parameter named “token”. The connect call returns a long-lived token.

GET V2_API_ENDPOINT/status (optional)

Use this call to check the status of the V2 API. You can call it from the game frontend, the game backend, or a third-party RGS.

parameters: none

response:         a JSON structure containing a message

GET V2_API_ENDPOINT/connect (mandatory to use)

The game launcher passes a connect URL and a short-lived token to the game frontend. The game frontend uses this information to establish communication with hizi.io. It also uses this information to get a long-lived token. The game frontend uses the long-lived token to authenticate further calls. The short-lived token is valid for 5 minutes only.

E.g. the game launcher is called via this URL

https://location-of-gamelauncher/index.html?token=206fa387-9565-4fc7-b6e6-b555ae064cfc&login=https%3A%2F%2Fapi.sample.hizi.io%2Fgameapi%2v2%2Fconnect

The game frontend then calls:

https://api.sample.hizi.io/v2/connect?token=206fa387-9565-4fc7-b6e6-b555ae064cfc

parameters: token

response: V2_ConnectReply

GET V2_API_ENDPOINT/reconnect (optional)

This call is similar to connect but uses a long-lived token from a previous connect call. Use it to reestablish connection after an error message.

parameters: token

response: V2_ConnectReply

GET V2_API_ENDPOINT/disconnect (optional)

Use this call to signal that a game frontend is closing or leaving to the operator. Some operators require this functionality. Implement this call. For the “token” parameter, use the long-lived token from a previous connect call. The response of this call is not defined. The frontend does not need to wait for the response.

parameters: token

response: none

Game engine / RGS calls

Game engines use this group of calls to communicate with the RGS. Operators do not use these calls. Game engines use these calls only to communicate with the RGS.

Signing RGS requests

All calls use the POST method with a JSON payload. Sign each request with a shared secret to hash the payload. The payload is always a JSON structure.

You need a secret to sign requests. Log in to the hizi.io backoffice with your credentials to get this secret. The signature is a base64-encoded SHA256 HMAC digest of a defined set of request parameters. This method shares the secret without including it in the request. You must also provide a timestamp in a request header field. Include this timestamp in the signature. Concatenate the fields with a hash character (#) before you calculate the SHA256 HMAC.

Every request sends the signature in the request header field X-H-AUTH-SIG. For an example implementation of creating signatures, log in to the hizi.io backoffice and look at the sample code provided.

See the sample source in the Appendix of this document.

Mandatory request headers

When you submit a call, pass the following request headers:


X-Request-Id	Unique ID to identify the call in logs
X-H-AUTH-ID	Game provider ID that hinterzimmer assigns
X-H-AUTH-SIG	Signature of the payload
X-H-TIMESTAMP	Timestamp (included in the signature data)

Response headers

The API sets the following headers in the response when it returns the call result:


X-Response-Status	For a successful call, this header is present and contains “ok”. Any other value, or the absence of this header, indicates an error.
X-H-ERROR-ID	Contains an error code if an error occurs
X-H-ERROR-MSG	An optional error message
X-Response-Id	Unique ID of the response, used to identify the call in logs

POST V2_API_ENDPOINT/testPing (optional)

This call sends a test payload to the API. The API returns the same payload back. Use this call to check basic communication and the signature of the payload.

request: V2_TestPingRequestBody

response:         proxies body back in testDataReceived

Example:

{
  url: '/gameapi/v2/testPing',
  method: 'POST',
  body: '{"testData":{"testInt":1,"testString":"something","testBoolean":true}}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.429Z',
    'x-request-id': '8c00b93dd861405cbeb7c14fded1e72a',
    'x-h-auth-sig': 'fea0tckY+PfMPQA1mfhRsyUWdcJ9BXGseFOgOVE9MvE='
  },
  response: '{"testDataReceived":{"testInt":1,"testString":"something","testBoolean":true}}',
  responseHeaders: {
    'x-request-id': 'c28bb1aa40714c54ad36fe2bc6154939',
    'x-response-id': '1a3b4d1d499c4f43a78cc7a138bebdd5',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/startGameRound (mandatory)

This call starts a new gameround and debits the bet. Optionally, it can also credit winnings and close the gameround immediately. Optionally, it can close any existing gameround and collect open winnings.

request: V2_StartGameRoundRequestBody

response: V2_GameAPIReply

Example (no win)

{
  url: '/gameapi/v2/startGameRound',
  method: 'POST',
  body: '{"token":"83020869-abc0-4123-a95e-ee4f5e8e8343","rngResult":{"rngCallId":"5cd23259ea4c49e7b955e79321da4365","result":"test","winAmount":0},"debitInformation":{"debitAmount":100,"currency":"EUR"},"endGame":true}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': '20e6bd07275c42fdb161f86a65a19a61',
    'x-h-auth-sig': 'Wq1xa11DsazyMNYoi26lBbes1P5SmVFc2VujHvgYea4='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"83020869-abc0-4123-a95e-ee4f5e8e8343","language":"DE","currencyMultiplier":1,"gameRound":"9f3e51d518024a98977be80c30106cc3"},"balance":{"totalBalance":6916,"mode":"REAL","currency":"EUR","balances":[{"type":"real","amount":6916,"currency":"EUR"}]},"amountToCollect":0,"amountCredited":0,"gameRoundInfo":{"hash":"9f3e51d518024a98977be80c30106cc3","status":"closed","stake":100,"mode":"REAL","currency":"EUR","game":"efbdc5b0ef8c434cbf11daab2fda0d5d"},"gameState":[{"hash":"9f3e51d518024a98977be80c30106cc3","type":"debit","result":{"winAmount":0},"processedOn":"2023-01-26T11:28:22.126Z"}]}',
  responseHeaders: {
    'x-response-id': '873ae012-ea6b-4b6e-b4d0-3946afb48b06',
    'x-h-error-id': '0',
    'x-h-repeatcount': '0',
    'x-response-status': 'ok',
    'x-request-id': 'c1822729c33f4ba69493ead9154291c9'
  }
}

Example (with win)

{
  url: '/gameapi/v2/startGameRound',
  method: 'POST',
  body: '{"token":"83020869-abc0-4123-a95e-ee4f5e8e8343","rngResult":{"rngCallId":"7c1d45ad589046f3b52fe779ffd96632","result":"test","winAmount":77},"debitInformation":{"debitAmount":100,"currency":"EUR"},"endGame":false}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': 'ace5640f237a4959b9a20e83b82dece7',
    'x-h-auth-sig': '3hG9jfqJtRAIdUppRQc6EJEELhUUtT95xbEAJHFed9A='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"83020869-abc0-4123-a95e-ee4f5e8e8343","language":"DE","currencyMultiplier":1},"balance":{"totalBalance":6816,"mode":"REAL","currency":"EUR","balances":[{"type":"real","amount":6816,"currency":"EUR"}]},"amountToCollect":77,"amountCredited":0,"gameRoundInfo":{"hash":"ff85e29cb4414c89a89829c8411dacc2","status":"open","stake":100,"mode":"REAL","currency":"EUR","game":"efbdc5b0ef8c434cbf11daab2fda0d5d"},"gameState":[{"hash":"ff85e29cb4414c89a89829c8411dacc2","type":"debit","result":{"winAmount":77},"processedOn":"2023-01-26T11:28:22.810Z"}]}',
  responseHeaders: {
    'x-response-id': 'e628b84c-6df4-45d1-9561-d7653e144a3a',
    'x-h-error-id': '0',
    'x-h-repeatcount': '0',
    'x-response-status': 'ok',
    'x-request-id': 'ec8a82e6ce0e4aa79095fe4119756a54'
  }
}

POST V2_API_ENDPOINT/endGameRound (mandatory)

This call ends an open gameround. It collects any open winnings.

request:         V2_EndGameRoundRequestBody

response: V2_GameAPIReply

Example

{
  url: '/gameapi/v2/endGameRound',
  method: 'POST',
  body: '{"token":"d182d578-dcce-4850-b091-205c482c0f58","gameRound":"3c2d66db3e5142d1986e210c809f88e4"}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': 'ba8cf3f65d1e4f25aefd42cdc6b1caa6',
    'x-h-auth-sig': 'YuIsLOFtIfSDhKfvoY2DLnc7UxlcRMc8z7XXm9UkGSc='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"d182d578-dcce-4850-b091-205c482c0f58","language":"DE","currencyMultiplier":1,"gameRound":"3c2d66db3e5142d1986e210c809f88e4"},"balance":{"totalBalance":6954,"mode":"REAL","currency":"EUR","balances":[{"type":"real","amount":6954,"currency":"EUR"}]},"amountToCollect":0,"amountCredited":0,"gameRoundInfo":{"hash":"3c2d66db3e5142d1986e210c809f88e4","status":"closed","stake":13,"mode":"REAL","currency":"EUR","game":"efbdc5b0ef8c434cbf11daab2fda0d5d"},"gameState":[{"hash":"3c2d66db3e5142d1986e210c809f88e4","type":"debit","result":{"winAmount":0},"processedOn":"2023-01-26T11:28:26.591Z"}]}',
  responseHeaders: {
    'x-response-id': '7ba96252-1aad-41a0-af34-abc9ff939299',
    'x-h-error-id': '0',
    'x-h-repeatcount': '0',
    'x-response-status': 'ok',
    'x-request-id': '7dd55c93439b474b8523be610c0e05d5'
  }
}

POST V2_API_ENDPOINT/getGameRoundInfo (optional)

This call returns information about a gameround.

request:         V2_GetGameRoundDetailsRequestBody

response: V2_GameAPIReply

Example

{
  url: '/gameapi/v2/getGameRoundInfo',
  method: 'POST',
  body: '{"token":"83020869-abc0-4123-a95e-ee4f5e8e8343","gameRound":"ff85e29cb4414c89a89829c8411dacc2"}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': '4dcef13fa1094f29b720df41e16376fc',
    'x-h-auth-sig': 'zwlF64lg7h71r1qgHPXuILziZsaZxHtH7AZJfrtQvPY='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"83020869-abc0-4123-a95e-ee4f5e8e8343","language":"DE","currencyMultiplier":1,"gameRound":"ff85e29cb4414c89a89829c8411dacc2"},"amountToCollect":77,"gameRoundInfo":{"hash":"ff85e29cb4414c89a89829c8411dacc2","status":"open","stake":100,"mode":"REAL","currency":"EUR","game":"efbdc5b0ef8c434cbf11daab2fda0d5d"},"gameState":[{"hash":"ff85e29cb4414c89a89829c8411dacc2","type":"debit","result":{"winAmount":77},"processedOn":"2023-01-26T11:28:22.810Z"}]}',
  responseHeaders: {
    'x-request-id': '57ad03d0c9f54cd6ab5b81d7895a154d',
    'x-response-id': '400f691553b3490080681432e3fd65c0',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/getGameRoundHistoryInfo (optional)

This call returns historical information about a gameround.

request:         V2_GetGameRoundDetailsRequestBody

response: V2_GameAPIReply. The response also includes any protectedInfo.

Notes: This call is not available for open gamerounds. Use getGameRoundInfo instead.

POST V2_API_ENDPOINT/voidGameRound (optional)

This call voids a debit for a gameround. The operator receives a doTransactions call with a void operation for the initial debit. This call does not work if the gameround is not open. It also does not work if the operator already processed a credit successfully. In these cases, the call returns an error.

request:         V2_VoidGameRoundRequestBody

response: V2_GameAPIReply,

Example

{
  url: '/gameapi/v2/voidGameRound',
  method: 'POST',
  body: '{"token":"83020869-abc0-4123-a95e-ee4f5e8e8343","gameRound":"ff85e29cb4414c89a89829c8411dacc2"}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': 'b5f00dc745f84da3adcd474da161f759',
    'x-h-auth-sig': '4c4gjIruvm+qHmZO+Jc2eFbdH35sr45xVXNW6pDKUAw='
  },
  response: '{"balance":6902941,"gameRoundInfo":{"hash":"8f105c8a01fc46d7bb45c317c619445a","status":"cancel","stake":13,"mode":"REAL","currency":"EUR","game":"093a992277e14d6bbb1e5ead156f6734","baseStake":13,"currencyMultiplier":1}}',
  responseHeaders: {
    'x-response-id': '23778189-4957-45fe-91f2-704541b11010',
    'x-h-error-id': '0',
    'x-h-repeatcount': '0',
    'x-response-status': 'ok',
    'x-request-id': '90f91efe393f4ca5af621728e11f7227'
  }
}

POST V2_API_ENDPOINT/collectWin (optional)

This call collects part or all open winnings. It optionally closes the gameround when the call collects all open winnings.

request:         V2_CollectWinRoundRequestBody

response: V2_GameAPIReply

Example

{
  url: '/gameapi/v2/collectWin',
  method: 'POST',
  body: '{"token":"83020869-abc0-4123-a95e-ee4f5e8e8343","gameRound":"ff85e29cb4414c89a89829c8411dacc2","collectInformation":{"currency":"EUR","creditAmount":37}}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': 'b5f00dc745f84da3adcd474da161f759',
    'x-h-auth-sig': '4c4gjIruvm+qHmZO+Jc2eFbdH35sr45xVXNW6pDKUAw='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"83020869-abc0-4123-a95e-ee4f5e8e8343","language":"DE","currencyMultiplier":1,"gameRound":"ff85e29cb4414c89a89829c8411dacc2"},"balance":{"totalBalance":6853,"mode":"REAL","currency":"EUR","balances":[{"type":"real","amount":6853,"currency":"EUR"}]},"amountToCollect":40,"amountCredited":37,"gameRoundInfo":{"hash":"ff85e29cb4414c89a89829c8411dacc2","status":"open","stake":100,"mode":"REAL","currency":"EUR","game":"efbdc5b0ef8c434cbf11daab2fda0d5d"},"gameState":[{"hash":"ff85e29cb4414c89a89829c8411dacc2","type":"debit","result":{"winAmount":77},"processedOn":"2023-01-26T11:28:22.810Z"},{"hash":"9e959481e6c8411f88a0fcdb43e9e55f","type":"credit","result":{},"collected":37,"reason":"collect 0.37 EUR","processedOn":"2023-01-26T11:28:23.260Z"}]}',
  responseHeaders: {
    'x-response-id': '23778189-4957-45fe-91f2-704541b11010',
    'x-h-error-id': '0',
    'x-h-repeatcount': '0',
    'x-response-status': 'ok',
    'x-request-id': '90f91efe393f4ca5af621728e11f7227'
  }
}

POST V2_API_ENDPOINT/addWin (mandatory)

This call adds an uncollected (open) win to an open gameround. Optionally, it can also collect the win amount immediately and close the gameround.

request: V2_AddWinRequestBody

response: V2_GameAPIReply

Example

{
  url: '/gameapi/v2/addWin',
  method: 'POST',
  body: '{"token":"d182d578-dcce-4850-b091-205c482c0f58","gameRound":"ff85e29cb4414c89a89829c8411dacc2","rngResult":{"rngCallId":"69cf2876471845ba8e97f3adbdf1d163","result":"test-uncollected","winAmount":10}}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': '9c6c2a59e2e9468d82214839ecf9c45d',
    'x-h-auth-sig': 'tMWdNcBZf+6SwrB9qm74B/uKhbE5qDotugxrwdssqqM='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"d182d578-dcce-4850-b091-205c482c0f58","language":"DE","currencyMultiplier":1,"gameRound":"ff85e29cb4414c89a89829c8411dacc2"},"amountToCollect":89,"gameState":[{"hash":"ff85e29cb4414c89a89829c8411dacc2","type":"debit","result":{"winAmount":77},"processedOn":"2023-01-26T11:28:22.810Z"},{"hash":"9e959481e6c8411f88a0fcdb43e9e55f","type":"credit","result":{},"collected":37,"reason":"collect 0.37 EUR","processedOn":"2023-01-26T11:28:23.260Z"},{"hash":"7ac21c2772124befbcd5c70500f421a8","type":"wager","result":{"winAmount":60},"amountWagered":21,"processedOn":"2023-01-26T11:28:24.037Z"},{"hash":"cfbbf8f2a6554d1c9738ecd14aabbb8a","type":"genericwin","result":{"winAmount":10},"processedOn":"2023-01-26T11:28:24.647Z"}]}',
  responseHeaders: {
    'x-request-id': '5c022f0582f04763b9751ce0aca1e8d9',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/wagerWin (optional)

This call wagers part or all of open winnings. It adds the result as a new open win amount.

request:         V2_WagerWinRoundRequestBody

response: V2_GameAPIReply

Example

{
  url: '/gameapi/v2/wagerWin',
  method: 'POST',
  body: '{"token":"d182d578-dcce-4850-b091-205c482c0f58","gameRound":"ff85e29cb4414c89a89829c8411dacc2","rngResult":{"rngCallId":"c976d024c19e4a76940b7302beb87939","result":"test","winAmount":60},"wagerInformation":{"currency":"EUR","wagerAmount":21}}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': 'b034474af1e242fa8377f6bfa275081e',
    'x-h-auth-sig': 'NTJrcVX3yfgFZdFp9lO7FdSti7UhGbIIsdSJjE3OF/0='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"d182d578-dcce-4850-b091-205c482c0f58","language":"DE","currencyMultiplier":1,"gameRound":"ff85e29cb4414c89a89829c8411dacc2"},"amountCredited":0,"amountToCollect":79,"gameState":[{"hash":"ff85e29cb4414c89a89829c8411dacc2","type":"debit","result":{"winAmount":77},"processedOn":"2023-01-26T11:28:22.810Z"},{"hash":"9e959481e6c8411f88a0fcdb43e9e55f","type":"credit","result":{},"collected":37,"reason":"collect 0.37 EUR","processedOn":"2023-01-26T11:28:23.260Z"},{"hash":"7ac21c2772124befbcd5c70500f421a8","type":"wager","result":{"winAmount":60},"amountWagered":21,"processedOn":"2023-01-26T11:28:24.037Z"}]}',
  responseHeaders: {
    'x-request-id': 'abe54ec392bd47ad8fc142b6e9349380',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/getUncollectedAmount (optional)

This call returns the amount of uncollected (open) winnings.

request:         V2_GetUncollectedAmountRequestBody
response:         V2_GameAPIGetUncollectedAmountReply

Example

{
  url: '/gameapi/v2/getUncollectedAmount',
  method: 'POST',
  body: '{"token":"d182d578-dcce-4850-b091-205c482c0f58","gameRound":"ff85e29cb4414c89a89829c8411dacc2"}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': '9ac31f8269514695b0cf287f3f721843',
    'x-h-auth-sig': '+iT88iL/NZ/QSrN5ovH6Ljr5OwQtFMBtYKGtxvNsklM='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"d182d578-dcce-4850-b091-205c482c0f58","language":"DE","currencyMultiplier":1,"gameRound":"ff85e29cb4414c89a89829c8411dacc2"},"amountToCollect":79}',
  responseHeaders: {
    'x-request-id': '54c06093d0ec405fab2142e0cb770f08',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/addSpinCounterGameState (optional, not needed for RGS-to-RGS)

This call adds a game request with a counter, for example free spins won. It can also consume a counter, for example when the game plays a free spin. When it consumes a counter, the call checks if the game state is available. This check makes sure the game does not play more free spins than it won.

request:         V2_AddSpinCounterGameStateRequestBody
response:         V2_GameAPIAddSpinCounterGameStateReply

Example

{
  url: '/gameapi/v2/addSpinCounterGameState',
  method: 'POST',
  body: '{"token":"d182d578-dcce-4850-b091-205c482c0f58","gameRound":"ff85e29cb4414c89a89829c8411dacc2","counterType":"customspin","rngResult":{"rngCallId":"937bfc0d50c4493fa47ce7221d9afc12","result":{"awarded":10},"winAmount":0}}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': '869a2d200905426f8e09d1fc15d91418',
    'x-h-auth-sig': 'HnjWEUTdQ56mAph4BFgiGfx6mwq+Lwebz2834nk9T0E='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"d182d578-dcce-4850-b091-205c482c0f58","language":"DE","currencyMultiplier":1,"gameRound":"ff85e29cb4414c89a89829c8411dacc2"},"amountToCollect":89,"spinsAvailable":10,"gameState":[{"hash":"ff85e29cb4414c89a89829c8411dacc2","type":"debit","result":{"winAmount":77},"processedOn":"2023-01-26T11:28:22.810Z"},{"hash":"9e959481e6c8411f88a0fcdb43e9e55f","type":"credit","result":{},"collected":37,"reason":"collect 0.37 EUR","processedOn":"2023-01-26T11:28:23.260Z"},{"hash":"7ac21c2772124befbcd5c70500f421a8","type":"wager","result":{"winAmount":60},"amountWagered":21,"processedOn":"2023-01-26T11:28:24.037Z"},{"hash":"cfbbf8f2a6554d1c9738ecd14aabbb8a","type":"genericwin","result":{"winAmount":10},"processedOn":"2023-01-26T11:28:24.647Z"},{"hash":"8531967219184c98a06cba7a009640b8","type":"genericwin","result":{"winAmount":10},"processedOn":"2023-01-26T11:28:24.806Z"},{"hash":"15171253390246f18d889d9d1c18e893","type":"credit","result":{},"collected":10,"reason":"collect 0.10 EUR","processedOn":"2023-01-26T11:28:24.826Z"},{"hash":"9ac37a5ceb754f78a51645fd8a9a316f","type":"customspin","result":{"winAmount":0},"processedOn":"2023-01-26T11:28:25.227Z"}]}',
  responseHeaders: {
    'x-request-id': 'b3a6057f422942918672b6c627921d17',
    'x-response-status': 'ok'
  }
}

POST/getAvailableSpinCounter (optional, not needed for RGS-to-RGS)

This call gets the value of a spin counter. For example, it returns the number of available free spins after an addSpinCountGameState call.

request:         V2_GetAvailableSpinCounterRequestBody
response:         V2_GameAPIGetAvailableSpinCounterReply

Example

{
  url: '/gameapi/v2/getAvailableSpinCounter',
  method: 'POST',
  body: '{"token":"d182d578-dcce-4850-b091-205c482c0f58","gameRound":"ff85e29cb4414c89a89829c8411dacc2","counterType":"customspin"}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': '8e162d3e2081490dbca7db48d84188a2',
    'x-h-auth-sig': 'LZX7T0pRn0ldVtwBfCJ+aBkhL9UfXj6h5S2abngBO2Q='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"d182d578-dcce-4850-b091-205c482c0f58","language":"DE","currencyMultiplier":1,"gameRound":"ff85e29cb4414c89a89829c8411dacc2"},"amountToCollect":104,"spinsAvailable":9}',
  responseHeaders: {
    'x-request-id': '96471d3f90824c4484a288169734bf5e',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/getTokenForGameRound (optional)

This call gets a new token for an open gameround. Use it for janitor or autoclose functions.

Note: This call revokes any existing tokens for the given player, operator, and game. Use this call only in janitor calls.

request:         V2_GetTokenForGameRoundRequestBody
response:         V2_GetTokenForGameRoundReply

Example

{
  url: '/gameapi/v2/getTokenForGameRound',
  method: 'POST',
  body: '{"gameRound":"ff85e29cb4414c89a89829c8411dacc2"}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': 'd5dd1017005d4c3ea9b31301bd7de6c0',
    'x-h-auth-sig': 'JbFPHyWd+EOgn+sCf1/QLK+SeRJuksnoqIze7mz2M4Y='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"d182d578-dcce-4850-b091-205c482c0f58","language":"DE","currencyMultiplier":1,"gameRound":"ff85e29cb4414c89a89829c8411dacc2"}}',
  responseHeaders: {
    'x-request-id': '2c19baca98a4424ab67ffa76bc1d74dc',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/getTokenData(optional)

This call gets token data from a given token ID.

request:         V2_GetTokenDataRequestBody

response: V2_GetTokenDataReply

Example

{
  url: '/gameapi/v2/getTokenData',
  method: 'POST',
  body: '{"token":"cfa822f6-4f53-4ecb-a6f9-647788a6fcd5"}',
  headers: {
    'x-h-auth-id': '000063ea2b200000000000000029',
    'x-h-timestamp': '2023-02-13T14:30:41.130Z',
    'x-request-id': '96317c437f264b3ba2fcd4bf68e8172f',
    'x-h-auth-sig': 'Pb0TjKXo9aAgongzqvAV+C3mz7L2qPspvjhz7y8riCI='
  },
  response: '{"tokenData":{"operatorId":"000063ea2b200000000000000029","playerId":"cd4def34682447ab9b5684340bf25cfe","gameId":"b42a6a2e13554d9cb5c1da72fcb22b8b","mode":"REAL","currency":"EUR","currentToken":"cfa822f6-4f53-4ecb-a6f9-647788a6fcd5","language":"DE","currencyMultiplier":1,"gameRound":"eb6320faf7ac4cdc85ce6f0043573f2f"}}',
  responseHeaders: {
    'x-request-id': 'b6f46c69b7a1454ab2075b67fa220265',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/getLastGameRounds (optional)

This call gets a list of recently closed games.

request: V2_GetLastGamesRequestBody

response: V2_GetLastGamesReply

Example

{
  url: '/gameapi/v2/getLastGameRounds',
  method: 'POST',
  body: '{"token":"d182d578-dcce-4850-b091-205c482c0f58"}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': 'cf64d9f4cb964a14a6c464b74512cf73',
    'x-h-auth-sig': 'b8QF77vhsf7rCp7hNZnHxUV4gBeQ0Nz/rYAdq2SwXYA='
  },
  response: '{"gameRoundList":[{"id":"a016d46dd75b4725baf06d0ef0fdbe7f","status":"closed","timestamp":"2023-01-26T11:28:28.953Z","bet":13,"won":10,"currency":"EUR","gameSpecificDetails":{"result":{"result":"test","rngCallId":"830e8c88405a48b2af5b33f89745084e","winAmount":10}}},{"id":"ed404d20c18b4821880e465b0e41c570","status":"closed","timestamp":"2023-01-26T11:28:28.769Z","bet":13,"won":10,"currency":"EUR","gameSpecificDetails":{"result":{"result":"test","rngCallId":"28732aa1acd3472fa743ef8e6acc36ef","winAmount":10}}}]}',
  responseHeaders: {
    'x-response-id': '25b52b253ab543239d8490d32b6a63cd',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/getRandomResult (conditional)

This call gets random integers or doubles within a given range from the hizi.io certified RNG.

When is this required? This call is required only when the game logic runs inside the hizi.io RGS. In this case, the game logic must obtain its randomness from hizi.io for compliance. This applies to direct game engine integrations hosted by hizi.io. It also applies to a partner RGS hosted within the hizi.io RGS ("RGS inception").
A classic RGS-to-RGS integration does not call this endpoint. In the typical RGS-to-RGS case, your RGS runs on your own infrastructure and uses your own certified (for example, provably-fair) RNG. Keep using your own RNG. Pass its results in the rngResult fields of /startGameRound, /addWin, and other calls. You run your own certification on your own infrastructure. hizi.io is not involved in your certification. hizi.io provides no certification suite (for example, core-docker) for it. No part of hizi.io expects /getRandomResult calls from such integrations.

request:         V2_GetRandomResultRequestBody

response: V2_GameAPIRngReply

Example

{
  url: '/gameapi/v2/getRandomResult',
  method: 'POST',
  body: '{"token":"123162d0-315d-474b-930c-7e43625c2ae3","rngEndPoint":"getDoubles","rngPayload":{"min":1,"max":10,"count":2}}',
  headers: {
    'x-h-auth-id': '000063d0ef400000000000000029',
    'x-h-timestamp': '2023-01-26T11:43:58.115Z',
    'x-request-id': '7f0fab897ea745d1a82b79934ee93b6d',
    'x-h-auth-sig': 'kLiIcxtblFF2+c9g5zUmKrNoOZFpqeO7ODXZGUklVSg='
  },
  response: '{"values":[3.068702629156329,9.509780327419449],"tokenData":{"operatorId":"000063d0ef400000000000000029","playerId":"9f1cfa5dfcbd4946817675ecbccc26c5","gameId":"f1252f6014084e1cbf5bb1982f911e0c","mode":"REAL","currency":"EUR","currentToken":"123162d0-315d-474b-930c-7e43625c2ae3","language":"DE","currencyMultiplier":1}}',
  responseHeaders: {
    'x-response-id': '0c83abf945a14e78ab8babaa4b96005b',
    'x-response-status': 'ok',
    'x-request-id': 'c95a958b11614905b932aa7dce9d695d'
  }
}

GET V2_API_ENDPOINT/getOperatorSettings (optional)

This call gets operator-specific settings.

request:         V2_GetOperatorSettingsQuery

response: V2_GameSettings

Example

 {
  url: '/gameapi/v2/getOperatorSettings?game=f1252f6014084e1cbf5bb1982f911e0c-unk&operator=000063d0ef400000000000000029-unk&currency=EUR',
  method: 'GET',
  body: undefined,
  headers: {
    'x-h-auth-id': '000063d0ef400000000000000029',
    'x-h-timestamp': '2023-01-26T11:43:58.115Z',
    'x-request-id': 'e67161f5bc354717871b021144945154',
    'x-h-auth-sig': 'D3p/3TU6q3DYGZ56TtFXVDog5UU4uVRw38FrMVd1ru4='
  },
  response: '{"autoplayEnabled":true,"autoplayLossLimitRequired":false,"displayCoins":true,"displayJackpotOdds":false,"displayRTP":false,"displayXRTP":false,"forceOrientation":0,"gambleEnabled":true,"historyURL":"","homeURL":"","loadMsg":"","maxExposure":25000000,"multipleInstancesAllowed":false,"rcDisplayWinLoss":false,"rcEnabled":false,"stopEnabled":true,"topupURL":"","turboEnabled":true,"homeEnabled":true,"dynamicMinSpinTime":false,"redirectTarget":"top","packageBuyEnabled":true}',
  responseHeaders: {
    'x-response-id': '475c54c307174c2a98d86b190feebb09',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/getBalance (optional)

This call gets the player's balance.

request: V2_GetTokenDataRequestBody

response: GameAPIBalanceReply

Example

{
  url: '/gameapi/v2/getBalance',
  method: 'POST',
  body: '{"token":"cfa822f6-4f53-4ecb-a6f9-647788a6fcd5"}',
  headers: {
    'x-h-auth-id': '000063ea2b200000000000000029',
    'x-h-timestamp': '2023-02-13T14:30:41.130Z',
    'x-request-id': '96317c437f264b3ba2fcd4bf68e8172f',
    'x-h-auth-sig': 'Pb0TjKXo9aAgongzqvAV+C3mz7L2qPspvjhz7y8riCI='
  },
  response: '{"totalBalance":6816,"mode":"REAL","currency":"EUR","balances":[{"type":"real","amount":6816,"currency":"EUR"}]}',
  responseHeaders: {
    'x-request-id': 'b6f46c69b7a1454ab2075b67fa220265',
    'x-response-status': 'ok'
  }

Calls provided by API V2 ​

Introduction ​

Game frontend calls ​

GET V2_API_ENDPOINT**/status (optional)** ​

GET V2_API_ENDPOINT**/connect (mandatory to use)** ​

GET V2_API_ENDPOINT**/reconnect (optional)** ​

GET V2_API_ENDPOINT**/disconnect (optional)** ​

Game engine / RGS calls ​

Signing RGS requests ​

Mandatory request headers ​

Response headers ​

POST V2_API_ENDPOINT**/testPing (optional)** ​

POST V2_API_ENDPOINT**/startGameRound (mandatory)** ​

POST V2_API_ENDPOINT**/endGameRound (mandatory)** ​

POST V2_API_ENDPOINT**/getGameRoundInfo (optional)** ​

POST V2_API_ENDPOINT**/getGameRoundHistoryInfo (optional)** ​

POST V2_API_ENDPOINT**/voidGameRound (optional)** ​

POST V2_API_ENDPOINT**/collectWin (optional)** ​

POST V2_API_ENDPOINT**/addWin (mandatory)** ​

POST V2_API_ENDPOINT**/wagerWin (optional)** ​

POST V2_API_ENDPOINT**/getUncollectedAmount (optional)** ​

POST V2_API_ENDPOINT**/addSpinCounterGameState (optional**, not needed for RGS-to-RGS**)** ​

POST**/getAvailableSpinCounter (optional**, not needed for RGS-to-RGS**)** ​

POST V2_API_ENDPOINT**/getTokenForGameRound (optional)** ​

POST V2_API_ENDPOINT**/getTokenData(optional)** ​

POST V2_API_ENDPOINT**/getLastGameRounds (optional)** ​

POST V2_API_ENDPOINT**/getRandomResult (conditional)** ​

GET V2_API_ENDPOINT**/getOperatorSettings (optional)** ​

POST V2_API_ENDPOINT**/getBalance (optional)** ​

Example ​

Calls provided by API V2

Introduction

Game frontend calls

GET V2_API_ENDPOINT/status (optional)

GET V2_API_ENDPOINT/connect (mandatory to use)

GET V2_API_ENDPOINT/reconnect (optional)

GET V2_API_ENDPOINT/disconnect (optional)

Game engine / RGS calls

Signing RGS requests

Mandatory request headers

Response headers

POST V2_API_ENDPOINT/testPing (optional)

POST V2_API_ENDPOINT/startGameRound (mandatory)

POST V2_API_ENDPOINT/endGameRound (mandatory)

POST V2_API_ENDPOINT/getGameRoundInfo (optional)

POST V2_API_ENDPOINT/getGameRoundHistoryInfo (optional)

POST V2_API_ENDPOINT/voidGameRound (optional)

POST V2_API_ENDPOINT/collectWin (optional)

POST V2_API_ENDPOINT/addWin (mandatory)

POST V2_API_ENDPOINT/wagerWin (optional)

POST V2_API_ENDPOINT/getUncollectedAmount (optional)

POST V2_API_ENDPOINT/addSpinCounterGameState (optional, not needed for RGS-to-RGS)

POST/getAvailableSpinCounter (optional, not needed for RGS-to-RGS)

POST V2_API_ENDPOINT/getTokenForGameRound (optional)

POST V2_API_ENDPOINT/getTokenData(optional)

POST V2_API_ENDPOINT/getLastGameRounds (optional)

POST V2_API_ENDPOINT/getRandomResult (conditional)

GET V2_API_ENDPOINT/getOperatorSettings (optional)

POST V2_API_ENDPOINT/getBalance (optional)

Example