Xsolla-logoXsolla Developers
или
Личный кабинет

Возврат платежаWebhook POST

При отмене платежа Xsolla отправляет детали отмененной транзакции в вебхуке с типом refund на URL-адрес вебхука. Подробная информация о процессе возврата платежа приведена в инструкции.

Если получен ответ с кодом 5xx, Xsolla отправляет вебхук повторно с увеличенным интервалом, пока ваш обработчик не подтвердит их получение. Максимальное количество попыток — 12.

Внимание

Если возврат платежа был инициирован Xsolla и в ответе на вебхук пришел ответ с кодом 5xx, платеж все равно будет возвращен.

When you save the webhook URL in Publisher Account, you can give permissions to receive detailed information in webhooks. To do that, set the following toggle to active in Publisher Account in the Project settings > Webhooks > Advanced settings section.

Note

If 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.

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

В вебхуке будет передаваться информация в кастомных параметрах:

  • saved_payment_method:
    • 0 — сохраненный способ оплаты не используется;
    • 1 — способ оплаты был сохранен при совершении текущей транзакции;
    • 2 — используется ранее сохраненный способ оплаты.
  • payment_type:
    • 1 — единоразовый платеж;
    • 2 — рекуррентный платеж.

Коды отмены:

Код Причина отмены Описание
1 Cancellation by the user request / the game request Используется, если отмена произошла из Личного кабинета.
2 Chargeback Используется, если по транзакции был chargeback.
3 Integration error Используется в случае проблем с интеграцией между Xsolla и игрой.
В этом случае мы не рекомендуем заносить пользователя в черный список.
4 Potential fraud Используется в случае потенциального фрода.
В этом случае мы рекомендуем добавить пользователя в черный список.
5 Test payment Используется в случае совершения тестового платежа с последующей отменой.
В этом случае мы не рекомендуем заносить пользователя в черный список.
6 User invoice expired Используется, если был выбран способ оплаты с системой отложенного платежа.
7 Fraud notification from PS Используется, если платежная система не произвела выплату по транзакции из-за потенциального фрода.
В этом случае мы рекомендуем добавить пользователя в черный список.
8 Cancellation by the PS request Используется, когда платежная система запросила отмену транзакции.
В этом случае мы не рекомендуем заносить пользователя в черный список.
9 Cancellation by the user request Используется, если игра или заказ не удовлетворяют требованиям пользователя по каким-либо причинам.
В этом случае мы не рекомендуем заносить пользователя в черный список.
10 Cancellation by the game request Используется, когда игра просит отменить транзакцию.
В этом случае мы не рекомендуем заносить пользователя в черный список.
11 Account holder called to report fraud Используется, когда владелец аккаунта сообщил, что не совершал данный платеж.
12 Friendly fraud Используется, если нам сообщили о friendly fraud.
13 Duplicate Используется, если произошла попытка повторной оплаты по счету.
Request
Request Body schema: application/json
notification_type
required
string

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

required
object

Объект с информацией о транзакции, связанной с этой операцией.

agreement
integer

ID соглашения.

dry_run
integer

Признак тестовой транзакции. Значение параметра равно 1 для тестового платежа, для реального платежа параметр не передается.

external_id
string

Внешний ID транзакции.

id
integer

ID транзакции.

payment_method_order_id
string

ID платежа в платежной системе.

required
object

Объект с финансовыми данными платежа.

object

Объект с данными о налоге с дохода, который удерживается с международных транзакций в некоторых странах.

amount
number <float>

Сумма.

currency
string

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

percent
number <float>

Ставка налога, %.

object

Налог, удерживаемый у источника выплаты.

amount
number <float>

Сумма.

currency
string

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

percent
number <float>

Процент налога, удерживаемого у источника выплаты.

object

Объект с данными о сумме, которую оплатил пользователь.

amount
number <float>

Сумма.

currency
string

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

object

Размер комиссии платежной системы.

amount
number <float>

Сумма.

currency
string

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

object

Объект с данными о сумме, которая была оплачена из платежной системы.

amount
number <float>

Сумма.

currency
string

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

object

Объект с данными о сумме выплаты.

amount
number <float>

Сумма.

currency
string

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

payout_currency_rate
string

Курс валюты платежа к валюте выплаты.

object

