Balla Games API Integration Specification

Table of Contents

Introduction

This document provides a comprehensive technical specification for integrating third-party platforms with the Balla Game Platform. The integration follows RESTful API standards and communicates using JSON messages. All messages must be secured using HMAC SHA-256 based hash values.

Configuration

Provider Endpoint and IP Whitelisting Configuration

Please provide the following details to complete the integration setup: API Endpoint URLs: Specify the base URLs for your API services (e.g. authentication ,balance check, debit , credit,refund etc.).

IP Addresses for Whitelisting: Provide the list of static IP addresses that will be used to send requests to the Balla Game Platform. These IPs will be whitelisted to allow secure communication. Kindly ensure that the provided IPs are final and publicly routable.

Hashing Logic (HMAC SHA-256)

Java Example: 
private String genHash(String textvalue, Strinsaltext) {
    byte[] key = saltext.getBytes()
    String gHmac = Hashing.hmacSha256(key)
    .newHasher()
    .putString(textvalue, StandardCharsets.UTF_8)
    .hash()
    .toString()
    .toUpperCase();
    return gHmac;
}
Sample Input:

String textvalue = "playerToken=" + playerToken + ",sessionId=" + sessionId;

String hashValue = genHash(textvalue, secretKey);

"Sort the keys alphabetically (A–Z) before hashing the request string; values must remain paired and unchanged."

Game Launch

https://<game_provider_domain>/<games>/<gamename>?gameId=<gameId>&site=<obtain_before_start>&playerToken=<player_token>

The above request method is GET and works with the browser to display and manage the game activities. All parameters are Mandatory (Required).

Parameters:

Authentication

The request method is POST. The message body is sent in JSON with the following parameters. This Request happens Once for each Game Launch time and the same sessionId value is used in the API Requests.

URL: https://{{URL}}/authentication

Request Payload

{
    "playerToken": "02796215-ac3d-41d5-85ce-3bbdcaf86513
    "sessionId": "21415c60-1b3c-6452-57bc-c5d9415a4cae"
    "hashValue": "8D66DAA2E2131C2C2B7B85A9972D407C6C7F"
}

Response

{
    "playerToken": "02796215-ac3d-41d5-85ce-3bbdcaf86513",
    "sessionId": "21415c60-1b3c-6452-57bc-c5d9415a4cae",
    "player": "Test01",
    "currency": "USD",
    "language": "en",
    "site": "inrmaster",
    "status": 200
    "message": "success",
    "hashValue": "8D66DAA2E2131C2C2B7B85A9972D407C6C7F",
}
Parameter Data Type Description Mandatory
playerToken String Player Token Required
sessionId String Game provider generated Unique identifier for a player engagement period Required
hashValue String HMACSHA(256) based hash value of the message with parameters (names but not values) in sorted order. Required

playerToken corresponds to what was received in the Game Launch request.

sessionId corresponds to a Unique identifier generated by the Game provider platform and is used with all Games Cycles for the corresponding playerToken.

It may happen that for a player Token, there may be multiple sessionlds as a player may launch multiple game windows. The playerToken validity is to be verified for each request by the Operator Platform and process the Request.

Authentication Response

The response expected will be in the form of JSON with the following parameters:

Parameter DataType Description Mandatory
playerToken String Player Token from Operator Required
sessionId String Session Id from Game Provider Required
player String Player Name for display in the Game Window Required
currency String Player Wallet Required
language String Player Game Language Required
site String Operator Id Required
status Int http Codes Required
message String Detailed Text Required
hashValue String HMACSHA(256) based hash value of the message with parameters (names) in sorted order. Required

Balance Request

The request method is POST. The balance is asynchronus call it will hit before and after every bet and win request something like this on balance API. The message body is sent in JSON with the following parameters.

URL: https://{{partnerURL}}/balance

Request Payload: 
{
    "playerToken": "02796215-ac3d-41d5-85ce-3bbdcaf86513",
    "sessionId": "21415c60-1b3c-6452-57bc-c5d9415a4cae",
    "hashValue": "8D66DAA2E2131C2C2B7B85A9972D407C6C7F"
}
Response: 
{
    "playerToken": "02796215-ac3d-41d5-85ce-3bbdcaf86513",
    "sessionId": "21415c60-1b3c-6452-57bc-c5d9415a4cae",
    "currency": "USD",
    "balance": 100.50,
    "status": 200,
    "message": "Balance fetched",
    "hashValue": "8D66DAA2E2131C2C2B7B85A9972D407C6C7F"
}
Parameter Datatype Description Mandatory
playerToken String Same as in Game Launch Request Required
sessionId String Same as in Authentication Request Required
hashValue String HMACSHA(256) based hash value of the message with parameters (names bu not values) in sorted order. Required

