Operator API Reference

This page renders every call, callback and schema of the Operator API from the OpenAPI 3.0 specification. Each operation has its own page. Each page shows the parameters, request and response schemas, examples and code samples for that operation.

The prose documentation under Operator API is the normative source. If this reference page disagrees with the prose, the notes in the spec and the prose take priority.

v1.8.9

hizi.io Operator API

Download OpenAPI Document

Server-to-server API between the hizi.io RGS (remote game server) and a casino operator (or aggregator) backend — game launch, player management, wallet transactions, free plays, discounts, backoffice reporting and health checks.

Two directions in one document

The protocol is bidirectional, and this document describes both halves. Use the tags to tell them apart:

Operator → hizi.io (tags Operator → hizi.io, Free Plays,
Backoffice, Health & Certified Hash) — endpoints hizi.io
implements and the operator calls. They live under the RGS base URL
([api-endpoint-url], supplied by hizi.io support).
hizi.io → Operator (tag hizi.io → Operator) — endpoints the
operator implements and hizi.io calls (the wallet/callback API). Each
of those operations carries its own servers entry pointing at the
operator's base URL, which is configured in the hizi.io backoffice.

Only getGameURL is mandatory for the operator to call; on the callback side getBalance and doTransactions are mandatory to implement, while logEvent, doGameRoundReport, doGameRoundResult and reportAnimationEnd are optional and only sent when enabled for the operator account.

Transport rules

HTTPS only — plain HTTP is not supported. * GET calls pass their parameters as URL-encoded query parameters, POST
calls send a JSON body with Content-Type: application/json.
Character set is always UTF-8; responses are application/json. * IP whitelisting may be in place in both directions. * CORS policies may apply.

Amounts are always 1/100 of the base currency

Every monetary value — bets, wins, balances, stakes, discounts — is an integer expressed as 1/100 of the base currency (a fixed ×100 factor), never a decimal: €10.00 is 1000, €1.50 is 150. This is a fixed 1/100 convention, not the currency's ISO minor unit (JPY and CLP have none, a few currencies use 1/1000) — hizi always expects 1/100 of the base currency. See the Amount schema.

Authentication

Every call in both directions is authenticated with three request headers — X-H-AUTH-ID, X-H-AUTH-SIG and X-H-TIMESTAMP — modelled here as three apiKey security schemes that must all be present. The signature is a base64-encoded SHA-256 HMAC over a #-joined list of request fields; the exact field list differs per operation and is given in each operation's description. See the hiziAuthSignature security scheme for the algorithm.

Errors

A call is successful only if it returns HTTP 200 and carries no X-H-ERROR-ID response header. A 200 with X-H-ERROR-ID present must be treated exactly like a 400. On a non-200 response the body may additionally carry an errorCode object. The full error-code catalogue is in the ErrorCode.id description and, machine-readable, in the top-level x-error-codes extension.

Not covered by this document

Appendix A — Events. The browser-side postMessage protocol between
the game iframe and the operator lobby (spin, turbo, roundStarted,
balance, …) is not an HTTP API and therefore cannot be expressed in
OpenAPI. It is documented separately at
https://docs.hizi.io/operator-api/appendix-a-events.
Appendix C — Game settings are not endpoints; they are modelled as the
GameSettings and GameVariables schemas, passed to getGameURL.
Appendix E — Discounts has no endpoint of its own; it is the
DiscountInfo schema returned alongside a balance by getBalance and
doTransactions.
Endpoints documented as "work in progress" have no published request or
response shape and are deliberately omitted rather than guessed at:
getGameHealth, getGameRoundState, forceCloseGameRound,
backoffice/getGameCriticalFiles, registerFreeroundTemplate,
getFreeroundTemplate, removeFreeroundTemplate. Contact hizi.io
support for details.

Contact

hizi.io support

External Documentation

Operator API documentation (normative source for this spec)

Servers

https://{apiEndpointUrl}hizi.io RGS endpoint, used for every Operator → hizi.io call (including the backoffice, free-play and health endpoints). The concrete host is supplied by hizi.io support and differs per environment.