v.1.11.5

Change log

Version	Changes
v1.11.0	- Updated response codes and error handling. - Added non-zero bet configuration option for rounds with standard zero bet amounts. - Minor fixes.
v1.11.1	Added parameter fr_finished to transactions.
v1.11.2	Added init parameter countryCode.
v1.11.3	Added new transaction method for single withdraw and deposit processing.
v1.11.4	- Removed deprecated methods. - Changed chapter intros and descriptions.
v1.11.5	Added rtp field to GET games response.

Introduction

This API provides Seamless wallet integration between Gamzix and your Casino. The API consists of three parts: Games API, Wallet API (including bonuses), and optional Free Rounds API.

It is important to note that one player can only have one currency (monowallet).

OpenAPI Documentation

OpenAPI documentation is available at: https://api.gamzix.com/api/v1/v13

The documentation includes endpoints for the Games API, Free Rounds API, and Rounds Report, as well as the ability to generate signatures for POST requests.

Required data for integration

Given by Gamzix

Name	Description	Example
gamzix_url	Gamzix API URL	https://api.gamzix.com/:casino_id/api
password	Message signature key	GoF4GdKcN65e5Ni11dVf7V6m

Given by Casino

Name	Description	Example
casino_url	Casino API URL	https://yoursite.com/the/api
casino_ip[ ]	Casino IP white list	127.0.0.1, 192.168.0.1

Communication format

Gamzix request URL to Casino starts with [casino_url]
Casino request URL to Gamzix starts with [gamzix_url]
All requests are GET or POST
All message bodies are JSON
Messages include Content-Type: application/json HTTP header
Response bodies contain a status field
Messages containing HTTP body such as HTTP POST requests must be signed for authentication.
Date format YYYY-MM-DD
DateTime format is ISO-8601 extended format (YYYY-MM-DDThh:mm:ss)
Time format hh:mm:ss in GMT(UTC) time zone
If a request is unsuccessful (status !== 200 || 201) its response will contain an error field with the type of error and a message field with the error description
All currencies in messages are based on ISO-4217 format – 3 uppercase letters: USD, EUR, etc.
All languages in messages are based on ISO-639-1 format – 2 lowercase letters: en, es, it, etc.
All requests are sent using HTTPS protocol.

Money format

Currencies are in ISO-4217 standard format.

Currencies are converted into related precision to maintain integer value. Casino must transform value conforming to the related precision with the currency required.

Currency	Precision
EUR	2
CLP	0
USD	2
COP	2
JOD	3

Mobile and desktop slot games

All games are presented in both mobile and desktop versions. Gamzix requires a query parameter client and launches the corresponding game client (mobile or desktop) depending on it.

About parameter "home"

The parameter "home" has three use cases, depending on its value, the game client reacts differently:

"home" is empty or undefined – the game client hides the button “home”;
"home" = “closePopup” – this case is to handle the game client is opened on a platform’s iframe and the button “home” is pressed;
"home" is something else – this case is to handle the game client is opened on a separate page and user has to return to a platform site

Balance management

Gamzix does not manage the player's balance, but may store the balances received from the Casino

Response status codes

The only acceptable HTTP status codes are 200 or 201
API status codes are contained in the response body
Status codes are similar to the HTTP status codes:
- The 200 or 201 codes mean a response with successfully processed request;
- The 4XX codes mean bad request;
- The 500 code means something bad and unexpected has happened;

Code	Description
200, 201	Successful Response
400	Bet limit reached
401	Signature invalid
402	Insufficient Funds
403	Game not allowed, Session expired
404	Page not found, Transaction not found
405	User is blocked
406	Withdraw operation already has a deposit action
409	Something went wrong
422	Unprocessable Entity (some parameter is invalid)
429	Too many requests
430	Freerounds not found
500	Server error, Unknown Error, Transactions declined

Authentication

It’s highly recommended to authenticate messages at the prod stage. x-signature header must be included in the HTTP message to sign a message.

x-signature is a hashed sha512 string = HTTP payload + ":" + password (given by Gamzix).

When a message with a signature is received it must be checked that the signature is valid.

If the message has an invalid signature, Casino must return an error message:

{
  "status": 401,
  "error": "Invalid Signature"
}

The following functions might be used to sign messages:

NodeJS

const crypto = require("crypto");
/**
 * @param { string } payload
 * @param { string } password
 */
const sign = (payload, password) =>
  crypto
    .createHash("sha512")
    .update(payload + ":" + password)
    .digest("hex");

PHP

function sign(string $payload, string $password): string {
return hash('sha512', $payload.':'.$password)};

Games API

GET /languages

Method: GET

URI: [gamzix_url]/languages

Description: Returns the list of languages available for the Casino

