Xsolla Documentation - Оповещения

Введение

Используйте webhook-и для оповещения о событиях, которые происходят с транзакцией в Иксолле. Вы можете использовать оповещения для автоматизации бэк-офиса и функций, таких как отображение статуса.

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

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

Например, вы можете отменить платеж через API Иксоллы, либо платежная система может нас оповестить об оспариваемой операции.

Примеры действий в результате обработки webhook:

Пополнение баланса пользователя
Предоставление новых предметов пользователю
Доставка физических товаров пользователю

Вы должны принимать оповещения со следующих IP-адресов: 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24.

Notice: В вашей базе данных не должно быть двух успешных транзакций с одинаковым ID. Если ваш обработчик оповещений получил оповещение с ID, который уже есть в вашей базе, вы должны вернуть результат предыдущей обработки данной транзакции. Пожалуйста, не зачисляйте пользователю покупку еще раз и не создавайте дублирующих записей в базе данных.

Мы не гарантируем, что ваш обработчик получит все оповещения. Поскольку интернет-соединение не является на 100% надежным, оповещения могут теряться или задерживаться. Ваш обработчик оповещений также может возвращать код статуса HTTP 5xx при временных проблемах на вашем сервере. Например, если пользователь совершил успешную покупку виртуального предмета, но она не была добавлена в инвентарь, обработчик вернет код статуса HTTP 500.

Чтобы уменьшить риск потери оповещений, в сервисе оповещений Иксоллы действует механизм повторных оповещений. Если оповещение не было доставлено, сервис оповещений начинает повторную отправку по следующему расписанию:

2 попытки с интервалом 5 минут;
7 попыток с интервалом 15 минут;
10 попыток с интервалом 60 минут.

Максимально сервис оповещений выполняет 20 попыток отправки оповещения в течение 12 часов с момента первой попытки.

Note: Хотя интернет-соединение является частой причиной проблем с оповещениями, наиболее вероятной причиной все же является проблема в логике обработчика оповещений.

Ответ

Иксолла использует HTTP коды ответа для обозначения успешного или ошибочного запроса. Код 204 обозначает успешную обработку оповещения. В случае возникновения ошибки вы должны вернуть 400 код (например, отсутствует обязательный параметр, или пополнение баланса невозможно). Код 500 обозначает временную серверную ошибку.

Подпись запроса

Подпись обеспечивает безопасность передачи данных. Генерация подписи состоит из двух шагов. Первый шаг — конкатенация JSON из тела запроса и секретного ключа проекта. Второй шаг — применение SHA-1 криптографической хэш-функции к получившейся на первом шаге строке.

Вы должны проверить, что подпись, которую вы сформировали, совпадает с подписью, отправленной в HTTP заголовке.

Copy

Full screen

Small screen

http

Запрос

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902

{
  "notification_type":"user_validation",
  "user":
    {
      "ip":"127.0.0.1",
      "phone":"18777976552",
      "email":"email@example.com",
      "id":1234567,
      "name":"Xsolla User",
      "country":"US"
    }
}

$curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip":"127.0.0.1",
        "phone":"18777976552",
        "email":"email@example.com",
        "id":1234567,
        "name":"Xsolla User",
        "country":"US"
      }
    }'

Ответ

Список типов оповещения

Тип оповещения передается в параметре notification_type.

Тип оповещения	Описание
order_paid	Оповещение о получении состава корзины при покупке.
order_canceled	Оповещение об отмене платежа.

Получение состава корзины при покупке

Когда пользователь подтверждает состав корзины при покупке, Иксолла отправляет оповещение order_paid на webhook URL.

Параметр	Тип	Описание
items	array	Список предметов, которые купил пользователь.
items.sku	string	Уникальный ID предмета. Для предметов с типом `game_key` используется значение в формате `sku_drm`.
items.type	string	Тип предмета. Может принимать значения `virtual_good`, `virtual_currency`, `game_key`, `physical_good`.
items.quantity	integer	Количество предметов.
items.amount	string	Общая стоимость предметов с учетом их количества. Может отличаться от цены товара из-за конвертации валют и комиссий.
items.promotions	array	Акции, которые применены. Если акции не применялись, в параметр записывается пустой массив.
items.promotions.amount_without_discount	string	Стоимость предметов без скидки.
items.promotions.amount_with_discount	string	Стоимость предметов со скидкой.
items.promotions.sequence	integer	ID акции, которая применена.
items.is_pre_order	boolean	Если значение `true`, предмет является предзаказом.
notification_type	string	Тип оповещения. Обязательный.
order	object	Информация о платеже.
order.id	integer	ID транзакции.
order.mode	string	Тип платежа. Может принимать значения `default` (по умолчанию) или `sandbox`.
order.currency_type	string	Тип оплаты. Может принимать значения `real` для реальной валюты или `virtual` для виртуальной валюты.
order.currency	string	Валюта заказа. Для виртуальной валюты используется артикул, для реальной валюты используется трехбуквенное обозначение согласно стандарту ISO 4217.
order.amount	string	Стоимость корзины с учетом выбранной валюты.
order.status	string	Статус заказа.
order.platform	string	Платформа платежа. Для платежей через Иксолла используется значение `xsolla`, для других платежей используется значение, соответствующее названию интегрированной платежной системы.
order.comment	string	Комментарий пользователя к заказу.
order.invoice_id	string	ID счета для платежей за реальную валюту. Для платежей за виртуальную валюту используется значение `null`.
order.promotions	array	Акции, которые применены. Если акции не применялись, в параметр записывается пустой массив.
order.promotions.amount_without_discount	string	Сумма заказа без скидки.
order.promotions.amount_with_discount	string	Сумма заказа со скидкой.
order.promotions.sequence	string	ID акции, которая применена.
user	object	Информация о пользователе.
user.external_id	string	ID пользователя.
user.email	string	Email-адрес пользователя.
custom_parameters	object	Дополнительная информация.

Copy

Full screen

Small screen

http

Запрос

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
  "items": [
    {
      "sku": "virtual-good-item-sku",
      "type": "virtual_good",
      "quantity": 3,
      "amount": "100",
      "promotions": [
        {
          "amount_without_discount": "200",
          "amount_with_discount": "100",
          "sequence": 1
        }
      ]
    },
    {
      "sku": "game_sku_steam",
      "type": "game_key",
      "quantity": 1,
      "amount": "200",
      "promotions": []
    },
    {
      "sku": "gold",
      "type": "virtual_currency",
      "quantity": 1500,
      "amount": "100",
      "promotions": []
    }
  ],
  "notification_type": "order_paid",
  "order": {
    "id": 42,
    "mode": "default",
    "currency_type": "real",
    "currency": "USD",
    "amount": "200",
    "status": "paid",
    "platform": "xsolla",
    "comment": null,
    "invoice_id": "23444",
    "promotions": [
      {
        "amount_without_discount": "400",
        "amount_with_discount": "200",
        "sequence": 1
      }
    ]
  },
  "user": {
    "external_id": "gamer_external_id",
    "email": "gamer@email.com"
  }
}

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
  "items": [
    {
      "sku": "virtual-good-item-sku",
      "type": "virtual_good",
      "quantity": 3,
      "amount": "100",
      "promotions": [
        {
          "amount_without_discount": "200",
          "amount_with_discount": "100",
          "sequence": 1
        }
      ]
    },
    {
      "sku": "game_sku_steam",
      "type": "game_key",
      "quantity": 1,
      "amount": "200",
      "promotions": []
    },
    {
      "sku": "gold",
      "type": "virtual_currency",
      "quantity": 1500,
      "amount": "100",
      "promotions": []
    }
  ],
  "notification_type": "order_paid",
  "order": {
    "id": 42,
    "mode": "default",
    "currency_type": "real",
    "currency": "USD",
    "amount": "200",
    "status": "paid",
    "platform": "xsolla",
    "comment": null,
    "invoice_id": "23444",
    "promotions": [
      {
        "amount_without_discount": "400",
        "amount_with_discount": "200",
        "sequence": 1
      }
    ]
  },
  "user": {
    "external_id": "gamer_external_id",
    "email": "gamer@email.com"
  }
}'

Ответ

HTTP/1.1 204 No Content

Отмена платежа

Когда пользователь отменяет платеж, Иксолла отправляет оповещение order_canceled на webhook URL.

Параметр	Тип	Описание
items	array	Список предметов, которые купил пользователь.
items.sku	string	Уникальный ID предмета. Для предметов с типом `game_key` используется значение в формате `sku_drm`.
items.type	string	Тип предмета. Может принимать значения `virtual_good`, `virtual_currency`, `game_key`, `physical_good`.
items.quantity	integer	Количество предметов.
items.amount	string	Общая стоимость предметов с учетом их количества. Может отличаться от цены товара из-за конвертации валют и комиссий.
items.promotions	array	Акции, которые применены. Если акции не применялись, в параметр записывается пустой массив.
items.promotions.amount_without_discount	string	Стоимость предметов без скидки.
items.promotions.amount_with_discount	string	Стоимость предметов со скидкой.
items.promotions.sequence	integer	ID акции, которая применена.
items.is_pre_order	boolean	Если значение `true`, предмет является предзаказом.
notification_type	string	Тип оповещения. Обязательный.
order	object	Информация о платеже.
order.id	integer	ID транзакции.
order.mode	string	Тип платежа. Может принимать значения `default` (по умолчанию) или `sandbox`.
order.currency_type	string	Тип оплаты. Может принимать значения `real` для реальной валюты или `virtual` для виртуальной валюты.
order.currency	string	Валюта заказа. Для виртуальной валюты используется артикул, для реальной валюты используется трехбуквенное обозначение согласно стандарту ISO 4217.
order.amount	string	Стоимость корзины с учетом выбранной валюты.
order.status	string	Статус заказа.
order.platform	string	Платформа платежа. Для платежей через Иксолла используется значение `xsolla`, для других платежей используется значение, соответствующее названию интегрированной платежной системы.
order.comment	string	Комментарий пользователя к заказу.
order.invoice_id	string	ID счета для платежей за реальную валюту. Для платежей за виртуальную валюту используется значение `null`.
order.promotions	array	Акции, которые применены. Если акции не применялись, в параметр записывается пустой массив.
order.promotions.amount_without_discount	string	Сумма заказа без скидки.
order.promotions.amount_with_discount	string	Сумма заказа со скидкой.
order.promotions.sequence	string	ID акции, которая применена.
user	object	Информация о пользователе.
user.external_id	string	ID пользователя.
user.email	string	Email-адрес пользователя.
custom_parameters	object	Дополнительная информация.

Copy

Full screen

Small screen

http

Запрос

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
  "items": [
    {
      "sku": "virtual-good-item-sku",
      "type": "virtual_good",
      "quantity": 3,
      "amount": "100",
      "promotions": [
        {
          "amount_without_discount": "200",
          "amount_with_discount": "100",
          "sequence": 1
        }
      ]
    },
    {
      "sku": "game_sku_steam",
      "type": "game_key",
      "quantity": 1,
      "amount": "200",
      "promotions": []
    },
    {
      "sku": "gold",
      "type": "virtual_currency",
      "quantity": 1500,
      "amount": "100",
      "promotions": []
    }
  ],
  "notification_type": "order_canceled",
  "order": {
    "id": 42,
    "mode": "default",
    "currency_type": "real",
    "currency": "USD",
    "amount": "200",
    "status": "canceled",
    "platform": "xsolla",
    "comment": null,
    "invoice_id": "23444",
    "promotions": [
      {
        "amount_without_discount": "400",
        "amount_with_discount": "200",
        "sequence": 1
      }
    ]
  },
  "user": {
    "external_id": "gamer_external_id",
    "email": "gamer@email.com"
  }
}

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
  "items": [
    {
      "sku": "virtual-good-item-sku",
      "type": "virtual_good",
      "quantity": 3,
      "amount": "100",
      "promotions": [
        {
          "amount_without_discount": "200",
          "amount_with_discount": "100",
          "sequence": 1
        }
      ]
    },
    {
      "sku": "game_sku_steam",
      "type": "game_key",
      "quantity": 1,
      "amount": "200",
      "promotions": []
    },
    {
      "sku": "gold",
      "type": "virtual_currency",
      "quantity": 1500,
      "amount": "100",
      "promotions": []
    }
  ],
  "notification_type": "order_canceled",
  "order": {
    "id": 42,
    "mode": "default",
    "currency_type": "real",
    "currency": "USD",
    "amount": "200",
    "status": "canceled",
    "platform": "xsolla",
    "comment": null,
    "invoice_id": "23444",
    "promotions": [
      {
        "amount_without_discount": "400",
        "amount_with_discount": "200",
        "sequence": 1
      }
    ]
  },
  "user": {
    "external_id": "gamer_external_id",
    "email": "gamer@email.com"
  }
}'

Ответ

HTTP/1.1 204 No Content

Спасибо за обратную связь!

Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.

Your browser is not supported. Please try a different browser

Оповещения

Введение

Ответ

Подпись запроса

Список типов оповещения

Получение состава корзины при покупке

items

items.sku

items.type

items.quantity

items.amount

items.promotions

items.promotions.amount_without_discount

items.promotions.amount_with_discount

items.promotions.sequence

items.is_pre_order

notification_type

order

order.id

order.mode

order.currency_type

order.currency

order.amount

order.status

order.platform

order.comment

order.invoice_id

order.promotions

order.promotions.amount_without_discount

order.promotions.amount_with_discount

order.promotions.sequence

user

user.external_id

user.email

custom_parameters

Отмена платежа

items

items.sku

items.type

items.quantity

items.amount

items.promotions

items.promotions.amount_without_discount

items.promotions.amount_with_discount

items.promotions.sequence

items.is_pre_order

notification_type

order

order.id

order.mode

order.currency_type

order.currency

order.amount

order.status

order.platform

order.comment

order.invoice_id

order.promotions

order.promotions.amount_without_discount

order.promotions.amount_with_discount

order.promotions.sequence

user

user.external_id

user.email

custom_parameters

Была ли статья полезна?