Callbacks¶

Callbacks are HTTP requests that the platform sends to the agent to process game transactions and balance requests. The agent must implement an endpoint to receive these requests.

General information¶

Callback URL¶

The callback URL is configured by the platform manager. Contact your platform manager to set it up.

Important

The URL must be publicly accessible and accept HTTPS requests.

Request format¶

Method: POST
Content-Type: application/json
X-Signature: Request signature in headers. Verify the signature before processing as described in Authorization.

Every callback includes request_id — a unique identifier of the incoming request on the platform side. Use it to correlate logs when investigating incidents (timeouts, duplicates, errors). The field is included in the X-Signature calculation.

Response format¶

All responses must be JSON:

Success response:¶

{
  "content": {
    "balance": 1000.50
  }
}

Error response:¶

{
  "error": "error_code",
  "message": "Error description"
}

getBalance — Balance request¶

The platform requests the player’s current balance. This callback is called:

When launching a game (to display the initial balance)
Periodically during the game (to keep the balance in sync)

Request parameters:

Parameter	Type	Description
`agent_id`	integer	Agent ID
`session_id`	string	Game session ID
`player_id`	string	Player ID
`player_username`	string	Player username
`type`	string	Callback type: `"getBalance"`
`game_id`	integer	Game ID
`currency`	string	Currency code (`RUB`, `USD`, `EUR`, etc.)
`language`	string	Language code (`ru`, `en`, etc.)
`request_id`	string	Unique platform-side request ID (for log correlation)
`freespins`	object	Optional. Free spins progress (see below)

Example request (without free spins):¶

POST /callback HTTP/1.1
Host: your-domain.com
Content-Type: application/json
X-Signature: abc123def456...

{
  "agent_id": 1,
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "player_id": "player_123",
  "player_username": "john_doe",
  "type": "getBalance",
  "game_id": 123,
  "currency": "RUB",
  "language": "ru",
  "request_id": "ba9d4445-779f-4b04-8bcb-6d17bc8dc3da"
}

Free spins progress¶

If the player has active free spins for the session’s game and currency, the platform adds a freespins object to the callback:

Field	Type	Description
`freespins.played`	integer	Number of free spins already played
`freespins.total`	integer	Total number of free spins in the pack
`freespins.is_finish`	boolean	`true` when all free spins are played (`played >= total`)
`freespins.accumulated_win`	float	Accumulated win for the pack

When the field is present:

While the player has active free spins for this game and currency — freespins is sent on every getBalance callback.
On the last free spin, is_finish: true is sent — this is the final notification that the pack is complete.
After the pack is finished, regular getBalance callbacks no longer include freespins.
The free spins win may be credited after the last getBalance with is_finish: true — in a separate makeBet callback with a win field. Do not use accumulated_win from getBalance to update the balance.

Agent-side handling

The agent response format does not change — return only content.balance. The freespins field is for the agent to track progress (UI, internal logic, etc.). If the field is present in the request, it is included in the X-Signature calculation.

Example request with free spins:¶

POST /callback HTTP/1.1
Host: your-domain.com
Content-Type: application/json
X-Signature: abc123def456...

{
  "agent_id": 1,
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "player_id": "player_123",
  "player_username": "john_doe",
  "type": "getBalance",
  "game_id": 123,
  "currency": "RUB",
  "language": "ru",
  "request_id": "ba9d4445-779f-4b04-8bcb-6d17bc8dc3da",
  "freespins": {
    "played": 3,
    "total": 10,
    "is_finish": false,
    "accumulated_win": 12.50
  }
}

Response format:¶

{
  "content": {
    "balance": 1000.50
  }
}

Response fields:¶

Field	Type	Required	Description
`content.balance`	float	Yes	Current player balance in the specified currency

makeBet — Bet and win¶

The platform notifies the agent about the player’s bet and win. When processing the callback, you must:

Debit the bet amount (bet) from the player’s account
Credit the win amount (win) to the player’s account
Return the player’s updated balance

Request parameters:¶

Parameter	Type	Description
`agent_id`	integer	Agent ID
`session_id`	string	Game session ID
`player_id`	string	Player ID
`player_username`	string	Player username
`type`	string	Callback type: `"makeBet"`
`currency`	string	Currency code
`language`	string	Language code
`bet`	float	Bet amount (debit)
`win`	float	Win amount (credit)
`transaction_id`	string	Unique transaction ID
`game_round_id`	string	Game round ID
`round_finished`	boolean	Whether the round is finished
`request_id`	string	Unique platform-side request ID (for log correlation)

