Интеграция с серверной частью

Seamless Wallet API введение

примечание

Партнер - сторона, интегрирующая игры.

Бренд - вебсайт казино партнера на котором пользователи играют в игры и делают ставки.

Провайдер - сторона, предоставляющая игры (Aviatrix).

В данной секции описаны основные методы, которые партнеру необходимо реализовать на своей стороне. Эти методы будут вызываться провайдером непосредственно во время игры.

примечание

Для старта игры ознакомьтесь с документом Game API

важно

Не совместимо с Transfer Wallet API

IP Whitelisting & Firewalls

Для обеспечения безопасного соединения и контроля над трафиком мы рекомендуем всем нашим партнерам использовать L7 Firewall и фильтрацию по заголовку запроса. В частности, каждый наш исходящий запрос содержит X-Auth-Signature поле в заголовке, которое необходимо для подтверждения подлинности хоста.

Мы крайне не рекомендуем использовать технологии IP Whitelisting и L4 Firewall. Такой подход накладывает серьезные ограничения на полноценное использование современных облачных технологий, которые предоставляют хостинг сервисы.

важно

Если партнер настаивает на использовании IP Whitelisting и L4 Firewall значит он соглашается на периодический даунтайм наших сервисов и обновление своих whitelist-списков в течение одного рабочего дня.

Seamless Wallet API методы

к сведению

Все POST запросы содержат HTTP заголовок X-Auth-Signature, необходимый для подтверждения подлинности хоста. Эта операция позволяет отказаться от IP whitelist при интеграции, так как последний лишает возможности провайдера оперативно масштабироваться (горизонтально), не предупреждая при этом партнера.

важно

Если бренд недоступен или отвечает ошибками 5xx, то запрос будет отправлен несколько раз с увеличением интервала повторения. Пример интервалов повторения [1s, 2s, 5s ... 1h, 3h]

к сведению

Все бонусные ставки рассчитываются внутри игры и не передаются платформе. Только выигрыши по бонусам будут переданы через /transactions/promoWin. Этот запрос также используется для начисления внутри-игровых наград.

не пропустите

Для /bet, /win и /transactions/promoWin мы ожидаем идемпотентное поведение в случае дублирования. Если первая транзакция была успешно обработана, то при повторной транзакции изменений не производится, и возвращается такой же успешный ответ, как если бы она была обработана в первый раз.

В рамках интеграции клиентского приложения, бренд должен передать в URL sessionToken пользователя.

Рекомендуем выбирать время жизни (TTL) токена между 1 час - 24 часа.

В случае, когда в бренд придет /bet или /playerInfo запрос с истекшим токеном пользователя - необходимо ответить соответствующей ошибкой (см. раздел ошибок клиента).

не пропустите

/win и /transactions/promoWin должны быть обработаны на стороне бренда, даже если sessionToken к этому времени истек.

важно

На все исходящие запросы установлено стандартное время жизни в X сек. После истечения этого времени запрос будет отменен и отправлен повторно. Внимательно ознакомьтесь с описанием каждого эндпоинта, чтобы узнать конкретные значения.

/health

Метод вызывается для проверки работоспособности. Желательно, чтобы он выполнял запрос в базу данных или в кэш. Метод не требует аутентификации.

В ответ ожидается получение HTTP кода 200 (OK).

важно

Ожидаемое время ответа (latency) < 500 мс, превышение 2 сек не должно допускаться. По истечении 2 сек запрос отменяется и считается ошибочным.

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

GET /health HTTP/1.1

/playerInfo

Метод вызывается, когда необходимо получить информацию о пользователе (баланс, валюту, страну). При этом передается sessionToken пользователя, который был вставлен партнером в URL клиентской части провайдера при интеграции.

важно

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

POST /playerInfo HTTP/1.1
Content-Type: application/json
X-Auth-Signature: <signature>

{
  "cid": "somebrand",
  "sessionToken": "some4session7token5",
  "timestamp": 1234567890
}

Параметр	Описание	Тип	Требования	Пояснение
cid	уникальный идентификатор бренда партнера	string	обязательный	значение из URL параметров провайдера игр при интеграции
sessionToken	токен с пользовательской сессией	string	обязательный	значение из URL параметров провайдера игр при интеграции
timestamp	время операции	integer	обязательный	Unix time формат

