Integrate as Games Provider

Provider Integration

This type of integration is aimed at those Partners who would like to integrate as a game provider, i.e integrate into BETCORE platform.

Seamless integration between Game Providers and Aggregators is vital for delivering a smooth player experience.

This API documentation serves as a comprehensive Integration guide for Game Providers, outlining the necessary steps to establish a robust connection, ensure secure transactions, and facilitate real-time data exchange. Here, you will find detailed instructions on authentication, integration processes, and best practices to optimize your gaming offerings.

What's new?

This table shows a history of recent updates to the BETCORE Aggregator API Documentation.

Date	Change
Mar 13, 2025	Try it out • Cloud mocks are configured for the endpoints, so you can try the methods out right from the documentation.
Feb 19, 2025	BetId • Now it is a unique ID of the user's bet in the game provider's system. Applies to all APIs (payIn, payOut, payInOut, refund).
Oct 10, 2024	PayInOut • WinOdd field was added (winning coefficient).
Oct 9, 2024	The terms used in the document were aligned with the glossary of terms to ensure clarity and consistency throughout the document.
Sep 12, 2024	Launch Game: • Demo mode explanation was corrected in the gameMode field. Now, instead of the line “demo”, the same sessionId that returns in launch request should be passed as the sessionId. PayOut: • WinOdd field was added (winning coefficient).
Aug 16, 2024	Launch Game: • minBet and maxBet were changed to obligatory fields. • Demo mode explanation was corrected in the gameMode field. UserId was replaced with sessionId. Possible response codes: • Authorization error was added (_responseCode 8 – HTTP 401).
Aug 13, 2024	Authentication • The example was supplemented with an explanation that the body may be absent in the concatenation.
Aug 6, 2024	GetGamesList • lobbyImgUrl response field was added.
Jul 25, 2024	GetGamesList • The maxOdd response field changed to optional depending on the game category.
Jul 3, 2024	Authentication and verification protocol was changed to HMAC.SHA256. A list of mandatory HTTP Headers has been defined. Minor changes were made to API fields, paths, and HTTP methods to follow the REST API format. Versioning of requests in request path was added. RefreshSessionToken endpoint was removed. Get Games List: • gameCategory parameter was added. • GameType parameter was renamed to gameId. Launch Game (ex. GetIFrameUri): • GameType and TimeZone parameters were removed. • Uri parameter was renamed to frameUri • SessionToken parameter was renamed to sessionId. GetBalance (ex. GetAccount): • GameType and UserId parameters were removed. CalculateCrashCoefficient (ex. GetCrashCoefficient): • Uuid, SeedHashes and GameType parameters were removed. • GameRoundId parameter was added. PayIn/PayOut/PayInOut/Refund: • Incoming parameters Bet/Win TransactionId and TicketId were replaced with betId and gameRoundId. Terms and Definitions section was added.
Mar 4, 2024	The document was created.

Quick Links

Authentication: details on authentication process.

Provider API for Aggregator: requests from Game Aggregator to Provider.

Aggregator API for Provider: requests from Provider to Game Aggregator.

Terms and definitions

Term	Definition
Aggregator	A system that offers common interfaces for connecting multiple game providers, with the aim of delivering their services to the clients.
Bet	User's action of investing funds in a game, anticipating the success of a specific gaming event.
Counterparty ID	A unique public identifier of a Game Provider in the Aggregator system. or The identifier provided by the Aggregator during the onboarding process.
Counterparty Key	The private key of the Game Provider in the Aggregator system, provided during the onboarding process.
Game	The specific instance game supplied by the Game Provider.
Game Category	A group of games united by a common gameplay mechanic. Possible value: Crash.
Game Provider	A system that directly implements the functionality of game mechanics.
Game Round	A game iteration that includes betting phase, draw, and determination of results. Multiple rounds can be played within a single game iteration.
Game Session	Overall gameplay activity within a single game launched in one instance of a frame for one user.

Integration Process

Integration Process involves two parties:

Game Provider – The party supplying the gaming content, specifically: frame displaying the game, interface for entering the bet amount and buttons for accepting bets, the internal game logic, etc.

Aggregator – A platform that integrates the Provider's games and further distributes them to various customers.

The Game Provider implements a number of API endpoints on its side:

• Games – getting a list of available games (GET /games).

• Launch – launching a game session and getting a link to the frame with the game (POST /games/{gameId}/launch).

The Game Provider provides the Aggregator with a Stage providers-api-url, where the endpoints must be available.

The Aggregator provides the Game Provider with its Base aggregators-api-url, where the endpoints for conducting betting operations must be available:

• PayIn – accepting a bet (POST /sessions/{{sessionId}}/bets/pay-in).

• PayOut – bet payout (POST /sessions/{{sessionId}}/bets/pay-out).

• PayInOut – simultaneous acceptance and payout of bet (POST /sessions/{{sessionId}}/bets/pay-in-out).

• Refund – bet refund (POST /sessions/{{sessionId}}/bets/refund).

