Partner API

API.URI - do not forget to specify in the Control Panel the address where you will process requests.

The request URI is formed according to the scheme API.URI + '/' + serviceName + '.' + methodName
All requests from the Platform to a Partner are made using the POST (HTTP) method and contain the header
Content-type: application/json
All Partner's responses to requests from the Platform must be sent in JSON format in the following form:
{
  "method" : "method_name",
  "status" : 200,
  "response" : {response body in JSON format, missing in some methods}
}
Any response other than the above is considered by the Platform as erroneous and runs the algorithm described for each method in the "Error handling" section.

General info:

Connect timeout 1s
Read timeout 3s
In case of any errors (failures) when communicating with a partner's server, an error is sent to a game. A game requires a restart to continue.
All non-essential queries are stopped on error. All requests with the semantics "request to perform an action" are canceled in case of errors (with attempts to inform a partner about this). All requests with "report result" semantics will be executed until unambiguously error-free processing.

Signature generation

The signature in a request is passed as a named parameter sign
ALL parameters that are passed in the body of the POST request are involved in the formation of the signature (GET parameters that are query part of a url address are not taken into account), except for the parameters meta, sign and those whose names begin with partner.
Generation:
1. Form a set of parameters from the body of the POST request
2. Filter out the parameters meta, sign and those whose names begin with partner.
3. Sort the remaining parameters in lexicographic order
4. Combine all parameter names and parameter values into a single string
5. Add the method name, Partner ID and Secret key to the received string
6. Hash the final string using the MD5 algorithm

Full signature generation algorithm (pseudo code):

val params = Map[Name,Value]

val joined = names
  .filter( name => !(name.startsWith("partner.") || name === "meta" || name === "sign") )
  .sorted
  .map( name => name + "=" + params(name))
  .join("&")

// Connecting particle "&" between 'joined' and 'serviceName' is put in anyway, even if there are no parameters.
val sign = md5(joined + "&" + serviceName + "." + methodName + "&" + "Partner ID" + "&" + "Secret key")

Full example of signature generation

METHOD: /games.list
PARAMS: 
paramA = paramValueA
paramC = paramValueC
paramZ = paramValueZ
paramB = paramValueB
partner.alias = test
meta.param1 = someValue
meta.paramEtc = etcValue

SIGN:
// URL-encode - NOT applicable
joined = "paramA=paramValueA&paramB=paramValueB&paramC=paramValueC&paramZ=paramValueZ"

stringToSign = joined + "&games.list&test&testsecret"
//stringToSign = "paramA=paramValueA&paramB=paramValueB&paramC=paramValueC&paramZ=paramValueZ&games.list&test&testsecret"

sign = md5(stringToSign)
//sign = "8cb94a439f507c1a6f9cede4982380a1"

FULL REQUEST BODY:
paramA=paramValueA&paramB=paramValueB&paramC=paramValueC&paramZ=paramValueZ&games.list&test&testsecret&partner.alias=test&partner.sign=8cb94a439f507c1a6f9cede4982380a1&meta.param1=someValue&meta.paramEtc=etcValue

`Partner` side methods

`/trx.cancel` - Cancel a transaction

Parameters
- @session - identifier of a player's session, which a Partner specified at a start of a game
- @currency - 3-Latin currency code that a Partner specified when starting a game
- @amount - Amount in cents (hundredths)
- @trx_id - a unique transaction identifier on the Platform side. A Partner must ensure uniqueness checks on its side and not make repeated withdrawals if there are repeated requests with a specified identifier.
- @sign - request signature
- @turn_id - number of a turn in a session on the Platform side (for reference only)
- @meta - meta data

Expected response

{
  "method" : "trx.cancel",
  "status" : 200,
  "response" : {
      currency: String // requested currency
      balance:Long // player's balance in specified currency after cancellation (for display in games)
  }
}

Example of a request sent by the Platform

JSON:

{
  "sign": "85520955afda57b28905181593440dbb",
  "session": "1b905c92daf4052f06e9d18303d83322",
  "currency": "USD",
  "amount": 7500,
  "trx_id": "LOCAL-50-0",
  "turn_id": 1,
  "meta": {
    "game": "slot"
  }
}