Пример ответа от сервера

HTTP/1.1 200 OK

{
  "playerId": "someplayerid123",
  "balance": 10000,
  "currency": "EUR"
}

Параметр	Описание	Тип	Требования	Пояснение
playerId	уникальный идентификатор пользователя	string	обязательный	уникальный в рамках бренда
balance	баланс пользователя	integer	обязательный	баланс пользователя в формате minor currency unit (учитывая центы, т.е. число, умноженное на 100)
currency	валюта пользователя	string	обязательный	валюта баланса пользователя

/bet

Метод вызывается, когда пользователь делает ставку в клиентской части приложения.

важно

Ожидаемое время ответа (latency) < 2 сек, превышение 5 сек не должно допускаться. По истечении 10 сек запрос отменяется и запускается логика повторных запросов. Если все попытки были неуспешными запускается отмена ставки (/win(operation=CancelBet)).

Bet

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

POST /bet HTTP/1.1
Content-Type: application/json
X-Auth-Signature: <signature>

{
  "betId": "1a2b3c4d-6f5e-4d3c-b2a1-f6e5d4c3b2a1",
  "cid": "somebrand",
  "sessionToken": "some4session7token5",
  "playerId": "someplayerid123",
  "productId": "nft-aviatrix",
  "txId": "eyJiaWQiOiIxYTJiM2M0ZC02ZjVlLTRkM2MtYjJhMS1mNmU1ZDRjM2IyYTEiLCJvcCI6IlBsYWNlQmV0Iiwia2V5IjoiIn0=",
  "roundId": "1234567",
  "market": "result",
  "outcome": "crash",
  "specifier": "",
  "odds": 10000,
  "amount": 100,
  "currency": "EUR",
  "roundClosed": false,
  "timestamp": 1234567890,
  "bonusId": ""
}

Параметр	Описание	Тип	Требования	Пояснение
betId	идентификатор ставки	string	обязательный	создается на стороне провайдера
cid	уникальный идентификатор бренда	string	обязательный	значение из URL параметров провайдера игр при интеграции
sessionToken	токен с пользовательской сессией	string	обязательный	значение из URL параметров провайдера игр при интеграции
playerId	идентификатор пользователя	string	обязательный	значение из запроса `/playerInfo`
productId	идентификатор игры в рамках бренда	string	обязательный	значение из URL параметров провайдера игр при интеграции
txId	идентификатор транзакции	string	обязательный	генерируется на стороне провайдера
roundId	идентификатор раунда	string	обязательный	создается на стороне провайдера
market	рынок	string	опциональный	может использоваться для дополнительной валидации, аналитики или для вывода где-то в интерфейсе пользователя
outcome	исход	string	опциональный	может использоваться для дополнительной валидации, аналитики или для вывода где-то в интерфейсе пользователя
specifier	спецификатор	string	опциональный	может использоваться для дополнительной валидации, аналитики или для вывода где-то в интерфейсе пользователя
odds	коэффициент	double	опциональный	коэффициент выплаты
amount	сумма ставки	integer	обязательный	сумма ставки пользователя в формате minor currency unit (учитывая центы, т.е. число умноженное на 100)
currency	валюта ставки	string	обязательный	валюта, в которой пользователь сделал ставку
roundClosed	маркер закрытия раунда	bool	опциональный	устарел, оставлен для обратной совместимости
timestamp	время операции	integer	обязательный	Unix time формат
bonusId	идентификатор бонуса	string	опциональный	создается на стороне провайдера

Пример ответа от сервера

HTTP/1.1 200 OK

{
  "processedTxId": "eyJiaWQiOiIxYTJiM2M0ZC02ZjVlLTRkM2MtYjJhMS1mNmU1ZDRjM2IyYTEiLCJvcCI6IlBsYWNlQmV0Iiwia2V5IjoiIn0="
  "createdAt": "0001-02-03T04:05:06.789Z",
  "balance": 10000,
}

