Appearance
Start a gameround and debit the bet
POST
/startGameRound
Mandatory. Starts a new gameround and debits the bet. Optionally it
can credit winnings and close the gameround immediately (endGame),
and can close any existing open gameround and collect its open
winnings first (closeOpenGame).
This is the entry point of the round state machine: it is the call that
creates the gameround hash returned as gameRoundInfo.hash (and as
tokenData.gameRound), which all subsequent round calls reference.
rngResultcarries the result of the RNG that produced the outcome —
your own certified RNG for a classic RGS-to-RGS integration, or the
result ofPOST /getRandomResultfor a hizi.io-hosted engine.debitInformation.debitAmountis the already-multiplied stake in
player-currency minor units (or the feature price on a buy-feature
round).- To consume a freeplay set
debitInformation.useTicketInfo.useTicket = true; the reply carries
updatedfreePlayInfo/freePlaysAvailable. externalGameProviderRoundIdmust not exceed 32 characters.
Retry semantics: idempotent on the transaction hash while the round
is open. On a lost response, query with POST /getGameRoundInfo rather
than blindly repeating the debit.
Authorizations
V2AuthId
Game provider ID assigned by hizi.io (Hinterzimmer). Identifies which
shared secret the signature must be verified against. Mandatory on
every game engine / RGS call.
Type
API Key (header: X-H-AUTH-ID)
V2Signature
HMAC signature of the request. OpenAPI cannot express a computed
signature, so the scheme is modelled as an apiKey header; the value
is derived per request as follows.
You need a shared secret, which you can retrieve by logging in to the
hizi.io backoffice with your credentials. The signature is a
base64-encoded SHA-256 HMAC digest of a defined set of request
parameters, joined with a hash character (#). This allows the secret
to be shared without ever being sent in the request. A timestamp
(X-H-TIMESTAMP) must also be supplied as a request header and is part
of the signed data.
Outbound (you → hizi.io RGS) — the fields signed are the
serialised JSON body and the timestamp:
X-H-AUTH-SIG = base64(
HMAC_SHA256( secret, [ JSON.stringify(body), X-H-TIMESTAMP ].join('#') )
)
See the Signing appendix for a complete
reference implementation.
Inbound (hizi.io RGS → your backendQueue) — same primitive, but
the RGS signs a fixed, per-endpoint ordered list of scalar fields
and the body is not hashed. The secret is used both as the HMAC key
and as the first element of the signed string:
X-H-AUTH-SIG = base64( HMAC_SHA256( secret, fields.join('#') ) )
| endpoint | fields (in order) |
|---|---|
GET /getGameConfiguration |
[ secret, X-H-AUTH-ID, X-H-TIMESTAMP, currency ] |
POST /getGameResult |
[ secret, X-H-AUTH-ID, X-H-TIMESTAMP, gameRound ] |
A wrong signature is reported as HTTP 401 / error code 1001
(SIGNATUREWRONG) and must not be retried.
The header family is shared with the Operator API, which documents the
same base64/SHA-256-HMAC/#-joined construction; the set of signed
fields differs per API and per direction, so do not assume a signer
written for one is reusable for the other without checking the field
list.
Type
API Key (header: X-H-AUTH-SIG)
V2Timestamp
ISO 8601 timestamp of the request (e.g. 2023-01-26T11:28:21.429Z).
Mandatory, and included in the signed data of X-H-AUTH-SIG.
Type
API Key (header: X-H-TIMESTAMP)
Parameters
Header Parameters
X-Request-Id*
Unique ID identifying the call in the logs. Documented as a mandatory
request header for all game engine / RGS calls.
Note: the reference implementation in the
Signing appendix additionally sets
X-Response-Id (a fresh UUID) and, when relaying a request,
X-Forwarded-Response-Id.
Type
Requiredstring
Example
"8c00b93dd861405cbeb7c14fded1e72a"Request Body
application/json
JSON "token": "83020869-abc0-4123-a95e-ee4f5e8e8343", "rngResult": { "rngCallId": "5cd23259ea4c49e7b955e79321da4365", "result": "test", "winAmount": 0 }, "debitInformation": { "debitAmount": 100, "currency": "EUR" }, "endGame": true
{
}
Responses
Round started. gameRoundInfo.status is open, or closed when
endGame was true. amountToCollect is the open (uncollected)
win, amountCredited what was credited in this call.
application/json
JSON "tokenData": { "operatorId": "string", "playerId": "string", "gameId": "string", "mode": "string", "currency": "EUR", "currentToken": "string", "gameRound": "ff85e29cb4414c89a89829c8411dacc2", "walletMode": "string", "language": "DE", "currencyMultiplier": 1, "device": "string", "commonDraw": "string" }, "balance": { "totalBalance": 0, "mode": "string", "currency": "EUR", "balances": [ { "type": "real", "currency": "EUR", "amount": 0 } ], "discountInfo": { "text": "string", "currency": "EUR", "discounts": [ { "stake": 0, "absoluteDiscountAmount": 0, "spinsRemaining": 0 } ], "campaignId": "string", "validFrom": "string", "validTo": "string" }, "tickets": [ { "count": 0, "stake": 0, "currency": "EUR", "price": 0, "feature": "string", "serial": "string" } ], "ticketInfo": { "used": 0, "granted": 0, "won": 0, "isLast": true, "promotions": { "protocolVersion": 0, "data": "string" }, "serial": "string" } }, "gameRoundInfo": { "hash": "ff85e29cb4414c89a89829c8411dacc2", "status": "open", "stake": 0, "baseStake": 0, "mode": "string", "currency": "EUR", "game": "string", "currencyMultiplier": 0, "commonRoundHash": "ff85e29cb4414c89a89829c8411dacc2" }, "commonGameRoundInfo": { "additionalProperties": "string" }, "gameState": [ { "hash": "ff85e29cb4414c89a89829c8411dacc2", "type": "debit", "processedOn": "string", "result": { "winAmount": 0, "info": { "additionalProperties": "string" } }, "amountWagered": 0, "collected": 0, "reason": "collect 0.37 EUR" } ], "amountToCollect": 0, "amountCredited": 0, "freePlayInfo": { "used": 0, "granted": 0, "won": 0, "isLast": true, "promotions": { "protocolVersion": 0, "data": "string" }, "serial": "string" }, "freePlaysAvailable": [ { "currency": "EUR", "stake": 0, "count": 0, "feature": "string", "serial": "string" } ], "passThroughData": { "additionalProperties": "string" }, "promoWinInfo": { "referenceId": "string" }
{
}