CURL request/response example

CURL:

curl -X POST -d "{\"sign\" : \"1b110f548f5b3baf21bd37e722020285\", \"session\" : \"5b3baf21bd37-5b3baf21bd37-5b3baf21bd37\", \"currency\" : \"USD\", \"amount\" : 7500, \"trx_id\" : \"LOCAL-50-0\", \"turn_id\" : 1}" http://example.com/trx.cancel

RESPONSE:

{
  "method" : "trx.cancel",
  "status" : 200,
  "response" : {
    "currency" : "USD",
    "balance" : 500000
  }
}

Error handling

If the Platform receives any response different from the expected one, several automatic attempts are made (current settings are 2 attempts in 5 and 15 seconds) to notify a Partner about the cancellation of the transaction.
In case of exhaustion of attempts, a Partner must, after eliminating the malfunction, initiate a request to cancel the transaction manually from the Control Panel

For more information about canceling transactions, see the section "Procedure for canceling a transaction"

`/trx.complete` - Complete transaction

Parameters
- @session - identifier of a player's session, which a Partner specified at a start of a game
- @currency - 3-Latin currency code that a Partner specified when starting a game
- @amount - Amount in cents (hundredths)
- @trx_id - a unique transaction identifier on the Platform side. A Partner must ensure uniqueness checks on its side and not make repeated withdrawals if there are repeated requests with a specified identifier.
- @sign - request signature
- @turn_id - number of a turn in a session on the Platform side (for reference only)
- @meta - meta data

Expected response

{
  "method" : "trx.complete,
  "status" : 200,
  "response" : {
      currency: String // requested currency
      balance:Long // player's balance in specified currency after cancellation (for display in games)
  }
}

Example of a request sent by the Platform

JSON:

{
  "sign": "85520955afda57b28905181593440dbb",
  "session": "1b905c92daf4052f06e9d18303d83322",
  "currency": "USD",
  "amount": 7500,
  "trx_id": "LOCAL-50-0",
  "turn_id": 1,
  "meta": {
    "game": "slot"
  }
}

CURL request/response example

CURL:

curl -X POST -d "{\"sign\" : \"1b110f548f5b3baf21bd37e722020285\", \"session\" : \"5b3baf21bd37-5b3baf21bd37-5b3baf21bd37\", \"currency\" : \"USD\", \"amount\" : 7500, \"trx_id\" : \"LOCAL-50-0\", \"turn_id\" : 1}" http://example.com/trx.complete

RESPONSE:

{
  "method" : "trx.complete",
  "status" : 200,
  "response" : {
    "currency" : "USD",
    "balance" : 500000
  }
}

Error handling

If the Platform receives any response different from the expected one, several automatic attempts are made (current settings are 2 attempts in 5 and 15 seconds) to notify a Partner about the cancellation of the transaction.
In case of exhaustion of attempts, a Partner must, after eliminating the malfunction, initiate a request to cancel the transaction manually from the Control Panel

For more information about canceling transactions, see the section "Procedure for canceling a transaction"

`/check.session` - Getting (checking) information about a session on a Partner's side.

id_player - is the player's unique number.
All games for the player with his id_player are launched in only one uniqe instance.

Note that it is important to specify a correct id_player when creating a session if the session is to be kept by a specific player.

To anonymize players on the Platform side, id_player can always be sent unique.

If the same id_player value is sent for all sessions, then the platform will not work correctly: games will be mixed, other players will be logged out and game data will be mixed

Parameters
- @session - identifier of a player's session, which a Partner specified at a start of a game
- @currency - 3-Latin currency code that a Partner specified when starting a game
- @sign - request signature
- @meta - meta data

Expected response

{
  "method" : "check.session",
  "status" : 200,
  "response" : {
    "id_player": Long|String // immutable player id on a partner's side. It is required to restore games full of player logs and more.
    "game_id": Int // game id
    "currency": String // requested currency
    "balance": Long // player's balance in the specified currency at the time of the request (for display in games)
    "denomination": Int // denominator in hundredths (if the value is 100 denomination is 1.00) used for the game session
  }
}