Параметр	Описание	Тип	Требования	Пояснение
processedTxId	идентификатор транзакции	string	опциональный	идентификатор транзакции на стороне бренда (полезен в случае ошибок, либо при обращении в support)
createdAt	время транзакции	timestamp	обязательный	yyyy-MM-ddThh:mm:ss.sssZ format
balance	баланс пользователя	integer	обязательный	новый баланс пользователя в формате minor currency unit (учитывая центы, т.е. число, умноженное на 100)

/win

Метод вызывается, когда пользователь совершает кэшаут. В таком случае серверная часть провайдера отправляет /win запросы для каждой ставки пользователя, чтобы ее рассчитать. /win отправляется, в том числе для проигранных ставок. В таком случае в поле amount записывается 0.

Кроме того /win отправляется в случае, если ставка отменяется. Например, по причине того, что игрок отменил свою ставку до начала игрового раунда. В таком случает в поле amount записывается значение изначальной ставки, а в поле operation указывается тип операции CancelBet.

Если /win был вызван для несуществующего betId, то бренд должен вернуть ошибку Bet not found. Если /win с разными операциями(SettleBet, CancelBet) был вызван для одинакового betId, то бренд должен вернуть ошибку Invalid transaction. Если был совершен успешный вызов /bet, то предполагается, что /win будет обработан партнером даже при истекшей сессии игрока.

важно

Ожидаемое время ответа (latency) < 2 сек, превышение 5 сек не должно допускаться. По истечении 10 сек запрос отменяется и запускается логика повторных запросов. Если все попытки были неуспешными, то ставка считается незавершенной и не попадает в финансовую статистику.

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

Ставка выиграла

POST /win HTTP/1.1
Content-Type: application/json
X-Auth-Signature: <signature>

{
  "betId": "1a2b3c4d-6f5e-4d3c-b2a1-f6e5d4c3b2a1",
  "cid": "somebrand",
  "sessionToken": "some4session7token5",
  "playerId": "someplayerid123",
  "productId": "nft-aviatrix",
  "txId": "eyJiaWQiOiIxYTJiM2M0ZC02ZjVlLTRkM2MtYjJhMS1mNmU1ZDRjM2IyYTEiLCJvcCI6IlNldHRsZUJldCIsImtleSI6IiJ9",
  "roundId": "1234567",
  "market": "result",
  "outcome": "crash",
  "specifier": "",
  "odds": 12.34,
  "amount": 1234,
  "currency": "EUR",
  "roundClosed": false,
  "timestamp": 1234567890,
  "operation": "SettleBet",
  "bonusId":""
}

Ставка проиграла

POST /win HTTP/1.1
Content-Type: application/json
X-Auth-Signature: <signature>

{
  "betId": "1a2b3c4d-6f5e-4d3c-b2a1-f6e5d4c3b2a1",
  "cid": "somebrand",
  "sessionToken": "some4session7token5",
  "playerId": "someplayerid123",
  "productId": "nft-aviatrix",
  "txId": "eyJiaWQiOiIxYTJiM2M0ZC02ZjVlLTRkM2MtYjJhMS1mNmU1ZDRjM2IyYTEiLCJvcCI6IlNldHRsZUJldCIsImtleSI6IiJ9",
  "roundId": "1234567",
  "market": "result",
  "outcome": "crash",
  "specifier": "",
  "odds": 12.34,
  "amount": 0,
  "currency": "EUR",
  "roundClosed": false,
  "timestamp": 1234567890,
  "operation": "SettleBet",
  "bonusId":""
}

Отмена ставки

POST /win HTTP/1.1
Content-Type: application/json
X-Auth-Signature: <signature>

{
  "betId": "1a2b3c4d-6f5e-4d3c-b2a1-f6e5d4c3b2a1",
  "cid": "somebrand",
  "sessionToken": "some4session7token5",
  "playerId": "someplayerid123",
  "productId": "nft-aviatrix",
  "txId": "eyJiaWQiOiIxYTJiM2M0ZC02ZjVlLTRkM2MtYjJhMS1mNmU1ZDRjM2IyYTEiLCJvcCI6IkNhbmNlbEJldCIsImtleSI6IiJ9",
  "roundId": "1234567",
  "market": "result",
  "outcome": "crash",
  "specifier": "",
  "odds": 1,
  "amount": 100,
  "currency": "EUR",
  "roundClosed": false,
  "timestamp": 1234567890,
  "operation": "CancelBet",
  "bonusId":""
}

