Integration

Conventions

Requests and responses#

Server calls are POST with Content-Type: application/json and a JSON object body.
Success answers contain "status": "ok" plus the result fields.
Errors are {"status":"error","message":"<CODE>"} with an HTTP status that depends on the code. message is always an upper-case code; see the error reference. A failure without a public code is REQUEST_FAILED.
Answers are sent with Cache-Control: no-store.
Public GET endpoints return JSON as well: /games/health, /capabilities, /health, /docs/openapi.json.

HTTP	Typical meaning
200	Success
400	Validation error or a business rule (`INVALID_REQUEST`, `PROJECT_BET_LIMIT`, …)
401	`UNAUTHORIZED`
403	`IP_NOT_ALLOWED` (or `FORBIDDEN`)
404	Unknown game or record (`UNSUPPORTED_GAME`, `GAME_NOT_FOUND`, `GRANT_NOT_FOUND`, `OUTCOME_NOT_FOUND`)
409	`IDEMPOTENCY_CONFLICT`, `DUPLICATE_EXTERNAL_ID`

Idempotency#

POST /playGame.do and POST /gameActions.do accept the optional header Idempotency-Key: 1 to 128 printable ASCII characters (no spaces).

The key is scoped to your project and to the method.
Repeating a request with the same key and the same body returns the first answer without doing the work again.
The same key with a different body is answered with HTTP 409 IDEMPOTENCY_CONFLICT.
The api_key field is not part of the comparison.
A malformed key gives HTTP 400 INVALID_IDEMPOTENCY_KEY.
Without the header the call is executed every time. For freespins_create and outcome_schedule the external_id field also protects against duplicates (DUPLICATE_EXTERNAL_ID).

Amounts#

Context	Format
Wallet callbacks	JSON number with up to 2 decimals (`12.5`, `100`)
`bet`, `total_win` of free spins	Decimal string, up to 2 decimals (`"1.00"`)
`min_minor`, `max_minor`	String of digits, minor units

At most two decimals are accepted and at most 13 digits before the point; leading zeros are not allowed. Amounts are exact — parse them with a decimal type, not floating point.

Dates and times#

expires_at, created_at, finished_at and similar fields are ISO 8601. When you send expires_at it must include a zone (Z or +02:00), for example 2026-11-01T12:00:00Z.
Wallet callbacks carry Unix timestamps in seconds (meta.time, timestamp).

Identifiers#

Id	Where it comes from
`player_id`	Chosen by you (1–128 characters)
`session_id`	Returned by the launch method
`round_id`	Generated by the platform; appears in wallet callbacks and the admin Game History
`meta.transaction`	Unique id of each wallet operation (`bet`, `win`)
`grant_id`, `outcome_id`	UUIDs generated by the platform
`external_id`	Optional id of your own for grants and outcomes, unique within the project (1–128 printable characters without spaces)

Unknown fields#

The launch method rejects fields it does not know with INVALID_REQUEST. Send only the documented fields.

Time-outs and retries from your side#

Use a client time-out of about 10 seconds; on a time-out or a 5xx, repeat the call with the same Idempotency-Key.