Example of a request sent by the Platform

JSON:

{
  "sign": "85520955afda57b28905181593440dbb",
  "session": "1",
  "currency": "USD",
  "meta": {
    "game": "slot"
  }
}

CURL request/response example

CURL:

curl -X POST -d "{\"sign\" : \"1b110f548f5b3baf21bd37e722020285\", \"session\" : \"5b3baf21bd37-5b3baf21bd37-5b3baf21bd37\", \"currency\" : \"USD\"}" http://example.com/check.session

RESPONSE:

{
  "method" : "check.session",
  "status" : 200,
  "response" : {
    "id_player" : "1",
    "game_id" : 1,
    "currency" : "USD",
    "balance" : 500000,
    "denomination" : 500000
  }
}

Error handling

Stop execution

`/check.balance` - Getting information about a balance on a partner's side.

Parameters
- @session - identifier of a player's session, which a Partner specified at a start of a game
- @currency - 3-Latin currency code that a Partner specified when starting a game
- @sign - request signature
- @meta - meta data

Expected response

{
  "method" : "check.balance",
  "status" : 200
  "response" : {
    currency: String // requested currency
    balance:Long // player's balance in the specified currency at the time of the request (for display in games)
  }
}

Example of a request sent by the Platform

JSON:

{
  "sign": "85520955afda57b28905181593440dbb",
  "session": "1",
  "currency": "USD",
  "meta": {
    "game": "slot"
  }
}

CURL request/response example

CURL:

curl -X POST -d "{\"sign\" : \"1b110f548f5b3baf21bd37e722020285\", \"session\" : \"5b3baf21bd37-5b3baf21bd37-5b3baf21bd37\", \"currency\" : \"USD\"}" http://example.com/check.balance

RESPONSE:

{
  "method" : "check.balance",
  "status" : 200,
  "response" : {
    "currency" : "USD",
    "balance" : 500000
  }
}

Error handling

Stop execution

`/withdraw.bet` - Withdrawal from a balance for making a bet.

Parameters
- @session - identifier of a player's session, which a Partner specified at a start of a game
- @currency - 3-Latin currency code that a Partner specified when starting a game
- @amount - Amount in cents (hundredths)
- @trx_id - a unique transaction identifier on the Platform side. A Partner must ensure uniqueness checks on its side and not make repeated withdrawals if there are repeated requests with a specified identifier.
- @sign - request signature
- @turn_id - number of a turn in a session on the Platform side (for reference only)
- @meta - meta data

Expected response

{
  "method" : "withdraw.bet",
  "status" : 200
  "response" : {
      currency: String // requested currency
      balance:Long // player's balance in the specified currency after withdrawal (for display in games)
  }
}

Example of a request sent by the Platform

JSON:

{
  "sign": "85520955afda57b28905181593440dbb",
  "session": "1b905c92daf4052f06e9d18303d83322",
  "currency": "USD",
  "amount": 7500,
  "trx_id": "LOCAL-50-0",
  "turn_id": 1,
  "meta": {
    "game": "slot"
  }
}

CURL request/response example

CURL:

curl -X POST -d "{\"sign\" : \"1b110f548f5b3baf21bd37e722020285\", \"session\" : \"5b3baf21bd37-5b3baf21bd37-5b3baf21bd37\", \"currency\" : \"USD\", \"amount\" : 7500, \"trx_id\" : \"LOCAL-50-0\", \"turn_id\" : 1}" http://example.com/withdraw.bet

RESPONSE:

{
  "method" : "withdraw.bet",
  "status" : 200,
  "response" : {
    "currency" : "USD",
    "balance" : 500000
  }
}

Error handling

In case of a response from a Partner to the Platform's request, where @status is in the range from 500 to 599, the game server considers that a Partner's server has refused to perform a transactionally significant action. The transaction is marked as completed failed.
In other cases, when the response differs from the expected one, the "Transaction Cancellation Procedure" is launched.

`/deposit.win` - Enrollment the winnings to a balance.