Параметр	Описание	Тип	Требования	Пояснение
betId	идентификатор ставки	string	обязательный	создается на стороне провайдера
cid	уникальный идентификатор бренда	string	обязательный	значение из URL параметров провайдера игр при интеграции
sessionToken	токен с пользовательской сессией	string	обязательный	значение из URL параметров провайдера игр при интеграции
playerId	идентификатор пользователя	string	обязательный	значение из запроса `/playerInfo`
productId	идентификатор игры в рамках бренда	string	обязательный	значение из URL параметров провайдера игр при интеграции
txId	идентификатор транзакции	string	обязательный	генерируется на стороне провайдера
roundId	идентификатор раунда	string	обязательный	создается на стороне провайдера
market	рынок	string	опциональный	может использоваться для дополнительной валидации, аналитики или для вывода где-то в интерфейсе пользователя
outcome	исход	string	опциональный	может использоваться для дополнительной валидации, аналитики или для вывода где-то в интерфейсе пользователя
specifier	спецификатор	string	опциональный	может использоваться для дополнительной валидации, аналитики или для вывода где-то в интерфейсе пользователя
odds	коэффициент	double	опциональный	коэффициент выплаты
amount	сумма выигрыша	integer	обязательный	сумма выигрыша пользователя в формате minor currency unit (учитывая центы, т.е. число умноженное на 100)
currency	валюта выигрыша	string	обязательный	валюта, в которой пользователь сделал ставку
roundClosed	маркер закрытия раунда	bool	опциональный	устарел, оставлен для обратной совместимости
timestamp	время операции	integer	обязательный	Unix time формат
operation	тип операции	string	обязательный	возможные значения: SettleBet, CancelBet
bonusId	идентификатор бонуса	string	опциональный	создается на стороне провайдера

Пример ответа от сервера

HTTP/1.1 200 OK

{
  "processedTxId": "eyJiaWQiOiIxYTJiM2M0ZC02ZjVlLTRkM2MtYjJhMS1mNmU1ZDRjM2IyYTEiLCJvcCI6IlNldHRsZUJldCIsImtleSI6IiJ9"
  "createdAt": "0001-02-03T04:05:06.789Z",
  "balance": 10000,
}

Параметр	Описание	Тип	Требования	Пояснение
processedTxId	идентификатор транзакции	string	опциональный	идентификатор транзакции на стороне бренда (полезен в случае ошибок, либо при обращении в support)
createdAt	время транзакции	timestamp	обязательный	yyyy-MM-ddThh:mm:ss.sssZ format
balance	баланс пользователя	integer	обязательный	новый баланс пользователя в формате minor currency unit (учитывая центы, т.е. число, умноженное на 100)

/transactions/promoWin

Метод вызывается, когда пользователь переводит бонусный выигрыш на свой счет.

важно

Ожидаемое время ответа (latency) < 2 сек, превышение 5 сек не должно допускаться. По истечении 10 сек запрос отменяется и запускается логика повторных запросов. Если все попытки были неуспешными, то бонусный выигрыш считается незавершенным и не попадает в финансовую статистику.

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

POST /transactions/promoWin HTTP/1.1
Content-Type: application/json
X-Auth-Signature: <signature>

{
  "cid": "somebrand",
  "sessionToken": "some4session7token5",
  "playerId": "someplayerid123",
  "productId": "nft-aviatrix",
  "txId": "eyJiaWQiOiIxYTJiM2M0ZC02ZjVlLTRkM2MtYjJhMS1mNmU1ZDRjM2IyYTEiLCJvcCI6IlByb21vV2luIiwia2V5IjoiIn0=",
  "amount": 1000,
  "currency":"EUR",
  "promo": {
    "type": "bonus",
    "bonusId": "some1bonus2id"
  }
}