Response Type:

type Result = string[]

Response:

{
  "status": 200,
  "ts": 1234567890,
  "result":["bg","en","cs","es","ge","it",...]
}

GET /currencies

Method: GET

URI: [gamzix_url]/currencies

Description: Returns the list of currencies available for the Casino

Response Type:

type Result = string[]

Response:

{
  "status": 200,
  "ts": 1234567890,
  "result":["EUR","LKR","MGA","UAH","USD","uBTC",...]
}

GET /games

Method: GET

URI: [gamzix_url]/games

Description: Returns the list of games available for the Casino

Response Type:

type Result = {
  id: number;
  name: string;
  logo: string; //Link to game logo image
  order: number;
  rtp: string; //Game rtp in percentages
  tags?: string[];
};

Response:

{
  "status": 200,
  "ts": 1234567890,
  "result": [
    {
      "id": 1045,
      "name": "Sunny Coin 2",
      "logo": "https://.../g1045.jpg",
      "order": 2,
      "rtp": "96.02",
      "tags": [
        "fruits",
        "snow"
      ]
    },
    {
      "id": 2001,
      "name": "Royal Hot v2",
      "logo": ".https://.../g2001.jpg",
      "order": 1,
      "rtp": "94"
    },
    ...
  ]
}

GET /freerounds/info

Method: GET

Params:

type Params = {
    gameIds?: number[] // List of Gamzix Game IDs (optional)
    currencies?: string[] // List of currencies (optional)
}

URI: [gamzix_url]/freerounds/info?gameIds=[ game id ]&currencies=[ currency ]

Description: Returns information about Free Rounds settings available for the Casino

Response Type:

type Result = {
    offers: {
        currency: string,
        game_id: string,
        game_name: string,
        bets: integer[] //list of free round bets available for the game and currency
    } []
}

Response:

{
  "status": 200,
  "ts": 1234567890,
  "result": {
    "offers": [
      {
        "currency": "UAH",
        "game_id": "1045",
        "game_name": "Sunny Coin 2",
        "bets": [200, 500, 1000]
      },
      {
        "currency": "USD",
        "game_id": "2001",
        "game_name": "Royal Hot v2",
        "bets": [100, 200, 1000]
      }, ...
    ]
  }
}

GET /init

Method: GET

Params:

type Params = {
    gid: integer // Gamzix Game ID
    pid: string // Casino Player ID
    currency: string //Casino Player currency
    home?: string  // Button HOME moves the player to this URL
    demo?: integer // Non zero value means the player is the demo
    lang?: string // Casino Player language
    client?: string // Html Client type. “desktop” or “mobile”
    token?: string // Game launch token
    countryCode?: string // Casino Player country code (KZ, TR, etc.)
}

URI: [gamzix_url]/init?gid=[ your gid ]&pid=[ your pid ]&currency=[ your currency ]&home=/&demo=0&lang=en&client=desktop&token=[ your token ]

Description: Returns the URL of the chosen game.

The Casino must forward the Player into an iframe with the returned URL. Make sure the iframe has an "allowfullscreen" attribute.

Response Type:

type Result = string

Response:

{
  "status": 200,
  "ts": 1234567890,
  "result": "https://cdn-v2.gamzix.com/3x3-hold-the-spin/v1.9.2?host=sapp.gamzix.com&port=443&lang=en&sid=avkdboqlz"
}

POST /opened

Method: POST

Body:

type Body = {
  pid: string; // Casino Player ID
  gid: string; // Gamzix Game ID
};

URI: [casino_url]/opened

Description: This request is sent when a player has opened the game.

Response:

  {
    "status": 200
  }

* This request is not being sent by default. If the Casino has a necessity of getting this request, please contact the Gamzix integration team

POST /closed

Method: POST

Body:

type Body = {
  pid: string; // Casino Player ID
  gid: string; // Gamzix Game ID
};

URI: [casino_url]/closed

Description: This request is sent when a player has closed the game.

Response:

  {
    "status": 200
  }

* This request is not being sent by default. If the Casino has a necessity of getting this request, please contact the Gamzix integration team

Wallet API

The Casino is expected to implement the Wallet API for Gamzix calls. Each Wallet API response must contain a player’s current balance.

Wallet API POST requests have to be idempotent. Those requests contain a bet and a win transaction IDs fields. The Casino has to ensure that requests with the same transaction IDs are not processed twice while the duplicate responses have to contain a message "Already processed".

Already processed response example:

{
  "status": 200,
  "result":
  {
    "balance": 8750,
    "currency": "USD",
    "message": "Already processed"
  }
}

If a withdrawal amount exceeds the player’s balance, an “Insufficient funds” error response has to be returned. Insufficient funds response example:

{
  "status": 402,
  "error": "Insufficient funds",
  "result":
  {
    "balance": 8750
  }
}

Round is processed by POST transaction request containing data on both withdrawal and deposit transactions. Every round has one withdrawal and one deposit transaction represented by POST /transaction request. There are no restrictions on the amount of rounds in the session.

Transaction request contains started and finished parameters that indicate the progress of the round. Started indicates this request includes the bet (withdrawal); finished indicates it includes the win (deposit) and closes the round. They describe what is in the request, not whether the round has begun.

Possible transaction progress states are:

started: true, finished: true - bet was placed, win was calculated, both amounts and transaction ids are defined. Round is closed.
started: true, finished: false - bet was placed, bet_amount and bet_tid are defined. Win was not able to be determined yet, win_amount and win_tid are undefined. Round is not closed.
started: false, finished: true - this request closes the round opened by case 1, win was calculated, win_amount and win_tid are defined. Bet was processed by a previous request, so bet_amount and bet_tid are undefined. Round is closed.

In most cases transaction request will handle the first described option, where both withdrawal and deposit data is sent. Other options are reserved for unique game features where winnings are impossible to calculate immediately after bet.

The type parameter in the transaction request can have the following values:

spin – an ordinary round
freeRound – a free round provided by Casino
prize – a round to send a tournament prize

The type parameter in the cancel action will always have value "refund"

FreeRounds are presented as separate rounds. FreeRound type has the withdrawal amount equal to 0 as the default option.

In case Casino cannot accept withdrawal amount 0, Gamzix can provide configuration that sends transaction request for these rounds with

{ "bet_amount": "min_bet" , "win_amount": "min_bet + win_amount" }

where min_bet is the minimum bet amount configured for the current Casino, game and currency. Win amount is sent with addition of min_bet to compensate the withdrawal amount. However, it should be considered that in case player's balance is less than min_bet, player will get Insufficient funds error, though the round is technically free.

Error processing

When a game session is interrupted during a game round (for example, a connection failure between the Gamzix client and the Gamzix server) the player can start the game from the lobby once again and continue the game from the same point.

When the game session is interrupted due to a transaction error between Gamzix and Casino, the reaction depends on the error type. In cases where the error code has refundable=true according to the errors table the Gamzix server tries to retry or refund the request. In cases where the error code has refundable=false the request is treated as final for particular round.

In case an error with refundable=true occurs on transaction with started: true, finished:false a cancel(rollback) request will be sent.
In case an error with refundable=true occurs on transaction with started: true/false, finished: true the transaction request will be retried.

Code	Description	Refundable
400	Bet limit reached	false
401	Invalid Signature	false
402	Insufficient Funds	false
403	Game not allowed, Session expired	false
404	Page not found, Transaction not found	false
405	User is blocked	false
406	Withdraw operation already has a deposit action	false
409	Something went wrong	true
422	Unprocessable Entity (some parameter is invalid)	true
429	Too many requests	false
430	Freerounds not found	false
500	Server error, Transaction declined	true

Error response example:

{
  "status": 409,
  "error": "Something went wrong"
}

GET /balance

Method: GET

Params:

type Params = {
  pid: string; // Casino Player ID
  token: string; // Game launch token (only if token was provided in init request)
}

URI: [casino_url]/balance

Description: Called when players balance is needed. Casino has to return the player's current balance.

Response Type:

type Result = {
  balance: integer; // Casino Player balance
  currency: string; // Casino Player currency
}

Response:

{
"status": 200,
"result":
  {
    "balance":8750,
    "currency":"USD"
  }
}

POST /transaction

Method: POST

Body:

type Body = {
  type: string; // Round type (spin, prize, freeRound)
  bet_amount?: integer; // Withdrawal amount
  bet_tid?: string; // Withdaw transaction id
  win_amount?: integer; // Deposit amount
  win_tid?: string; // Deposit transaction id
  started: boolean; // Indicates whether the round is started
  finished: boolean; //Indicates whether the round is finished
  pid: string; // Casino Player ID
  rid: string; // Gamzix Round ID
  gid: string; // Gamzix Game ID
  ts: integer; // Transaction timestamp (Unix time in milliseconds)
  fr_id?: string; // Free Rounds campaign ID (only if round type=freeRound)
  fr_finished?: boolean; //If freeround is last (only if round type=freeRound)
  token?: string; // Game launch token (only if token was provided in init request)
}

URI: [casino_url]/transaction

Description: Withdraws and deposits money in single request. The Casino has to return the player’s current balance.

Response Type :

type Result = {
  balance: integer; // Casino Player balance
  bet_tid?: string; // Casino withdraw Transaction ID, required only if bet_tid is present in request
  win_tid?: string; // Casino deposit Transaction ID, required only if win_tid is present in request
}

