Appearance
Add an uncollected (open) win to a gameround
POST
/addWin
Mandatory. Adds an uncollected (open) win to an open gameround.
Optionally collects the win amount immediately and closes the gameround
(collect).
The win is recorded in gameState as a genericwin entry and raises
amountToCollect.
Retry semantics: if the response is lost, do not blindly repeat
the call. Query POST /getGameRoundInfo; if the round shows closed
with the expected win, log success, and if it shows open, close it
with POST /endGameRound. Only 5xx failures should be retried.
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": "string", "gameRound": "ff85e29cb4414c89a89829c8411dacc2", "rngResult": { "rngCallId": "string", "result": "string", "winAmount": 0, "betData": { "additionalProperties": "string" } }, "collect": true, "externalGameProviderTransactionId": "string", "jackpotPayout": [ { "jackpotId": "string", "jackpotMode": "string" } ]
{
}
Responses
Win added; new open amount in amountToCollect.
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" }
{
}