Коллбеки¶

Коллбеки - это HTTP запросы, которые платформа отправляет агенту для обработки игровых транзакций и запросов баланса. Агент должен реализовать endpoint для приема этих запросов.

Общая информация¶

URL коллбека¶

URL для приема коллбеков настраивается менеджером платформы. Для настройки URL обратитесь к вашему менеджеру.

Важно

URL должен быть доступен из интернета и принимать HTTPS запросы.

Формат запросов¶

Метод: POST
Content-Type: application/json
X-Signature: Подпись запроса в заголовке. Проверяйте подпись перед обработкой согласно разделу Авторизация.

Во всех коллбеках платформа передаёт request_id — уникальный идентификатор входящего запроса на стороне платформы. Используйте его для корреляции логов при расследовании инцидентов (таймауты, дубликаты, ошибки). Поле участвует в расчёте подписи X-Signature.

Формат ответов¶

Все ответы должны быть в JSON формате:

Успешный ответ:¶

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

Ответ с ошибкой:¶

{
  "error": "error_code",
  "message": "Описание ошибки"
}

getBalance — Запрос баланса¶

Платформа запрашивает текущий баланс игрока. Этот коллбек вызывается:

При запуске игры (для отображения начального баланса)
Периодически во время игры (для синхронизации баланса)

Параметры запроса:

Параметр	Тип	Описание
`agent_id`	integer	ID агента
`session_id`	string	ID игровой сессии
`player_id`	string	ID игрока
`player_username`	string	Имя пользователя игрока
`type`	string	Тип коллбека: `"getBalance"`
`game_id`	integer	ID игры
`currency`	string	Код валюты (RUB, USD, EUR, и т.д.)
`language`	string	Код языка (ru, en, и т.д.)
`request_id`	string	Уникальный ID запроса на стороне платформы (для корреляции логов)
`freespins`	object	Необязательно. Прогресс фриспинов (см. ниже)

Пример запроса (без фриспинов):¶

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:

Поле	Тип	Описание
`freespins.played`	integer	Сколько фриспинов уже отыграно
`freespins.total`	integer	Общее количество фриспинов в пачке
`freespins.is_finish`	boolean	`true`, если все фриспины отыграны (`played >= total`)
`freespins.accumulated_win`	float	Накопленный выигрыш за пачку

Когда поле присутствует:

Пока у игрока есть активные фриспины для этой игры и валюты — поле freespins отправляется при каждом getBalance.
На последнем фриспине приходит is_finish: true — это финальное уведомление о завершении пачки.
После завершения пачки в обычных getBalance поле freespins больше не отправляется.
Выигрыш за фриспины может быть зачислен после последнего getBalance с is_finish: true — отдельным коллбеком makeBet с полем win. Не используйте accumulated_win из getBalance для изменения баланса.

Обработка на стороне агента

Формат ответа агента не меняется — верните только content.balance. Поле freespins предназначено для учёта прогресса на стороне агента (UI, внутренняя логика и т.д.). Если поле присутствует в запросе, оно участвует в расчёте подписи X-Signature.

Пример запроса с фриспинами:¶

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

Формат ответа:¶

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

Поля ответа:¶

Поле	Тип	Обязательный	Описание
`content.balance`	float	Да	Текущий баланс игрока в указанной валюте

makeBet — Ставка и выигрыш¶

Платформа уведомляет агента о ставке игрока и выигрыше. При обработке коллбека необходимо:

Списать сумму ставки (bet) со счета игрока
Начислить сумму выигрыша (win) на счет игрока
Вернуть новый баланс игрока

Параметры запроса:¶

Параметр	Тип	Описание
`agent_id`	integer	ID агента
`session_id`	string	ID игровой сессии
`player_id`	string	ID игрока
`player_username`	string	Имя пользователя игрока
`type`	string	Тип коллбека: `"makeBet"`
`currency`	string	Код валюты
`language`	string	Код языка
`bet`	float	Сумма ставки (списание)
`win`	float	Сумма выигрыша (начисление)
`transaction_id`	string	Уникальный ID транзакции
`game_round_id`	string	ID игрового раунда
`round_finished`	boolean	Завершен ли раунд
`request_id`	string	Уникальный ID запроса на стороне платформы (для корреляции логов)

Пример запроса:¶

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

Формат ответа:¶

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

Логика обработки:¶