Balance Response

The response expected will be in the form of JSON with following parameters:

Parameter Datatype Description Mandatory
playerToken String Same as in Game Launch Request Required
sessionId String Same as in Authentication Request Required
currency String 3 Char ISO Code Required
balance BigDecimal With 2 decimals Required
status Int http Codes Required
message String Detailed Text Required
hashValue String Optional HMACSHA(256) based hash value of the message with parameters (names bu not values) in sorted order. Optional

Debit Request

The request method is POST. The request is made at the time of a player making a Bet on the Game. The message body is sent in JSON with the following parameters.

URL: https://{{partnerURL}}/debit

Request Payload: 
{
    "playerToken": "02796215-ac3d-41d5-85ce-3bbdcaf86513",
    "sessionId": "21415c60-1b3c-6452-57bc-c5d9415a4cae",
    "currency": "USD",
    "amount": 50.00,
    "type": "BET",
    "transactionId": 7788994468,
    "gameId": 20,
    "gameRoundId": 7896541230,
    "gameRoundStatus": "Bet",
    "gameFinished": false,
    "hashValue": "8D66DAA2E2131C2C2B7B85A9972D407C6C7F"
}
Response: 
{
    "status": 200,
    "message": "Success",
    "sessionId": "21415c60-1b3c-6452-57bc-c5d9415a4cae",
    "playerToken": "02796215-ac3d-41d5-85ce-3bbdcaf86513",
    "hashValue": "8D66DAA2E2131C2C2B7B85A9972D407C6C7F"
}
Parameter Datatype Description Mandatory
sessionId String Same as in Authentication Request Required
playerToken String Same as in Game Launch Request Required
currency String 3 Char ISO Code Required
amount BigDecimal With 2 decimals Required
type Transcation Type Create a Transaction Type pojo and add these Parameters like BET, WIN, REFUND Required
gameFinished boolean If game Finished set field as true or if game not finished set field as false. Required
transactionId long Unique Id Required
gameId long From the list supplied before Integration Required
gameRound Id long Unique ID Required
gameRoundStatus String Indicates the game state. Required
hashValue String HMACSHA(256)based hash value of the message with parameters (names bu not values) in sorted order. Required

A Balance Request will follow this Request to Refresh the Game Window Balance.

Debit Response

The response expected will be in the form of JSON with following parameters:

Parameter Datatype Description Mandatory
status Int http Codes Required
message String Detailed Text Required
sessionId String Required
playerToken String Same as in Authentication Request Same as in Game Launch Request Required
hashValue String HMACSHA(256) based hash value of the message with parameters (names bu not values) in sorted order. Required

Timeout Policy: If no response is received within 3 seconds, the request is considered failed.

Credit Request

The request method is POST. The request is made at time of Game round result is sent.

URL: https://{{partnerURL}}/credit

Request Payload: 
{
    "playerToken": "02796215-ac3d-41d5-85ce-3bbdcaf86513",
    "sessionId": "21415c60-1b3c-6452-57bc-c5d9415a4cae",
    "currency": "USD",
    "debitTransactionId": 7788994468,
    "winTransactionId": 1122334455,
    "winAmount": 75.00,
    "type": "WIN",
    "gameId": 20,
    "gameRoundId": 7896541230,
    "gameFinished": true,
    "hashValue": "8D66DAA2E2131C2C2B7B85A9972D407C6C7F"
}
Response: 
{
    "status": 200,
    "message": "Success",
    "sessionId": "21415c60-1b3c-6452-57bc-c5d9415a4cae",
    "currency": "USD",
    "winAmount": 75.00,
    "totalBalance": 125.50,
    "playerToken": "02796215-ac3d-41d5-85ce-3bbdcaf86513",
    "hashValue": "8D66DAA2E2131C2C2B7B85A9972D407C6C7F"
}
Parameter Datatype Description Mandatory
sessionId String Same as in Authentication Request Required
playerToken String Same as in Game Launch Request Required
currency String 3 Char ISO Code Required
debitTransactionId long Refers to Debit Transaction ID sent earlier Required
win Transaction Id long Unique ID for Game Result Required
gameFinished boolean If game Finished set field as true or if game not finished set field as false. Required
type Transaction Type Create a Transaction Type pojo and add these Parameters like BET, WIN, REFUND Required
winAmount BigDecimal With 2 decimals Required
gameId long Game Id Required
gameRoundId long Unique Id Required
hashValue String HMACSHA(256) based hash value of the message with parameters (names bu not values) in sorted order. Required