Параметр	Описание	Тип	Требования	Пояснение
cid	уникальный идентификатор бренда	string	обязательный	значение из URL параметров провайдера игр при интеграции
sessionToken	токен с пользовательской сессией	string	обязательный	значение из URL параметров провайдера игр при интеграции
playerId	идентификатор пользователя	string	обязательный	значение из запроса `/playerInfo`
productId	идентификатор игры в рамках бренда	string	обязательный	значение из URL параметров провайдера игр при интеграции
txId	идентификатор транзакции	string	обязательный	генерируется на стороне провайдера
amount	сумма выигрыша	integer	обязательный	сумма выигрыша пользователя в формате minor currency unit (учитывая центы, т.е. число умноженное на 100)
currency	валюта выигрыша	string	обязательный	валюта, в которой назначен бонус
promo	детали промо транзакции	object	обязательный	содержит тип промо транзакции и дополнительные идентификаторы
promo.type	тип промо транзакции	string	обязательный	возможные значения: `bonus`, `tournament`
promo.bonusId	идентификатор бонуса	string	опциональный	присутствует в реквесте при `bonus` типе промо транзакции

Пример ответа от сервера

HTTP/1.1 200 OK

{
  "processedTxId": "eyJiaWQiOiIxYTJiM2M0ZC02ZjVlLTRkM2MtYjJhMS1mNmU1ZDRjM2IyYTEiLCJvcCI6IlByb21vV2luIiwia2V5IjoiIn0="
  "createdAt": "0001-02-03T04:05:06.789Z",
  "balance": 10000,
}

Параметр	Описание	Тип	Требования	Пояснение
processedTxId	идентификатор транзакции	string	опциональный	идентификатор транзакции на стороне бренда (полезен в случае ошибок, либо при обращении в support)
createdAt	время транзакции	timestamp	обязательный	yyyy-MM-ddThh:mm:ss.sssZ format
balance	баланс пользователя	integer	обязательный	новый баланс пользователя в формате minor currency unit (учитывая центы, т.е. число, умноженное на 100)

/closeMatch (optional)

Метод вызывается при завершении определенного раунда. Раундом является промежуток между началом приема ставок и расчетом их. Бренды могут использовать /closeMatch для конечного закрытия ставки. Метод вызывается для каждого игрока, кто успел сделать хотя бы одну ставку в раунде.

После завершения раунда бренд не должен получать bet/win вызовы. В случае вызова bet/win ожидается ошибка Invalid transaction.

важно

Ожидаемое время ответа (latency) < 2 сек, превышение 5 сек не должно допускаться. По истечении 10 сек запрос отменяется и запускается логика повторных запросов.

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

POST /closeMatch HTTP/1.1
Content-Type: application/json
X-Auth-Signature: <signature>

{
  "cid": "somebrand",
  "playerId": "someplayerid123",
  "productId": "nft-aviatrix",
  "matchId": "1234567",
  "txId": "eyJiaWQiOiIxMjM0NS0xMjM0NTYiLCJvcCI6IkNsb3NlTWF0Y2giLCJrZXkiOiIifQ=="
}

Параметр	Описание	Тип	Требования	Пояснение
cid	уникальный идентификатор бренда	string	обязательный	значение из URL параметров провайдера игр при интеграции
playerId	идентификатор пользователя	string	обязательный	значение из запроса `/playerInfo`
productId	идентификатор игры в рамках бренда	string	обязательный	значение из URL параметров провайдера игр при интеграции
matchId	идентификатор матча (раунда игры)	string	обязательный	генерируется на стороне провайдера
txId	идентификатор транзакции	string	обязательный	генерируется на стороне провайдера

Пример ответа от сервера

HTTP/1.1 200 OK

{
  "processedTxId": "eyJiaWQiOiIxMjM0NS0xMjM0NTYiLCJvcCI6IkNsb3NlTWF0Y2giLCJrZXkiOiIifQ=="
}

Параметр	Описание	Тип	Требования	Пояснение
processedTxId	идентификатор транзакции	string	опциональный	идентификатор транзакции на стороне бренда (полезен в случае ошибок, либо при обращении в support)

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

В общем случае при возникновения ошибки на стороне бренда, кроме соответствующего HTTP статус кода, необходимо вернуть объект вида:

{
  "message": "error text"
}

важно