Parameters
- @session - identifier of a player's session, which a Partner specified at a start of a game
- @currency - 3-Latin currency code that a Partner specified when starting a game
- @amount - Amount in cents (hundredths)
- @trx_id - a unique transaction identifier on the Platform side. A Partner must ensure uniqueness checks on its side and not make repeated enrollments if there are repeated requests with a specified identifier.
- @sign - request signature
- @turn_id - number of a turn in a session on the Platform side (for reference only)
- @meta - meta data

Expected response

{
  "method" : "deposit.win",
  "status" : 200,
  "response" : {
    currency: String // requested currency
    balance:Long // player's balance in the specified currency after enrollment the winnings (for display in games)
  }
}

Example of a request sent by the Platform

JSON:

{
  "sign": "85520955afda57b28905181593440dbb",
  "session": "1",
  "currency": "USD",
  "amount": "7500",
  "trx_id": "LOCAL-50-0",
  "turn_id":"1",
  "meta": {
    "game": "slot"
  }
}

CURL request/response example

CURL:

curl -X POST -d "{\"sign\" : \"1b110f548f5b3baf21bd37e722020285\", \"session\" : \"5b3baf21bd37-5b3baf21bd37-5b3baf21bd37\", \"currency\" : \"USD\", \"amount\" : 7500, \"trx_id\" : \"LOCAL-50-0\", \"turn_id\" : 1}" http://example.com/deposit.win

RESPONSE:

{
  "method" : "deposit.win",
  "status" : 200,
  "response" : {
    "currency" : "USD",
    "balance" : 500000
  }
}

Error handling

"Procedure for delayed completion of a transaction"

Freerounds

Each @freerounds.id must be unique within a partner
Partner needs to check that each @freerounds.id cannot be activated and completed more than once.
If a player has an active game session, then when the freerounds are activated, it will be forcibly ended.Learn more about force ending sessions

Bets and winnings on freerounds:

It is not possible to change a bet during the freerounds
A game always launch at the minimum bet and a maximum number of lines
The size of the potential winnings is regulated by a Partner by specifying a number of freerounds issued and a denomination

Why can't I change a bet and a number of lines on freerounds?
The platform contains hundreds of games from dozens of different series. Many games have very specific line bet sets. In some games, the number of lines is fixed or there are none at all (calculation by ways not lines). Increasing the bet will extremely unevenly distribute potential winnings between games with a small and large number of lines, and reducing the number of lines dramatically affects the game's interest for a Player.

Thus, the minimum bet with the maximum number of lines allows to get the maximum involvement of a Player due to the high probability of small wins. And at the same time, a Partner does not need to take into account the specifics of the mathematics of the game.

Steps:

