Calls to be implemented by games

General

To supply information about games, health, and automatic closing of games, the engine must listen for the calls below. The engine must respond to each call.

Authenticating the calls you receive from the RGS

The RGS signs the calls it sends to your backendQueue. It uses the shared secret associated with the X-H-AUTH-ID in the request. This is a different construction from the outbound direction, documented in the Signing appendix (the outbound direction signs the JSON body). For the inbound calls below, the RGS signs a fixed, per-endpoint ordered list of scalar fields. The RGS does not hash the request body itself.

The following request headers are sent:

header	comment
X-H-AUTH-ID	Identifies the shared secret used to verify the signature.
X-H-TIMESTAMP	ISO timestamp. The RGS includes it in the signed string.
X-H-AUTH-SIG	Signature. The RGS includes it on the signed endpoints below.

Calculate the signature with the same primitive as the outbound direction:

X-H-AUTH-SIG = base64( HMAC_SHA256( secret, fields.join('#') ) )

secret is the shared secret. fields is the per-endpoint list below. The secret serves two roles. It is the HMAC key. It is also the first element of the signed string.

endpoint	signed	fields (in order)
GET /getGameConfiguration	yes	[ secret, X-H-AUTH-ID, X-H-TIMESTAMP, currency ]
POST /getGameResult	yes	[ secret, X-H-AUTH-ID, X-H-TIMESTAMP, gameRound ]
GET /health	no	Liveness probe. The endpoint does not require a signature. Leave it open to all IPs.
GET /certifiedfiles	no	Informational. The endpoint does not require a signature. Leave it open to all IPs.
POST /doAutoClose	no	Not signed. See the doAutoClose section.

For getGameResult, the RGS signs only the gameRound value, not the full JSON body.

health and certifiedfiles are intentionally unauthenticated. Make them reachable from any IP. External monitoring tools and certification bodies use them. Do not restrict them to the RGS egress range.

GET ${backendQueue}/certifiedfiles [optional, mandatory for some jurisdiction]

This call must return information about certified components, with hashes. It takes no parameters.

Example of response (JSON)

{
    "list": [
        {
            "file": "./dist/certified/certifiedLogic.js",
            "hash": "e6a01ef0f88b1cac2696ce30166fca0bf6b6c793"
        },
        {
            "file": "./dist/certified/certifiedGameSettings.js",
            "hash": "1409450b798f0ac552ea1c128ff40b0f137e3f38"
        }
    ]
}

GET ${backendQueue}/getGameConfiguration [optional, mandatory for freeplay]

This call must return the game configuration. The response must include the allowed stakes.

The RGS sends the following parameters as URL (query) parameters.

Message.query['currency']
message.query['currencyMultiplier']
message.query['gameCode']

The call must return a JSON structure. Example:

{
  "config": {
    "stakes": [
      10,
      20,
      50,
      100,
      200,
      500,
      1000,
      2000,
      5000,
      10000
    ],
    "currency": "EUR",
    "currencyMultiplier": 1,
    "expectedRtp": 96.19,
    "oneHundredXOdds": 5522,
    "maxWinOdds": 103680,
    "maxPayout": 1000,
    "maxPayoutOdds": 2488327800,
    "maxExposure": 10000000,
    "calculatedMaxExposure": 10000000,
    "operator": "internal_testoperator",
    "winlineCount": 5
  },
  "gameCode": "game-bells"
}

Note: The game engine must return these mandatory fields: stakes, currency, currencyMultiplier, expectedRtp, maxPayoutOdds, and the top-level gameCode. All other fields in the sample above (oneHundredXOdds, maxWinOdds, maxPayout, maxExposure, calculatedMaxExposure, operator, winlineCount) are optional. This call can be mandatory for some operators.

Note: This call is mandatory if the operator supports freeplays.

How currencyMultiplier and stakes relate

The getGameConfiguration call receives currency and currencyMultiplier as query parameters. currencyMultiplier is a currency conversion factor, similar to an exchange rate (for example: EUR 1, USD 1, BRL 6, JPY 150). You apply it once, when you build the stake ladder:

stakes = baseStakes.map(s => s * currencyMultiplier)

The same factor scales maxStake, minStake, and maxPackageStake. The resulting stakes are the amounts the player actually stakes. hizi engine expresses these amounts in the player's currency minor units (×100, see Basics).

Do not apply currencyMultiplier a second time to transaction amounts. The debitInformation / creditInformation amounts you send in startGameRound (and related calls) are already in the player's currency minor units. These are the already-multiplied stake amounts. Do not multiply them again. debitInformation.debitAmount must equal the chosen stake (or the feature price on a buy-feature round). Never send the pre-multiplier base stake.

baseStake (seen in gameRoundInfo and round history) is not stake ÷ currencyMultiplier. For a normal round, baseStake equals stake. baseStake differs from stake only on buy-feature rounds. On a buy-feature round, the debited transaction amount is the feature price, and baseStake records the underlying stake. Both stake and baseStake use the same scale: player currency, already multiplied, minor units.

GET ${backendQueue}/health [mandatory]

This call must return an HTTP status code of 200. It must also return a JSON structure with information about game health, in a free format. You can also use this call for testing.

POST ${backendQueue}/getGameResult [mandatory]

The RGS uses this call to get an HTML representation of a game result. The RGS proxies the call back to a request from an operator. Include externalPlayerId in the response, so the result matches the information in the operator's support systems.

Request body

attribute	comment
externalPlayerId	Player ID on the operator side.
operatorName	Friendly name of the operator.
gameRound	Hash of gameround.
gameRoundDetails	All information stored in the hizi.io database.
short	Boolean (true or false). If not set, or set to false, return a representation you can show to the player. Some operators use this for in-game history.

Response (example)

The response is a JSON object. It has the key msg. The value of msg is an HTML representation of the game result.

{
 msg: '<html>...</html>'
}

POST ${backendQueue}/doGetGameHistory [optional]

You can use this command to display in-game history of game events. Contact hinterzimmer support to enable this command. They can give you more details.

---

POST ${backendQueue}/doAutoClose [mandatory, also for RGS-to-RGS]

The hizi.io janitor task sends this call to the game engine. Most operators require the game engine to close (auto-close) open gamerounds after a given time span. This time span is normally between 12 and 48 hours. The game engine must listen for this call. If the gameround is open and can be closed, the game engine must run a close or autoplay routine.

The doAutoClose request must produce the same result as when a player reloads the game and continues the gameround.

The game engine must run the normal flow. The game engine must pay out potential winnings. The game engine must send a request to end the gameround.

Request body

attribute	comment
gameRound	Hash of the gameround to close.
gameSettings	Game settings for the operator and currency of the gameround.

Response

The response is a JSON structure in free format. The HTTP status code shows whether the gameround closed. 200 means success. Any other status code means an error.

Authentication: The doAutoClose request carries X-H-AUTH-ID and X-H-TIMESTAMP. The RGS does not sign this request (no X-H-AUTH-SIG). Use X-H-AUTH-ID to attribute the call. Use it to match the referenced open gameRound on your side. We recommend that you also restrict this endpoint to the RGS egress IP range. This is a recommendation, not a requirement.

Notes: This call does not carry a player or session token (this is separate from the request signature). The game must request a token for further API calls. See the getTokenForGameRound call.

When your engine receives this call, you can use any V2 calls to get information about the gameround, for example collectWin.

---