Skip to content

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.

Response format

All responses must be JSON:

Success response:

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

Error response:

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

Callback types

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"
currency string Currency code (RUB, USD, EUR, etc.)
language string Language code (ru, en, etc.)

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": "getBalance",
  "currency": "RUB",
  "language": "ru"
}

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:

  1. Debit the bet amount (bet) from the player’s account
  2. Credit the win amount (win) to the player’s account
  3. 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

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
}

Response format:

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

Handling logic:

  1. Verify the request signature as described in Authorization
  2. Check whether the transaction has already been processed (by transaction_id)
  3. If it has, return the current balance (without repeating debit/credit)
  4. 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

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"
}

Response format:

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

Handling logic:

  1. Verify the request signature as described in Authorization
  2. Find the transaction by transaction_id
  3. If the transaction is not found or has already been rolled back, return the current balance (no changes)
  4. 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"
}
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.