Xsolla-logo

Успешная оплата заказаWebhook POST

Xsolla отправляет вебхук order_paid на указанный URL-адрес, когда выполнены условия:

  1. Пользователь успешно оплатил заказ.
  2. Xsolla получила ответ об успешной обработке вебхука payment.

В вебхуке order_paid содержится информация о купленных товарах и детали транзакции.

Вебхук order_paid не будет отправлен, если:

  • Оплата не была успешной, например:
    • форма оплаты была открыта, но пользователь не оплатил заказ;
    • форма оплаты была открыта, но при оплате возникли ошибки.
  • Ответ об успешной обработке вебхука payment не получен.

Рекомендуется обеспечить скорость обработки вебхука order_paid менее 3 секунд.

Ожидаемые коды ответов описаны в разделе Responses. Вы можете использовать другие коды ответов. В зависимости от кода ответа и подключения функциональности автоматического возврата платежа логика обработки вебхука на стороне Xsolla следующая:

Код ответа Автоматический возврат платежа не включен (по умолчанию) Автоматический возврат платежа включен
400, 401, 402, 403, 404, 409, 422, 415 Нет действий Автоматический возврат средств пользователю.
200, 201, 204 Нет действий Нет действий
Другой код или отсутствие ответа на вебхук Многократная отправка вебхуков через заданный временной промежуток: 2 попытки с шагом 5 минут, 7 попыток с шагом 15 минут, 10 попыток с шагом 60 минут. Многократная отправка вебхуков через заданный временной промежуток: 2 попытки с шагом 5 минут, 7 попыток с шагом 15 минут, 10 попыток с шагом 60 минут. Если все вебхуки отправлены, а успешный ответ не получен, осуществляется автоматический возврат средств пользователю.

Для подключения функциональности автоматических возвратов обратитесь к аккаунт-менеджеру проекта или напишите на am@xsolla.com.

Request
Request Body schema: application/json
notification_type
required
string

Тип оповещения.

required
Array of objects

Список предметов, которые купил пользователь.

Array
sku
required
string

Уникальный ID предмета. Для предметов с типом game_key используется значение в формате sku_drm.

type
required
string

Тип предмета. Может принимать значения virtual_good, virtual_currency, game_key, bundle. Для предмета с типом bundle, в том числе для пакета виртуальной валюты, в массиве items будут отображены:

  • параметры бандла или пакета виртуальной валюты;
  • предметы, которые входят в бандл, или валюты, которые входят в пакет.
Enum: "virtual_good" "virtual_currency" "game_key" "bundle"
quantity
required
integer

Количество предметов.

amount
required
string

Общая стоимость предметов с учетом их количества. Может отличаться от цены товара из-за конвертации валют и комиссий.

required
Array of objects

Примененные акции. Если акции не применялись, в параметр передается пустой массив.

Array
amount_with_discount
string

Стоимость предметов со скидкой.

amount_without_discount
string

Стоимость предметов без скидки.

sequence
integer

Порядок применения акций.

is_pre_order
required
boolean

Если передано значение true, предмет является предзаказом.

custom_attributes
object <json>

JSON-объект, содержащий атрибуты товара и их значения.

required
object

Информация о заказе.

id
required
integer

Уникальный идентификатор заказа пользователя на стороне Xsolla.

mode
required
string

Тип платежа. Значение default (по умолчанию) используется для реальных платежей. Значение sandbox используется для тестовых платежей.

Enum: "default" "sandbox"
currency_type
required
string

Тип валюты платежа. Для бесплатного заказа указывается значение unknown.

Enum: Description
real

для реальной валюты

unknown

для бесплатного заказа

virtual

для виртуальной валюты

currency
required
string

Валюта заказа. Для виртуальной валюты используется артикул, для реальной валюты используется трехбуквенное обозначение согласно стандарту ISO 4217.

amount
required
string

Стоимость корзины с учетом выбранной валюты.

status
required
string

Статус заказа.

platform
required
string or null

Платформа платежа. Для платежей через Xsolla используется значение xsolla. Для других платежей используется значение, соответствующее названию платформы публикации игры.

Enum: "xsolla" "playstation_network" "xbox_live" "pc_standalone" "nintendo_shop" "google_play" "app_store_ios" "android_standalone" "ios_standalone" "android_other" "ios_other" "pc_other"
comment
required
string or null

Комментарий пользователя к заказу.

invoice_id
required
string or null

ID счета для платежей за реальную валюту. Для платежей за виртуальную валюту или для бесплатных товаров передается значение null.

required
Array of objects

Примененные акции. Если акции не применялись, в параметр передается пустой массив.

Array
amount_with_discount
string

Стоимость предметов со скидкой.

amount_without_discount
string

Стоимость предметов без скидки.

sequence
integer

Порядок применения акций.

Array of objects

Примененные купоны. Если купон не был применен, массив не возвращается.

Array
code
string

Код примененного купона.

external_id
string

Внешний ID.

Array of objects

Примененные промокоды. Если промокод не был применен, массив не возвращается.

Array
code
string

Код примененного промокода.

external_id
string

Внешний ID.

required
object

Информация о пользователе.

external_id
required
string

ID пользователя.

email
required
string

Email-адрес пользователя.

custom_parameters
object

Дополнительная информация.

Responses
200

Верните, чтобы сообщить об успешной обработке вехбука.

400

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

Request samples
curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
-d '{
    "notification_type": "order_paid",
    "items": [
      {
        "sku": "virtual-good-item_test",
        "type": "virtual_good",
        "is_pre_order": false,
        "quantity": 3,
        "amount": "1000",
        "promotions": [
          {
            "amount_without_discount": "6000",
            "amount_with_discount": "5000",
            "sequence": 1
          },
          {
            "amount_without_discount": "5000",
            "amount_with_discount": "4000",
            "sequence": 2
          }
        ]
        "custom_attributes":
          {
            "purchased": 0,
            "attr": "value"
          },
      },
      {
        "sku": "virtual-good-item_test_test_new",
        "type": "bundle",
        "is_pre_order": false,
        "quantity": 1,
        "amount": "1000",
        "promotions": []
      },
      {
        "sku": "gold",
        "type": "virtual_currency",
        "is_pre_order": false,
        "quantity": 1500,
        "amount": "[null]",
        "promotions": []
      }
    ],
    "order": {
      "id": 1,
      "mode": "default",
      "currency_type": "virtual",
      "currency": "sku_currency",
      "amount": "2000",
      "status": "paid",
      "platform": "xsolla",
      "comment": null,
      "invoice_id": "1",
      "promotions": [
        {
          "amount_without_discount": "4000",
          "amount_with_discount": "2000",
          "sequence": 1
        }
      ],
      "promocodes": [
        {
          "code": "promocode_some_code",
          "external_id": "promocode_sku"
        }
      ],
      "coupons": [
        {
          "code": "WINTER2021",
          "external_id": "coupon_sku"
        }
      ]
    },
    "user": {
      "external_id": "id_xsolla_login_1",
      "email": "gc_user@xsolla.com"
    }

}'