Коллбеки

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

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

URL коллбека

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

Важно

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

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

• Метод: POST
• Content-Type: application/json
• 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"
currency	string	Код валюты (RUB, USD, EUR, и т.д.)
language	string	Код языка (ru, en, и т.д.)

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

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

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

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

Поля ответа:

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

makeBet - Ставка и выигрыш

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

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

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

Параметр	Тип	Описание
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	Завершен ли раунд

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

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
}

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

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

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

1. Проверьте подпись запроса согласно разделу Авторизация коллбеков от платформы
2. Проверьте, не обрабатывалась ли уже эта транзакция (по transaction_id)
3. Если транзакция уже обработана, верните текущий баланс (без повторного списания/начисления)
4. Если транзакция новая:
   • Проверьте достаточность баланса для ставки
   • Спишите 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 транзакции для отмены

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

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

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

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

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

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

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

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

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

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

• Сохраняйте все обработанные transaction_id в базе данных
• Проверяйте наличие transaction_id перед обработкой

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

• Обработка одного и того же запроса несколько раз должна давать одинаковый результат
• Не списывайте средства повторно при дубликате
• Если транзакция уже обработана, просто верните текущий баланс без изменений

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

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

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

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

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

Поддержка

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