Skip to main content

v.1.11.0

Change log​

  • Updated response codes and error handling.
  • Added non-zero bet configuration option for rounds with standards zero bet amounts.
  • Minor fixes

Introduction​

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

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

Required data for integration​

Given by Gamzix

NameDescriptionExample
gamzix_urlGamzix API URLhttps://api.gamzix.com/:casino_id/api
passwordMessage signature keyGoF4GdKcN65e5Ni11dVf7V6m

Given by Casino

NameDescriptionExample
casino_urlCasino API URLhttps://yoursite.com/the/api
casino_ip[ ]Casino IP white list127.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.

CurrencyPrecision
EUR2
CLP0
USD2
COP2
JOD3

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:

  1. home" is empty or undefined – the game client hides the button “home”;
  2. home" = “closePopup” – this case is to handle the game client is opened on a platform’s iframe and the button “home” is pressed;
  3. "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​

  1. The only acceptable HTTP status codes are 200 or 201

  2. API status codes are contained in the response body

  3. 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;
CodeDescritpion
200, 201Successful Response
401Signature invalid
402Insufficient Funds
403Game not allowed,
Session expired
404Page not found,
Transaction not found
406Withdraw operation already has a deposit action
409Something went wrong
422Unprocessable Entity (some parameter is invalid)
430Freerounds not found
500Server 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","go","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: string;
  name: string;
  logo: string;
  order: number;
  tags?: string[];
};

Response:

{
  "status": 200,
  "ts": 1234567890,
  "result": [
    {
      "id": 1022,
      "name": "Snow Coin",
      "logo": ".../image1.png",
      "order": 2,
      "tags": ["fruits", "snow"]
    },
    {
      "id": 1017,
      "name": "Make Money Rich Edition",
      "logo": ".../image2.png",
      "order": 1
    },...
  ]
}

GET /freerounds/info​

Method: GET

URI: [gamzix_url]/freerounds/info

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

Response Type:

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

Response:

{
  "status": 200,
  "ts": 1234567890,
  "result": {
    "offers": [
      {
        "currency": "UAH",
        "game_id": "1022",
        "game_name": "Snow Coin",
        "bets": [200, 500, 1000]
      },
      {
        "currency": "USD",
        "game_id": "1017",
        "game_name": "Make Money Rich Edition",
        "bets": [100, 200, 1000]
      }, ...
    ]
  }
}

GET /jackpots/balance​

Method: GET

Params:


 type Params =  { currency: string }

URI: [gamzix_url]/jackpots/balance?currency=[ currencyCode ]

Description: Returns the list of jackpot balances (pools) for the Casino, if progressive jackpot is enabled

Response Type:

type Result  = {
    id: number;
    name: string;
    amount: number,
    currency: string;
}

Response:

{
  "status": 200,
  "ts": 1234567890,
  "result": [
      {
        "id": 23,
        "name": "Major",
        "amount": 35678,
        "currency": "EUR"
      },
      {
        "id": 23,
        "name": "Mega",
        "amount": 29600,
        "currency": "EUR"
      },...
    ]
}

GET /init​

Method: GET

Params:


type Params = {
    gid: number // Gamzix Game ID
    pid: string // Casino Player ID
    currency: string //Casino Player currency
    home?: string  // Button HOME moves the player to this URL
    demo?: number // 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
}

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 transaction_id field. The Casino has to ensure that requests with the same transaction_id 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 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
  }
}


Every round has one withdrawal and one deposit request. There are no restrictions on the amount of rounds in the session. Jackpots and free spins are presented as separate rounds.

The “type” parameter in the deposit and withdraw actions can have the following values:

  • spin – an ordinary round
  • freeRound – a free round provided by Casino
  • jackpot – a jackpot game round
  • reward – a round to send an achievement prize
  • prize – a round to send a tournament prize
  • roll – daily roll promotion round

FreeRound, jackpot, reward, prize and roll types have the withdrawal amount equal to 0.

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


