Balla Games Platform Integration

Introduction

This document provides technical details required to Integrate with the Game Platform by the Operators or Aggregators Platform. The Integration is made available with REST APIs that receive and respond with JSON objects. The Game Client operates via Secure Web Socket Connection to Game Servers. The Integration may be co-ordinated with the technical team to facilitate a few Configurations before Start.

Getting Started

The APIs operate with Content-type for the requests is application/json. All money transactions for currencies are carried out in cents. Operators / Aggregators may note that all Transactions MUST be idempotent.

The following Parameters are required to be Configured on the Game Servers.

Parameter	Data Type	Description
Site	String	Brand Site name
Currency	String	INR, USD, EUR 3 character ISO code for Currency
authentication URL	String	URL for Authentication Request
balanceURL	String	URL for Player Balance
debitURL	String	URL for Debit Request
creditURL	String	URL for Credit Request
refundURL	String	URL for Debit Refund
Language	String	2 Character ISO Code for Language en English, pt Portuguese
playerToken	String	A Unique identifier representing a player for game activities generated by Operator
sessionId	String	A Unique identifier from the Game Provider platform for a player to use its games.
secretKey	String	A String based secret key is shared by each side with the other for generating Hash value of the parameters being sent.

For Integration development, the Operator is required to work with Staging environment for which the URL may be obtained from the technical team. The game names and game ids will also be provided before the Start of the Integration.

Game Launch

The Game Client may be launched with the following URL:

https://<game_provider_domain>/<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).

gameID: corresponds to a Game that is being launched.
site: corresponds to the name of the Brand and may or may not relate to the URL or Web Domain. It is an identifier to a commercial entity.
playerToken: corresponds to a Unique identifier for Player Game activities provided by the Operator platform.

Authentication

The request method is POST. The Operator / Aggregator URL is configured on the Server. 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.

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.	Optional

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.	Optional

Balance Request

The request method is POST. The request is sent more often to inquire player balance for display on the Game client display from time to time. The Operator / Aggregator URL is configured on the Server. The message body is sent in JSON with the following parameters.

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.	Optional

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 Operator / Aggregator URL is configured on the Server. The message body is sent in JSON with the following parameters.

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.	Optional

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.	Optional

Credit Request

The request method is POST. The request is made at time of Game round result is sent. The Operator / Aggregator URL is configured on the Server.

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.	Optional

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.	Optional

Refund Request

The request method is POST. The request is made at time of any failure to accept Bet by the Game round. The operator / Aggregator URL is configured on the Server.

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.	Optional

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.	Optional

Error Codes

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

Error Code	Description
200	Ok
200	success
107	Insufficient Funds
109	Wager Limit Exceeded
110	Transaction Failed
111	Unsupported gameId
112	Game name does not exist
113	Incorrect parameters
114	Incorrect player identifier for secure token
116	Transaction already exists
117	Transaction does not exist
118	Invalid currency
204	Empty request
209	Negative amount value
400	Bad Request
401	Player account locked
401	Incomplete or malformed request
401	Player not found
401	Invalid secure token
401	The player session has expired
401	The player session Not Found
500	Internal Server Error
503	Service Unavailable
504	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

INTEGRATION API EXAMPLE

Authentication Request

https://{{URL}}/authentication

Request Payload

{
    "playerToken": "49e37c1d-abb2-421f-aa83-17fecdebf24e"
}

Response

{
    "currency": "USD",
    "language": "English",
    "message": "success",
    "player": "partialBonus",
    "playerToken": "49e37c1d-abb2-421f-aa83-17fecdebf24e",
    "site": "your network",
    "status": 200
}

Balance Request

https://{{partnerURL}}/balance

Request Payload

{
    "playerToken": "49e37c1d-abb2-421f-aa83-17fecdebf24e"
}

Response

{
    "balance": 3679.40,
    "currency": "USD",
    "message": "Success",
    "playerToken": "49e37c1d-abb2-421f-aa83-17fecdebf24e",
    "status": 200
}

Debit Request

https://{{partnerURL}}/debit

Request Payload

{
    "playerToken": "{{iToken}}",
    "currency": "USD",
    "amount": 50,
    "type": "ANTE_BET",
    "transactionId": 7788994468,
    "gameId": 20,
    "gameRoundId": 7896541230,
    "gameRoundStatus": "Bet",
    "hashValue": null,
    "gameFinished": false
}

Response

{
    "message": "Success",
    "playerToken": "49e37c1d-abb2-421f-aa83-17fecdebf24e",
    "status": 200
}

Credit Request

https://{{partnerURL}}/credit

Request Payload

{
    "playerToken": "{{iToken}}",
    "currency": "USD",
    "winAmount": 20,
    "type": "ANTE_WIN",
    "transactionId": 1234564023,
    "gameId": 20,
    "gameRoundId": 7896541230,
    "gameRoundStatus": "Win",
    "gameFinished": false
}

Response

{
    "message": "Success",
    "playerToken": "9427d3e2-4d7e-4469-b1cb-8b0d57794437",
    "status": 200
}

Refund Request

https://{{partnerURL}}/refund

Request Payload

{
    "playerToken": "{{iToken}}",
    "currency": "USD",
    "debitTransactionId": "7788994468",
    "amount": 16.0,
    "transactionId": 426545475,
    "timestamp": "2023-04-07 07:04:0000",
    "siteId": "your site name",
    "gameRoundId": 7896541230
}

Response

{
    "message": "Success",
    "playerToken": "9427d3e2-4d7e-4469-b1cb-8b0d57794437",
    "status": 200
}

Note:

A round id can have multiple bets for example russian poker have AnteBet,Bet,InsuranceBet in single round as well as one roundId can have multiple win transaction each transaction have its unique ID (transaction ID).