Example request:¶

POST /callback HTTP/1.1
Host: your-domain.com
Content-Type: application/json
X-Signature: abc123def456...

{
  "agent_id": 1,
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "player_id": "player_123",
  "player_username": "john_doe",
  "type": "makeBet",
  "currency": "RUB",
  "language": "ru",
  "bet": 10.50,
  "win": 25.00,
  "transaction_id": "txn_abc123",
  "game_round_id": "round_xyz789",
  "round_finished": true,
  "request_id": "ba9d4445-779f-4b04-8bcb-6d17bc8dc3da"
}

Response format:¶

{
  "content": {
    "balance": 1015.00
  }
}

Handling logic:¶

Verify the request signature as described in Authorization
Check whether the transaction has already been processed (by transaction_id)
If it has, return the current balance (without repeating debit/credit)
If it’s a new transaction:
- Verify the player has enough balance for the bet
- Debit bet from the player’s account
- Credit win to the player’s account
- Save the transaction information
- Return the updated balance

rollback — Transaction rollback¶

The platform requests cancelling a previous transaction. This may happen due to:

Technical issues
The player leaving/cancelling the game
Errors while processing the transaction

Request parameters:¶

Parameter	Type	Description
`agent_id`	integer	Agent ID
`session_id`	string	Game session ID
`player_id`	string	Player ID
`player_username`	string	Player username
`type`	string	Callback type: `"rollback"`
`currency`	string	Currency code
`language`	string	Language code
`transaction_id`	string	Transaction ID to rollback
`request_id`	string	Unique platform-side request ID (for log correlation)

Example request:¶

POST /callback HTTP/1.1
Host: your-domain.com
Content-Type: application/json
X-Signature: abc123def456...

{
  "agent_id": 1,
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "player_id": "player_123",
  "player_username": "john_doe",
  "type": "rollback",
  "currency": "RUB",
  "language": "ru",
  "transaction_id": "txn_abc123",
  "request_id": "ba9d4445-779f-4b04-8bcb-6d17bc8dc3da"
}

Response format:¶

{
  "content": {
    "balance": 1000.50
  }
}

Handling logic:¶

Verify the request signature as described in Authorization
Find the transaction by transaction_id
If the transaction is not found or has already been rolled back, return the current balance (no changes)
If the transaction is found:
- Roll back the transaction (refund the bet, revert the win)
- Update the player’s balance
- Mark the transaction as rolled back
- Return the updated balance

Duplicate transactions¶

The platform may send the same callback multiple times (e.g. due to network errors or timeouts). The agent must handle duplicates correctly.

Recommendations for handling duplicates¶

Use `transaction_id` for identification¶

Store all processed transaction_id values in your database
Check for transaction_id before processing

Idempotency¶

Processing the same request multiple times must produce the same result
Do not debit funds again when receiving a duplicate
If the transaction has already been processed, return the current balance unchanged

Error handling¶

Error response format¶

{
  "error": "error_code",
  "message": "Error description"
}

Recommended error codes¶

Error code	Description
`invalid_signature`	Invalid request signature
`insufficient_balance`	Insufficient funds for the bet
`transaction_not_found`	Transaction not found (for rollback)
`player_not_found`	Player not found
`invalid_currency`	Invalid currency
`internal_error`	Internal error on the agent side

Support¶

If you have any questions about callback integration, contact your platform manager.

Callbacks¶

General information¶

Callback URL¶

Request format¶

Response format¶

Success response:¶

Error response:¶

getBalance — Balance request¶

Example request (without free spins):¶

Free spins progress¶

Example request with free spins:¶

Response format:¶

Response fields:¶

makeBet — Bet and win¶

Request parameters:¶

Example request:¶

Response format:¶

Handling logic:¶

rollback — Transaction rollback¶

Request parameters:¶

Example request:¶

Response format:¶

Handling logic:¶

Duplicate transactions¶

Recommendations for handling duplicates¶

Use transaction_id for identification¶

Idempotency¶

Error handling¶

Error response format¶

Recommended error codes¶

Support¶

Use `transaction_id` for identification¶