{ "amount": "min_bet" }

where min_bet is the minimum bet amount configured for the current Casino, game and currency, and deposit request with


 {"amount": "min_bet + win_amount"}

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.

Also a game session may be interrupted due to a transaction error between Gamzix and Casino.

The Gamzix server tries to resend the request several times automatically if Casino does not respond or the response HTTP status is not 200 or 201.

If all requests fail or some request has incorrect content, the game session will be blocked and the player will see an error message.

If the game session has an erroneous transaction, the player is not allowed to play the game until the error will not be resolved manually and during initialization of the game an error message will be returned:


{
  "status": 403,
  "error": "User has unresolved transactions on this game"
}

CodeDescriptionRefundable
402Insufficient Fundsfalse
403Game not allowed, Session expiredfalse
404Page not found, Transaction not foundfalse
406Withdraw operation already has a deposit actionfalse
409Something went wrongtrue
422Unprocessable Entity (some parameter is invalid)true
500Server error, Transaction declinedtrue
  • In case an error with refundable=true occurs on withdraw(bet) transaction a cancel(rollback) transaction will be sent. Cancel(rollback) transaction will be resent till the Gamzix server will get a successful response.
  • In case an error with refundable=true occurs on deposit(win) transaction the win transaction will be resent till the Gamzix server will get a successful response.

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: number; // Casino Player balance
  currency: string; // Casino Player currency
}

Response:

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

POST /withdraw​

Method: POST

Body:


type Body = {
  type: string; // Round type
  amount: number; // Withdrawal amount
  tid: string; // Gamzix Transaction ID
  pid: string; // Casino Player ID
  rid: string; // Gamzix Round ID
  gid: string; // Gamzix Game ID
  fr_id?: string; // Free Rounds campaign ID (only if round type=freeRound)
  token?: string; // Game launch token (only if token was provided in init request)
}

URI: [casino_url]/withdraw

Description: Withdraws money from the player’s wallet. The Casino has to return the player’s current balance.

Response Type :


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

Response:

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

POST /deposit​

Method: POST

Body:


type Body = {
  type: string; // Round type
  amount: number; // Withdrawal amount
  tid: string; // Gamzix Transaction ID
  pid: string; // Casino Player ID
  rid: string; // Gamzix Round ID
  gid: string; // Gamzix Game ID
  fr_id?: string; // Free Rounds campaign ID (only if round type=freeRound)
  token?: string; // Game launch token (only if token was provided in init request)
}

URI: [casino_url]/deposit

Description: Deposits money to the player’s wallet. The Casino has to return the player’s current balance.

Response Type :


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

Response:

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

POST /cancel​

Method: POST

Body:


type Body = {
  type: string; // Round type
  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
  bet: number; // Bet amount (just for info)
  win: number; // 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: number; // 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”. Jackpots and Freespins (Free rounds provided by slot game rules) are not counted as Freeround because they are already “free”.

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 | number []; // List of Gamzix Game IDs
  bet_amount: number; // Bet Amount
  rounds: number; // 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/create​

⚠️ WARNING: This method is deprecated

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 | number []; // List of Gamzix Game IDs
  bet_level: number; // Bet Level
  bet_coins: number; //Bet Coins
  rounds: number; // Amount of FR 
  pid: string; // Casino Player ID
}

* The total bet is calculated as bet_lines * bet_level * bet_coins, where "bet_lines" is the maximum number of lines in the game.
If the “bet_level” parameter is not set, the default is 1.
If the “bet_coins” parameter is not set, the default is the FR bet is game min bet.

URI: [gamzix_url]/freerounds/create

Description: Creates or updates the freerounds settings if exists

Response Type:


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

Response:


{
  "status":200,
  "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: number; // Round bet amount
  win: string; // Round win amount
  created_at: datetime; // Round created date
  closed_at: datetime; // Round closed date
  type: string, // Round type (spin, freeRound, jackpot, reward, 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
}