Section 05

Aggregator endpoints

Game list, opening and closing sessions, and round lookup.

Aggregator endpoints#

These are the endpoints your platform calls on AIC: list games, open a game for a player, close the game session, and query the detail of a round. Protected endpoints require the Bearer JWT token (see Connection setup).

Get game list#

Returns the games enabled for your project.

POST{{URL_AGG}}/games/getGameList

AuthBearer JWT required

Example request

curl -X POST "{{URL_AGG}}/games/getGameList" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "projectId": "projectId"
  }'

Request body

Parameter	Type	Required	Description
projectId	string	Yes	Your project's Project ID.

Successful response (excerpt)

{
  "statusCode": 200,
  "data": [
    {
      "id": "clmgj4mer000fawnho0gyt7ma",
      "gameId": "clmgj4mer000fawnho0gyt7ma",
      "name": "Roman",
      "imageUrl": "https://res.cloudinary.com/.../clmgj4mer000fawnho0gyt7ma.png",
      "gameCategoryCat": {
        "id": "cl8z582jm0000vu1keo4slqp3",
        "name": "Slots",
        "code": "sm"
      },
      "gameModel": "SEAMLESS",
      "supplierName": "AIC Games",
      "enabled": true,
      "gameAggregatorStatusCat": "Enabled"
    }
  ],
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Relevant fields per game

Parameter	Type	Description
gameId	string	Game identifier. It is the value you send in enterGame and the one you will receive in wallet calls.
name	string	Commercial name of the game.
imageUrl	string	Game image for your lobby.
gameCategoryCat	object	Game category (name and code).
gameModel	string	Wallet type of the game: SEAMLESS or TRANSFER.
supplierName	string	Commercial name of the game's supplier or brand.
enabled	boolean	Whether the game is enabled for your project.

Note

The response includes additional fields for internal use; base your integration only on the fields documented in this table.

Open a game#

Opens a game session for a player and returns the launch URL.

POST{{URL_AGG}}/games/enterGame

AuthBearer JWT required

Example request

curl -X POST "{{URL_AGG}}/games/enterGame" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "gameId": "clmgj4mer000fawnho0gyt7ma",
    "playerName": "casinoPlayer123",
    "projectId": "projectId",
    "token": "playerSessionToken",
    "language": "es",
    "device": "desktop"
  }'

Successful response

{
  "statusCode": 200,
  "data": {
    "url": "https://provider.example.com/launch?session=..."
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Error response

{
  "statusCode": 200,
  "data": "GAME_DISABLED",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Body parameters

Parameter	Type	Required	Description
gameId	string	Yes	Game identifier (from the game list).
playerName	string	Yes	Player identifier on your platform. See the rules in Wallet flows.
projectId	string	Yes	Your project's Project ID.
token	string	Yes	Player session token generated by your platform, unique per game session. AIC will send it back as token_room on every wallet call so you can identify the session.
language	string	No	Game language (e.g. es, en, pt). Applies if the supplier supports it.
device	string	No	Device type: desktop or mobile. Applies if the supplier supports it.

Response

Success: data.url holds the game launch URL. Some suppliers return data.html instead, a document you must embed rather than redirect to.
Errors: the game could not be opened in any of these cases:

Response	Meaning
HTTP 401 or 402 with `No games available`	Your project is not enabled or has no games available.
HTTP 200 with `data` = `No games available`	The game is not available for your project.
HTTP 200 with `data` = `GAME_DISABLED`	The game is disabled.
HTTP 200 with `data` = `Not a valid supplier`	The game's supplier is not available for your project.
HTTP 400 with `An error has occurred in enterGame`	The game could not be opened (for example, a non-existent `gameId`).

Important

Launch the game only if the response is HTTP 200 and data is an object with url (or html). Any other response means the game was not opened.

Close the game session#

Closes the player's game session. It is mandatory for Transfer games: it is the call that brings the balance back to your platform (see Wallet flows).

POST{{URL_AGG}}/games/logout-game/:projectId

AuthBearer JWT required

Example request

curl -X POST "{{URL_AGG}}/games/logout-game/:projectId" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "playerName": "casinoPlayer123"
  }'

Successful response

{
  "statusCode": 200,
  "data": {
    "status": "success",
    "message": "user logged out successfully"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

URL parameter

Parameter	Type	Required	Description
projectId	string	Yes	Your project's Project ID.

Body parameters

Parameter	Type	Required	Description
playerName	string	Yes	Identifier of the player whose session is closed.

The session is looked up only within your project. If the playerName has no open session in your project, the response is HTTP 200 with data = { "status": "error", "message": "GAME_ROOM_NOT_FOUND" } and no session is closed.

Note

For Transfer games, the resulting balance does not travel in this response: AIC credits it to your platform through the add-win call to your API.

Get played round#

Queries the detail of a round. Useful for reconciliation and incident handling.

GET{{URL_AGG}}/games/:merchantName/round-played/:idTransaction

AuthBearer JWT required

Example request

curl "{{URL_AGG}}/games/:merchantName/round-played/:idTransaction" \
  -H "Authorization: Bearer <token>"

Successful response

{
  "data": {
    "id": "9db6be09-7afa-4a30-b388-66ffa1f2f191",
    "playerName": "casinoPlayer123",
    "amountBet": 90,
    "amountWin": 100,
    "balanceAfterBet": 10,
    "balanceAfterWin": 110,
    "idTransaction": "9db6be09-7afa-4a30-b388-66ffa1f2f190",
    "token_room": "playerSessionToken",
    "gameId": "clmgj4mer000fawnho0gyt7ma",
    "timestamp": "1723644383536",
    "movements": [
      {
        "movementId": "3f2a9c4e-7b1d-5e8a-9c2f-1a6b4d8e0f73",
        "type": "add-bet",
        "amount": 90,
        "idTransaction": "9db6be09-7afa-4a30-b388-66ffa1f2f190",
        "createdAt": "2026-11-02T15:39:12.104Z"
      },
      {
        "movementId": "b7d40e19-2c8f-5a6e-8d13-5f9c0a2e7b46",
        "type": "add-win",
        "amount": 100,
        "idTransaction": "9db6be09-7afa-4a30-b388-66ffa1f2f191",
        "createdAt": "2026-11-02T15:39:14.587Z"
      }
    ]
  },
  "status": {
    "code": "0",
    "message": "Success",
    "datetime": "2026-10-20T21:07:03.930Z"
  }
}

Error response

{
  "data": null,
  "status": {
    "code": 404,
    "message": "Transaction not found",
    "datetime": "2026-10-20T15:34:40.304Z"
  }
}

URL parameters

Parameter	Type	Required	Description
merchantName	string	Yes	Your project's Merchant Name.
idTransaction	string	Yes	idTransaction you received in the wallet call (add-bet or add-win) of that round.

Errors

Unknown Merchant Name: HTTP 400 with CUSTOMER_NOT_FOUND.
Transaction not found: HTTP 200 with status.code 404.
Transaction that does not belong to your project: HTTP 200 with status.code 409.

Response fields

Parameter	Type	Description
id	string	Transaction id.
playerName	string	Player identifier.
amountBet	number	Amount bet.
amountWin	number	Amount won (0 if there was no win).
balanceAfterBet	number	Balance after the bet.
balanceAfterWin	number	Balance after the win (null if there was no win).
idTransaction	string	Transaction identifier.
timestamp	string	Round timestamp in milliseconds (Unix epoch).
token_room	string	Token of the associated game session.
gameId	string	Game identifier.
movements	array	Balance movements of the round, in order. Each one has movementId, type (add-bet, add-win or rollback), amount, idTransaction and createdAt.