Проверьте подпись запроса согласно разделу Авторизация коллбеков от платформы
Проверьте, не обрабатывалась ли уже эта транзакция (по transaction_id)
Если транзакция уже обработана, верните текущий баланс (без повторного списания/начисления)
Если транзакция новая:
- Проверьте достаточность баланса для ставки
- Спишите bet со счета игрока
- Начислите win на счет игрока
- Сохраните информацию о транзакции
- Верните новый баланс

rollback — Отмена транзакции¶

Платформа запрашивает отмену предыдущей транзакции. Это может произойти при:

Технических ошибках
Отмене игры игроком
Ошибках в обработке транзакции

Параметры запроса:¶

Параметр	Тип	Описание
`agent_id`	integer	ID агента
`session_id`	string	ID игровой сессии
`player_id`	string	ID игрока
`player_username`	string	Имя пользователя игрока
`type`	string	Тип коллбека: `"rollback"`
`currency`	string	Код валюты
`language`	string	Код языка
`transaction_id`	string	ID транзакции для отмены
`request_id`	string	Уникальный ID запроса на стороне платформы (для корреляции логов)

Пример запроса:¶

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

Формат ответа:¶

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

Логика обработки:¶

Проверьте подпись запроса согласно разделу Авторизация коллбеков от платформы
Найдите транзакцию по transaction_id
Если транзакция не найдена или уже отменена, верните текущий баланс (без изменений)
Если транзакция найдена:
- Отмените транзакцию (верните ставку, отмените выигрыш)
- Обновите баланс игрока
- Пометьте транзакцию как отмененную
- Верните новый баланс

Дубликаты транзакций¶

Платформа может отправить один и тот же коллбек несколько раз (например, при сетевых ошибках или таймаутах). Агент должен корректно обрабатывать дубликаты.

Обработка ошибок¶

Формат ответа при ошибке¶

{
  "error": "error_code",
  "message": "Описание ошибки"
}

Поддержка¶

Если у вас возникли вопросы по интеграции коллбеков, обратитесь к вашему менеджеру.

Код ошибки	Описание
`invalid_signature`	Неверная подпись запроса
`insufficient_balance`	Недостаточно средств для ставки
`transaction_not_found`	Транзакция не найдена (для rollback)
`player_not_found`	Игрок не найден
`invalid_currency`	Неверная валюта
`internal_error`	Внутренняя ошибка на стороне агента

Коллбеки¶

Общая информация¶

URL коллбека¶

Формат запросов¶

Формат ответов¶

Успешный ответ:¶

Ответ с ошибкой:¶

getBalance — Запрос баланса¶

Пример запроса (без фриспинов):¶

Прогресс фриспинов¶

Пример запроса с фриспинами:¶

Формат ответа:¶

Поля ответа:¶

makeBet — Ставка и выигрыш¶

Параметры запроса:¶

Пример запроса:¶

Формат ответа:¶

Логика обработки:¶

rollback — Отмена транзакции¶

Параметры запроса:¶

Пример запроса:¶

Формат ответа:¶

Логика обработки:¶

Дубликаты транзакций¶

Рекомендации по обработке дубликатов¶

Используйте `transaction_id` для идентификации¶

Идемпотентность операций¶

Обработка ошибок¶

Формат ответа при ошибке¶

Рекомендуемые коды ошибок¶

Поддержка¶

Коллбеки¶

Общая информация¶

URL коллбека¶

Формат запросов¶

Формат ответов¶

Успешный ответ:¶

Ответ с ошибкой:¶

getBalance — Запрос баланса¶

Пример запроса (без фриспинов):¶

Прогресс фриспинов¶

Пример запроса с фриспинами:¶

Формат ответа:¶

Поля ответа:¶

makeBet — Ставка и выигрыш¶

Параметры запроса:¶

Пример запроса:¶

Формат ответа:¶

Логика обработки:¶

rollback — Отмена транзакции¶

Параметры запроса:¶

Пример запроса:¶

Формат ответа:¶

Логика обработки:¶

Дубликаты транзакций¶

Рекомендации по обработке дубликатов¶

Используйте transaction_id для идентификации¶

Идемпотентность операций¶

Обработка ошибок¶

Формат ответа при ошибке¶

Рекомендуемые коды ошибок¶

Поддержка¶

Используйте `transaction_id` для идентификации¶