Оповещения

Введение

Используйте 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
  • http
  • curl
Запрос
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
integerID акции, которая применена.
items.is_pre_order
booleanЕсли значение true, предмет является предзаказом.
notification_type
stringТип оповещения. Обязательный.
order
objectИнформация о платеже.
order.id
integerID транзакции.
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
stringID счета для платежей за реальную валюту. Для платежей за виртуальную валюту используется значение null.
order.promotions
arrayАкции, которые применены. Если акции не применялись, в параметр записывается пустой массив.
order.promotions.amount_without_discount
stringСумма заказа без скидки.
order.promotions.amount_with_discount
stringСумма заказа со скидкой.
order.promotions.sequence
stringID акции, которая применена.
user
objectИнформация о пользователе.
user.external_id
stringID пользователя.
user.email
stringEmail-адрес пользователя.
custom_parameters
objectДополнительная информация.
Copy
Full screen
Small screen
http
  • http
  • curl
Запрос
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
integerID акции, которая применена.
items.is_pre_order
booleanЕсли значение true, предмет является предзаказом.
notification_type
stringТип оповещения. Обязательный.
order
objectИнформация о платеже.
order.id
integerID транзакции.
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
stringID счета для платежей за реальную валюту. Для платежей за виртуальную валюту используется значение null.
order.promotions
arrayАкции, которые применены. Если акции не применялись, в параметр записывается пустой массив.
order.promotions.amount_without_discount
stringСумма заказа без скидки.
order.promotions.amount_with_discount
stringСумма заказа со скидкой.
order.promotions.sequence
stringID акции, которая применена.
user
objectИнформация о пользователе.
user.external_id
stringID пользователя.
user.email
stringEmail-адрес пользователя.
custom_parameters
objectДополнительная информация.
Copy
Full screen
Small screen
http
  • http
  • curl
Запрос
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
Была ли статья полезна?
Спасибо!
Что может сделать статью еще лучше? Сообщение
Жаль, что так произошло
Расскажите, почему статья не была полезна. Сообщение
Спасибо за обратную связь!
Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.