Response:

{
  "status": 200,
  "result": {
    "balance": 8750,
    "bet_tid": "t-1",
    "win_tid": "t-2"
  }
}

POST /cancel

Method: POST

Body:

type Body = {
  type: string; // Round type (refund)
  tid: string; // Gamzix Rollback Transaction ID
  originalTid: string; // Gamzix Bet Transaction ID
  pid: string; // Casino Player ID
  rid: string; // Gamzix Round ID
  gid: string; // Gamzix Game ID
  ts: integer; // Transaction timestamp (Unix time in milliseconds)
  bet: integer; // Bet amount (just for info)
  win: integer; // Win amount (just for info)
  token: string; // Game launch token (only if token was provided in init request)
}

URI: [casino_url]/cancel

Description: Rollbacks a bet transaction on Casino and closes the round in order to reverse the transaction and adjust the player’s balance. Casino has to return the money back when receives a Cancel request. Refunds must be made before the response to the request is sent.

Response Type :

type Result = {
  balance: integer; // Casino Player balance
  transaction_id: string; // Casino Rollback Transaction ID
}

Response:

{
  "status": 200,
  "result": {
    "balance": 8750,
    "transaction_id": "t-1"
  }
}

Free Rounds API

Free Rounds (FR) API is an optional API.

The Casino using the FR API is able to grant free bets to users. First-time-user bonuses are supported: FR feature functions even if a player has not played Gamzix games yet.

FR settings may have constraints set by Gamzix: games, currencies, bet values or time.

The Casino may have several FR settings with its constraints. To provide FR to some players, Casino has to specify which FR settings they are based on.

When players use FR their deposit/withdraw bet types are “freeRound”.

POST /freerounds/v2/create

Method: POST

Body:

type Body = {
  fr_id: string; // Gamzix FR ID
  started_at: datetime; // FR allowed from this time (optional)
  finished_at: datetime; // FR allowed to this time (optional)
  gid: string | integer []; // List of Gamzix Game IDs
  bet_amount: integer; // Bet Amount
  rounds: integer; // Amount of FR
  pid: string; // Casino Player ID
  currency?: string; // Casino Player currency (optional)
}

* As "bet_amount" you can set a value from the list of game bets for currency

URI: [gamzix_url]/freerounds/v2/create

Description: Creates or updates the freerounds settings if exists

Response Type:

type Result = {
  fr_id: string // Gamzix FR ID
}

Response:

{
  "status":200,
  "ts": 1234567890,
  "result": 
  {
    "fr_id":"13ec1944-4106-42ae-b410-c634a6a08f19"
  }
}

POST /freerounds/cancel

Method: POST

Body:

type Body = {
  fr_id: string // Gamzix FR ID
}

URI: [gamzix_url]/freerounds/cancel

Description: Deletes the freerounds settings if exists.

Rounds Report

POST /round/info

Method: POST

Body:

type Body = {
  externalId: string // Gamzix round ID
}

URI: [gamzix_url]/round/info

Description: Returns information about specific round.

Response Type:

type Info = {
  bet: integer; // Round bet amount
  win: integer; // Round win amount
  created_at: datetime; // Round created date
  closed_at: datetime; // Round closed date
  type: string; // Round type (spin, freeRound, prize)
  currency: string; // Round currency
}

Response:

{
    "info": {
        "bet": 10,
        "win": 100,
        "created_at": "2024-01-15T14:27:41.202000Z",
        "closed_at": "2024-01-15T14:27:41.278499Z",
        "type": "spin",
        "currency": "EUR"
    },
    "success": true
}

Change log​

Introduction​

OpenAPI Documentation​

Required data for integration​

Communication format​

Money format​

Mobile and desktop slot games​

Balance management​

Response status codes​

Authentication​

Games API​

GET /languages​

GET /currencies​

GET /games​

GET /freerounds/info​

GET /init​

POST /opened​

POST /closed​

Wallet API​

Error processing​

GET /balance​

POST /transaction​

POST /cancel​

Free Rounds API​

POST /freerounds/v2/create​

POST /freerounds/cancel​

Rounds Report​

POST /round/info​

Change log

Introduction

OpenAPI Documentation

Required data for integration

Communication format

Money format

Mobile and desktop slot games

Balance management

Response status codes

Authentication

Games API

GET /languages

GET /currencies

GET /games

GET /freerounds/info

GET /init

POST /opened

POST /closed

Wallet API

Error processing

GET /balance

POST /transaction

POST /cancel

Free Rounds API

POST /freerounds/v2/create

POST /freerounds/cancel

Rounds Report

POST /round/info