The Aggregator provides the Game Provider with a page to launch and test the integration using test accounts.

After the tests are completed the Game Provider is given a new pair of Counterparty ID and Counterparty Key for the Production environment, and the Game Provider provides the Aggregator with a Production Base URL. The launch is then planned.

Workflow diagram

Authentication

Communication between the Aggregator and the Game Provider represents a back-to-back connection with mutually trusting participants.

The HMAC SHA256 algorithm is used for request authentication.

All requests between the Aggregator and the Game Provider are signed with HMAC and verified with the private Counterparty Key, which is provided during the onboarding stage of the Game Provider.

The HMAC SHA256 algorithm is used to generate the signature.

Each request has a set of mandatory parameters that are passed in the HTTP Headers:

Header name	Format	Comment
X-Counterparty-Id	string	The public identifier of the subject provided during the onboarding process.
X-Timestamp	13 digits Unix epoch timestamp	Request generation time. All requests longer than 30 seconds will be considered expired.
X-Request-Id	string	A random sequence of 32 hexadecimal digits (Nonce) representing a unique request identifier.
X-Sign	string	HMAC.SHA256 message signature.

For any request from the Aggregator to the Game Provider or vice versa, an authentication code for the request must be generated using the private key (Counterparty Key). Then this code must be sent in the X-Sign request header for validation on the recipient's side.

Example of calculating the X-Sign value

Take the JSON body of the HTTP request being sent.

Convert it to canonical JSON scheme RFC 8785: JSON Canonicalization Scheme (JCS):

{"gameId":1,"gameRoundId":"322bca0b-a883-4f52-9b72-3c800b936ae5"}

If there is no request body (GET request), then omit it during concatenation. For the example above, you get:
933a215f-a9e6-4f88-9d91-52a87cd50499.1719766365.ajdfb72nedfisd8723d8esn

Using the private Counterparty Key obtained during the onboarding process, calculate
HMAC.SHA256({{HTTP_Request_Body}}.{{X-Counterparty-Id}}.{{X-Timestamp}}.{{X-Request-Id}}, Counterparty_Key):

c4d62f77cdfaadb6690b3bcbe5a0ca9ef1e5bf41d746d361a1269558eeb7ccd1

Add the calculated value to the X-Sign header along with the other values used:

POST / HTTP/1.1
X-Counterparty-Id: 933a215f-a9e6-4f88-9d91-52a87cd50499
X-Timestamp: 1719766365
X-Request-Id: 5a0679b6e5fa48f6892c777b0fa92392
X-Sign: c4d62f77cdfaadb6690b3bcbe5a0ca9ef1e5bf41d746d361a1269558eeb7ccd1
...
Content-Type: application/json

{"gameId":1,"gameRoundId":"322bca0b-a883-4f52-9b72-3c800b936ae5"}

Response Codes

To implement the logic of request calls, please also take into account the response codes and server or network errors.

Code	Description	HTTP Status
1	Success	200
2	Insufficient funds	402
3	User is blocked	403
4	User's betting limit reached	429
5	Maximum user coefficient threshold reached	429
6	The bet amount is outside the minimum and maximum bet limits	400
7	Request rejected. Unable to place a bet due to internal system reasons	500
8	Authorization error	401
9-98	Reserved
99	System error	500

Error Handling Scenarios

Errors	Actions
Response Codes: 2 - 8	If you receive one of the error codes listed, it is assumed that the bet was not accepted and no further action is required. It is advisable to display a message to the user about the cause of the error.
• Response Code 99 • Request Timeout • HTTP 5xx	When PayInOut requests were sent: • Retry the request within an acceptable time period. • Make a Refund request if retry didn’t help. When PayOut or Refund requests were sent: • The request must be repeated until its successful execution (response code 1). Retries must be done with exponential timing, up to 24hrs maximum. • If all attempts were unsuccessful, then the IDs of such bets should be collected and transferred to the Aggregator for further manual analysis.

Errors

Actions

Response Codes:
2 - 8

If you receive one of the error codes listed, it is assumed that the bet was not accepted and no further action is required.
It is advisable to display a message to the user about the cause of the error.

• Response Code 99
• Request Timeout
• HTTP 5xx

When PayInOut requests were sent:

• Retry the request within an acceptable time period.
• Make a Refund request if retry didn’t help.

When PayOut or Refund requests were sent:

• The request must be repeated until its successful execution (response code 1). Retries must be done with exponential timing, up to 24hrs maximum.
• If all attempts were unsuccessful, then the IDs of such bets should be collected and transferred to the Aggregator for further manual analysis.

Provider Integration#

Quick Links#

Terms and definitions#

Integration Process#

Workflow diagram#

Authentication#

Example of calculating the X-Sign value#

Response Codes#

Error Handling Scenarios#

Provider Integration

Quick Links

Terms and definitions

Integration Process

Workflow diagram

Authentication

Example of calculating the X-Sign value

Response Codes

Error Handling Scenarios