Operator API

The Operator API is the server-to-server integration for casino operators that integrate with hizi.io. It covers game launch, player management and transactions, in real-money or demo mode.

Amounts are always 1/100 of base currency

Every monetary value in this API is an integer. This includes bets, wins, balances, stakes, and discounts. The API always expresses the value as 1/100 of the base currency (a fixed ×100 factor), never as a decimal. For example, the API sends €10.00 as 1000, and €1.50 as 150.

This is a fixed 1/100 convention, not the currency's ISO minor unit. Some currencies have no minor unit (for example JPY, CLP). A few currencies use 1/1000. Hizi always expects 1/100 of the base currency. Never send or expect fractions or decimals. See the amount type for the full definition.

Scope

The Operator API provides a standardized, TypeScript-based interface. Game clients use this interface to integrate with casino operators and aggregators. The API is reliable and easy to use. It manages game states, player interactions, and communications with the backend. It supports real-money mode and demo mode.

Key functions include server-to-server calls. The API uses these calls to launch games, query balances, and process transactions (for example debits, credits, and voids). The API also handles events, such as spins, errors, and reality checks. It supports an event-based protocol for two-way communication. This protocol uses post messages between game iframes and operator lobbies. The protocol keeps operations secure and idempotent. It includes robust error handling and authentication.

Built-in compatibility with major aggregators supports deployments across multiple operators. The API also offers methods for game control. It offers optional backoffice calls for configuration and statistics.

See Response Codes & Error Codes for the full reference. It lists the HTTP return codes, response headers, and error codes for these calls.

The Parts of the API

The API consists of several parts.

Server to server calls

The operator server sends calls to the hizi.io server.

The hizi.io server sends calls to the operator server.

All calls use HTTPS (hizi does not support HTTP). Authenticate each call with one of the supported methods. For GET calls, always use URL-encoded parameters. For POST calls, set the Content-Type header field to application/json. Always use UTF8 as the character set. Note that CORS policies may apply. The response content type is application/json.

This section outlines the basic flow. Additional calls may be possible. See the detailed documentation in this document.

Post Messages between game iFrame and operator lobby (embedding site)

The game client sends Post Messages to the operator lobby.

The operator lobby sends Post Messages to the game client.

Game client implementation

The game client sends calls to the hizi.io game server. Game developers only need this section.

Backoffice calls

Use these calls to configure settings and game parameters. You can also access this functionality through the hizi.io Operator back office. These calls are optional. You can make all settings in the back office instead.

What's In This Section

• OpenAPI Reference: Every call and callback, with parameters, schemas, examples, and copy-paste code samples (Browse the API Reference).
• Game Launch & Sessions: The calls that launch a game in real-money mode or demo mode, and that manage the game state (Operator → hizi.io).
• Players & Transactions: The calls that query a balance and that process debits, credits, and voids (hizi.io → Operator).
• Event Protocol: The two-way post messages between the game iframe and the operator lobby, for spins, errors, and reality checks (Appendix A: Events).
• Backoffice Calls: The optional calls that return configurations and statistics for your integration (Appendix B: Backoffice Calls).
• Game Settings Parameters: The full reference of the settings you can pass at launch, such as autoplay, orientation, and display of the RTP (Appendix C: Game Settings).
• Freeplays & Discounts: How to grant freeplays and how to apply discounts for player promotions and campaigns (Appendix D: Freeplays).
• Discounts: How to return discount information with a balance response, so that hizi.io applies your own promotions to later transactions (Appendix E: Discounts).
• Health & Certified Hash: The health-check and certified-hash calls for monitoring and for verification by a regulator (Appendix F: Health & Certified Hash).
• Response & Error Codes: The HTTP return codes, the response headers, and the error codes in the X-H-ERROR-ID field (Response Codes & Error Codes).

OpenAPI Specification

This site provides a machine-readable OpenAPI 3.0 specification. The specification covers every documented call, callback, and data type on this page. Point your tooling (codegen, request collections, or LLM/agent integrations) at https://docs.hizi.io/operator-api/openapi.yaml. This site generates the spec from this prose documentation. The spec notes a few places where the source docs are ambiguous or contradictory. Where a note and the spec's own types conflict, treat the note as authoritative.

This site also renders the same spec as a browsable OpenAPI Reference, with one page per operation.