Объект с информацией о затратах на репатриацию, возлагаемых на Xsolla третьими сторонами.

amount
number <float>

Сумма.

currency
string

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

object

Размер налога (только для США и Канады).

amount
number <float>

Сумма.

currency
string

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

percent
number <float>

Процент налога.

object

Объект с данными о сумме вознаграждения каналов привлечения трафика (аффилированные сети и инфлюенсеры).

amount
number <float>

Сумма.

currency
string

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

percent
number <float>

Ставка вознаграждения за привлечение пользователей, %.

object

Размер VAT (только для Евросоюза).

amount
number <float>

Сумма.

currency
string

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

percent
number <float>

Процент VAT.

object

Объект с данными о сумме, которая была оплачена с Xsolla-баланса.

amount
number <float>

Сумма.

currency
string

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

object

Размер комиссии Xsolla.

amount
number <float>

Сумма.

currency
string

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

custom_parameters
object

Ваши дополнительные параметры.

object

Объект с информацией о заказе.

required
object

Объект с данными об общей стоимости покупки.

amount
number <float>

Общая сумма покупки.

currency
string

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

object

Объект с информацией о заказе.

amount
number <float>

Сумма заказа.

currency
string

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

object

Объект с данными о подписке.

amount
number <float>

Сумма покупки.

currency
string

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

date_create
string

Дата создания подписки. Дата и время согласно стандарту ISO 8601.

plan_id
string

ID плана (внешний id, если план был создан через API).

subscription_id
integer

ID подписки в базе данных Xsolla.

tags
Array of strings

Теги плана.

object

Объект с финансовыми данными рефанда.

author
string

Инициатор возврата платежа. Значение поля передается согласно таблице:

Инициатор возврата Значение поля
Игра (через API). API
Пользователь Личного кабинета (автоматический возврат). Email-адрес пользователя
Пользователь Личного кабинета (при участии службы поддержки Xsolla). support@xsolla.com
Xsolla (при участии службы поддержки Xsolla). support@xsolla.com
code
integer

ID кода.

reason
string

Причина отмены.

object

Объект, содержащий настройки проекта.

merchant_id
integer

ID продавца.

project_id
integer

ID проекта. Вы можете найти этот параметр в Личном кабинете рядом с названием проекта.

object

Объект с информацией о пользователе.

id
required
string

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

country
string

Страна пользователя. Используется двухбуквенное обозначение страны согласно стандарту ISO 3166-1 alpha-2.

email
string

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

ip
string

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

name
string

Имя пользователя.

phone
string

Номер телефона пользователя (в международном формате).

zip
string

Почтовый индекс.

Responses
204

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

400

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

500

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

Request samples 
curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
        "notification_type": "refund",
        "settings": {
          "project_id": 18404,
          "merchant_id": 2340
        },
        "purchase": {
            "subscription": {
                "plan_id": "b5dac9c8",
                "subscription_id": "10",
                "date_create": "2014-09-22T19:25:25+04:00",
                "currency": "USD",
                "amount": 9.99
            },
            "checkout": {
                "currency": "USD",
                "amount": 50
            },
            "total":{
                "currency": "USD",
                "amount": 200
            }
        },
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "John Smith",
            "country": "US"
        },
        "transaction": {
            "id": 1,
            "external_id": 1,
            "dry_run": 1,
            "agreement": 1
        },
        "refund_details": {
            "code": 4,
            "reason": "Potential fraud"
        },
        "payment_details": {
            "sales_tax": {
                "currency": "USD",
                "amount": 0
            },
            "direct_wht": {
                "currency": "USD",
                "amount": 0.70
            },
            "xsolla_fee": {
                "currency": "USD",
                "amount": "10"
            },
            "payout": {
                "currency": "USD",
                "amount": "200"
            },
            "payment_method_fee": {
                "currency": "USD",
                "amount": "20"
            },
            "payment": {
                "currency": "USD",
                "amount": "230"
            },
            "repatriation_commission": {
                "currency": "USD",
                "amount": 10
            }
        }
    }
}'
Response samples
application/json
{
  • "error": {
    }
}
Статус системыВсе сервисы работают

Do Not Sell My Personal Information

Политика конфиденциальностиПользовательское соглашение© 2006–2025 Xsolla Inc.