A partner launch a game as usual + parameter @freerounds.id
The platform activates freerounds on a Partner's server
A player plays freerounds (during freerounds winnings are not enrolled to the partner's server)
The Platform completes the freerounds on a Partner's server, indicating the total winnings for the freerounds.

`/freerounds.activate` - Freerounds activation.

Parameters
- @session - identifier of a player's session, which a Partner specified at a start of a game
- @currency - 3-Latin currency code that a Partner specified when starting a game
- @game_id - game id (a Partner can perform an additional check to limit the games in which freerounds can be used)
- @freerounds_id - String - unique identifier of freerounds.
- @sign - request signature
- @meta - meta data

Expected response

{
  "method" : "freerounds.activate",
  "status" : 200,
  "response" : {
    "total": Int
  }
}

Example of a request sent by the Platform

JSON:

{
  "sign": "85520955afda57b28905181593440dbb",
  "session": "1",
  "currency": "USD",
  "freerounds_id": "09fafb5e3794c3e07f585a790898b0e1",
  "game_id": 1,
  "meta": {
    "game": "slot"
  }
}

CURL request/response example

CURL:

curl -X POST -d "{\"session\":\"1b6a31e8d65bbf17fcf7c5b09a2302fe\",\"sign\":\"20e455b3bd7e6c5e89dbe7db062f5c0a\",\"currency\":\"EUR\",\"freerounds_id\":\"09fafb5e3794c3e07f585a790898b0e1\",\"game_id\":1}" http://example.com/freerounds.activate

RESPONSE:

{
  "method" : "freerounds.activate",
  "status" : 200,
  "response" : {
    "total" : 10
  }
}

Error handling

Stop execution

`/freerounds.complete` - Completion of freerounds.

Parameters
- @session - identifier of a player's session, which a Partner specified at a start of a game
- @currency - 3-Latin currency code that a Partner specified when starting a game
- @freerounds_id - String - unique identifier of freerounds.
- @trx_id - unique transaction identifier on the side of the Platform.
- @amount - Long (in hundredths of a specific currency)
- @turn_id - number of a turn in a session on the Platform side (for reference only)
- @sign - request signature
- @meta - meta data

Expected response

{
  "method" : "freerounds.complete",
  "status" : 200,
  "response" : {
    currency: String // requested currency
    balance:Long // player's balance in the specified currency after enrollment the winnings (for display in games)
  }
}

Example of a request sent by the Platform

JSON:

{
  "sign": "85520955afda57b28905181593440dbb",
  "freerounds_id": "09fafb5e3794c3e07f585a790898b0e1",
  "session": "1",
  "currency": "USD",
  "amount": "7500",
  "trx_id": "LOCAL-50-0",
  "turn_id":"1",
  "meta": {
    "game": "slot"
  }
}

CURL request/response example

CURL:

curl -X POST -d "{\"trx_id\":\"347\",\"amount\":2200,\"session\":\"1b6a31e8d65bbf17fcf7c5b09a2302fe\",\"sign\":\"f2afb1d7095cce85819556493053bf50\",\"currency\":\"USD\",\"freerounds_id\":\"09fafb5e3794c3e07f585a790898b0e1\",\"turn_id\":\"5\"}" http://example.com/freerounds.complete

RESPONSE:

{
  "method" : "freerounds.complete",
  "status" : 200,
  "response" : {
    "currency" : "USD",
    "balance" : 500000
  }
}

Error handling

"Procedure for delayed completion of a transaction"

`/freerounds.step` - Notification of the completion of the freeround step. This is NOT a transactional action. Do not use it to change a player's balance! Requests in case of errors are not duplicated.

Parameters
- @session - identifier of a player's session, which a Partner specified at a start of a game
- @currency - 3-Latin currency code that a Partner specified when starting a game
- @freerounds_id - String - unique identifier of freerounds within a Partner.
- @step - Int - Step number. Value >= 1
- @step_win - Long (in hundredths) - Win at a specific step
- @total_win - Long (in hundredths of a specific currency) - Accumulated win taking into account previous steps.
- @sign - request signature
- @meta - meta data

Expected response

{
  "method" : "freerounds.step",
  "status" : 200,
  "response" : true
}

Example of a request sent by the Platform

JSON:

{
  "sign": "85520955afda57b28905181593440dbb",
  "freerounds_id": "09fafb5e3794c3e07f585a790898b0e1",
  "session": "1",
  "currency": "USD",
  "step_win": 500,
  "total_win": 7500,
  "step": 1,
  "meta": {
    "game": "slot"
  }
}

CURL request/response example

CURL:

curl -X POST -d "{\"step_win\":2200,\"session\":\"1b6a31e8d65bbf17fcf7c5b09a2302fe\",\"sign\":\"fc1ab09e67798052c8e3f959b8b313f7\",\"currency\":\"USD\",\"step\":\"2\",\"freerounds_id\":\"09fafb5e3794c3e07f585a790898b0e1\",\"total_win\":2200}" http://example.com/freerounds.step

RESPONSE:

{
  "method" : "freerounds.step",
  "status" : 200,
  "response" : true
}

Error handling

Errors on this request are ignored

Error handling

Game errors handling:

All errors that occur in games cause the notification "A technical error, please contact with support". This alert contains a "Reload" button prompting you to restart a game. In some cases this is enough to continue a game. All winnings and activated game features will be saved. If using the "Reload" button causes the error notification to reappear, please contact the Platform support.
It is possible to forcibly end a game session in order to withdraw the player's funds from a game. Learn more about force ending sessions

List of policies:

Stop on fail

List of methods:
- check.session
- check.balance
Behavior:
- For any error - stop.
Cancel on undefined behavior

List of methods:
- withdraw.bet
- freerounds.activate
Behavior in case of receiving a response depending on the @status field (NOT http status code):
- 200 - regular behavior. The transaction is marked as successful and completed.
- 500-599 - the game server (Platform) believes that the Partner's server refused to perform a transactionally significant action. The transaction is marked as completed failed.
- Any other code - despite the fact that the game server (Platform) received the response body from a Partner in the agreed format, it considers that an abnormal situation has occurred on a Partner's server, which does not allow determining the status of the transaction. The procedure for canceling the transaction is started.
Behavior in the case when the game server (Platform) did not receive a response (timeout, communication failure or any other - it does not matter):
- The procedure for canceling the transaction is started.
Transaction cancellation procedure:
- The transaction is marked as canceled and not completed.
- The game server with some delay makes several attempts (current settings are 2 attempts in 5 and 15 seconds) to inform a Partner that the transaction has been canceled by calling the /trx.cancel method.
- If a Partner responds with a status of 200, the transaction is marked as completed.
- If a Partner responds with a status other than 200, attempts continue.
- After a limit of attempts is exhausted, they stop.
- All canceled transactions and their statuses can be viewed in the Control Panel.
- In case of exhaustion of attempts to complete the transaction, a Partner can manually initiate a request in the Control Panel with a message about canceling the transaction. In this case the game server (Platform) will immediately try to send /trx.cancel and, in case of successful confirmation, will mark the transaction as completed.
Proceed on fail.

List of methods:
- deposit.win
- freerounds.complete
Behavior in case of receiving a response depending on the @status field (NOT http status code):
- 200 - regular behavior. The transaction is marked as successful and completed.
- Any other code - despite the fact that the game server (Platform) received the response body from a Partner in the agreed format, it considers that an abnormal situation has occurred on a Partner's server, which does not allow determining the status of the transaction. The procedure for delayed completion of the transaction is started.
Behavior in the case when the game server (Platform) did not receive a response (timeout, communication failure or any other - it does not matter):
- The procedure for delayed completion of the transaction is started.
The procedure for delayed completion of the transaction:
- The transaction is marked as incomplete.
- The game server with some delay makes several attempts (current settings are 2 attempts in 5 and 15 seconds) to inform a Partner that the transaction has been canceled by calling the /trx.complete method.
- If a Partner responds with a status of 200, the transaction is marked as completed.
- If a Partner responds with a status other than 200, attempts continue.
- After a limit of attempts is exhausted, they stop.
- All canceled transactions and their statuses can be viewed in the Control Panel.
- In case of exhaustion of attempts to complete the transaction, a Partner can manually initiate a request in the Control Panel with a message about complete the transaction. In this case the game server (Platform) will immediately try to send /trx.complete and, in case of successful confirmation, will mark the transaction as completed.

Partner API

General info:

Signature generation

Partner side methods

/trx.cancel - Cancel a transaction

/trx.complete - Complete transaction

/check.session - Getting (checking) information about a session on a Partner's side.

/check.balance - Getting information about a balance on a partner's side.

/withdraw.bet - Withdrawal from a balance for making a bet.

/deposit.win - Enrollment the winnings to a balance.

Freerounds

/freerounds.activate - Freerounds activation.

/freerounds.complete - Completion of freerounds.

/freerounds.step - Notification of the completion of the freeround step. This is NOT a transactional action. Do not use it to change a player's balance! Requests in case of errors are not duplicated.

Error handling

Game errors handling:

List of policies:

`Partner` side methods

`/trx.cancel` - Cancel a transaction

`/trx.complete` - Complete transaction

`/check.session` - Getting (checking) information about a session on a Partner's side.

`/check.balance` - Getting information about a balance on a partner's side.

`/withdraw.bet` - Withdrawal from a balance for making a bet.

`/deposit.win` - Enrollment the winnings to a balance.

`/freerounds.activate` - Freerounds activation.

`/freerounds.complete` - Completion of freerounds.

`/freerounds.step` - Notification of the completion of the freeround step. This is NOT a transactional action. Do not use it to change a player's balance! Requests in case of errors are not duplicated.