A Balance Request will follow this Request to Refresh the Game Window Balance.

Credit Response

Parameter Datatype Description Mandatory
status Int http Codes Required
message String Detailed Text Required
sessionId String Same as in Authentication Request Required
currency String 3 Char ISO Code Required
winAmount BigDecimal With 2 decimals Required
totalBalance BigDecimal With 2 decimals Required
playerToken String Same as in Game Launch Request Required
hashValue String HMACSHA(256) based hash value of the message with parameters (names but not values) in sorted order. Required

Retry Mechanism: If a response is not received, the credit request is retried after 1 minute.

Refund Request

The request method is POST. The request is made at time of any failure to accept Bet by the Game round.

URL: https://{{partnerURL}}/refund

Request Payload: 
{
    "playerToken": "02796215-ac3d-41d5-85ce-3bbdcaf86513",
    "sessionId": "21415c60-1b3c-6452-57bc-c5d9415a4cae",
    "currency": "USD",
    "debitTransactionId": "7788994468",
    "amount": 50.00,
    "transactionId": 999888777,
    "timestamp": "2023-04-07 07:04:00",
    "siteId": "inrmaster",
    "gameRoundId": 7896541230,
    "hashValue": "8D66DAA2E2131C2C2B7B85A9972D407C6C7F";
}
Response: 
{
    "status": 200,
    "message": "Success",
    "sessionId": "21415c60-1b3c-6452-57bc-c5d9415a4cae",
    "currency": "USD",
    "balance": 100.00,
    "playerToken": "02796215-ac3d-41d5-85ce-3bbdcaf86513",
    "hashValue": "8D66DAA2E2131C2C2B7B85A9972D407C6C7F";
}
Parameter Datatype Description Mandatory
sessionId Int Same as in Authentication Request Required
playerToken String Same as in Game Launch Request Required
currency String 3 Char ISO Code Required
debitTransactionId String Refers to Debit Transaction ID sent earlier Required
amount BigDecimal 2 decimal and equals to Bet amount Required
transactionId BigDecimal Unique Id for this transaction Required
timestamp BigDecimal Format ‘YYYY-MM-DD HH:Mi:SSsss Required
siteId String Operator Id Required
hashValue String HMACSHA(256) based hash value of the message with parameters (names but not values) in sorted order. Required

A Balance Request will follow this Request to Refresh the Game Window Balance.

Refund Response

Parameter Datatype Description Mandatory
status Int http Codes Required
message String Detailed Text Required
sessionId String Same as in Authentication Request Required
currency String 3 Char ISO Code Required
balance BigDecimal With 2 decimals Required
playerToken String Same as in Game Launch Request Required
hashValue String HMACSHA(256) based hash value of the message with parameters (names but not values) in sorted order. Required

Error Codes

The following table provides the various error code to be used in the respective events.

Error Code Action Description
200 All Ok / Success
107 Debit Insufficient Funds
109 Debit Wager Limit Exceeded
110 Debit Transaction Failed
111 All Unsupported gameId
112 All Game name does not exist
113 All Incorrect parameters
114 All Invalid player token
116 Debit / Credit Duplicate transaction
117 Credit / Refund Transaction not found
118 All Invalid currency
204 All Empty request
209 All Negative amount
400 All Bad Request
401 All Unauthorized / Session expired / Player not found
500 All Internal Server Error
503 All Service Unavailable
504 All Gateway Timeout

Game Codes

The below is the list of games and it changes with time. Please consult the technical team before Configuring.

GameName gameId
FUN_CARD 1
TARGET_TIMER 2
FUN_ROULETTE 3
TARGET 5
ROULETTE 6
MATKA1 7
EUROPEAN_ROULETTE_TIMER 12
EUROPEAN_ROULETTE 13
MATKA_NON 14
SORAT_TIMER 19
DRAGON_TIGER 20
MONEY_WHEEL 23
ANDAR_BAHAR 24
RUSSIAN_POKER 28
JACKS_OR_BETTER 30
CARIBBEAN_POKER 33
TROPICAL_STUD_POKER 39

Notes on Game Flow

Multi-Transaction Game Rounds

Some games, such as Poker variants, may involve multiple actions in a single round (e.g., side bets, insurance, card buys). Each action must be sent as an independent API call with unique transaction identifiers.

Supported transactionType Values: