Примечание
В зависимости от используемого решения и типа интеграции набор вебхуков и последовательность взаимодействия могут отличаться от приведенного примера.
\n| Продукт/ Решение | \nОбязательно/ Опционально | \nДля чего нужны вебхуки | \n
|---|---|---|
| Payments | \nОбязательно | \n\n
| \n
| Магазин | \nОбязательно | \n\n
| \n
| Game Sales | \nОпционально | \nДля продажи ключей не требуется валидация пользователя и начисление ему товаров. Вы можете подключить вебхуки, если вы хотите получать информацию о событиях, например об оплате или отмене заказа. Если вы подключите вебхуки, важно обрабатывать все поступающие обязательные вебхуки.\n | \n
| Subscriptions | \nОпционально | \nПолучение информации о создании, изменении или отмене подписки. Альтернативный вариант — запрос информации с помощью API.\n | \n
| Web Shop | \nОбязательно | \n\n
| \n
| Digital Distribution Hub | \nОбязательно | \n\n
Подробная информация по настройке вебхуков для Digital Distribution Hub приведена в инструкции. \n | \n
| Login | \nОпционально | \n\n Получение информации о наступлении события: \n
Подробная информация о настройке вебхуков приведена в документации Login. \n | \n
Примечание
Publisher Account is a legacy tool.
\n| Название и тип вебхука | \nОписание | \n
|---|---|
Проверка пользователей > Проверка существования пользователя (user_validation) | \n Отправляется на разных этапах оплаты, чтобы удостовериться, что пользователь зарегистрирован в игре. | \n
Игровые сервисы > Объединенные вебхуки > Успешная оплата заказа (order_paid) | \n Данные платежа, детали транзакции и информация о купленных товарах. Используйте данные вебхука для начисления товаров пользователю. | \n
Игровые сервисы > Объединенные вебхуки > Отмена заказа (order_canceled) | \n Данные отмененного платежа, детали транзакции и информацию о купленных товарах. Используйте данные вебхука для списания купленных товаров у пользователя. | \n
| Название и тип вебхука | \nОписание | \n
|---|---|
Проверка пользователей > Проверка существования пользователя (user_validation) | \n Отправляется на разных этапах оплаты, чтобы удостовериться, что пользователь зарегистрирован в игре. | \n
Платежи > Успешный платеж (payment) | \n Данные платежа и детали транзакции. | \n
Игровые сервисы > Отдельные вебхуки > Успешная оплата заказа (order_paid) | \n Информация о купленных товарах. Используйте данные вебхука для начисления товаров пользователю. | \n
Платежи > Возврат платежа (refund) | \n Данные платежа и детали транзакции. | \n
Игровые сервисы > Отдельные вебхуки > Отмена заказа (order_canceled) | \n Информация о купленных товарах. Используйте данные вебхука для списания купленных товаров у пользователя. | \n
Примечание
\nЧтобы принимать реальные платежи, достаточно подписать лицензионный договор и реализовать обработку вебхуков:
\nВнимание
\nДля передачи данных используется протокол HTTPS, протокол HTTP не поддерживается.
\nNotice
\nKey recommendations:
Примечание
\nДля тестирования вебхуков вы можете выбрать любой специализированный сайт, например webhook.site, или платформу, например ngrok.
\nNotice
\nYou can’t simultaneously send webhooks to different URLs. What you can do in the account is specify a URL for testing first, and then replace it with the real one.
\nNotice
\nKey recommendations:
Примечание
\nЕсли расширенные настройки не отображаются, убедитесь, что получение вебхуков подключено в общих настройках и вы находитесь на вкладке Тестирование > Payments and Store.
\n| Переключатель | \nОписание | \n
|---|---|
| Показывать информацию о транзакциях сохраненными способами оплаты (отображается, если вы зарегистрировались в Личном кабинете до 22 января 2025 г. и получаете отдельные вебхуки). | \nИнформация о сохраненном способе оплаты передается в кастомном объекте payment_account. | \n
| Показывать информацию о транзакциях сохраненными способами оплаты. | \nВ вебхуке будет передаваться информация в кастомных параметрах:
| \n
Добавить объект order в вебхук (отображается, если вы зарегистрировались в Личном кабинете до 22 января 2025 г. и получаете отдельные вебхуки). | \n В вебхуке Успешный платеж будет передаваться информация о заказе в объекте order. | \n
| Показывать только необходимую информацию о пользователе без чувствительных данных. | \nВ вебхуке о пользователе будет передаваться только следующая информация:
| \n
| Передавать кастомные параметры. | \nВ вебхуке будет передаваться информация о кастомных параметрах из токена. | \n
| Показывать БИН карты и последние 4 цифры ее номера. | \nВ вебхуке будет передаваться следующая информация о номере карты:
| \n
| Показывать бренд карты. | \nБренд карты, с которой была совершена оплата. Например, Mastercard или Visa. | \n
| Показывать информацию о причине возврата. | \nДетальная информация о причине возврата. | \n
| Показать региональный налог у источника и стоимость каналов привлечения трафика. | \nВ вебхуке будут передаваться объекты payment_details.country_wht и payment_details.user_acquisition_fee. По умолчанию этот переключатель активирован. | \n
| Отправлять информацию о 3DS. | \nВ вебхуке будет передаваться объект cards с данными о прохождении пользователем проверки 3-D Secure. | \n
| Название вкладки для тестирования вебхуков | \nНазвание и тип вебхука | \n
|---|---|
| Payments and Store | \nПроверка пользователей > Проверка существования пользователя (user_validation) | \n
| \n | Игровые сервисы > Объединенные вебхуки > Успешная оплата заказа (order_paid) | \n
| \n | Игровые сервисы > Объединенные вебхуки > Отмена заказа (order_canceled) | \n
| Subscriptions | \nПроверка пользователей > Проверка существования пользователя (user_validation) | \n
| \n | Платежи > Успешный платеж (payment) | \n
| Название вкладки для тестирования вебхуков | \nНазвание и тип вебхука | \n
|---|---|
| Store | \nИгровые сервисы > Отдельные вебхуки > Успешная оплата заказа (order_paid) | \n
| \n | Игровые сервисы > Отдельные вебхуки > Отмена заказа (order_canceled) | \n
| Payments | \nПроверка пользователей > Проверка существования пользователя (user_validation) | \n
| \n | Платежи > Успешный платеж (payment) | \n
| Subscriptions | \nПроверка пользователей > Проверка существования пользователя (user_validation) | \n
| \n | Платежи > Успешный платеж (payment) | \n
Примечание
\nЕсли в блоке тестирования отобразилось предупреждение, что тест не пройден, проверьте настройки ответа на вебхук в вашем обработчике вебхуков. Причины ошибок в тестировании указаны в результатах тестирования.
\nПример:
\nДля тестирования вы используете специализированный сайт webhook.site.
\nВ разделе Тестирование ответа на неверную подпись отображается ошибка.
\nЭто происходит, потому что Xsolla отправляет вебхук с неверной подписью и ожидает, что ваш обработчик ответит 4xx HTTP-кодом с указанием кода ошибки INVALID_SIGNATURE.
webhook.site отправляет 200 HTTP-код в ответ на все вебхуки, в том числе на вебхук с неверной подписью. Ожидаемый 4xx HTTP-код не может быть получен, поэтому в результате тестирования отображается ошибка.
Note
\nTo test webhooks, you should have at least one subscription plan created in the account in the Items catalog > Subscriptions section.
\nПримечание
\nТестирование других сценариев управления подписками описано в руководстве по интеграции.
\nПримечание
\nВы можете использовать библиотеку Pay Station PHP SDK, которая содержит готовые классы для обработки вебхуков.
\nВнимание
Используйте JSON в полученном \n виде. Не парсите и не перекодируйте данные, так как это изменит форматирование \n и приведет к ошибке проверки подписи.
Примечание
\nЭтот пример кода совместим с .NET Framework 4.0 и выше, а также с .NET Core и другими современными версиями .NET. Для проверки подписи реализовано сравнение с постоянным временем выполнения с помощью метода ConstantTimeEquals, что помогает предотвратить атаки по времени.
Примечание
\nЧтобы использовать метод Convert.ToHexString, вам необходима версия .NET 5.0 или выше.
CryptographicOperations.FixedTimeEquals вместо ConstantTimeEquals.\nПримечание
\nЕсли у вас версия .NET 7.0 или выше, вы можете использовать метод CryptographicOperations.FixedTimeEquals.
Внимание
\nПри одновременном выполнении следующих условий платеж все равно будет возвращен пользователю:
4xx, или после всех повторных попыток ответ не был получен, или был получен код 5xx.| Код | \nОписание | \n
|---|---|
| INVALID_USER | \nНеверный пользователь | \n
| INVALID_PARAMETER | \nНеверный параметр | \n
| INVALID_SIGNATURE | \nПодпись неверна | \n
| INCORRECT_AMOUNT | \nНекорректная сумма | \n
| INCORRECT_INVOICE | \nНеверный заказ | \n
Note
\nIf you are testing the integration locally, POST requests from Xsolla don’t reach URLs like http://localhost:3000/my-webhook-endpoint. Use services such as Ngrok that allow you to create a tunnel for external access, enabling you to receive requests from Xsolla locally. E.g., you can read more about this in the ngrok documentation.
Примечание
\nТип оповещения передается в параметре notification_type.
| Вебхук | \nТип оповещения | \nОписание | \n
|---|---|---|
| Проверка существования пользователя | \nuser_validation | \n Проверка существования пользователя в игре. | \n
| Поиск пользователя | \nuser_search | \n Получение информации о пользователе по публичному ID пользователя. | \n
| Успешный платеж | \npayment | \n Оповещение об успешном платеже. | \n
| Возврат платежа | \nrefund | \n Оповещение об отмене платежа. | \n
| Частичный возврат платежа | \npartial_refund | \n Оповещение о частичном возврате платежа. | \n
| Отмена платежа | \nps_declined | \n Оповещение об отмене транзакции платежной системой. | \n
| Транзакция отклонена при проверке AFS | \nafs_reject | \n Оповещение об отмене транзакции системой расширенного антифрода. | \n
| Обновление черного списка AFS | \nafs_black_list | \n Оповещение об изменении черного списка AFS. | \n
| Создание подписки | \ncreate_subscription | \n Оповещение о создании подписки. | \n
| Изменение подписки | \nupdate_subscription | \n Оповещение о продлении подписки или о смене каких-либо параметров внутри подписки. | \n
| Отмена подписки | \ncancel_subscription | \n Оповещение об отмене подписки. | \n
| Непродлеваемая подписка | \nnon_renewal_subscription | \n Оповещение о смене статуса на непродлеваемый. | \n
| Добавление платежного аккаунта | \npayment_account_add | \n Оповещение о добавлении или сохранении платежного аккаунта. | \n
| Удаление платежного аккаунта | \npayment_account_remove | \n Оповещение об удалении платежного аккаунта. | \n
| Проверка пользователя в Web Shop | \n- | \n Отправлено из Web Shop для проверки существования пользователя в игре. | \n
| Персонализация каталога на стороне партнера | \npartner_side_catalog | \n Отправляется, когда пользователь взаимодействует с магазином. | \n
| Успешная оплата заказа | \norder_paid | \n Отправляется, когда заказ оплачен. | \n
| Отмена заказа | \norder_canceled | \n Отправляется, когда заказ отменен. | \n
| Диспут | \ndispute | \n Оповещение об открытии нового диспута. | \n
Note
\nIf you registered in Publisher Account on or before January 22, 2025, you can find the toggles in the Settings > Webhooks > Testing > Payments > Advanced settings section.
\n| Переключатель | \nОписание | \n
|---|---|
| Показывать информацию о транзакциях сохраненными способами оплаты | \nВ вебхуке будет передаваться информация в кастомных параметрах:
| \n
| Инициатор возврата | \nЗначение поля | \n
|---|---|
| Игра (через API). | \nAPI | \n
| Account user (automatic refund). | \nEmail-адрес пользователя | \n
| Account user (with assistance from Xsolla customer support). | \nsupport@xsolla.com | \n
| Xsolla (при участии службы поддержки Xsolla). | \nsupport@xsolla.com | \n
| Код | \nПричина отмены | \nОписание | \n
|---|---|---|
| 1 | \nCancellation initiated from the account. | \n|
| 2 | \nИспользуется, если по транзакции был chargeback. | \n|
| 3 | \nИспользуется в случае проблем с интеграцией между Xsolla и игрой. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 4 | \nИспользуется, когда транзакция была отклонена из-за потенциального фрода, который обнаружила система Xsolla Anti-fraud. | \n|
| 5 | \nИспользуется в случае совершения тестового платежа с последующей отменой. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 6 | \nИспользуется, если был выбран способ оплаты с системой отложенного платежа. | \n|
| 7 | \nИспользуется, если платежная система не произвела выплату по транзакции из-за потенциального фрода. В этом случае мы рекомендуем добавить пользователя в черный список. | \n |
| 8 | \nИспользуется, когда платежная система запросила отмену транзакции. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 9 | \nИспользуется, если игра или заказ не удовлетворяют требованиям пользователя по каким-либо причинам. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 10 | \nИспользуется, когда игра просит отменить транзакцию. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 11 | \nИспользуется, когда владелец аккаунта сообщил, что не совершал данный платеж. В этом случае мы рекомендуем добавить пользователя в черный список. | \n |
| 12 | \nИспользуется, когда законный держатель карты оспорил свою транзакцию. | \n|
| 13 | \nИспользуется, если произошла попытка повторной оплаты по счету. | \n|
| 21 | \nИспользуется, когда происходит массовая кража данных карт с одним или несколькими BIN. Особенность: всплеск попыток использования одинаковых BIN за короткий промежуток времени, зачастую с использованием последовательных номеров карт. | \n|
| 22 | \nИспользуется, когда товары, доступные для обмена, были куплены с помощью украденной карты с целью перепродажи. | \n|
| 23 | \nИспользуется, когда происходит кража данных карт с одним или несколькими BIN. Не такая масштабная и скоординированная, как атака по BIN (код отмены 21). | \n |
| 24 | \nИспользуется при злоупотреблении региональными ценами или перепродажей ключей. Пользователи воспользовались региональными ценами — зачастую через смену геолокации или подмену информации о способе оплаты — чтобы дешевле купить товары и перепродать их по более высоким ценам. | \n|
| 25 | \nИспользуется, когда происходит кража учетных данных и захват аккаунта. Относится к злоупотреблению учетной записью или интеграцией на стороне партнера или платежной системы, а не к использованию карты. | \n|
| 26 | \nИспользуется, когда фрод был подтвержден, но доказательств недостаточно, чтобы определить конкретный тип атаки. | \n|
| 27 | \nИспользуется, когда транзакция отсутствует в отчете платежной системы по фроду, но она связана с другими мошенническими транзакциями. Например, платежи по таким транзакциям могут быть сделаны с помощью одинакового номера карты или устройства и возвращены пользователям по причинам, связанным с фродом. | \n
order_canceled на указанный URL-адрес, \nкогда платеж отменен пользователем, партнером или автоматически. В вебхуке \nсодержится информация о возвращенных товарах, платежные данные и детали \nотмененного заказа.\n\nВебхук не отправляется, если оплата не была успешной, например:\n* платежный интерфейс был открыт, но пользователь не оплатил заказ;\n* платежный интерфейс был открыт, но при оплате возникли ошибки.\n\nРекомендуемое время обработки вебхука — до 3 секунд.\n",
"operationId": "order-cancellation",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"billing": {
"description": "Детали платежа и транзакции.",
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"payment_details": {
"description": "Объект с финансовыми данными платежа.",
"properties": {
"country_wht": {
"$ref": "#/components/schemas/country_whc"
},
"direct_wht": {
"description": "Налог, удерживаемый у источника выплаты.",
"properties": {
"amount": {
"description": "Сумма.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"percent": {
"description": "Процент налога, удерживаемого у источника выплаты.",
"format": "float",
"type": "number"
}
},
"type": "object"
},
"payment": {
"description": "Объект с данными о сумме, которую оплатил пользователь.",
"properties": {
"amount": {
"description": "Сумма.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"type": "object"
},
"payment_method_fee": {
"description": "Размер комиссии платежной системы.",
"properties": {
"amount": {
"description": "Сумма.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"type": "object"
},
"payment_method_sum": {
"description": "Объект с данными о сумме, которая была оплачена из платежной системы.",
"properties": {
"amount": {
"description": "Сумма.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"type": "object"
},
"payout": {
"description": "Объект с данными о сумме выплаты.",
"properties": {
"amount": {
"description": "Сумма.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"type": "object"
},
"payout_currency_rate": {
"description": "Курс валюты платежа к валюте выплаты.",
"type": "string"
},
"repatriation_commission": {
"description": "Объект с информацией о затратах на репатриацию, возлагаемых на Xsolla третьими сторонами.",
"properties": {
"amount": {
"description": "Сумма.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"type": "object"
},
"sales_tax": {
"description": "Размер налога (только для США и Канады).",
"properties": {
"amount": {
"description": "Сумма.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"percent": {
"description": "Процент налога.",
"format": "float",
"type": "number"
}
},
"type": "object"
},
"user_acquisition_fee": {
"description": "Объект с данными о сумме вознаграждения каналов привлечения трафика (аффилированные сети и инфлюенсеры).",
"properties": {
"amount": {
"description": "Сумма.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"percent": {
"description": "Ставка вознаграждения за привлечение пользователей, %.",
"format": "float",
"type": "number"
}
},
"type": "object"
},
"vat": {
"description": "Размер VAT (только для Евросоюза).",
"properties": {
"amount": {
"description": "Сумма.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"percent": {
"description": "Процент VAT.",
"format": "float",
"type": "number"
}
},
"type": "object"
},
"xsolla_balance_sum": {
"description": "Объект с данными о сумме, которая была оплачена с Xsolla-баланса.",
"properties": {
"amount": {
"description": "Сумма.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"type": "object"
},
"xsolla_fee": {
"description": "Размер комиссии Xsolla.",
"properties": {
"amount": {
"description": "Сумма.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"type": "object"
}
},
"type": "object"
},
"purchase": {
"description": "Объект с информацией о заказе.",
"properties": {
"subscription": {
"description": "Объект с данными о подписке.",
"properties": {
"amount": {
"$ref": "#/components/schemas/amount-float"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"date_create": {
"$ref": "#/components/schemas/subscription.date_create"
},
"plan_id": {
"$ref": "#/components/schemas/subscription.plan_id"
},
"subscription_id": {
"$ref": "#/components/schemas/subscription.subscription_id"
},
"tags": {
"$ref": "#/components/schemas/subscription.tags"
}
},
"type": "object"
},
"total": {
"description": "Объект с данными об общей стоимости покупки.",
"properties": {
"amount": {
"description": "Общая сумма покупки.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"type": "object"
}
},
"required": [
"total"
],
"type": "object"
},
"refund_details": {
"description": "Объект с финансовыми данными рефанда.",
"properties": {
"author": {
"description": "Инициатор возврата платежа. Значение поля передается согласно таблице:\n\n| Инициатор возврата | \nЗначение поля | \n
|---|---|
| Игра (через API). | \nAPI | \n
| Account user (automatic refund). | \nEmail-адрес пользователя | \n
| Account user (with assistance from Xsolla customer support). | \nsupport@xsolla.com | \n
| Xsolla (при участии службы поддержки Xsolla). | \nsupport@xsolla.com | \n
order_canceled на указанный URL-адрес, \nкогда платеж отменен пользователем, партнером или автоматически. В вебхуке \nсодержится информация о возвращенных товарах и детали отмененного заказа.\n\nВебхук не отправляется, если оплата не была успешной, например:\n* платежный интерфейс был открыт, но пользователь не оплатил заказ;\n* платежный интерфейс был открыт, но при оплате возникли ошибки.\n\nРекомендуемое время обработки вебхука — до 3 секунд.\n",
"operationId": "order-cancellation-separate",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"custom_parameters": {
"description": "Дополнительная информация.",
"type": "object"
},
"items": {
"description": "Список предметов, которые купил пользователь.\n\nНабор передаваемых параметров в массиве зависит от версии вебхука. В версии 2 \nдополнительно передаются параметры `is_free`, `is_bonus` и `is_bundle_content`. \nДля переключения версии передайте ее номер в параметре `version` в методе \n[Обновление версии вебхука](/ru/api/catalog/common-webhooks/update-webhook-version/).\n",
"items": {
"oneOf": [
{
"properties": {
"amount": {
"description": "Цена единицы товара.",
"type": "string"
},
"custom_attributes": {
"description": "JSON-объект, содержащий атрибуты товара и их значения.",
"type": "object"
},
"is_pre_order": {
"description": "Если передано значение `true`, товар является предзаказом.",
"type": "boolean"
},
"promotions": {
"$ref": "#/components/schemas/items.promotions"
},
"quantity": {
"description": "Количество товаров.",
"type": "integer"
},
"sku": {
"$ref": "#/components/schemas/items.sku"
},
"type": {
"$ref": "#/components/schemas/items.type"
}
},
"required": [
"sku",
"type",
"quantity",
"amount",
"promotions",
"is_pre_order"
],
"title": "version = 1",
"type": "object"
},
{
"properties": {
"amount": {
"description": "Цена единицы товара.",
"type": "string"
},
"custom_attributes": {
"description": "JSON-объект, содержащий атрибуты товара и их значения.",
"type": "object"
},
"is_bonus": {
"description": "Если передано значение `true`, товар является бонусом.",
"type": "boolean"
},
"is_bundle_content": {
"description": "Если передано значение `true`, товар является частью бандла.",
"type": "boolean"
},
"is_free": {
"description": "Если передано значение `true`, товар является бесплатным.",
"type": "boolean"
},
"is_pre_order": {
"description": "Если передано значение `true`, товар является предзаказом.",
"type": "boolean"
},
"promotions": {
"description": "Примененные акции. Если акции не применялись, в параметр передается пустой массив.",
"items": {
"properties": {
"amount_with_discount": {
"description": "Стоимость товаров со скидкой.",
"type": "string"
},
"amount_without_discount": {
"description": "Стоимость товаров без скидки.",
"type": "string"
},
"sequence": {
"description": "Порядок применения акций.",
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"quantity": {
"description": "Количество товаров.",
"type": "integer"
},
"sku": {
"$ref": "#/components/schemas/items.sku"
},
"type": {
"$ref": "#/components/schemas/items.type"
}
},
"required": [
"sku",
"type",
"quantity",
"amount",
"promotions",
"is_pre_order",
"is_free",
"is_bonus",
"is_bundle_content"
],
"title": "version = 2",
"type": "object"
}
]
},
"type": "array"
},
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"order": {
"description": "Информация о заказе.",
"properties": {
"amount": {
"description": "Стоимость корзины с учетом выбранной валюты.",
"type": "string"
},
"comment": {
"description": "Комментарий пользователя к заказу.",
"nullable": true,
"type": "string"
},
"coupons": {
"description": "Примененные купоны. Если купон не был применен, массив не возвращается.",
"items": {
"properties": {
"code": {
"description": "Код примененного купона.",
"type": "string"
},
"external_id": {
"description": "Внешний ID.",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"currency": {
"description": "Валюта заказа. Для виртуальной валюты используется артикул, для реальной валюты используется трехбуквенное обозначение согласно стандарту [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).",
"type": "string"
},
"currency_type": {
"$ref": "#/components/schemas/currency-type"
},
"id": {
"description": "Уникальный идентификатор заказа пользователя на стороне Xsolla.",
"type": "integer"
},
"invoice_id": {
"description": "ID счета для платежей за реальную валюту. Для платежей за виртуальную валюту или для бесплатных товаров передается значение `null`.",
"nullable": true,
"type": "string"
},
"mode": {
"description": "Тип платежа. Значение `default` (по умолчанию) используется для реальных платежей. Значение `sandbox` используется для тестовых платежей.",
"enum": [
"default",
"sandbox"
],
"type": "string"
},
"platform": {
"description": "Платформа платежа. Для платежей через Xsolla используется значение `xsolla`. Для других платежей используется значение, соответствующее названию платформы публикации игры: `playstation_network`, `xbox_live`, `pc_standalone`, `nintendo_shop`, `google_play`, `app_store_ios`, `android_standalone`, `ios_standalone`, `android_other`, `ios_other`, `pc_other`.",
"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"
],
"nullable": true,
"type": "string"
},
"promocodes": {
"description": "Примененные промокоды. Если промокод не был применен, массив не возвращается.",
"items": {
"properties": {
"code": {
"description": "Код примененного промокода.",
"type": "string"
},
"external_id": {
"description": "Внешний ID.",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"promotions": {
"$ref": "#/components/schemas/order.promotions"
},
"status": {
"description": "Статус заказа.",
"type": "string"
}
},
"required": [
"id",
"mode",
"currency_type",
"currency",
"amount",
"status",
"platform",
"comment",
"invoice_id",
"promotions"
],
"type": "object"
},
"user": {
"description": "Информация о пользователе.",
"properties": {
"country": {
"$ref": "#/components/schemas/user.country"
},
"email": {
"description": "Email-адрес пользователя.",
"type": "string"
},
"external_id": {
"description": "ID пользователя.",
"type": "string"
}
},
"required": [
"external_id",
"email"
],
"type": "object"
}
},
"required": [
"notification_type",
"items",
"order",
"user"
]
}
}
}
},
"responses": {
"200": {
"description": "Верните, чтобы сообщить об успешной обработке вехбука."
},
"400": {
"description": "Верните в случае ошибки в предоставленной информации (например, обязательный параметр не передан, или авторизация не прошла)."
}
},
"summary": "Отмена заказа (без деталей платежа и транзакции)",
"tags": [
"separate-webhooks"
],
"x-codeSamples": [
{
"label": "CURL",
"lang": "cURL",
"source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-H 'accept: application/json' \\\n-H 'content-type: application/json' \\\n-H 'authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \\\n-d '{\n \"notification_type\": \"order_canceled\",\n \"items\": [\n {\n \"sku\": \"com.xsolla.v.item_1\",\n \"type\": \"virtual_good\",\n \"is_pre_order\": false,\n \"quantity\": 3,\n \"amount\": \"1000\",\n \"promotions\": [\n {\n \"amount_without_discount\": \"6000\",\n \"amount_with_discount\": \"5000\",\n \"sequence\": 1\n },\n {\n \"amount_without_discount\": \"5000\",\n \"amount_with_discount\": \"4000\",\n \"sequence\": 2\n }\n ],\n \"custom_attributes\": {\n \"purchased\": 0,\n \"attr\": \"value\"\n }\n },\n {\n \"sku\": \"com.xsolla.v.item_new_1\",\n \"type\": \"bundle\",\n \"is_pre_order\": false,\n \"quantity\": 1,\n \"amount\": \"1000\",\n \"promotions\": []\n },\n {\n \"sku\": \"com.xsolla.gold_1\",\n \"type\": \"virtual_currency\",\n \"is_pre_order\": false,\n \"quantity\": 1500,\n \"amount\": \"[null]\",\n \"promotions\": []\n }\n ],\n \"order\": {\n \"id\": 1,\n \"mode\": \"default\",\n \"currency_type\": \"virtual\",\n \"currency\": \"sku_currency\",\n \"amount\": \"2000\",\n \"status\": \"paid\",\n \"platform\": \"xsolla\",\n \"comment\": null,\n \"invoice_id\": \"1\",\n \"promotions\": [\n {\n \"amount_without_discount\": \"4000\",\n \"amount_with_discount\": \"2000\",\n \"sequence\": 1\n }\n ],\n \"promocodes\": [\n {\n \"code\": \"promocode_some_code\",\n \"external_id\": \"promocode_sku\"\n }\n ],\n \"coupons\": [\n {\n \"code\": \"WINTER2021\",\n \"external_id\": \"coupon_sku\"\n }\n ]\n },\n \"user\": {\n \"external_id\": \"id_xsolla_login_1\",\n \"email\": \"email@example.com\",\n \"country\": \"US\"\n }\n\n}'"
},
{
"label": "HTTP",
"lang": "HTTP",
"source": "POST /your/uri HTTP/1.1\nhost: your.hostname\naccept: application/json\ncontent-length: 258\ncontent-type: application/json\nauthorization: Signature d90d319f05df7b0f86d2485f48e7079f0f752523\n\n\n{\n \"notification_type\": \"order_canceled\",\n \"items\": [\n {\n \"sku\": \"com.xsolla.v.item_1\",\n \"type\": \"virtual_good\",\n \"is_pre_order\": false,\n \"quantity\": 3,\n \"amount\": \"1000\",\n \"promotions\": [\n {\n \"amount_without_discount\": \"6000\",\n \"amount_with_discount\": \"5000\",\n \"sequence\": 1\n },\n {\n \"amount_without_discount\": \"5000\",\n \"amount_with_discount\": \"4000\",\n \"sequence\": 2\n }\n ],\n \"custom_attributes\": {\n \"purchased\": 0,\n \"attr\": \"value\"\n }\n },\n {\n \"sku\": \"com.xsolla.v.item_new_1\",\n \"type\": \"bundle\",\n \"is_pre_order\": false,\n \"quantity\": 1,\n \"amount\": \"1000\",\n \"promotions\": []\n },\n {\n \"sku\": \"com.xsolla.gold_1\",\n \"type\": \"virtual_currency\",\n \"is_pre_order\": false,\n \"quantity\": 1500,\n \"amount\": \"[null]\",\n \"promotions\": []\n }\n ],\n \"order\": {\n \"id\": 1,\n \"mode\": \"default\",\n \"currency_type\": \"virtual\",\n \"currency\": \"sku_currency\",\n \"amount\": \"2000\",\n \"status\": \"paid\",\n \"platform\": \"xsolla\",\n \"comment\": null,\n \"invoice_id\": \"1\",\n \"promotions\": [\n {\n \"amount_without_discount\": \"4000\",\n \"amount_with_discount\": \"2000\",\n \"sequence\": 1\n }\n ],\n \"promocodes\": [\n {\n \"code\": \"promocode_some_code\",\n \"external_id\": \"promocode_sku\"\n }\n ],\n \"coupons\": [\n {\n \"code\": \"WINTER2021\",\n \"external_id\": \"coupon_sku\"\n }\n ]\n },\n \"user\": {\n \"external_id\": \"id_xsolla_login_1\",\n \"email\": \"email@example.com\",\n \"country\": \"US\"\n }\n}"
}
]
}
},
"partial-refund": {
"post": {
"description": "При частичном возврате платежа Xsolla отправляет детали отмененной транзакции в \nвебхуке с типом `partial_refund` на URL-адрес вебхука. Подробная информация о \nпроцессе частичного возврата платежа приведена в [инструкции](/ru/doc/pay-station/features/refund/#pay_station_features_refund_how_it_works_partial_refund_flow).\n\nWhen you save the webhook URL in the account, you can give permissions to \nreceive detailed information in webhooks. To do that, activate the following \ntoggle in your [account](/ru/webhooks/overview/#business-accounts) in the \n**Settings > Webhooks > Advanced settings** section.\n\nNote
\nIf you registered in Publisher Account on or before January 22, 2025, you can find the toggles in the Project settings > Webhooks > Testing > Payments > Advanced settings section.
\n| Переключатель | \nОписание | \n
|---|---|
| Показывать информацию о транзакциях сохраненными способами оплаты | \nВ вебхуке будет передаваться информация в кастомных параметрах:
| \n
| Код | \nПричина отмены | \nОписание | \n
|---|---|---|
| 1 | \nCancellation initiated from the account. | \n|
| 3 | \nИспользуется в случае проблем с интеграцией между Xsolla и игрой. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 5 | \nИспользуется в случае совершения тестового платежа с последующей отменой. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 7 | \nИспользуется, если платежная система не произвела выплату по транзакции из-за потенциального фрода. В этом случае мы рекомендуем добавить пользователя в черный список. | \n |
| 9 | \nИспользуется, если игра или заказ не удовлетворяют требованиям пользователя по каким-либо причинам. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 10 | \nИспользуется, когда игра просит отменить транзакцию. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
| Инициатор возврата | \nЗначение поля | \n
|---|---|
| Игра (через API). | \nAPI | \n
| Account user (automatic refund). | \nEmail-адрес пользователя | \n
| Account user (with assistance from Xsolla customer support). | \nsupport@xsolla.com | \n
| Xsolla (при участии службы поддержки Xsolla). | \nsupport@xsolla.com | \n
| Код ответа | \nОписание | \n
|---|---|
200, 201, 204 | \n Успешный ответ. | \n
4xx | \n Возникновение ошибки. Например, если указанный пользователь не был найден или если передана недействительная подпись. | \n
5xx | \n Временная ошибка на сервере. При получении этого ответа Xsolla отправляет вебхук повторно с увеличенным интервалом, пока ваш обработчик не подтвердит их получение. Максимальное количество попыток — 12 в течение 48 часов. | \n
Note
\nIf you registered in Publisher Account on or before January 22, 2025, you can find the toggles in your project in the Settings > Webhooks > Testing > Payments > Advanced settings section.
\n| Переключатель | \nОписание | \n
|---|---|
| Показывать информацию о сохраненном платежном аккаунте | \nИнформация о сохраненном способе оплаты передается в кастомном объекте payment_account. | \n
| Показывать информацию о транзакциях сохраненными способами оплаты | \nВ вебхуке будет передаваться информация в кастомных параметрах:
| \n
| Добавить объект order в вебхук | \nВ вебхуке Успешный платеж будет передаваться информация о заказе в объекте order. | \n
| Показывать только необходимую информацию о пользователе без чувствительных данных | \nВ вебхуке о пользователе будет передаваться только следующая информация:
| \n
| Показывать БИН карты и последние 4 цифры ее номера | \nВ вебхуке будет передаваться следующая информация о номере карты:
| \n
| Показывать бренд карты | \nБренд карты, с которой была совершена оплата. Например, Mastercard или Visa. | \n
| Показать региональный налог у источника и стоимость каналов привлечения трафика. | \nВ вебхуке будут передаваться объекты payment_details.country_wht и payment_details.user_acquisition_fee. По умолчанию этот переключатель активирован. | \n
| Отправлять информацию о 3DS. | \nВ вебхуке будет передаваться объект cards с данными о прохождении пользователем проверки 3-D Secure. | \n
Notice
\nThe set of fields sent in a webhook depends on:
If you have any questions, contact your Customer Success Manager or email to csm@xsolla.com.
\nПримечание
\nЧтобы получать вебхук ps_declined, обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.
| Инициатор возврата | \nЗначение поля | \n
|---|---|
| Игра (через API). | \nAPI | \n
| Account user (automatic refund). | \nEmail-адрес пользователя | \n
| Account user (with assistance from Xsolla customer support). | \nsupport@xsolla.com | \n
| Xsolla (при участии службы поддержки Xsolla). | \nsupport@xsolla.com | \n
| Код | \nПричина отмены | \nОписание | \n
|---|---|---|
| 1 | \nCancellation initiated from the account. | \n|
| 2 | \nИспользуется, если по транзакции был chargeback. | \n|
| 3 | \nИспользуется в случае проблем с интеграцией между Xsolla и игрой. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 4 | \nИспользуется, когда транзакция была отклонена из-за потенциального фрода, который обнаружила система Xsolla Anti-fraud. | \n|
| 5 | \nИспользуется в случае совершения тестового платежа с последующей отменой. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 6 | \nИспользуется, если был выбран способ оплаты с системой отложенного платежа. | \n|
| 7 | \nИспользуется, если платежная система не произвела выплату по транзакции из-за потенциального фрода. В этом случае мы рекомендуем добавить пользователя в черный список. | \n |
| 8 | \nИспользуется, когда платежная система запросила отмену транзакции. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 9 | \nИспользуется, если игра или заказ не удовлетворяют требованиям пользователя по каким-либо причинам. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 10 | \nИспользуется, когда игра просит отменить транзакцию. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 11 | \nИспользуется, когда владелец аккаунта сообщил, что не совершал данный платеж. В этом случае мы рекомендуем добавить пользователя в черный список. | \n |
| 12 | \nИспользуется, когда законный держатель карты оспорил свою транзакцию. | \n|
| 13 | \nИспользуется, если произошла попытка повторной оплаты по счету. | \n|
| 21 | \nИспользуется, когда происходит массовая кража данных карт с одним или несколькими BIN. Особенность: всплеск попыток использования одинаковых BIN за короткий промежуток времени, зачастую с использованием последовательных номеров карт. | \n|
| 22 | \nИспользуется, когда товары, доступные для обмена, были куплены с помощью украденной карты с целью перепродажи. | \n|
| 23 | \nИспользуется, когда происходит кража данных карт с одним или несколькими BIN. Не такая масштабная и скоординированная, как атака по BIN (код отмены 21). | \n |
| 24 | \nИспользуется при злоупотреблении региональными ценами или перепродажей ключей. Пользователи воспользовались региональными ценами — зачастую через смену геолокации или подмену информации о способе оплаты — чтобы дешевле купить товары и перепродать их по более высоким ценам. | \n|
| 25 | \nИспользуется, когда происходит кража учетных данных и захват аккаунта. Относится к злоупотреблению учетной записью или интеграцией на стороне партнера или платежной системы, а не к использованию карты. | \n|
| 26 | \nИспользуется, когда фрод был подтвержден, но доказательств недостаточно, чтобы определить конкретный тип атаки. | \n|
| 27 | \nИспользуется, когда транзакция отсутствует в отчете платежной системы по фроду, но она связана с другими мошенническими транзакциями. Например, платежи по таким транзакциям могут быть сделаны с помощью одинакового номера карты или устройства и возвращены пользователям по причинам, связанным с фродом. | \n
partner_side_catalog, который содержит параметры пользователя и \nпроекта, на URL-адрес вебхука.\n\nВ ответе вам следует вернуть список item_id или артикулов \nпредметов, которые доступны пользователю. При этом вы также можете передать \nинформацию о том, что конкретный пользователь может купить определенный товар \nзаданное количество раз. Эта возможность позволяет регулировать количество и \nвид товаров, которые пользователь может добавить в корзину и купить.\n\nВнимание
При обработке вебхука учитывайте следующие ограничения:
Внимание
\nПри одновременном выполнении следующих условий платеж все равно будет возвращен пользователю:
4xx, или после всех повторных попыток ответ не был получен, или был получен код 5xx.Note
\nIf you registered in Publisher Account on or before January 22, 2025, you can find the toggles in your project in the Settings > Webhooks > Testing > Payments > Advanced settings section.
\n| Переключатель | \nОписание | \n
|---|---|
| Показывать информацию о транзакциях сохраненными способами оплаты | \nВ вебхуке будет передаваться информация в кастомных параметрах:
| \n
| Показывать информацию о причине возврата. | \nДетальная информация о причине возврата. | \n
| Код | \nПричина отмены | \nОписание | \n
|---|---|---|
| 1 | \nCancellation initiated from the account. | \n|
| 2 | \nИспользуется, если по транзакции был chargeback. | \n|
| 3 | \nИспользуется в случае проблем с интеграцией между Xsolla и игрой. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 4 | \nИспользуется, когда транзакция была отклонена из-за потенциального фрода, который обнаружила система Xsolla Anti-fraud. | \n|
| 5 | \nИспользуется в случае совершения тестового платежа с последующей отменой. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 6 | \nИспользуется, если был выбран способ оплаты с системой отложенного платежа. | \n|
| 7 | \nИспользуется, если платежная система не произвела выплату по транзакции из-за потенциального фрода. В этом случае мы рекомендуем добавить пользователя в черный список. | \n |
| 8 | \nИспользуется, когда платежная система запросила отмену транзакции. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 9 | \nИспользуется, если игра или заказ не удовлетворяют требованиям пользователя по каким-либо причинам. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 10 | \nИспользуется, когда игра просит отменить транзакцию. В этом случае мы не рекомендуем заносить пользователя в черный список. | \n |
| 11 | \nИспользуется, когда владелец аккаунта сообщил, что не совершал данный платеж. В этом случае мы рекомендуем добавить пользователя в черный список. | \n |
| 12 | \nИспользуется, когда законный держатель карты оспорил свою транзакцию. | \n|
| 13 | \nИспользуется, если произошла попытка повторной оплаты по счету. | \n|
| 21 | \nИспользуется, когда происходит массовая кража данных карт с одним или несколькими BIN. Особенность: всплеск попыток использования одинаковых BIN за короткий промежуток времени, зачастую с использованием последовательных номеров карт. | \n|
| 22 | \nИспользуется, когда товары, доступные для обмена, были куплены с помощью украденной карты с целью перепродажи. | \n|
| 23 | \nИспользуется, когда происходит кража данных карт с одним или несколькими BIN. Не такая масштабная и скоординированная, как атака по BIN (код отмены 21). | \n |
| 24 | \nИспользуется при злоупотреблении региональными ценами или перепродажей ключей. Пользователи воспользовались региональными ценами — зачастую через смену геолокации или подмену информации о способе оплаты — чтобы дешевле купить товары и перепродать их по более высоким ценам. | \n|
| 25 | \nИспользуется, когда происходит кража учетных данных и захват аккаунта. Относится к злоупотреблению учетной записью или интеграцией на стороне партнера или платежной системы, а не к использованию карты. | \n|
| 26 | \nИспользуется, когда фрод был подтвержден, но доказательств недостаточно, чтобы определить конкретный тип атаки. | \n|
| 27 | \nИспользуется, когда транзакция отсутствует в отчете платежной системы по фроду, но она связана с другими мошенническими транзакциями. Например, платежи по таким транзакциям могут быть сделаны с помощью одинакового номера карты или устройства и возвращены пользователям по причинам, связанным с фродом. | \n
| Инициатор возврата | \nЗначение поля | \n
|---|---|
| Игра (через API). | \nAPI | \n
| Account user (automatic refund). | \nEmail-адрес пользователя | \n
| Account user (with assistance from Xsolla customer support). | \nsupport@xsolla.com | \n
| Xsolla (при участии службы поддержки Xsolla). | \nsupport@xsolla.com | \n
order_paid на указанный URL-адрес, когда \nпользователь успешно оплатил заказ.\n\nВ вебхуке order_paid содержится информация о купленных товарах, \nданные платежа и детали транзакции.\n\nВебхук order_paid не отправляется, если оплата неуспешна, например:\n* форма оплаты была открыта, но пользователь не оплатил заказ;\n* форма оплаты была открыта, но при оплате возникли ошибки.\n\nРекомендуется обеспечить время обработки вебхука order_paid менее \n3 секунд.\n\nNotice
\nThe set of fields sent in a webhook depends on the following settings:
If you have any questions, contact your Customer Success Manager or email to csm@xsolla.com.
\n| Код ответа | \nАвтоматический возврат платежа не включен (по умолчанию) | \nАвтоматический возврат платежа включен | \n
|---|---|---|
400, 401, 402, 403, 404, 409, 422, 415 | \n Нет действий | \nАвтоматический возврат средств пользователю. | \n
200, 201, 204 | \n Нет действий | \nНет действий | \n
| Другой код или отсутствие ответа на вебхук | \nМногократная отправка вебхуков через заданный временной промежуток: 2 попытки с шагом 5 минут, 7 попыток с шагом 15 минут, 10 попыток с шагом 60 минут. | \nМногократная отправка вебхуков через заданный временной промежуток: 2 попытки с шагом 5 минут, 7 попыток с шагом 15 минут, 10 попыток с шагом 60 минут. Если все вебхуки отправлены, а успешный ответ не получен, осуществляется автоматический возврат средств пользователю. | \n
order_paid на указанный URL-адрес, когда \nвыполнены условия:\n1. Пользователь успешно оплатил заказ.\n2. Xsolla получила ответ об успешной обработке вебхука \n [payment](/ru/webhooks/operation/payment/).\n\nВ вебхуке order_paid содержится информация о купленных товарах и \nдетали транзакции.\n\nВебхук order_paid не отправляется, если:\n* Оплата не была успешной, например:\n * форма оплаты была открыта, но пользователь не оплатил заказ;\n * форма оплаты была открыта, но при оплате возникли ошибки.\n* Ответ об успешной обработке вебхука [payment](/ru/webhooks/operation/payment/) не \n получен.\n\nРекомендуется обеспечить время обработки вебхука order_paid менее \n3 секунд.\n\nОжидаемые коды ответов описаны в разделе Responses. Вы можете \nиспользовать другие коды ответов. В зависимости от кода ответа и подключения \nфункциональности автоматического возврата платежа логика обработки вебхука на \nстороне Xsolla следующая:\n\n| Код ответа | \nАвтоматический возврат платежа не включен (по умолчанию) | \nАвтоматический возврат платежа включен | \n
|---|---|---|
400, 401, 402, 403, 404, 409, 422, 415 | \n Нет действий | \nАвтоматический возврат средств пользователю. | \n
200, 201, 204 | \n Нет действий | \nНет действий | \n
| Другой код или отсутствие ответа на вебхук | \nМногократная отправка вебхуков через заданный временной промежуток: 2 попытки с шагом 5 минут, 7 попыток с шагом 15 минут, 10 попыток с шагом 60 минут. | \nМногократная отправка вебхуков через заданный временной промежуток: 2 попытки с шагом 5 минут, 7 попыток с шагом 15 минут, 10 попыток с шагом 60 минут. Если все вебхуки отправлены, а успешный ответ не получен, осуществляется автоматический возврат средств пользователю. | \n
Note
\nIf you registered in Publisher Account on or before January 22, 2025, you can find the toggles in the Settings > Webhooks > Testing > Payments > Advanced settings section.
\n| Переключатель | \nОписание | \n
|---|---|
| Показывать только необходимую информацию о пользователе без чувствительных данных | \nВ вебхуке о пользователе будет передаваться только следующая информация:
| \n
| Передавать кастомные параметры | \nВ вебхуке будет передаваться информация о кастомных параметрах из токена. | \n
custom_parameters в методе получения платежного токена.