Значение поля message должно полностью совпадать с текстом ошибки из таблицы ниже.

Также в ответе необходимо установить HTTP заголовок Content-Type:

Content-Type: application/json

к сведению

Бренд может не возвращать весь список необходимых ошибок, если конкретная ошибка не применима для нее.

к сведению

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

Ошибки клиента 4XX

HTTP Status	Текст ошибки	Запросы	Повторная отправка	Описание
400	Invalid authentication signature	`playerInfo` `bet` `win` `promoWin` `closeMatch`	Нет	Аутентификационная подпись, отправляемая в заголовке X-Auth-Signature, не совпадает с рассчитанной на стороне сервера подписью параметров тела запроса.
400	Invalid session token	`playerInfo` `bet` `win` `promoWin`	Нет	Сессионный токен, отправляемый в теле запроса как параметр sessionToken, имеет неправильный формат.
400	Invalid request	`playerInfo` `bet` `win` `promoWin` `closeMatch`	Нет	Бренд не смог десериализовать запрос или же он содержит неверный формат.
400	Invalid transaction	`bet` `win` `promoWin` `closeMatch`	Нет	Транзакция, отправляемая в теле запроса как параметр txId, имеет неправильный формат.
400	Invalid player currency	`bet` `win` `promoWin`	Нет	Валюта, отправляемая в теле запроса как параметр currency, не совпадает с валютой игрока.
401	Session token expired	`playerInfo` `bet`	Нет	Время жизни сессионного токена, отправляемого в теле запроса как параметр sessionToken, истекло.
403	Player banned	`bet` `win` `promoWin` `closeMatch`	Нет	Игрок, отправляемый в теле запроса как параметр playerId, заблокирован.
403	Insufficient balance	`bet`	Нет	Игрок, отправляемый в теле запроса как параметр playerId, имеет недостаточный баланс для размещения ставки.
403	Bet limit exceeded	`bet`	Нет	Игрок, отправляемый в теле запроса как параметр playerId, превысил какой-либо лимит на стороне бренда.
404	Platform not found	`playerInfo` `bet` `win` `promoWin` `closeMatch`	Нет	Бренд, отправляемая в теле запроса как параметр cid, не существует.
404	Product not found	`bet` `win` `promoWin` `closeMatch`	Нет	Продукт (игра), отправляемая в теле запроса как параметр productId, не существует.
404	Player not found	`bet` `win` `promoWin` `closeMatch`	Нет	Игрок, отправляемый в теле запроса как параметр playerId, не существует.
404	Bet not found	`win`	Нет	Ставка, отправляемая в теле запроса как параметр betId, не существует.
429	Service overloaded	`bet` `win` `promoWin` `closeMatch`	Да	Сервис перегружен запросами.

Ошибки клиента 5XX

HTTP Status	Текст ошибки	Повторная отправка	Описание
500	<Любая серверная ошибка>	Да	Любая серверная ошибка, не описанная ниже.
501	Method not supported	Нет	Запрос отправлен неподдерживаемым HTTP методом (т.е. любым не POST методом).
503	Service unavailable	Да	Сервер временно недоступен.

Пример ошибки

HTTP/1.1 400 Bad Request

{
  "message": "Invalid session token"
}

Seamless Wallet API введение​

IP Whitelisting & Firewalls​

Seamless Wallet API методы​

/health​

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

/playerInfo​

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

Пример ответа от сервера​

/bet​

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

Пример ответа от сервера​

/win​

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

Пример ответа от сервера​

/transactions/promoWin​

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

Пример ответа от сервера​

/closeMatch (optional)​

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

Пример ответа от сервера​

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

Ошибки клиента 4XX​

Ошибки клиента 5XX​

Пример ошибки​

Seamless Wallet API введение

IP Whitelisting & Firewalls

Seamless Wallet API методы

/health

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

/playerInfo

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

Пример ответа от сервера

/bet

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

Пример ответа от сервера

/win

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

Пример ответа от сервера

/transactions/promoWin

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

Пример ответа от сервера

/closeMatch (optional)

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

Пример ответа от сервера

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

Ошибки клиента 4XX

Ошибки клиента 5XX

Пример ошибки