Aggregator API Documentation

Overview

This documentation provides details on the API endpoints for the casino aggregator, including request and response formats for various operations.

Base URLs

Environment Base URL
Staging https://staging.example.com/api/v1/{tenant}
Production https://prod.example.com/api/v1/{tenant}

Endpoints

1. Get All Games

Retrieve all available games.

GET /games

Response

The response is paginated and includes the following fields:

Field Name Type Description
id Integer The unique identifier for the game.
name String The name of the game.
image String The URL of the game's image.
category String The category of the game.
provider Object An object containing provider details (id and image).

Example Response:

{
    "data": [
        {
            "id": 1,
            "name": "Game One",
            "image": "https://example.com/images/game1.png",
            "category": "Slot",
            "provider": {
                "id": 1,
                "image": "https://example.com/images/provider1.png"
            }
        }
    ],
    "links": {
        "first": "https://example.com/api/v1/{tenant}/games?page=1",
        "last": "https://example.com/api/v1/{tenant}/games?page=10",
        "prev": null,
        "next": "https://example.com/api/v1/{tenant}/games?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 10,
        "path": "https://example.com/api/v1/{tenant}/games",
        "per_page": 15,
        "to": 15,
        "total": 150
    }
}

2. Launch Game

Launch a specific game by sending a POST request.

POST /games/launch

Request Body

The request to launch a game includes the following parameters:

Field Name Type Required Description
game_id Integer Yes The unique identifier for the game.
player_id Integer Yes The unique identifier for the player.
player_name String Yes The username of the player.
player_balance Double Yes The player's balance in the specified currency.
platform Boolean Yes Indicates the platform from which the game is being launched. true for mobile and false for desktop.

Example Request:

{
    "game_id": 1,
    "player_id": 123,
    "player_name": "PlayerOne",
    "player_balance": 1500.00,
    "platform": true
}

Response

The response from the casino aggregator includes the following fields:

Field Name Type Required Description
sessionId String Yes A unique session identifier for the game session.
url String No The URL to launch the game.
html String No The HTML content to embed the game.

Example Response:

{
    "sessionId": "abc123",
    "url": "https://gameurlexample.com",
    "html": "
Game HTML Content
"
}

3. Get All Providers

Retrieve all game providers.

GET /providers

Response

The response is paginated and includes the following fields:

Field Name Type Description
id Integer The unique identifier for the provider.
image String The URL of the provider's image.

Example Response:

{
    "data": [
        {
            "id": 1,
            "image": "https://example.com/images/provider1.png"
        }
    ],
    "links": {
        "first": "https://example.com/api/v1/{tenant}/providers?page=1",
        "last": "https://example.com/api/v1/{tenant}/providers?page=10",
        "prev": null,
        "next": "https://example.com/api/v1/{tenant}/providers?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 10,
        "path": "https://example.com/api/v1/{tenant}/providers",
        "per_page": 15,
        "to": 15,
        "total": 150
    }
}

4. Get Games by Provider

Retrieve all games by a specific provider.

GET /provider/{provider}/games

Callbacks

Bet Callback

The Bet callback handles the betting action within the game.

Request Body

The request to place a bet includes the following parameters:

Field Name Type Required Description
transactionId UUID Yes The unique identifier for the transaction.
betAmount Integer Yes The amount being bet.
roundId Integer Yes The unique identifier for the game round.
freeSpin Boolean Yes Indicates if the bet is part of a free spin.
playerId Integer Yes The unique identifier for the player.
gameId Integer Yes The unique identifier for the game.

Example Request:

{
    "transactionId": "123e4567-e89b-12d3-a456-426614174000",
    "betAmount": 100,
    "roundId": 1,
    "freeSpin": false,
    "playerId": 123,
    "gameId": 1
}

Response

The response to a bet request includes the following fields:

Field Name Type Required Description
statusCode Integer Yes The status code of the response (e.g., 0 for success).
status String Yes The status message.
balance Double Yes The updated balance of the player.

Example Response:

{
    "statusCode": 0,
    "status": "success",
    "balance": 1400.00
}

Win Callback

The Win callback handles the winning action within the game.

Request Body

The request to record a win includes the following parameters:

Field Name Type Required Description
transactionId UUID Yes The unique identifier for the transaction.
winAmount Integer Yes The amount won.
roundId Integer Yes The unique identifier for the game round.
freeSpin Boolean Yes Indicates if the win is part of a free spin.
jackpot Boolean No Indicates if the win includes a jackpot.
playerId Integer Yes The unique identifier for the player.
gameId Integer Yes The unique identifier for the game.

Example Request:

{
    "transactionId": "123e4567-e89b-12d3-a456-426614174000",
    "winAmount": 200,
    "roundId": 1,
    "freeSpin": false,
    "jackpot": true,
    "playerId": 123,
    "gameId": 1
}

Response

The response to a win request includes the following fields:

Field Name Type Required Description
statusCode Integer Yes The status code of the response (e.g., 0 for success).
status String Yes The status message.
balance Double Yes The updated balance of the player.

Example Response:

{
    "statusCode": 0,
    "status": "success",
    "balance": 1600.00
}

Rollback Callback

The Rollback callback handles the action of rolling back a transaction within the game.

Request Body

The request to rollback a transaction includes the following parameters:

Field Name Type Required Description
transactionId UUID Yes The unique identifier for the transaction.
roundId Integer Yes The unique identifier for the game round.
playerId Integer Yes The unique identifier for the player.
gameId Integer Yes The unique identifier for the game.

Example Request:

{
    "transactionId": "123e4567-e89b-12d3-a456-426614174000",
    "roundId": 1,
    "playerId": 123,
    "gameId": 1
}

Response

The response to a rollback request includes the following fields:

Field Name Type Required Description
statusCode Integer Yes The status code of the response (e.g., 0 for success).
status String Yes The status message.
balance Double Yes The updated balance of the player.

Example Response:

{
    "statusCode": 0,
    "status": "success",
    "balance": 1500.00
}

Approve Callback

The Approve callback handles the action of approving a game round.

Request Body

The request to approve a game round includes the following parameters:

Field Name Type Required Description
roundId Integer Yes The unique identifier for the game round.
playerId Integer Yes The unique identifier for the player.
gameId Integer Yes The unique identifier for the game.

Example Request:

{
    "roundId": 1,
    "playerId": 123,
    "gameId": 1
}

Response

The response to an approve request includes the following fields:

Field Name Type Required Description
statusCode Integer Yes The status code of the response (e.g., 0 for success).
status String Yes The status message.

Example Response:

{
    "statusCode": 0,
    "status": "approved"
}

End Callback

The End callback handles the action of ending a game session.

Request Body

The request to end a game session includes the following parameters:

Field Name Type Required Description
playerId Integer Yes The unique identifier for the player.

Example Request:

{
    "playerId": 123
}

Response

The response to an end request includes the following fields:

Field Name Type Required Description
statusCode Integer Yes The status code of the response (e.g., 0 for success).
status String Yes The status message.

Example Response:

{
    "statusCode": 0,
    "status": "success"
}

Security

All requests include a signature for security purposes. This signature is generated using the createSign method from the SignService class.

Creating a Signature

The signature generation involves:

  1. Generating headers including X-Nonce, X-Timestamp, and Authorization.
  2. Merging these headers with the request parameters.
  3. Sorting the merged parameters.
  4. Generating a SHA256 HMAC using the sorted parameters and the secret key.
  5. Including the HMAC in the request headers as X-Sign.

Validating a Signature

The signature validation involves:

  1. Extracting headers including X-Nonce, X-Timestamp, and Authorization from the request.
  2. Merging these headers with the request parameters.
  3. Sorting the merged parameters.
  4. Generating a SHA256 HMAC using the sorted parameters and the secret key.
  5. Comparing the generated HMAC with the X-Sign header from the request.

Status Codes

The following table outlines the status codes used in responses:

Status Code Description
200 Success
0 General Error
1 Information Mismatch
2 Token Not Found
3 Token Expired
4 Insufficient Balance
5 Wager Denied
6 Transaction Not Found
7 Crediting Denied
8 Non-Revocable Transaction
9 Duplicate Transaction
400 Invalid Request Parameters

Response Handling

The responses for callbacks have two ways of handling, based on the response code:

  1. Success Response (Code: SUCCESS)
  2. Error Response