(digest[i]);\n }\n return hexStream.str();\n }\n static bool verifySignature(const std::string& jsonBody, const std::string& secretKey, const std::string& receivedSignature) {\n std::string computedSignature = computeSha1(jsonBody, secretKey);\n // Timing-safe comparison\n if (computedSignature.length() != receivedSignature.length()) {\n return false;\n }\n volatile unsigned char result = 0;\n for (size_t i = 0; i < computedSignature.length(); ++i) {\n result |= (computedSignature[i] ^ receivedSignature[i]);\n }\n return result == 0;\n }\n};\n```\n\n### Пример реализации генерации подписи для Go:\n\n```go\npackage main\nimport (\n\t\"crypto/sha1\"\n \"crypto/subtle\"\n\t\"encoding/hex\"\n\t\"strings\"\n)\ntype XsollaWebhookSignature struct{}\nfunc (x *XsollaWebhookSignature) ComputeSha1(jsonBody, secretKey string) string {\n\t// Concatenation of the JSON from the request body and the project's secret key\n\tdataToSign := jsonBody + secretKey\n\t// Create SHA1 hash\n\th := sha1.New()\n\th.Write([]byte(dataToSign))\n\tsignature := h.Sum(nil)\n\t// Convert to lowercase hexadecimal string\n\treturn strings.ToLower(hex.EncodeToString(signature))\n}\nfunc (x *XsollaWebhookSignature) VerifySignature(jsonBody, secretKey, receivedSignature string) bool {\n\tcomputedSignature := x.ComputeSha1(jsonBody, secretKey)\n\treceivedSignatureLower := strings.ToLower(receivedSignature)\n\t// Use constant time comparison to prevent timing attacks\n\treturn subtle.ConstantTimeCompare([]byte(computedSignature), []byte(receivedSignatureLower)) == 1\n}\n```\n\n### Пример реализации генерации подписи для PHP:\n\n```php\n\n```\n\n### Пример реализации генерации подписи для Node.js:\n\n```js\nconst crypto = require('crypto');\nclass XsollaWebhookSignature {\n // IMPORTANT: jsonBody must be the raw JSON string exactly as received from Xsolla\n static computeSha1(jsonBody, secretKey) {\n // Concatenation of the JSON from the request body and the project's secret key\n const dataToSign = jsonBody + secretKey;\n // Create SHA1 hash\n const hash = crypto.createHash('sha1');\n hash.update(dataToSign, 'utf8');\n // Convert to lowercase hexadecimal string\n return hash.digest('hex').toLowerCase();\n }\n static verifySignature(jsonBody, secretKey, receivedSignature) {\n const computedSignature = this.computeSha1(jsonBody, secretKey);\n const cleanReceivedSignature = receivedSignature.toLowerCase();\n // Check if signatures have the same length before using timingSafeEqual\n if (computedSignature.length !== cleanReceivedSignature.length) {\n return false;\n }\n try {\n return crypto.timingSafeEqual(\n Buffer.from(computedSignature, 'hex'),\n Buffer.from(cleanReceivedSignature, 'hex')\n );\n } catch (error) {\n // Return false if there's any error (e.g., invalid hex characters)\n return false;\n }\n }\n}\n```\n\n## Отправка ответов на вебхук\n\nЧтобы подтвердить получение вебхука, ваш сервер должен вернуть:\n* `200`, `201`, или `204` HTTP-код в случае успешного ответа.\n* `400` HTTP-код с описанием \n проблемы, если указанный пользователь не был найден или если передана \n недействительная подпись. Ваш обработчик вебхуков также может возвращать `5xx` \n HTTP-код при временных проблемах на вашем сервере.\n\nЕсли на вебхуки Успешная \nоплата заказа и Отмена \nзаказа сервер Xsolla не получил ответ или получил ответ с кодом `5xx`, \nосуществляется повторная отправка вебхуков по следующему расписанию:\n* 2 попытки с интервалом 5 минут;\n* 7 попыток с интервалом 15 минут;\n* 10 попыток с интервалом 60 минут.\n\nМаксимально осуществляется 20 попыток отправки вебхуков в течение 12 часов с \nмомента первой попытки.\n\nЛогика повторной отправки вебхуков Успешный платеж и Возврат платежа описана на странице \nсоответствующего вебхука.\n\n\n
Внимание
\n
При одновременном выполнении следующих условий платеж все равно будет возвращен пользователю:
- Инициатор возврата — Xsolla.
- На вебхук получен ответ с кодом
4xx, или после всех повторных попыток ответ не был получен, или был получен код 5xx.
\n
\n\n \n | Код | \n Описание | \n
\n\n\n \n | INVALID_USER | \n Неверный пользователь | \n
\n \n | INVALID_PARAMETER | \n Неверный параметр | \n
\n \n | INVALID_SIGNATURE | \n Подпись неверна | \n
\n \n | INCORRECT_AMOUNT | \n Некорректная сумма | \n
\n \n | INCORRECT_INVOICE | \n Неверный заказ | \n
\n\n
\n\n```\nHTTP/1.1 400 Bad Request\n{\n \"error\":{\n \"code\":\"INVALID_USER\",\n \"message\":\"Invalid user\"\n }\n}\n```\n\n# Лучшие практики\n\n## Безопасность\n\nСоблюдайте следующие рекомендации:\n\n* Используйте только протокол HTTPS с действительным сертификатом.\n* При проверке подписи всегда используйте тело запроса в полученном виде — не \n парсите и не перекодируйте данные.\n* Не передавайте чувствительные данные в URL-адресах и не раскрывайте технические \n детали в сообщениях об ошибках.\n* Отключите проверку [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) для URL-адреса вебхука — входящие запросы от Xsolla не \n содержат токен CSRF и будут отклонены без этой настройки.\n* Добавьте [IP-адреса Xsolla](/ru/webhooks/section/webhook-listener) в белый список.\n\n\n## Архитектура обработчика вебхуков\n\nСоблюдайте следующие рекомендации:\n\n1. Принимайте `POST`-запрос с телом запроса и заголовками, **не изменяя их**.\n2. [Сгенерируйте подпись для проверки подлинности вебхука](/ru/webhooks/section/webhook-listener/generation-of-signature) и верните в ответе соответствующий \n статус:\n * `4xx` — при несовпадении подписей.\n * `2xx` — в случае успешного ответа. Мы рекомендуем вернуть `204 No Content` до \n выполнения основной бизнес-логики. `200 OK` также допустим.\n3. Передайте тело ответа (payload) в асинхронную задачу или очередь для дальнейшей \n обработки.\n4. Обеспечьте \n [идемпотентность](https://en.wikipedia.org/wiki/Idempotence#Computer_science_meaning). Ваша система должна быть готова к [повторному получению \n вебхуков](/ru/webhooks/section/webhook-listener/sending-responses-to-webhook).\n\n**Пример сценария:**\n\n```http\nHTTP POST /webhooks/xsolla\n read raw_body, headers\n if !verify_signature(raw_body, headers['authorization']):\n return 400 {\"error\":{\"code\":\"INVALID_SIGNATURE\",\"message\":\"Invalid signature\"}}\n enqueue(raw_body)\n return 204 # or 200\n```\n\n## Идемпотентность и дубликаты\n\nСоблюдайте следующие рекомендации:\n\n* Используйте ID транзакции и/или [внешний ID](/ru/dev-resources/faq/payments/#faq_payments_q_new_transaction_external_id), ID заказа \n в качестве ключей идемпотентности.\n* Сохраняйте обработанные ID и возвращайте прежний результат при получении \n дубликата.\n* Исключите повторное начисление товаров, двойное списание средств и дублирование \n записей в базе данных.\n* Обратите внимание, что при последовательной доставке сбой на более раннем \n событии блокирует обработку последующих.\n\n## Стабильность системы\n\nСоблюдайте следующие рекомендации:\n\n* Для выполнения ресурсозатратных задач (таких как обращение к внешним сервисам, \n биллинг или начисление товаров) используйте очереди и асинхронный подход.\n* Установите интервалы для обработчика вебхука (1–3 с). При временных сбоях \n полагайтесь на [механизм повторной отправки Xsolla](/ru/webhooks/section/webhook-listener/sending-responses-to-webhook).\n* Не используйте обработчик для повторной отправки вебхуков — это выполняется на \n стороне Xsolla.\n* Логируйте время отправки вебхуков и статусы их обработки, настройте оповещения \n при резком росте ошибок `5xx` и повторных попыток.\n* Передавайте ID корреляции из вебхука в логи и систему мониторинга (APM).\n* Настройте логирование и мониторинг ошибок. В случае неустранимых ошибок \n перемещайте задачи в очередь недоставленных сообщений (dead-letter queue, DLQ). \n Реализуйте инструмент безопасного воспроизведения событий, защищенный \n механизмом идемпотентности.\n\n## Примеры реализации\n\n**Успешная покупка — начисление выполнено один раз:**\n\n\n\n**Повторная отправка (таймаут на стороне партнера):**\n\n\n\n**Возврат платежа:**\n\n\n\n**Недоступность сервера партнера:**\n\n\n\n# Частые вопросы\n\n## Необходимо ли для вебхуков использовать HTTPS?\n\nДа.\n\n## Могу ли я получать платежные вебхуки на несколько URL-адресов?\n\nНет. Платежные вебхуки работают по протоколу Server-to-Server и отправляются на \nодин URL-адрес, указанный в [настройках проекта](/ru/webhooks/section/set-up-webhooks-in-publisher-account). Если вы хотите получать оповещения в вашей \nигре, на сайте или мобильном приложении, реализуйте отправку вебхуков на \nсобственном сервере, чтобы пересылать данные между Xsolla и игрой. Вы также \nможете протестировать работу вебхуков из консоли разработчика.\n\n\n
Примечание
\n
Если вы тестируете интеграцию локально, `POST`-запросы от Xsolla не доходят до URL-адресов вида http://localhost:3000/my-webhook-endpoint. Используется такие сервисы как ngrok, которые позволяют создать туннель для внешнего доступа, благодаря чему вы сможете локально получать запросы от Xsolla. Подробнее вы можете прочитать, например, в документации ngrok.
\n
\n
Примечание
\n
Тип оповещения передается в параметре notification_type.
\n
\n\n \n | Переключатель | \n Описание | \n
\n\n\n \n | Показывать информацию о транзакциях сохраненными способами оплаты | \n В вебхуке будет передаваться информация в кастомных параметрах: saved_payment_method:0 — сохраненный способ оплаты не используется;1 — способ оплаты был сохранен при совершении текущей транзакции;2 — используется ранее сохраненный способ оплаты.
payment_type:1 — единоразовый платеж;2 — рекуррентный платеж.
| \n
\n\n
\n",
"operationId": "afs-rejected-transaction",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"refund_details": {
"description": "Объект с финансовыми данными рефанда.",
"properties": {
"author": {
"description": "Инициатор возврата платежа. Значение поля передается согласно таблице:\n\n\n \n \n | Инициатор возврата | \n Значение поля | \n
\n \n \n \n | Игра (через API). | \n API | \n
\n \n | Пользователь Личного кабинета (автоматический возврат). | \n Email-адрес пользователя | \n
\n \n | Пользователь Личного кабинета (при участии службы поддержки Xsolla). | \n support@xsolla.com | \n
\n \n | Xsolla (при участии службы поддержки Xsolla). | \n support@xsolla.com | \n
\n \n
\n",
"type": "string"
},
"code": {
"description": "ID кода.\n\n\n \n \n | Код | \n Причина отмены | \n Описание | \n
\n \n \n \n | 1 | \n Cancellation by the user request / the game request | \n Используется, если отмена произошла из Личного кабинета. | \n
\n \n | 2 | \n Chargeback | \n Используется, если по транзакции был chargeback. | \n
\n \n | 3 | \n Integration error | \n Используется в случае проблем с интеграцией между Xsolla и игрой.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 4 | \n Potential fraud | \n Используется в случае потенциального фрода.
В этом случае мы рекомендуем добавить пользователя в черный список. | \n
\n \n | 5 | \n Test payment | \n Используется в случае совершения тестового платежа с последующей отменой.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 6 | \n User invoice expired | \n Используется, если был выбран способ оплаты с системой отложенного платежа. | \n
\n \n | 7 | \n Fraud notification from PS | \n Используется, если платежная система не произвела выплату по транзакции из-за потенциального фрода.
В этом случае мы рекомендуем добавить пользователя в черный список. | \n
\n \n | 8 | \n Cancellation by the PS request | \n Используется, когда платежная система запросила отмену транзакции.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 9 | \n Cancellation by the user request | \n Используется, если игра или заказ не удовлетворяют требованиям пользователя по каким-либо причинам.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 10 | \n Cancellation by the game request | \n Используется, когда игра просит отменить транзакцию.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 11 | \n Account holder called to report fraud | \n Используется, когда владелец аккаунта сообщил, что не совершал данный платеж. | \n
\n \n | 12 | \n Friendly fraud | \n Используется, если нам сообщили о friendly fraud. | \n
\n \n | 13 | \n Duplicate | \n Используется, если произошла попытка повторной оплаты по счету. | \n
\n \n
\n",
"type": "integer"
},
"reason": {
"description": "Причина отмены.",
"type": "string"
}
},
"type": "object"
},
"settings": {
"description": "Объект, содержащий настройки проекта.",
"properties": {
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
},
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
}
},
"type": "object"
},
"transaction": {
"description": "Объект с информацией о транзакции, связанной с этой операцией.",
"properties": {
"agreement": {
"description": "ID соглашения.",
"type": "integer"
},
"dry_run": {
"description": "Признак тестовой транзакции. Значение параметра равно 1 для тестового платежа, для реального платежа параметр не передается.",
"type": "integer"
},
"external_id": {
"description": "Внешний ID транзакции.",
"type": "string"
},
"id": {
"description": "ID транзакции.",
"format": "int64",
"type": "integer"
}
},
"type": "object"
},
"user": {
"description": "Объект с информацией о пользователе.",
"properties": {
"country": {
"$ref": "#/components/schemas/user.country"
},
"email": {
"$ref": "#/components/schemas/user.email"
},
"id": {
"$ref": "#/components/schemas/user.id"
},
"ip": {
"$ref": "#/components/schemas/user.ip"
},
"name": {
"$ref": "#/components/schemas/user.name"
},
"phone": {
"description": "Номер телефона пользователя (в международном формате).",
"type": "string"
},
"zip": {
"$ref": "#/components/schemas/user.zip"
}
},
"required": [
"id"
],
"type": "object"
}
},
"required": [
"notification_type",
"transaction"
]
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"summary": "Транзакция отклонена при проверке системой Anti-fraud",
"tags": [
"anti-fraud"
],
"x-codeSamples": [
{
"label": "CURL",
"lang": "cURL",
"source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-d '{\n \"notification_type\": \"afs_reject\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"ip\": \"127.0.0.1\",\n \"phone\": \"18777976552\",\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"name\": \"John Smith\",\n \"country\": \"US\"\n },\n \"transaction\": {\n \"id\": 1,\n \"external_id\": 1,\n \"dry_run\": 1,\n \"agreement\": 1\n },\n \"refund_details\": {\n \"code\": 4,\n \"reason\": \"Potential fraud\"\n }\n}'"
},
{
"label": "PHP",
"lang": "PHP",
"source": " 'afs_reject',\n 'settings' => array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'user' => array(\n 'ip' => '127.0.0.1',\n 'phone' => '18777976552',\n 'email' => 'email@example.com',\n 'id' => '1234567',\n 'country' => 'US'\n ),\n 'transaction' => array(\n 'id' => 87654321,\n 'payment_method' => 1380,\n 'dry_run' => 1\n ),\n 'refund_details' => array(\n 'code' => 4,\n 'reason' => 'Potential fraud'\n )\n);"
},
{
"label": "HTTP",
"lang": "HTTP",
"source": "POST /your_uri HTTP/1.1\nhost: your.host\naccept: application/json\ncontent-type: application/json\ncontent-length: 1220\nauthorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7\n\n{\n \"notification_type\": \"afs_reject\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"ip\": \"127.0.0.1\",\n \"phone\": \"18777976552\",\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"name\": \"John Smith\",\n \"country\": \"US\"\n },\n \"transaction\": {\n \"id\": 1,\n \"external_id\": 1,\n \"dry_run\": 1,\n \"agreement\": 1\n },\n \"refund_details\": {\n \"code\": 4,\n \"reason\": \"Potential fraud\"\n }\n}"
}
]
}
},
"canceled-subscription": {
"post": {
"description": "Когда подписка отменяется по каким-либо причинам, Xsolla отправляет вебхук с типом `cancel_subscription` на URL-адрес вебхука.",
"operationId": "canceled-subscription",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"description": "Объект, содержащий настройки проекта.",
"properties": {
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
},
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
}
},
"type": "object"
},
"subscription": {
"description": "Объект с данными о подписке.",
"properties": {
"date_create": {
"$ref": "#/components/schemas/subscription.date_create"
},
"date_end": {
"$ref": "#/components/schemas/subscription.date_end"
},
"plan_id": {
"$ref": "#/components/schemas/subscription.plan_id"
},
"product_id": {
"$ref": "#/components/schemas/subscription.product_id"
},
"subscription_id": {
"$ref": "#/components/schemas/subscription.subscription_id"
},
"tags": {
"$ref": "#/components/schemas/subscription.tags"
}
},
"type": "object"
},
"user": {
"description": "Объект с информацией о пользователе.",
"properties": {
"id": {
"$ref": "#/components/schemas/user.id"
},
"name": {
"$ref": "#/components/schemas/user.name"
}
},
"required": [
"id"
],
"type": "object"
}
},
"required": [
"notification_type"
]
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"summary": "Отмена подписки",
"tags": [
"subscriptions"
],
"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 13342703ccaca5064ad33ba451d800c5e823db8f' \\\n-d '{\n \"notification_type\": \"cancel_subscription\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"id\": \"1234567\",\n \"name\": \"John Smith\"\n },\n \"subscription\": {\n \"plan_id\": \"b5dac9c8\",\n \"subscription_id\": \"10\",\n \"product_id\": \"Demo Product\",\n \"date_create\": \"2014-09-22T19:25:25+04:00\",\n \"date_end\": \"2015-01-22T19:25:25+04:00\"\n }\n }'"
},
{
"label": "PHP",
"lang": "PHP",
"source": " 'cancel_subscription',\n 'settings' => array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'user' => array(\n 'id' => '1234567',\n 'name' => 'John Smith'\n ),\n 'subscription' => array(\n 'plan_id' => 'b5dac9c8',\n 'subscription_id' => '10',\n 'product_id' => 'Demo Product',\n 'date_create' => '2014-09-22T19:25:25+04:00',\n 'date_end' => '2015-01-22T19:25:25+04:00',\n )\n);"
},
{
"label": "HTTP",
"lang": "HTTP",
"source": "POST /your/uri HTTP/1.1\nhost: your.hostname\naccept: application/json\ncontent-type: application/json\ncontent-length: 240\nauthorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f\n\n{\n \"notification_type\": \"cancel_subscription\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\":{\n \"id\": \"1234567\",\n \"name\": \"John Smith\"\n },\n \"subscription\": {\n \"plan_id\": \"b5dac9c8\",\n \"subscription_id\": \"10\",\n \"product_id\": \"Demo Product\",\n \"date_create\": \"2014-09-22T19:25:25+04:00\",\n \"date_end\": \"2015-01-22T19:25:25+04:00\"\n }\n}"
}
]
}
},
"created-subscription": {
"post": {
"description": "Когда пользователь создает подписку, Xsolla отправляет вебхук с типом `create_subscription` на URL-адрес вебхука.",
"operationId": "created-subscription",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"custom_parameters": {
"description": "Ваши дополнительные параметры.",
"type": "object"
},
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"description": "Объект, содержащий настройки проекта.",
"properties": {
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
},
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
}
},
"type": "object"
},
"subscription": {
"description": "Объект с данными о подписке.",
"properties": {
"date_create": {
"$ref": "#/components/schemas/subscription.date_create"
},
"date_next_charge": {
"$ref": "#/components/schemas/subscription.date_next_charge"
},
"is_gift": {
"$ref": "#/components/schemas/subscription.is_gift"
},
"plan_id": {
"$ref": "#/components/schemas/subscription.plan_id"
},
"product_id": {
"$ref": "#/components/schemas/subscription.product_id"
},
"subscription_id": {
"$ref": "#/components/schemas/subscription.subscription_id"
},
"tags": {
"$ref": "#/components/schemas/subscription.tags"
},
"trial": {
"description": "Объект с информацией о триальном периоде подписки.",
"properties": {
"type": {
"description": "Тип триального периода: day.",
"type": "string"
},
"value": {
"description": "Длительность триального периода.",
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
},
"user": {
"description": "Объект с информацией о пользователе.",
"properties": {
"id": {
"$ref": "#/components/schemas/user.id"
},
"name": {
"$ref": "#/components/schemas/user.name"
}
},
"required": [
"id"
],
"type": "object"
}
},
"required": [
"notification_type"
]
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"summary": "Создание подписки",
"tags": [
"subscriptions"
],
"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 13342703ccaca5064ad33ba451d800c5e823db8f' \\\n-d '{\n \"notification_type\": \"create_subscription\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"id\": \"1234567\",\n \"name\": \"John Smith\"\n },\n \"subscription\": {\n \"plan_id\": \"b5dac9c8\",\n \"subscription_id\": \"10\",\n \"product_id\": \"Demo Product\",\n \"date_create\": \"2014-09-22T19:25:25+04:00\",\n \"date_next_charge\": \"2015-01-22T19:25:25+04:00\",\n \"trial\": {\n \"value\": 90,\n \"type\": \"day\"\n },\n \"is_gift\": true\n }\n }'"
},
{
"label": "PHP",
"lang": "PHP",
"source": " 'create_subscription',\n 'settings' => array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'user' => array(\n 'id' => '1234567',\n 'name' => 'John Smith'\n ),\n 'subscription' => array(\n 'plan_id' => 'b5dac9c8',\n 'subscription_id' => '10',\n 'product_id' => 'Demo Product',\n 'date_create' => '2014-09-22T19:25:25+04:00',\n 'date_next_charge' => '2015-01-22T19:25:25+04:00',\n 'trial' => array(\n 'value' => 90,\n 'type' => 'day'\n ),\n 'is_gift' => true,\n )\n);"
},
{
"label": "HTTP",
"lang": "HTTP",
"source": "POST /your/uri HTTP/1.1\nHost: your.hostname\naccept: application/json\ncontent-type: application/json\ncontent-length: 240\nauthorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f\n\n{\n \"notification_type\": \"create_subscription\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"id\": \"1234567\",\n \"name\": \"John Smith\"\n },\n \"subscription\": {\n \"plan_id\": \"b5dac9c8\",\n \"subscription_id\": \"10\",\n \"product_id\": \"Demo Product\",\n \"date_create\": \"2014-09-22T19:25:25+04:00\",\n \"date_next_charge\": \"2015-01-22T19:25:25+04:00\",\n \"trial\": {\n \"value\": 90,\n \"type\": \"day\"\n },\n \"is_gift\": true\n }\n}"
}
]
}
},
"dispute": {
"post": {
"description": "При открытии нового диспута или изменении статуса диспута Xsolla отправляет вебхук с типом `dispute` на URL-адрес вебхука. Чтобы получать вебхук, обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.",
"operationId": "dispute",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"action": {
"description": "Тип действия.",
"enum": [
"adding",
"updating"
],
"type": "string",
"x-enumDescriptions": {
"adding": "Открытие нового диспута.",
"updating": "Изменение статуса диспута."
}
},
"dispute": {
"description": "Объект с информацией о диспуте.",
"properties": {
"incoming_date": {
"$ref": "#/components/schemas/dispute-date"
},
"reason": {
"$ref": "#/components/schemas/dispute-reason"
},
"status": {
"$ref": "#/components/schemas/dispute-status"
},
"type": {
"$ref": "#/components/schemas/dispute-type"
}
},
"required": [
"incoming_date",
"reason",
"type",
"status"
],
"type": "object"
},
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"description": "Объект с информацией о кастомных настройках проекта.",
"properties": {
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
},
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
}
},
"required": [
"project_id",
"merchant_id"
],
"type": "object"
},
"transaction": {
"description": "Объект с информацией о транзакции.",
"properties": {
"country_code": {
"$ref": "#/components/schemas/user.country"
},
"date_create": {
"$ref": "#/components/schemas/date-create"
},
"external_id": {
"$ref": "#/components/schemas/external-id"
},
"id": {
"$ref": "#/components/schemas/transaction-id"
},
"payment_method": {
"$ref": "#/components/schemas/dispute-payment-method"
},
"total": {
"description": "Объект с информацией о сумме транзакции.",
"properties": {
"amount": {
"$ref": "#/components/schemas/transaction-total-amount"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"required": [
"amount",
"currency"
],
"type": "object"
}
},
"required": [
"id",
"date_create",
"total",
"payment_method",
"country_code"
],
"type": "object"
},
"user": {
"description": "Объект с информацией о пользователе.",
"properties": {
"email": {
"$ref": "#/components/schemas/user.email"
},
"id": {
"$ref": "#/components/schemas/user.id"
}
},
"required": [
"id"
],
"type": "object"
}
},
"required": [
"notification_type",
"action",
"transaction",
"settings",
"user",
"dispute"
]
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"summary": "Диспут",
"tags": [
"anti-fraud"
],
"x-codeSamples": [
{
"label": "CURL",
"lang": "cURL",
"source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-H 'authorization: Signature 32c64a80d2527dc08906ae1891bac4489509b9f6' \\\n-d '{\n \"notification_type\": \"dispute\",\n \"action\": \"adding\",\n \"transaction\": {\n \"id\": 123456789,\n \"date_create\": \"2023-08-24T10:21:00+04:00\",\n \"total\": {\n \"amount\": 1,\n \"currency\": \"EUR\"\n },\n \"payment_method\": \"credit_debit_card\"\n },\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"id\": \"1234567\",\n \"email\": \"email@example.com\",\n \"country_code\": \"US\"\n },\n \"dispute\": {\n \"incoming_date\": \"2024-01-25T01:02:03+04:00\",\n \"reason\": \"not_as_described\",\n \"type\": \"retrieval\",\n \"status\": \"new\"\n }\n}'"
},
{
"label": "HTTP",
"lang": "HTTP",
"source": "POST /your_uri HTTP/1.1\nhost: your.host\naccept: application/json\ncontent-Type: application/json\ncontent-Length: 578\nauthorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7\n\n{\n \"notification_type\": \"dispute\",\n \"action\": \"adding\",\n \"transaction\": {\n \"id\": 123456789,\n \"date_create\": \"2023-08-24T10:21:00+04:00\",\n \"total\": {\n \"amount\": 1,\n \"currency\": \"EUR\"\n },\n \"payment_method\": \"credit_debit_card\"\n },\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"id\": \"1234567\",\n \"email\": \"email@example.com\",\n \"country_code\": \"US\"\n },\n \"dispute\": {\n \"incoming_date\": \"2024-01-25T01:02:03+04:00\",\n \"reason\": \"not_as_described\",\n \"type\": \"retrieval\",\n \"status\": \"new\"\n }\n}"
}
]
}
},
"nonrenewing-subscription": {
"post": {
"description": "Если статус подписки меняется на непродлеваемый, Xsolla отправляет вебхук с типом `non_renewal_subscription` на URL-адрес вебхука. Чтобы получать вебхук, обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.",
"operationId": "nonrenewing-subscription",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"description": "Объект, содержащий настройки проекта.",
"properties": {
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
},
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
}
},
"required": [
"project_id"
],
"type": "object"
},
"subscription": {
"description": "Объект с данными о подписке.",
"properties": {
"amount": {
"description": "Сумма покупки.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"date_create": {
"$ref": "#/components/schemas/subscription.date_create"
},
"date_next_charge": {
"description": "Дата следующего списания. Это дата следующего платежа, ожидаемого до того, как статус подписки пользователя был изменен на непродлеваемый. Дата и время согласно стандарту [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).",
"type": "string"
},
"plan_id": {
"$ref": "#/components/schemas/subscription.plan_id"
},
"subscription_id": {
"$ref": "#/components/schemas/subscription.subscription_id"
}
},
"type": "object"
},
"user": {
"description": "Объект с информацией о пользователе.",
"properties": {
"email": {
"$ref": "#/components/schemas/user.email"
},
"id": {
"$ref": "#/components/schemas/user.id"
},
"name": {
"$ref": "#/components/schemas/user.name"
}
},
"required": [
"id"
],
"type": "object"
}
},
"required": [
"notification_type"
]
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"summary": "Непродлеваемая подписка",
"tags": [
"subscriptions"
],
"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 13342703ccaca5064ad33ba451d800c5e823db8f' \\\n-d '{\n \"notification_type\": \"non_renewal_subscription\",\n \"settings\": {\n \"project_id\": 12345,\n \"merchant_id\": 1234\n },\n \"user\": {\n \"id\": \"1234567\",\n \"email\": \"email@example.com\"\n },\n \"subscription\": {\n \"plan_id\": \"a1bcd2e3\",\n \"subscription_id\": \"10\",\n \"date_create\": \"2014-12-22T15:25:25+04:00\",\n \"date_next_charge\": \"2015-01-22T19:25:25+04:00\",\n \"currency\": \"USD\",\n \"amount\": 0.03\n }\n }'"
},
{
"label": "PHP",
"lang": "PHP",
"source": " 'non_renewal_subscription',\n 'settings' => array(\n 'project_id' => 12345,\n 'merchant_id' => 1234\n ),\n 'user' => array(\n 'id' => '1234567',\n 'email' => 'email@example.com'\n ),\n 'subscription' => array(\n 'plan_id' => 'a1bcd2e3',\n 'subscription_id' => '10',\n 'date_create' => '2014-12-22T15:25:25+04:00',\n 'date_next_charge' => '2015-01-22T19:25:25+04:00',\n 'currency' => 'USD',\n 'amount' => 0.03\n )\n);"
},
{
"label": "HTTP",
"lang": "HTTP",
"source": "POST /your/uri HTTP/1.1\nhost: your.hostname\naccept: application/json\ncontent-type: application/json\ncontent-length: 240\nauthorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f\n\n{\n \"notification_type\": \"non_renewal_subscription\",\n \"settings\": {\n \"project_id\": 12345,\n \"merchant_id\": 1234\n },\n \"user\": {\n \"id\": \"1234567\",\n \"email\": \"email@example.com\"\n },\n \"subscription\": {\n \"plan_id\": \"a1bcd2e3\",\n \"subscription_id\": \"10\",\n \"date_create\": \"2014-12-22T15:25:25+04:00\",\n \"date_next_charge\": \"2015-01-22T19:25:25+04:00\",\n \"currency\": \"USD\",\n \"amount\": 0.03\n }\n}"
}
]
}
},
"order-cancellation": {
"post": {
"description": "Xsolla отправляет вебхук 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 \n | Инициатор возврата | \n Значение поля | \n
\n \n \n \n | Игра (через API). | \n API | \n
\n \n | Пользователь Личного кабинета (автоматический возврат). | \n Email-адрес пользователя | \n
\n \n | Пользователь Личного кабинета (при участии службы поддержки Xsolla). | \n support@xsolla.com | \n
\n \n | Xsolla (при участии службы поддержки Xsolla). | \n support@xsolla.com | \n
\n \n
\n",
"type": "string"
},
"code": {
"description": "ID кода.",
"type": "integer"
},
"reason": {
"description": "Причина отмены.",
"type": "string"
}
},
"type": "object"
},
"settings": {
"description": "Объект, содержащий настройки проекта.",
"properties": {
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
},
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
}
},
"type": "object"
},
"transaction": {
"description": "Объект с информацией о транзакции, связанной с этой операцией.",
"properties": {
"agreement": {
"description": "ID соглашения.",
"type": "integer"
},
"dry_run": {
"description": "Признак тестовой транзакции. Значение параметра равно 1 для тестового платежа, для реального платежа параметр не передается.",
"type": "integer"
},
"external_id": {
"description": "Внешний ID транзакции.",
"type": "string"
},
"id": {
"description": "ID транзакции.",
"format": "int64",
"type": "integer"
},
"payment_method_order_id": {
"description": "ID платежа в платежной системе.",
"type": "string"
}
},
"type": "object"
}
},
"required": [
"notification_type",
"transaction",
"payment_details"
],
"type": "object"
},
"custom_parameters": {
"description": "Дополнительная информация.",
"type": "object"
},
"items": {
"description": "Список предметов, которые купил пользователь.\n\nНабор передаваемых параметров в массиве зависит от версии вебхука. В версии 2 \nдополнительно передаются параметры `is_free`, `is_bonus` и `is_bundle_content`. \nДля переключения версии передайте ее номер в параметре `version` в методе \n[Обновление информации о настройках вебхуков](/ru/api/igs/operation/update-webhook/).\n",
"items": {
"oneOf": [
{
"properties": {
"amount": {
"description": "Общая стоимость товаров, рассчитанная c учетом их количества.",
"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": "Общая стоимость товаров, рассчитанная c учетом их количества.",
"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": {
"$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",
"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",
"transaction",
"payment_details"
]
}
}
}
},
"responses": {
"200": {
"description": "Верните, чтобы сообщить об успешной обработке вехбука."
},
"400": {
"description": "Верните в случае ошибки в предоставленной информации (например, обязательный параметр не передан, или авторизация не прошла)."
}
},
"summary": "Отмена заказа (с деталями платежа и транзакции)",
"tags": [
"combined-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 \"billing\": {\n \"notification_type\": \"refund\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"purchase\": {\n \"subscription\": {\n \"plan_id\": \"b5dac9c8\",\n \"subscription_id\": \"10\",\n \"date_create\": \"2014-09-22T19:25:25+04:00\",\n \"currency\": \"USD\",\n \"amount\": 9.99\n },\n \"total\":{\n \"currency\": \"USD\",\n \"amount\": 200\n }\n },\n \"transaction\": {\n \"id\": 1,\n \"external_id\": 1,\n \"dry_run\": 1,\n \"agreement\": 1\n },\n \"refund_details\": {\n \"code\": 4,\n \"reason\": \"Potential fraud\"\n },\n \"payment_details\": {\n \"sales_tax\": {\n \"currency\": \"USD\",\n \"amount\": 0\n },\n \"direct_wht\": {\n \"currency\": \"USD\",\n \"amount\": 0.70\n },\n \"xsolla_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"10\"\n },\n \"payout\": {\n \"currency\": \"USD\",\n \"amount\": \"200\"\n },\n \"payment_method_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"20\"\n },\n \"payment\": {\n \"currency\": \"USD\",\n \"amount\": \"230\"\n },\n \"repatriation_commission\": {\n \"currency\": \"USD\",\n \"amount\": 10\n }\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 \"billing\": {\n \"notification_type\": \"refund\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"purchase\": {\n \"subscription\": {\n \"plan_id\": \"b5dac9c8\",\n \"subscription_id\": \"10\",\n \"date_create\": \"2014-09-22T19:25:25+04:00\",\n \"currency\": \"USD\",\n \"amount\": 9.99\n },\n \"total\": {\n \"currency\": \"USD\",\n \"amount\": 200\n }\n },\n \"transaction\": {\n \"id\": 1,\n \"external_id\": 1,\n \"dry_run\": 1,\n \"agreement\": 1\n },\n \"refund_details\": {\n \"code\": 4,\n \"reason\": \"Potential fraud\"\n },\n \"payment_details\": {\n \"sales_tax\": {\n \"currency\": \"USD\",\n \"amount\": 0\n },\n \"direct_wht\": {\n \"currency\": \"USD\",\n \"amount\": 0.70\n },\n \"xsolla_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"10\"\n },\n \"payout\": {\n \"currency\": \"USD\",\n \"amount\": \"200\"\n },\n \"payment_method_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"20\"\n },\n \"payment\": {\n \"currency\": \"USD\",\n \"amount\": \"230\"\n },\n \"repatriation_commission\": {\n \"currency\": \"USD\",\n \"amount\": 10\n }\n }\n }\n }"
}
]
}
},
"order-cancellation-separate": {
"post": {
"description": "Xsolla отправляет вебхук 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/igs/operation/update-webhook/).\n",
"items": {
"oneOf": [
{
"properties": {
"amount": {
"description": "Общая стоимость товаров, рассчитанная c учетом их количества.",
"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": "Общая стоимость товаров, рассчитанная c учетом их количества.",
"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\nПосле сохранения URL-адреса вебхука в Личном кабинете вы можете настроить \nполучение дополнительной информации в вебхуке. Для этого в разделе Настройки \nпроекта > Вебхуки > Расширенные настройки установите следующий \nпереключатель в активное положение.\n\n\n\n\n\n \n | Переключатель | \n Описание | \n
\n\n\n \n | Показывать информацию о транзакциях сохраненными способами оплаты | \n В вебхуке будет передаваться информация в кастомных параметрах: saved_payment_method:0 — сохраненный способ оплаты не используется;1 — способ оплаты был сохранен при совершении текущей транзакции;2 — используется ранее сохраненный способ оплаты.
payment_type:1 — единоразовый платеж;2 — рекуррентный платеж.
| \n
\n\n
\n\nКоды отмены:\n\n\n \n \n | Код | \n Причина отмены | \n Описание | \n
\n \n \n \n | 1 | \n Cancellation by the user request / the game request | \n Используется, если отмена произошла из Личного кабинета. | \n
\n \n | 3 | \n Integration error | \n Используется в случае проблем с интеграцией между Xsolla и игрой.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 5 | \n Test payment | \n Используется в случае совершения тестового платежа с последующей отменой.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 7 | \n Fraud notification from PS | \n Используется, если платежная система не произвела выплату по транзакции из-за потенциального фрода.
В этом случае мы рекомендуем добавить пользователя в черный список. | \n
\n \n | 9 | \n Cancellation by the user request | \n Используется, если игра или заказ не удовлетворяют требованиям пользователя по каким-либо причинам.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 10 | \n Cancellation by the game request | \n Используется, когда игра просит отменить транзакцию.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n
\n",
"operationId": "partial-refund",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"custom_parameters": {
"description": "Ваши дополнительные параметры.",
"type": "object"
},
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"payment_details": {
"description": "Объект с финансовыми данными платежа.",
"properties": {
"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"
},
"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": {
"checkout": {
"description": "Объект с информацией о заказе.",
"properties": {
"amount": {
"description": "Сумма заказа.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"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 \n | Инициатор возврата | \n Значение поля | \n
\n \n \n \n | Игра (через API). | \n API | \n
\n \n | Пользователь Личного кабинета (автоматический возврат). | \n Email-адрес пользователя | \n
\n \n | Пользователь Личного кабинета (при участии службы поддержки Xsolla). | \n support@xsolla.com | \n
\n \n | Xsolla (при участии службы поддержки Xsolla). | \n support@xsolla.com | \n
\n \n
\n",
"type": "string"
},
"code": {
"description": "ID кода.",
"type": "integer"
},
"date": {
"description": "Дата возврата платежа.",
"type": "string"
},
"reason": {
"description": "Причина отмены.",
"type": "string"
}
},
"type": "object"
},
"settings": {
"description": "Объект, содержащий настройки проекта.",
"properties": {
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
},
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
}
},
"type": "object"
},
"transaction": {
"description": "Объект с информацией о транзакции, связанной с этой операцией.",
"properties": {
"agreement": {
"description": "ID соглашения.",
"type": "integer"
},
"date": {
"description": "Дата транзакции.",
"type": "string"
},
"dry_run": {
"description": "Признак тестовой транзакции. Значение параметра равно 1 для тестового платежа, для реального платежа параметр не передается.",
"type": "integer"
},
"external_id": {
"description": "Внешний ID транзакции.",
"type": "string"
},
"id": {
"description": "ID транзакции.",
"format": "int64",
"type": "integer"
}
},
"type": "object"
},
"user": {
"description": "Объект с информацией о пользователе.",
"properties": {
"country": {
"$ref": "#/components/schemas/user.country"
},
"email": {
"$ref": "#/components/schemas/user.email"
},
"id": {
"$ref": "#/components/schemas/user.id"
},
"ip": {
"$ref": "#/components/schemas/user.ip"
},
"name": {
"$ref": "#/components/schemas/user.name"
},
"phone": {
"$ref": "#/components/schemas/user.phone"
},
"zip": {
"$ref": "#/components/schemas/user.zip"
}
},
"required": [
"id"
],
"type": "object"
}
},
"required": [
"notification_type",
"transaction",
"payment_details"
]
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"summary": "Частичный возврат платежа",
"tags": [
"payments"
],
"x-codeSamples": [
{
"label": "CURL",
"lang": "cURL",
"source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-d '{\n \"notification_type\": \"partial_refund\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"purchase\": {\n \"checkout\": {\n \"currency\": \"USD\",\n \"amount\": 50\n },\n \"total\":{\n \"currency\": \"USD\",\n \"amount\": 200\n }\n },\n \"user\": {\n \"ip\": \"127.0.0.1\",\n \"phone\": \"18777976552\",\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"name\": \"John Smith\",\n \"country\": \"US\"\n },\n \"transaction\": {\n \"id\": 1,\n \"external_id\": 1,\n \"dry_run\": 1,\n \"agreement\": 1,\n \"date\": \"2022-03-01 10:53:15\"\n },\n \"refund_details\": {\n \"author\": \"email@example.com\",\n \"date\": \"2022-03-01 10:56:48\"\n },\n \"payment_details\": {\n \"sales_tax\": {\n \"currency\": \"USD\",\n \"amount\": 0\n },\n \"direct_wht\": {\n \"currency\": \"USD\",\n \"amount\": 0.70\n },\n \"xsolla_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"10\"\n },\n \"payout\": {\n \"currency\": \"USD\",\n \"amount\": \"200\"\n },\n \"payment_method_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"20\"\n },\n \"payment\": {\n \"currency\": \"USD\",\n \"amount\": \"230\"\n },\n \"repatriation_commission\": {\n \"currency\": \"USD\",\n \"amount\": 10\n }\n }\n }\n}'"
},
{
"label": "PHP",
"lang": "PHP",
"source": " 'partial_refund',\n 'settings' => array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'purchase' => array(\n 'total' => array(\n 'currency' => 'USD',\n 'amount' => 9.99\n )\n ),\n 'user' => array(\n 'ip' => '127.0.0.1',\n 'phone' => '18777976552',\n 'email' => 'email@example.com',\n 'id' => '1234567',\n 'country' => 'US'\n ),\n 'transaction' => array(\n 'id' => 87654321,\n 'payment_date' => '2014-09-23T19:25:25+04:00',\n 'payment_method' => 1380,\n 'dry_run' => 1,\n 'date' => '2022-03-31 10:53:15'\n ),\n 'refund_details' => array(\n 'author' => 'email@example.com',\n 'date' => '2022-03-01 10:56:48'\n ),\n 'payment_details' => array(\n 'payment' => array(\n 'currency' => 'USD',\n 'amount' => 9.99\n ),\n 'vat' => array(\n 'currency' => 'USD',\n 'amount' => 0\n ),\n 'sales_tax' => array(\n 'currency' => 'USD',\n 'amount' => 0\n ),\n 'direct_wht' => array(\n 'currency' => 'USD',\n 'amount' => 70\n ),\n 'payout_currency_rate' => 1,\n 'payout' => array(\n 'currency' => 'USD',\n 'amount' => 9.49\n ),\n 'xsolla_fee' => array(\n 'currency' => 'USD',\n 'amount' => 0.19\n ),\n 'payment_method_fee' => array(\n 'currency' => 'USD',\n 'amount' => 0.31\n ),\n 'repatriation_commission' => array(\n 'currency' => 'USD',\n 'amount' => 0.2\n )\n )\n);"
},
{
"label": "HTTP",
"lang": "HTTP",
"source": "POST /your_uri HTTP/1.1\nhost: your.host\naccept: application/json\ncontent-type: application/json\ncontent-length: 1220\nauthorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7\n\n{\n \"notification_type\": \"partial_refund\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"purchase\": {\n \"checkout\": {\n \"currency\": \"USD\",\n \"amount\": 50\n },\n \"total\": {\n \"currency\": \"USD\",\n \"amount\": 200\n }\n },\n \"user\": {\n \"ip\": \"127.0.0.1\",\n \"phone\": \"18777976552\",\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"name\": \"John Smith\",\n \"country\": \"US\"\n },\n \"transaction\": {\n \"id\": 1,\n \"external_id\": 1,\n \"dry_run\": 1,\n \"agreement\": 1,\n \"date\": \"2022-03-31 10:53:15\"\n },\n \"refund_details\": {\n \"author\": \"email@example.com\",\n \"date\": \"2022-03-31 10:56:48\"\n },\n \"payment_details\": {\n \"sales_tax\": {\n \"currency\": \"USD\",\n \"amount\": 0\n },\n \"direct_wht\": {\n \"currency\": \"USD\",\n \"amount\": 0.70\n },\n \"xsolla_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"10\"\n },\n \"payout\": {\n \"currency\": \"USD\",\n \"amount\": \"200\"\n },\n \"payment_method_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"20\"\n },\n \"payment\": {\n \"currency\": \"USD\",\n \"amount\": \"230\"\n },\n \"repatriation_commission\": {\n \"currency\": \"USD\",\n \"amount\": 10\n }\n }\n}"
}
]
}
},
"payment": {
"post": {
"description": "Когда пользователь успешно совершает оплату, Xsolla отправляет детали платежа в \nвебхуке с типом `payment` на URL-адрес вебхука.\n\nОжидаемые коды ответов описаны в разделе Responses, но вы можете \nиспользовать и другие коды:\n\n\n \n \n | Код ответа | \n Описание | \n
\n \n \n \n 200, 201, 204 | \n Успешный ответ. | \n
\n \n 4xx | \n Возникновение ошибки. Например, если указанный пользователь не был найден или если передана недействительная подпись. | \n
\n \n 5xx | \n Временная ошибка на сервере. При получении этого ответа Xsolla отправляет вебхук повторно с увеличенным интервалом, пока ваш обработчик не подтвердит их получение. Максимальное количество попыток — 12 в течение 48 часов. | \n
\n \n
\n\nПосле сохранения URL-адреса вебхука в Личном \nкабинете вы можете настроить получение дополнительной информации в вебхуке.\n\n\n\n\n\n \n | Переключатель | \n Описание | \n
\n\n\n \n | Показывать информацию о сохраненном платежном аккаунте | \n Информация о сохраненном способе оплаты передается в кастомном объекте payment_account. | \n
\n \n | Показывать информацию о транзакциях сохраненными способами оплаты | \n В вебхуке будет передаваться информация в кастомных параметрах: saved_payment_method:0 — сохраненный способ оплаты не используется;1 — способ оплаты был сохранен при совершении текущей транзакции;2 — используется ранее сохраненный способ оплаты.
payment_type:1 — единоразовый платеж;2 — рекуррентный платеж.
| \n
\n \n | Добавить объект order в вебхук | \n В вебхуке Успешный платеж будет передаваться информация о заказе в объекте order. | \n
\n \n | Показывать только необходимую информацию о пользователе без чувствительных данных | \n В вебхуке о пользователе будет передаваться только следующая информация: | \n
\n \n | Показывать БИН карты и последние 4 цифры ее номера | \n В вебхуке будет передаваться следующая информация о номере карты: - первые 6 цифр в параметре
card_bin; - последние 4 цифры в параметре
card_suffix.
| \n
\n \n | Показывать бренд карты | \n Бренд карты, с которой была совершена оплата. Например, Mastercard или Visa. | \n
\n \n | Показать региональный налог у источника и стоимость каналов привлечения трафика. | \n В вебхуке будут передаваться объекты payment_details.country_wht и payment_details.user_acquisition_fee. По умолчанию этот переключатель активирован. | \n
\n \n | Отправлять информацию о 3DS. | \n В вебхуке будет передаваться объект cards с данными о прохождении пользователем проверки 3-D Secure. | \n
\n\n
\n\n\n
Внимание
\n
Набор полей, отправляемых в вебхуке, зависит:
- от расширенных настроек, которые вы установили в Личном кабинете;
- кастомных настроек, которые были заданы на стороне Xsolla.
При возникновении вопросов обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.
\n
\n
Примечание
\n
Чтобы получать вебхук ps_declined, обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.
\n
\n \n \n | Инициатор возврата | \n Значение поля | \n
\n \n \n \n | Игра (через API). | \n API | \n
\n \n | Пользователь Личного кабинета (автоматический возврат). | \n Email-адрес пользователя | \n
\n \n | Пользователь Личного кабинета (при участии службы поддержки Xsolla). | \n support@xsolla.com | \n
\n \n | Xsolla (при участии службы поддержки Xsolla). | \n support@xsolla.com | \n
\n \n
\n",
"type": "string"
},
"code": {
"description": "ID кода.\n\n\n \n \n | Код | \n Причина отмены | \n Описание | \n
\n \n \n \n | 1 | \n Cancellation by the user request / the game request | \n Используется, если отмена произошла из Личного кабинета. | \n
\n \n | 2 | \n Chargeback | \n Используется, если по транзакции был chargeback. | \n
\n \n | 3 | \n Integration error | \n Используется в случае проблем с интеграцией между Xsolla и игрой.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 4 | \n Potential fraud | \n Используется в случае потенциального фрода.
В этом случае мы рекомендуем добавить пользователя в черный список. | \n
\n \n | 5 | \n Test payment | \n Используется в случае совершения тестового платежа с последующей отменой.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 6 | \n User invoice expired | \n Используется, если был выбран способ оплаты с системой отложенного платежа. | \n
\n \n | 7 | \n Fraud notification from PS | \n Используется, если платежная система не произвела выплату по транзакции из-за потенциального фрода.
В этом случае мы рекомендуем добавить пользователя в черный список. | \n
\n \n | 8 | \n Cancellation by the PS request | \n Используется, когда платежная система запросила отмену транзакции.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 9 | \n Cancellation by the user request | \n Используется, если игра или заказ не удовлетворяют требованиям пользователя по каким-либо причинам.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 10 | \n Cancellation by the game request | \n Используется, когда игра просит отменить транзакцию.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 11 | \n Account holder called to report fraud | \n Используется, когда владелец аккаунта сообщил, что не совершал данный платеж. | \n
\n \n | 12 | \n Friendly fraud | \n Используется, если нам сообщили о friendly fraud. | \n
\n \n | 13 | \n Duplicate | \n Используется, если произошла попытка повторной оплаты по счету. | \n
\n \n
\n",
"type": "integer"
},
"reason": {
"description": "Причина отмены.",
"type": "string"
}
},
"type": "object"
},
"settings": {
"description": "Объект, содержащий настройки проекта.",
"properties": {
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
},
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
}
},
"type": "object"
},
"transaction": {
"description": "Объект с информацией о транзакции, связанной с этой операцией.",
"properties": {
"dry_run": {
"description": "Признак тестовой транзакции. Значение параметра равно 1 для тестового платежа, для реального платежа параметр не передается.",
"type": "integer"
},
"external_id": {
"description": "Внешний ID транзакции.",
"type": "string"
},
"id": {
"description": "ID транзакции.",
"format": "int64",
"type": "integer"
},
"payment_method": {
"description": "ID способа оплаты.",
"type": "integer"
}
},
"type": "object"
},
"user": {
"description": "Объект с информацией о пользователе.",
"properties": {
"country": {
"$ref": "#/components/schemas/user.country"
},
"email": {
"$ref": "#/components/schemas/user.email"
},
"id": {
"$ref": "#/components/schemas/user.id"
},
"ip": {
"$ref": "#/components/schemas/user.ip"
},
"name": {
"$ref": "#/components/schemas/user.name"
}
},
"required": [
"id"
],
"type": "object"
}
},
"required": [
"notification_type",
"transaction"
]
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400-payment"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"summary": "Отмена платежа",
"tags": [
"payments"
],
"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 80543ba63e1e50cf05f15150fe75e7245da9a898' \\\n-d '{\n \"notification_type\": \"ps_declined\",\n \"settings\": {\n \"project_id\": \"18404\",\n \"merchant_id\": \"2340\"\n },\n \"user\": {\n \"ip\": \"127.0.0.1\",\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"country\": \"US\"\n },\n \"transaction\": {\n \"id\": \"1\",\n \"dry_run\": \"1\",\n \"payment_method\": \"1\"\n },\n \"refund_details\": {\n \"author\": \"support@xsolla.com\",\n \"code\": \"8\",\n \"reason\": \"Cancellation by the PS request\",\n \"reason_detail\": \"Insufficient funds\"\n }\n}'"
},
{
"label": "PHP",
"lang": "PHP",
"source": " 'ps_declined',\n 'settings' => array(\n 'project_id' => '18404',\n 'merchant_id' => '2340',\n ),\n 'user' => array(\n 'ip' => '127.0.0.1',\n 'email' => 'email@example.com',\n 'id' => '1234567',\n 'country' => 'US',\n ),\n 'transaction' => array(\n 'id' => '1',\n 'dry_run' => '1',\n 'payment_method' => '1',\n ),\n 'refund_details' => array(\n 'author' => 'support@xsolla.com',\n 'code' => '8',\n 'reason' => 'Cancellation by the PS request',\n 'reason_detail' => 'Insufficient funds',\n ),\n);"
},
{
"label": "HTTP",
"lang": "HTTP",
"source": "POST /your_uri HTTP/1.1\nhost: your.host\naccept: application/json\ncontent-type: application/json\ncontent-length: 338\nauthorization: Signature 80543ba63e1e50cf05f15150fe75e7245da9a898\n\n{\n \"notification_type\": \"ps_declined\",\n \"settings\": {\n \"project_id\": \"18404\",\n \"merchant_id\": \"2340\"\n },\n \"user\": {\n \"ip\": \"127.0.0.1\",\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"country\": \"US\"\n },\n \"transaction\": {\n \"id\": \"1\",\n \"dry_run\": \"1\",\n \"payment_method\": \"1\"\n },\n \"refund_details\": {\n \"author\": \"support@xsolla.com\",\n \"code\": \"8\",\n \"reason\": \"Cancellation by the PS request\",\n \"reason_detail\": \"Insufficient funds\"\n }\n}"
}
]
}
},
"personalized-partner-catalog": {
"post": {
"description": "Xsolla при взаимодействии пользователя с магазином отправит вебхук \npartner_side_catalog, который содержит параметры пользователя и \nпроекта, на URL-адрес вебхука.\n\nВ ответе вам следует вернуть список item_id или артикулов \nпредметов, которые доступны пользователю. При этом вы также можете передать \nинформацию о том, что конкретный пользователь может купить определенный товар \nзаданное количество раз. Эта возможность позволяет регулировать количество и \nвид товаров, которые пользователь может добавить в корзину и купить.\n\n\n
Внимание
При обработке вебхука учитывайте следующие ограничения:
- Вебхук должен обрабатываться менее, чем за 3 секунды. Если обработка занимает больше времени, методы получения каталога, создания платежного токена и создания заказа вернут ошибку.
- Размер ответа на вебхук не должен превышать 64 КБ. Ответы большего размера не обрабатываются. В этом случае пользователь увидит пустой каталог и не сможет купить товары. Чтобы изменить допустимый размер ответа, обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.
\n
\n
Внимание
\n
При одновременном выполнении следующих условий платеж все равно будет возвращен пользователю:
- Инициатор возврата — Xsolla.
- На вебхук получен ответ с кодом
4xx, или после всех повторных попыток ответ не был получен, или был получен код 5xx.
\n
\n\n \n | Переключатель | \n Описание | \n
\n\n\n \n | Показывать информацию о транзакциях сохраненными способами оплаты | \n В вебхуке будет передаваться информация в кастомных параметрах: saved_payment_method:0 — сохраненный способ оплаты не используется;1 — способ оплаты был сохранен при совершении текущей транзакции;2 — используется ранее сохраненный способ оплаты.
payment_type:1 — единоразовый платеж;2 — рекуррентный платеж.
| \n
\n \n | Показывать информацию о причине возврата. | \n Детальная информация о причине возврата. | \n
\n\n
\n\nКоды отмены:\n\n\n \n \n | Код | \n Причина отмены | \n Описание | \n
\n \n \n \n | 1 | \n Cancellation by the user request / the game request | \n Используется, если отмена произошла из Личного кабинета. | \n
\n \n | 2 | \n Chargeback | \n Используется, если по транзакции был chargeback. | \n
\n \n | 3 | \n Integration error | \n Используется в случае проблем с интеграцией между Xsolla и игрой.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 4 | \n Potential fraud | \n Используется в случае потенциального фрода.
В этом случае мы рекомендуем добавить пользователя в черный список. | \n
\n \n | 5 | \n Test payment | \n Используется в случае совершения тестового платежа с последующей отменой.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 6 | \n User invoice expired | \n Используется, если был выбран способ оплаты с системой отложенного платежа. | \n
\n \n | 7 | \n Fraud notification from PS | \n Используется, если платежная система не произвела выплату по транзакции из-за потенциального фрода.
В этом случае мы рекомендуем добавить пользователя в черный список. | \n
\n \n | 8 | \n Cancellation by the PS request | \n Используется, когда платежная система запросила отмену транзакции.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 9 | \n Cancellation by the user request | \n Используется, если игра или заказ не удовлетворяют требованиям пользователя по каким-либо причинам.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 10 | \n Cancellation by the game request | \n Используется, когда игра просит отменить транзакцию.
В этом случае мы не рекомендуем заносить пользователя в черный список. | \n
\n \n | 11 | \n Account holder called to report fraud | \n Используется, когда владелец аккаунта сообщил, что не совершал данный платеж. | \n
\n \n | 12 | \n Friendly fraud | \n Используется, если нам сообщили о friendly fraud. | \n
\n \n | 13 | \n Duplicate | \n Используется, если произошла попытка повторной оплаты по счету. | \n
\n \n
\n",
"operationId": "refund",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"custom_parameters": {
"description": "Ваши дополнительные параметры.",
"type": "object"
},
"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": {
"checkout": {
"description": "Объект с информацией о заказе.",
"properties": {
"amount": {
"description": "Сумма заказа.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
},
"type": "object"
},
"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 \n | Инициатор возврата | \n Значение поля | \n
\n \n \n \n | Игра (через API). | \n API | \n
\n \n | Пользователь Личного кабинета (автоматический возврат). | \n Email-адрес пользователя | \n
\n \n | Пользователь Личного кабинета (при участии службы поддержки Xsolla). | \n support@xsolla.com | \n
\n \n | Xsolla (при участии службы поддержки Xsolla). | \n support@xsolla.com | \n
\n \n
\n",
"type": "string"
},
"code": {
"description": "ID кода.",
"type": "integer"
},
"reason": {
"description": "Причина отмены.",
"type": "string"
}
},
"type": "object"
},
"settings": {
"description": "Объект, содержащий настройки проекта.",
"properties": {
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
},
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
}
},
"type": "object"
},
"transaction": {
"description": "Объект с информацией о транзакции, связанной с этой операцией.",
"properties": {
"agreement": {
"description": "ID соглашения.",
"type": "integer"
},
"dry_run": {
"description": "Признак тестовой транзакции. Значение параметра равно 1 для тестового платежа, для реального платежа параметр не передается.",
"type": "integer"
},
"external_id": {
"description": "Внешний ID транзакции.",
"type": "string"
},
"id": {
"description": "ID транзакции.",
"format": "int64",
"type": "integer"
},
"payment_method_order_id": {
"description": "ID платежа в платежной системе.",
"type": "string"
}
},
"type": "object"
},
"user": {
"description": "Объект с информацией о пользователе.",
"properties": {
"country": {
"$ref": "#/components/schemas/user.country"
},
"email": {
"$ref": "#/components/schemas/user.email"
},
"id": {
"$ref": "#/components/schemas/user.id"
},
"ip": {
"$ref": "#/components/schemas/user.ip"
},
"name": {
"$ref": "#/components/schemas/user.name"
},
"phone": {
"$ref": "#/components/schemas/user.phone"
},
"zip": {
"$ref": "#/components/schemas/user.zip"
}
},
"required": [
"id"
],
"type": "object"
}
},
"required": [
"notification_type",
"transaction",
"payment_details"
]
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"summary": "Возврат платежа",
"tags": [
"payments"
],
"x-codeSamples": [
{
"label": "CURL",
"lang": "cURL",
"source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-d '{\n \"notification_type\": \"refund\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"purchase\": {\n \"subscription\": {\n \"plan_id\": \"b5dac9c8\",\n \"subscription_id\": \"10\",\n \"date_create\": \"2014-09-22T19:25:25+04:00\",\n \"currency\": \"USD\",\n \"amount\": 9.99\n },\n \"checkout\": {\n \"currency\": \"USD\",\n \"amount\": 50\n },\n \"total\":{\n \"currency\": \"USD\",\n \"amount\": 200\n }\n },\n \"user\": {\n \"ip\": \"127.0.0.1\",\n \"phone\": \"18777976552\",\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"name\": \"John Smith\",\n \"country\": \"US\"\n },\n \"transaction\": {\n \"id\": 1,\n \"external_id\": 1,\n \"dry_run\": 1,\n \"agreement\": 1\n },\n \"refund_details\": {\n \"code\": 4,\n \"reason\": \"Potential fraud\"\n },\n \"payment_details\": {\n \"sales_tax\": {\n \"currency\": \"USD\",\n \"amount\": 0\n },\n \"direct_wht\": {\n \"currency\": \"USD\",\n \"amount\": 0.70\n },\n \"xsolla_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"10\"\n },\n \"payout\": {\n \"currency\": \"USD\",\n \"amount\": \"200\"\n },\n \"payment_method_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"20\"\n },\n \"payment\": {\n \"currency\": \"USD\",\n \"amount\": \"230\"\n },\n \"repatriation_commission\": {\n \"currency\": \"USD\",\n \"amount\": 10\n }\n }\n }\n}'"
},
{
"label": "PHP",
"lang": "PHP",
"source": " 'refund',\n 'settings' => array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'purchase' => array(\n 'total' => array(\n 'currency' => 'USD',\n 'amount' => 9.99\n )\n ),\n 'user' => array(\n 'ip' => '127.0.0.1',\n 'phone' => '18777976552',\n 'email' => 'email@example.com',\n 'id' => '1234567',\n 'country' => 'US'\n ),\n 'transaction' => array(\n 'id' => 87654321,\n 'payment_date' => '2014-09-23T19:25:25+04:00',\n 'payment_method' => 1380,\n 'dry_run' => 1\n ),\n 'refund_details' => array(\n 'code' => 4,\n 'reason' => 'Potential fraud'\n ),\n 'payment_details' => array(\n 'payment' => array(\n 'currency' => 'USD',\n 'amount' => 9.99\n ),\n 'vat' => array(\n 'currency' => 'USD',\n 'amount' => 0\n ),\n 'sales_tax' => array(\n 'currency' => 'USD',\n 'amount' => 0\n ),\n 'direct_wht' => array(\n 'currency' => 'USD',\n 'amount' => 70\n ),\n 'payout_currency_rate' => 1,\n 'payout' => array(\n 'currency' => 'USD',\n 'amount' => 9.49\n ),\n 'xsolla_fee' => array(\n 'currency' => 'USD',\n 'amount' => 0.19\n ),\n 'payment_method_fee' => array(\n 'currency' => 'USD',\n 'amount' => 0.31\n ),\n 'repatriation_commission' => array(\n 'currency' => 'USD',\n 'amount' => 0.2\n )\n )\n);"
},
{
"label": "HTTP",
"lang": "HTTP",
"source": "POST /your_uri HTTP/1.1\nhost: your.host\naccept: application/json\ncontent-type: application/json\ncontent-length: 1220\nauthorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7\n\n{\n \"notification_type\": \"refund\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"purchase\": {\n \"subscription\": {\n \"plan_id\": \"b5dac9c8\",\n \"subscription_id\": \"10\",\n \"date_create\": \"2014-09-22T19:25:25+04:00\",\n \"currency\": \"USD\",\n \"amount\": 9.99\n },\n \"checkout\": {\n \"currency\": \"USD\",\n \"amount\": 50\n },\n \"total\": {\n \"currency\": \"USD\",\n \"amount\": 200\n }\n },\n \"user\": {\n \"ip\": \"127.0.0.1\",\n \"phone\": \"18777976552\",\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"name\": \"John Smith\",\n \"country\": \"US\"\n },\n \"transaction\": {\n \"id\": 1,\n \"external_id\": 1,\n \"dry_run\": 1,\n \"agreement\": 1\n },\n \"refund_details\": {\n \"code\": 4,\n \"reason\": \"Potential fraud\"\n },\n \"payment_details\": {\n \"sales_tax\": {\n \"currency\": \"USD\",\n \"amount\": 0\n },\n \"direct_wht\": {\n \"currency\": \"USD\",\n \"amount\": 0.70\n },\n \"xsolla_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"10\"\n },\n \"payout\": {\n \"currency\": \"USD\",\n \"amount\": \"200\"\n },\n \"payment_method_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"20\"\n },\n \"payment\": {\n \"currency\": \"USD\",\n \"amount\": \"230\"\n },\n \"repatriation_commission\": {\n \"currency\": \"USD\",\n \"amount\": 10\n }\n }\n}"
}
]
}
},
"remove-payment-account": {
"post": {
"description": "Когда пользователь удаляет платежный аккаунт из сохраненных, Xsolla отправляет вебхук с типом `payment_account_remove` на URL-адрес вебхука. Чтобы получать вебхук, обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.",
"operationId": "remove-payment-account",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"payment_account": {
"description": "Объект с информацией о платежном аккаунте.",
"properties": {
"id": {
"$ref": "#/components/schemas/payment_account.id"
},
"name": {
"$ref": "#/components/schemas/payment_account.name"
},
"payment_method": {
"$ref": "#/components/schemas/payment_account.payment_method"
},
"type": {
"$ref": "#/components/schemas/payment_account.type"
}
},
"required": [
"id"
],
"type": "object"
},
"settings": {
"description": "Объект, содержащий настройки проекта.",
"properties": {
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
},
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
}
},
"type": "object"
},
"user": {
"description": "Объект с информацией о пользователе.",
"properties": {
"email": {
"$ref": "#/components/schemas/user.email"
},
"id": {
"$ref": "#/components/schemas/user.id"
},
"name": {
"$ref": "#/components/schemas/user.name"
}
},
"required": [
"id"
],
"type": "object"
}
},
"required": [
"notification_type"
]
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"summary": "Удаление платежного аккаунта",
"tags": [
"payments"
],
"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\": \"payment_account_remove\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"name\": \"John Smith\"\n },\n \"payment_account\": {\n \"id\": \"12345678\",\n \"name\": \"email@example.com\",\n \"payment_method\": \"24\",\n \"type\": \"paypal\"\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\": \"payment_account_remove\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"name\": \"John Smith\"\n },\n \"payment_account\": {\n \"id\": \"12345678\",\n \"name\": \"email@example.com\",\n \"payment_method\": \"24\",\n \"type\": \"paypal\"\n }\n}"
}
]
}
},
"successful-order-payment": {
"post": {
"description": "Xsolla отправляет вебхук order_paid на указанный URL-адрес, когда \nпользователь успешно оплатил заказ.\n\nВ вебхуке order_paid содержится информация о купленных товарах, \nданные платежа и детали транзакции.\n\nВебхук order_paid не отправляется, если оплата неуспешна, например:\n* форма оплаты была открыта, но пользователь не оплатил заказ;\n* форма оплаты была открыта, но при оплате возникли ошибки.\n\nРекомендуется обеспечить время обработки вебхука order_paid менее \n3 секунд.\n\n\n
Внимание
\n
Набор полей, отправляемых в вебхуке, зависит от настроек, которые:
При возникновении вопросов обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.
\n
\n \n \n | Код ответа | \n Автоматический возврат платежа не включен (по умолчанию) | \n Автоматический возврат платежа включен | \n
\n \n \n \n 400, 401, 402, 403, 404, 409, 422, 415 | \n Нет действий | \n Автоматический возврат средств пользователю. | \n
\n \n 200, 201, 204 | \n Нет действий | \n Нет действий | \n
\n \n | Другой код или отсутствие ответа на вебхук | \n Многократная отправка вебхуков через заданный временной промежуток: 2 попытки с шагом 5 минут, 7 попыток с шагом 15 минут, 10 попыток с шагом 60 минут. | \n Многократная отправка вебхуков через заданный временной промежуток: 2 попытки с шагом 5 минут, 7 попыток с шагом 15 минут, 10 попыток с шагом 60 минут. Если все вебхуки отправлены, а успешный ответ не получен, осуществляется автоматический возврат средств пользователю. | \n
\n \n
\n\nДля подключения функциональности автоматических возвратов обратитесь к \nперсональному менеджеру проекта или напишите на csm@xsolla.com\n",
"operationId": "successful-order-payment",
"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": {
"coupon": {
"description": "Объект с информацией о купоне (если при создании подписки был использован купон).",
"properties": {
"campaign_code": {
"description": "Код кампании купонов.",
"type": "string"
},
"coupon_code": {
"description": "Код купона.",
"type": "string"
}
},
"type": "object"
},
"gift": {
"description": "Объект с информацией о подарке.",
"properties": {
"giver_id": {
"description": "ID дарителя.",
"type": "string"
},
"hide_giver_from_receiver": {
"description": "Флаг, показывать ли дарителя получателю подарка.",
"type": "string"
},
"message": {
"description": "Сообщение от дарителя.",
"type": "string"
},
"receiver_email": {
"description": "Email получателя подарка.",
"type": "string"
},
"receiver_id": {
"description": "ID получателя подарка.",
"type": "string"
}
},
"type": "object"
},
"promotions": {
"description": "Массив с данными акций, которые действуют на данную покупку.",
"items": {
"properties": {
"id": {
"description": "ID акции.",
"type": "integer"
},
"technical_name": {
"description": "Техническое название акции.",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"subscription": {
"description": "Объект с данными о подписке.",
"properties": {
"amount": {
"$ref": "#/components/schemas/amount-float"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"date_create": {
"$ref": "#/components/schemas/subscription.date_create"
},
"date_next_charge": {
"description": "Дата следующего списания. Дата и время согласно стандарту [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).",
"type": "string"
},
"plan_id": {
"$ref": "#/components/schemas/subscription.plan_id"
},
"product_id": {
"description": "ID продукта (если был отправлен в токене).",
"type": "string"
},
"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"
},
"settings": {
"description": "Объект, содержащий настройки проекта.",
"properties": {
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
},
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
}
},
"type": "object"
},
"transaction": {
"description": "Объект с информацией о транзакции, связанной с этой операцией.",
"properties": {
"agreement": {
"description": "ID соглашения.",
"type": "integer"
},
"dry_run": {
"description": "Признак тестовой транзакции. Значение параметра равно 1 для тестового платежа, для реального платежа параметр не передается.",
"type": "integer"
},
"external_id": {
"$ref": "#/components/schemas/external-id"
},
"id": {
"description": "ID транзакции.",
"format": "int64",
"type": "integer"
},
"payment_date": {
"description": "Дата платежа.",
"type": "string"
},
"payment_method": {
"description": "ID способа оплаты.",
"type": "integer"
},
"payment_method_name": {
"description": "Название способа оплаты.",
"type": "string"
},
"payment_method_order_id": {
"description": "ID платежа в платежной системе.",
"type": "string"
}
},
"type": "object"
}
},
"required": [
"notification_type",
"transaction",
"payment_details"
],
"type": "object"
},
"custom_parameters": {
"description": "Дополнительная информация.",
"type": "object"
},
"items": {
"description": "Список предметов, которые купил пользователь.\n\nНабор передаваемых параметров в массиве зависит от версии вебхука. В версии 2 \nдополнительно передаются параметры `is_free`, `is_bonus` и `is_bundle_content`. \nДля переключения версии передайте ее номер в параметре `version` в методе \n[Обновление информации о настройках вебхуков](/ru/api/igs/operation/update-webhook/).\n",
"items": {
"oneOf": [
{
"properties": {
"amount": {
"description": "Общая стоимость товаров, рассчитанная c учетом их количества.",
"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": "Общая стоимость товаров, рассчитанная c учетом их количества.",
"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": {
"$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",
"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`. Для других платежей используется значение, соответствующее названию платформы публикации игры.",
"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",
"transaction",
"payment_details"
]
}
}
}
},
"responses": {
"200": {
"description": "Верните, чтобы сообщить об успешной обработке вехбука."
},
"400": {
"description": "Верните в случае ошибки в предоставленной информации (например, обязательный параметр не передан, или авторизация не прошла)."
}
},
"summary": "Успешная оплата заказа (с деталями платежа и транзакции)",
"tags": [
"combined-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_paid\",\n \"items\": [\n {\n \"sku\": \"com.xsolla.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 {\n \"purchased\": 0,\n \"attr\": \"value\"\n }\n },\n {\n \"sku\": \"com.xsolla.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\": \"gc_user@xsolla.com\",\n \"country\": \"US\"\n },\n \"billing\": {\n \"notification_type\": \"payment\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"purchase\": {\n \"subscription\": {\n \"plan_id\": \"b5dac9c8\",\n \"subscription_id\": \"10\",\n \"product_id\": \"Demo Product\",\n \"date_create\": \"2014-09-22T19:25:25+04:00\",\n \"date_next_charge\": \"2014-10-22T19:25:25+04:00\",\n \"currency\": \"USD\",\n \"amount\": 9.99\n },\n \"total\": {\n \"currency\": \"USD\",\n \"amount\": 200\n },\n \"promotions\": [{\n \"technical_name\": \"Demo Promotion\",\n \"id\": 853\n }],\n \"coupon\": {\n \"coupon_code\": \"ICvj45S4FUOyy\",\n \"campaign_code\": \"1507\"\n }\n },\n \"transaction\": {\n \"id\": 1,\n \"external_id\": 1,\n \"payment_date\": \"2014-09-24T20:38:16+04:00\",\n \"payment_method\": 1,\n \"payment_method_name\": \"PayPal\",\n \"payment_method_order_id\": 1234567890123456789,\n \"dry_run\": 1,\n \"agreement\": 1\n },\n \"payment_details\": {\n \"payment\": {\n \"currency\": \"USD\",\n \"amount\": 230\n },\n \"vat\": {\n \"currency\": \"USD\",\n \"amount\": 0,\n \"percent\": 20\n },\n \"sales_tax\": {\n \"currency\": \"USD\",\n \"amount\": 0,\n \"percent\": 0\n },\n \"direct_wht\": {\n \"currency\": \"USD\",\n \"amount\": 0,\n \"percent\": 0\n },\n \"payout_currency_rate\": \"1\",\n \"payout\": {\n \"currency\": \"USD\",\n \"amount\": 200\n },\n \"country_wht\": {\n \"currency\": \"USD\",\n \"amount\": 2,\n \"percent\": 10\n },\n \"user_acquisition_fee\": {\n \"currency\": \"USD\",\n \"amount\": 2,\n \"percent\": 1\n },\n \"xsolla_fee\": {\n \"currency\": \"USD\",\n \"amount\": 10\n },\n \"payment_method_fee\": {\n \"currency\": \"USD\",\n \"amount\": 20\n },\n \"repatriation_commission\": {\n \"currency\": \"USD\",\n \"amount\": 10\n }\n }\n }\n ,\n \"custom_parameters\": {\n \"parameter1\": \"value1\",\n \"parameter2\": \"value2\"\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_paid\",\n \"items\": [\n {\n \"sku\": \"com.xsolla.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 {\n \"purchased\": 0,\n \"attr\": \"value\"\n }\n },\n {\n \"sku\": \"com.xsolla.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\": \"gc_user@xsolla.com\",\n \"country\": \"US\"\n },\n \"billing\": {\n \"notification_type\": \"payment\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"purchase\":{\n \"subscription\": {\n \"plan_id\": \"b5dac9c8\",\n \"subscription_id\": \"10\",\n \"product_id\": \"Demo Product\",\n \"date_create\": \"2014-09-22T19:25:25+04:00\",\n \"date_next_charge\": \"2014-10-22T19:25:25+04:00\",\n \"currency\": \"USD\",\n \"amount\": 9.99\n },\n \"total\": {\n \"currency\": \"USD\",\n \"amount\": 200\n },\n \"promotions\": [{\n \"technical_name\": \"Demo Promotion\",\n \"id\": 853\n }],\n \"coupon\": {\n \"coupon_code\": \"ICvj45S4FUOyy\",\n \"campaign_code\": \"1507\"\n }\n },\n \"transaction\": {\n \"id\": 1,\n \"external_id\": 1,\n \"payment_date\": \"2014-09-24T20:38:16+04:00\",\n \"payment_method\": 1,\n \"payment_method_name\": \"PayPal\",\n \"payment_method_order_id\": 1234567890123456789,\n \"dry_run\": 1,\n \"agreement\": 1\n },\n \"payment_details\": {\n \"payment\": {\n \"currency\": \"USD\",\n \"amount\": 230\n },\n \"vat\": {\n \"currency\": \"USD\",\n \"amount\": 0,\n \"percent\": 20\n },\n \"sales_tax\": {\n \"currency\": \"USD\",\n \"amount\": 0,\n \"percent\": 0\n },\n \"direct_wht\": {\n \"currency\": \"USD\",\n \"amount\": 0,\n \"percent\": 0\n },\n \"payout_currency_rate\": \"1\",\n \"country_wht\": {\n \"currency\": \"USD\",\n \"amount\": 2,\n \"percent\": 10\n },\n \"user_acquisition_fee\": {\n \"currency\": \"USD\",\n \"amount\": 2,\n \"percent\": 1\n },\n \"payout\": {\n \"currency\": \"USD\",\n \"amount\": 200\n },\n \"xsolla_fee\": {\n \"currency\": \"USD\",\n \"amount\": 10\n },\n \"payment_method_fee\": {\n \"currency\": \"USD\",\n \"amount\": 20\n },\n \"repatriation_commission\": {\n \"currency\": \"USD\",\n \"amount\": 10\n }\n }\n },\n \"custom_parameters\": {\n \"parameter1\": \"value1\",\n \"parameter2\": \"value2\"\n }\n }"
}
]
}
},
"successful-order-payment-separate": {
"post": {
"description": "Xsolla отправляет вебхук 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 | Код ответа | \n Автоматический возврат платежа не включен (по умолчанию) | \n Автоматический возврат платежа включен | \n
\n \n \n \n 400, 401, 402, 403, 404, 409, 422, 415 | \n Нет действий | \n Автоматический возврат средств пользователю. | \n
\n \n 200, 201, 204 | \n Нет действий | \n Нет действий | \n
\n \n | Другой код или отсутствие ответа на вебхук | \n Многократная отправка вебхуков через заданный временной промежуток: 2 попытки с шагом 5 минут, 7 попыток с шагом 15 минут, 10 попыток с шагом 60 минут. | \n Многократная отправка вебхуков через заданный временной промежуток: 2 попытки с шагом 5 минут, 7 попыток с шагом 15 минут, 10 попыток с шагом 60 минут. Если все вебхуки отправлены, а успешный ответ не получен, осуществляется автоматический возврат средств пользователю. | \n
\n \n
\n\nДля подключения функциональности автоматических возвратов обратитесь к \nперсональному менеджеру проекта или напишите на csm@xsolla.com\n",
"operationId": "successful-order-payment-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/igs/operation/update-webhook/).\n",
"items": {
"oneOf": [
{
"properties": {
"amount": {
"description": "Общая стоимость товаров, рассчитанная c учетом их количества.",
"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": "Общая стоимость товаров, рассчитанная c учетом их количества.",
"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": {
"$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",
"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`. Для других платежей используется значение, соответствующее названию платформы публикации игры.",
"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_paid\",\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 {\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\": \"gc_user@xsolla.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_paid\",\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 {\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\": \"gc_user@xsolla.com\",\n \"country\": \"US\"\n }\n}"
}
]
}
},
"updated-subscription": {
"post": {
"description": "В случае изменения каких-либо параметров (`plan_id`, `date_next_charge`) подписки и в случае каждого продления подписки, Xsolla отправляет вебхук с типом `update_subscription` на URL-адрес вебхука.",
"operationId": "updated-subscription",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"description": "Объект, содержащий настройки проекта.",
"properties": {
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
},
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
}
},
"type": "object"
},
"subscription": {
"description": "Объект с данными о подписке.",
"properties": {
"date_next_charge": {
"$ref": "#/components/schemas/subscription.date_next_charge"
},
"plan_id": {
"$ref": "#/components/schemas/subscription.plan_id"
},
"product_id": {
"$ref": "#/components/schemas/subscription.product_id"
},
"subscription_id": {
"$ref": "#/components/schemas/subscription.subscription_id"
},
"tags": {
"$ref": "#/components/schemas/subscription.tags"
}
},
"type": "object"
},
"user": {
"description": "Объект с информацией о пользователе.",
"properties": {
"id": {
"$ref": "#/components/schemas/user.id"
},
"name": {
"$ref": "#/components/schemas/user.name"
}
},
"required": [
"id"
],
"type": "object"
}
},
"required": [
"notification_type"
]
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"summary": "Изменение подписки",
"tags": [
"subscriptions"
],
"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 13342703ccaca5064ad33ba451d800c5e823db8f' \\\n-d '{\n \"notification_type\": \"update_subscription\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"id\": \"1234567\",\n \"name\": \"John Smith\"\n },\n \"subscription\": {\n \"plan_id\": \"b5dac9c8\",\n \"subscription_id\": \"10\",\n \"product_id\": \"Demo Product\",\n \"date_next_charge\": \"2015-01-22T19:25:25+04:00\"\n }\n }'"
},
{
"label": "PHP",
"lang": "PHP",
"source": " 'update_subscription',\n 'settings' => array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'user' => array(\n 'id' => '1234567',\n 'name' => 'John Smith'\n ),\n 'subscription' => array(\n 'plan_id' => 'b5dac9c8',\n 'subscription_id' => '10',\n 'product_id' => 'Demo Product',\n 'date_next_charge' => '2015-01-22T19:25:25+04:00'\n )\n);"
},
{
"label": "HTTP",
"lang": "HTTP",
"source": "POST /your/uri HTTP/1.1\nhost: your.hostname\naccept: application/json\ncontent-type: application/json\ncontent-length: 240\nauthorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f\n\n{\n \"notification_type\": \"update_subscription\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"id\": \"1234567\",\n \"name\": \"John Smith\"\n },\n \"subscription\": {\n \"plan_id\": \"b5dac9c8\",\n \"subscription_id\": \"10\",\n \"product_id\": \"Demo Product\",\n \"date_next_charge\": \"2015-01-22T19:25:25+04:00\"\n }\n}"
}
]
}
},
"user-search": {
"post": {
"description": "Public User ID — параметр, по которому можно однозначно идентифицировать пользователя и который хорошо известен пользователю в отличие от User ID (в качестве Public User ID может быть email, никнейм и т. д.). Xsolla отправляет вебхук с типом `user_search`, когда оплата совершается вне игры (например, при оплате в терминале).",
"operationId": "user-search",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"description": "Объект, содержащий настройки проекта.",
"properties": {
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
},
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
}
},
"type": "object"
},
"user": {
"description": "Объект с информацией о пользователе.",
"properties": {
"id": {
"$ref": "#/components/schemas/user.id"
},
"public_id": {
"$ref": "#/components/schemas/user.public_id"
}
},
"required": [
"id"
],
"type": "object"
}
},
"required": [
"notification_type",
"user"
]
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"summary": "Поиск пользователя",
"tags": [
"user-validation"
],
"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 13342703ccaca5064ad33ba451d800c5e823db8f' \\\n-d '{\n \"notification_type\": \"user_search\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"public_id\": \"email@example.com\"\n }\n}'"
},
{
"label": "PHP",
"lang": "PHP",
"source": " 'user_search',\n 'settings' => array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'user' => array(\n 'public_id' => 'email@example.com'\n )\n);"
},
{
"label": "HTTP",
"lang": "HTTP",
"source": "POST /your/uri HTTP/1.1\nhost: your.hostname\naccept: application/json\ncontent-type: application/json\ncontent-length: 240\nauthorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f\n\n{\n \"notification_type\": \"user_search\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"public_id\": \"email@example.com\"\n }\n}"
}
]
}
},
"user-validation": {
"post": {
"description": "Xsolla отправляет вебхук с типом `user_validation` на URL-адрес вебхука, чтобы \nудостовериться, что пользователь зарегистрирован в игре. В процессе оплаты \nзапрос отправляется несколько раз:\n\n* при выборе способа оплаты в платежном интерфейсе;\n* вводе данных в форме оплаты, например, при вводе данных банковской карты или \n индекса для оплаты с помощью PayPal;\n* нажатии **Далее** для перехода к оплате;\n* завершении обработки платежа и переходе транзакции в статус `done`.\n\nЗапрос отправляется при оплате любыми способами.\n\nПосле сохранения URL-адреса вебхука в Личном кабинете вы можете настроить \nполучение дополнительной информации в вебхуке. Для этого в разделе Настройки \nпроекта > Вебхуки > Расширенные настройки установите необходимые \nпереключатели в активное положение.\n\n\n\n\n\n \n | Переключатель | \n Описание | \n
\n\n\n \n | Показывать только необходимую информацию о пользователе без чувствительных данных | \n В вебхуке о пользователе будет передаваться только следующая информация: | \n
\n \n | Передавать кастомные параметры | \n В вебхуке будет передаваться информация о кастомных параметрах из токена. | \n
\n\n
\n",
"operationId": "user-validation",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"description": "Объект, содержащий настройки проекта.",
"properties": {
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
},
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
}
},
"type": "object"
},
"user": {
"description": "Объект с информацией о пользователе.",
"properties": {
"country": {
"$ref": "#/components/schemas/user.country"
},
"email": {
"$ref": "#/components/schemas/user.email"
},
"id": {
"$ref": "#/components/schemas/user.id"
},
"ip": {
"$ref": "#/components/schemas/user.ip"
},
"name": {
"$ref": "#/components/schemas/user.name"
},
"phone": {
"$ref": "#/components/schemas/user.phone"
}
},
"required": [
"id"
],
"type": "object"
}
},
"required": [
"notification_type"
]
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"summary": "Проверка пользователей",
"tags": [
"user-validation"
],
"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 13342703ccaca5064ad33ba451d800c5e823db8f' \\\n-d '{\n \"notification_type\":\"user_validation\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"ip\": \"127.0.0.1\",\n \"phone\": \"18777976552\",\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"name\": \"John Smith\",\n \"country\": \"US\"\n }\n}'"
},
{
"label": "PHP",
"lang": "PHP",
"source": " 'user_validation',\n 'settings' => array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'user' => array(\n 'ip' => '127.0.0.1',\n 'phone' => '18777976552',\n 'email'=> 'email@example.com',\n 'id'=> '1234567',\n 'country' => 'US'\n )\n);"
},
{
"label": "HTTP",
"lang": "HTTP",
"source": "POST /your/uri HTTP/1.1\nhost: your.hostname\naccept: application/json\ncontent-type: application/json\ncontent-length: 240\nauthorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f\n\n{\n \"notification_type\": \"user_validation\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"ip\": \"127.0.0.1\",\n \"phone\": \"18777976552\",\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"name\": \"John Smith\",\n \"country\": \"US\"\n }\n}"
}
]
}
},
"user-validation-in-webshop": {
"post": {
"description": "Xsolla отправляет вебхук с сайта интернет-магазина на URL-адрес вебхука для проверки существования пользователя в игре. Вебхук поступает с IP-адреса `34.102.38.178`.\nПримечание Вебхук используется только для\nпроверки пользователя в Web Shop. Дополнительные сведения о настройке вебхука вы можете найти в
инструкции.
",
"operationId": "user-validation-in-webshop",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"settings": {
"description": "Объект, содержащий настройки проекта.",
"properties": {
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
},
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
}
},
"type": "object"
},
"user": {
"description": "Объект с информацией о пользователе.",
"properties": {
"country": {
"$ref": "#/components/schemas/user.country"
},
"id": {
"$ref": "#/components/schemas/user.id"
}
},
"required": [
"id"
],
"type": "object"
}
},
"required": [
"user"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"attributes": [
{
"key": "level",
"value": "2"
},
{
"key": "register_country",
"value": "AE"
}
],
"removingKeys": [
"company"
],
"user": {
"appPlayerId": "cuid12345",
"id": "1234567890",
"name": "test-name",
"picture": "https://example.com"
}
},
"schema": {
"properties": {
"attributes": {
"description": "Атрибуты пользователя, используемые для персонализации. Подробную информацию вы можете найти в документации.",
"items": {
"properties": {
"key": {
"description": "Имя атрибута.",
"type": "string"
},
"value": {
"description": "Значение атрибута."
}
},
"required": [
"key",
"value"
]
},
"type": "array"
},
"removingKeys": {
"description": "Список атрибутов, которые вы хотите удалить. Если вы укажете тот же атрибут в `attributes`параметре, он не будет удален.",
"items": {
"type": "string"
},
"type": "array"
},
"user": {
"description": "Объект с информацией о пользователе.",
"properties": {
"appPlayerId": {
"$ref": "#/components/schemas/appPlayerId"
},
"id": {
"description": "ID пользователя.",
"type": "string"
},
"name": {
"description": "Имя пользователя.",
"type": "string"
},
"picture": {
"description": "Ссылка на аватар пользователя.",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
}
},
"required": [
"user"
],
"type": "object"
}
}
},
"description": "Возвращает информацию о пользователе."
},
"404": {
"description": "Пользователь не найден."
}
},
"summary": "Проверка пользователя в Web Shop",
"tags": [
"user-validation"
],
"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-d '{\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"id\": \"1234567\",\n \"country\": \"US\"\n }\n}'"
},
{
"label": "HTTP",
"lang": "HTTP",
"source": "POST /your/uri HTTP/1.1\nhost: your.hostname\naccept: application/json\ncontent-type: application/json\ncontent-length: 240\n\n{\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"id\": \"1234567\",\n \"country\": \"US\"\n }\n}"
}
]
}
}
},
"components": {
"schemas": {
"notification_type": {
"description": "Тип оповещения.",
"type": "string"
},
"payment_account.country": {
"description": "Страна платежного аккаунта. Например, страна выпуска карты или страна, указанная при создании аккаунта PayPal. Используется двухбуквенное обозначение страны согласно стандарту [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).",
"type": "string"
},
"payment_account.id": {
"description": "ID платежного аккаунта.",
"type": "string"
},
"payment_account.name": {
"description": "Название платежного аккаунта в платежной системе (например: номер карты, email-адрес).",
"type": "string"
},
"payment_account.payment_method": {
"description": "ID способа оплаты.",
"type": "integer"
},
"payment_account.type": {
"description": "Тип платежного аккаунта (например: карта, PayPal).",
"type": "string"
},
"settings.merchant_id": {
"description": "ID продавца.",
"type": "integer"
},
"settings.project_id": {
"description": "ID проекта. Вы можете найти этот параметр в [Личном кабинете](https://publisher.xsolla.com/) рядом с названием проекта.",
"type": "integer"
},
"user.country": {
"description": "Страна пользователя. Используется двухбуквенное обозначение страны согласно стандарту [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).",
"type": "string"
},
"user.email": {
"description": "Email пользователя.",
"type": "string"
},
"user.id": {
"description": "ID пользователя.",
"type": "string"
},
"user.ip": {
"description": "IP адрес пользователя.",
"type": "string"
},
"user.name": {
"description": "Имя пользователя.",
"type": "string"
},
"user.zip": {
"description": "Почтовый индекс.",
"type": "string"
},
"subscription.date_create": {
"description": "Дата создания подписки. Дата и время согласно стандарту [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).",
"type": "string"
},
"subscription.date_end": {
"description": "Дата окончания срока действия подписки. Дата и время согласно стандарту [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).",
"type": "string"
},
"subscription.plan_id": {
"description": "ID плана (внешний id, если план был создан через API).",
"type": "string"
},
"subscription.product_id": {
"description": "ID продукта (если был отправлен в токене).",
"type": "string"
},
"subscription.subscription_id": {
"description": "ID подписки в базе данных Xsolla.",
"type": "integer"
},
"subscription.tags": {
"description": "Теги плана.",
"items": {
"type": "string"
},
"type": "array"
},
"subscription.date_next_charge": {
"description": "Дата следующего списания. Дата и время согласно стандарту [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).",
"type": "string"
},
"subscription.is_gift": {
"description": "Была ли подписка подарена. Параметр передается, только если принимает значение `true`.",
"type": "boolean"
},
"dispute-date": {
"description": "Дата открытия диспута согласно стандарту [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339).",
"type": "string"
},
"dispute-reason": {
"description": "Причина открытия диспута. Описания групп причин приведены в [документации](/ru/payment-ui-and-flow/anti-fraud/chargeback/#payments_chargeback_reasons).",
"enum": [
"non_receipt",
"not_as_described",
"duplicate_processing",
"paid_by_other_means",
"incorrect_amount",
"credit_not_processed",
"general",
"fraud",
"cancelled_recurring",
"cancelled_merchandise",
"late_presentment",
"no_authorization",
"problem_with_remittance",
"other"
],
"type": "string"
},
"dispute-status": {
"description": "Статус диспута.",
"enum": [
"new",
"accepted",
"no_actions_required",
"won",
"lost"
],
"type": "string",
"x-enumDescriptions": {
"accepted": "Принят",
"lost": "Проигран",
"new": "Новый",
"no_actions_required": "В процессе",
"won": "Выигран"
}
},
"dispute-type": {
"description": "Тип диспута.",
"enum": [
"1st_time_chargeback",
"2nd_time_chargeback",
"arbitration",
"retrieval",
"representment",
"chargeback_reversal",
"representment_reversal",
"reimbursement",
"dispute",
"chargeback",
"claim",
"reimbursement_reversal",
"inquiry",
"other"
],
"type": "string",
"x-enumDescriptions": {
"1st_time_chargeback": "Первичный чарджбэк.",
"2nd_time_chargeback": "Повторный чарджбэк (pre-arbitration).",
"arbitration": "Решение спора между банком-эмитентом и продавцом, когда первичный и повторный чарджбэк были отклонены.",
"chargeback": "Первичный чарджбэк.",
"chargeback_reversal": "Чарджбэк отозван.",
"claim": "Спор между покупателем и продавцом в PayPal.",
"dispute": "Владелец карты запрашивает детали платежа через банк.",
"inquiry": "Владелец карты запрашивает детали платежа через банк.",
"other": "Используется в случае, когда ни один из существующих типов не подходит.",
"reimbursement": "Сделан возврат средств.",
"reimbursement_reversal": "Чарджбэк отозван.",
"representment": "Команда управления чарджбэками отправляет доказательства платежной системе.",
"representment_reversal": "Чарджбэк отозван.",
"retrieval": "Владелец карты запрашивает детали платежа через банк."
}
},
"date-create": {
"description": "Дата платежа.",
"type": "string"
},
"external-id": {
"description": "Внешний ID транзакции. Изучите подробную информацию в [Частых вопросах](/ru/doc/pay-station/references/faq/#faq_payments_q_new_transaction_external_id).",
"type": "string"
},
"transaction-id": {
"description": "ID транзакции.",
"format": "int64",
"type": "integer"
},
"dispute-payment-method": {
"description": "Способ оплаты.",
"enum": [
"credit_debit_card",
"paypal"
],
"type": "string",
"x-enumDescriptions": {
"credit_debit_card": "Кредитная или дебитовая карта",
"paypal": "PayPal"
}
},
"transaction-total-amount": {
"description": "Сумма платежа.",
"format": "float",
"type": "number"
},
"currency": {
"description": "Валюта. Используется трехбуквенное обозначение валюты согласно стандарту [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).",
"type": "string"
},
"country_whc": {
"description": "Объект с данными о дополнительных издержках при международных транзакциях в некоторых странах.",
"properties": {
"amount": {
"description": "Сумма.",
"format": "float",
"type": "number"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"percent": {
"description": "Размер дополнительных издержек, в процентах.",
"format": "float",
"type": "number"
}
},
"type": "object"
},
"amount-float": {
"description": "Сумма покупки.",
"format": "float",
"type": "number"
},
"items.promotions": {
"description": "Примененные акции для отдельных товаров в заказе.\nМассив возвращается, если:\n - Скидочная акция настроена для отдельного товара.\n - Применяется промокод с настройкой **Скидка на выбранные товары**.\n\nЕсли акции на уровне отдельных товаров не применялись, возвращается пустой массив.",
"items": {
"properties": {
"amount_with_discount": {
"description": "Стоимость товаров со скидкой.",
"type": "string"
},
"amount_without_discount": {
"description": "Стоимость товаров без скидки.",
"type": "string"
},
"sequence": {
"description": "Порядок применения акций.",
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"items.sku": {
"description": "Уникальный ID предмета. Для предметов с типом `game_key` используется значение в формате `sku_drm`.",
"type": "string"
},
"items.type": {
"description": "Тип предмета.\nДля предмета с типом `bundle`, в том числе для пакета виртуальной валюты, в массиве `items` будут отображены:\nпараметры бандла или пакета виртуальной валюты;\nпредметы, которые входят в бандл, или валюты, которые входят в пакет.\n \nТип `value_point` используется при [операциях с баллами лояльности](/ru/solutions/loyalty-as-service/) – их оплате или начислении.",
"enum": [
"virtual_good",
"virtual_currency",
"game_key",
"bundle",
"value_point"
],
"type": "string"
},
"currency-type": {
"description": "Тип валюты платежа. Для бесплатного заказа указывается значение `unknown`.",
"enum": [
"real",
"virtual",
"unknown",
"loyalty_point"
],
"type": "string",
"x-enumDescriptions": {
"loyalty_point": "баллы лояльности",
"real": "реальная валюта",
"unknown": "бесплатный заказ",
"virtual": "виртуальная валюта"
}
},
"order.promotions": {
"description": "Примененные акции для всего заказа.\nМассив возвращается, если:\n - Акция влияет на общую сумму покупки при использовании промокода с настройкой **Скидка на покупку**.\n - Скидки на покупку нет, но к заказу добавляются бонусные товары. В этом случае значения стоимости со скидкой ([amount_with_discount](/ru/webhooks/#operation/order-cancellation!path=order/promotions/amount_with_discount&t=request)) и без нее ([amount_without_discount](/ru/webhooks/#operation/order-cancellation!path=order/promotions/amount_without_discount&t=request)) передаются и совпадают, поскольку скидка не применяется.\n\nЕсли акции на уровне заказа не применялись, передается пустой массив.",
"items": {
"properties": {
"amount_with_discount": {
"description": "Стоимость товаров со скидкой.",
"type": "string"
},
"amount_without_discount": {
"description": "Стоимость товаров без скидки.",
"type": "string"
},
"sequence": {
"description": "Порядок применения акций.",
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"user.phone": {
"description": "Номер телефона пользователя (в международном формате).",
"type": "string"
},
"order": {
"description": "Объект с информацией о заказе. Чтобы получать эту информацию, в [Личном кабинете](https://publisher.xsolla.com/) в разделе **Настройки проекта > Вебхуки > Расширенные настройки** установите переключатель **Добавить объект order в вебхук** в положение **Вкл**.",
"type": "object"
},
"locale": {
"description": "Язык интерфейса пользователя. Используется [двухбуквенное обозначение](https://developers.xsolla.com/ru/doc/pay-station/features/localization/) (в нижнем регистре).",
"type": "string"
},
"quantity": {
"deprecated": true,
"description": "Количество товара, которое может приобрести один пользователь. Чтобы не ограничивать количество товара, передайте `null`. Чтобы товар был недоступен для покупки, но отображался в каталоге, передайте `0`.\n\nЕсли вы используете этот параметр, информация о лимите покупок не отображается в каталоге. Чтобы информация о лимите покупок отображалась в каталоге (например, `7/10`), передайте пару `available` и `total` вместо `quantity`.",
"type": "integer"
},
"available": {
"description": "Оставшееся количество товара, которое может приобрести пользователь.\n\nЧтобы информация о лимите покупок отображалась в каталоге (например, `7/10`), передайте пару `available` и `total`.",
"type": "integer"
},
"total": {
"description": "Максимальное количество товара, которое может приобрести один пользователь.\n\nЗначение должно быть больше 0.Чтобы информация о лимите покупок отображалась в каталоге (например, `7/10`), передайте пару `available` и `total`.",
"exclusiveMinimum": 0,
"type": "integer"
},
"bundle_content": {
"description": "Массив объектов с содержимым бандла для отображения в каталоге. Может использоваться только для бандлов с типом [partner_side_content](https://developers.xsolla.com/ru/api/shop-builder/operation/admin-create-bundle/).",
"items": {
"properties": {
"description": {
"description": "Описание товара для отображения в каталоге в составе бандла. Если не указано, передается `null`.",
"maxLength": 255,
"type": "string"
},
"image_url": {
"description": "URL-адрес изображения товара для отображения в каталоге в составе бандла. Поддерживается только протокол HTTPS. Если URL-адрес не указан, передается `null`.",
"format": "uri",
"maxLength": 255,
"type": "string"
},
"name": {
"description": "Название товара для отображения в каталоге в составе бандла. Если не указано, передается пустая строка.",
"maxLength": 255,
"type": "string"
},
"quantity": {
"default": 1,
"description": "Количество товара в составе бандла.",
"minimum": 1,
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"date_from": {
"description": "Дата, начиная с которой товар доступен для продажи. Используется [стандарт RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339).",
"type": "string"
},
"date_until": {
"description": "Дата, начиная с которой товар недоступен для продажи. Используется [стандарт RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339).",
"type": "string"
},
"description": {
"description": "Описание товара для отображения в каталоге. Заменяет сохраненное название товара.",
"maxLength": 255,
"type": "string"
},
"image_url": {
"description": "URL-адрес изображения для отображения в каталоге. Заменяет сохраненный URL-адрес изображения. Поддерживается только протокол HTTPS. Если URL-адрес не соответствует требованиям, он будет проигнорирован.",
"format": "uri",
"maxLength": 255,
"type": "string"
},
"json_attributes": {
"description": "Объект JSON, содержащий атрибуты товара и их значения. Заменяет [custom_attributes](https://developers.xsolla.com/ru/webhooks/operation/successful-order-payment/#!path=items/0/custom_attributes&t=request), сохраненный для товара. Если JSON не соответствует требованиям или превышает допустимую длину, он будет проигнорирован.",
"format": "json",
"maxLength": 500,
"type": "object"
},
"name": {
"description": "Название товара для отображения в каталоге. Заменяет сохраненное название товара.",
"maxLength": 255,
"type": "string"
},
"sku": {
"description": "Уникальный ID предмета, который вы указали в Личном кабинете. Должен быть передан либо `sku`, либо `item_id`.",
"type": "string"
},
"item_id": {
"description": "Уникальный ID предмета на стороне Xsolla. Должен быть передан либо `sku`, либо `item_id`.",
"type": "integer"
},
"user.public_id": {
"description": "Public ID пользователя.",
"type": "string"
},
"appPlayerId": {
"description": "ID пользователя, установленный владельцем приложения в момент регистрации пользователя (customer user ID).\nПримечание
Xsolla передает эти данные в объекте custom_parameters в методе получения платежного токена.
",
"type": "string"
}
},
"responses": {
"204": {
"description": "Верните, чтобы сообщить об успешной обработке вехбука."
},
"400": {
"content": {
"application/json": {
"schema": {
"properties": {
"error": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"description": "Верните в случае ошибки в предоставленной информации (например, обязательный параметр не передан, или авторизация не прошла).",
"x-examples": {
"application/json": {
"INCORRECT_AMOUNT": {
"summary": "Incorrect amount",
"value": {
"error": {
"code": "INCORRECT_AMOUNT",
"message": "Incorrect amount"
}
}
},
"INCORRECT_INVOICE": {
"summary": "Incorrect invoice",
"value": {
"error": {
"code": "INCORRECT_INVOICE",
"message": "Incorrect invoice"
}
}
},
"INVALID_PARAMETER": {
"summary": "Invalid parameter",
"value": {
"error": {
"code": "INVALID_PARAMETER",
"message": "Invalid parameter"
}
}
},
"INVALID_SIGNATURE": {
"summary": "Invalid signature",
"value": {
"error": {
"code": "INVALID_SIGNATURE",
"message": "Invalid signature"
}
}
},
"INVALID_USER": {
"summary": "Invalid user",
"value": {
"error": {
"code": "INVALID_USER",
"message": "Invalid user"
}
}
}
}
}
},
"500": {
"description": "Верните, чтобы сообщить о временных ошибках на ваших серверах."
},
"400-payment": {
"content": {
"application/json": {
"schema": {
"properties": {
"error": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"description": "Верните в случае ошибки в предоставленной информации (например, обязательный параметр не передан, или авторизация не прошла). В этом случае денежные средства пользователя списываются, но покупка не осуществляется. Чтобы оформить возврат платежа, необходимо обратиться в службу поддержки Xsolla на support@xsolla.com.",
"x-examples": {
"application/json": {
"INCORRECT_AMOUNT": {
"summary": "Incorrect amount",
"value": {
"error": {
"code": "INCORRECT_AMOUNT",
"message": "Incorrect amount"
}
}
},
"INCORRECT_INVOICE": {
"summary": "Incorrect invoice",
"value": {
"error": {
"code": "INCORRECT_INVOICE",
"message": "Incorrect invoice"
}
}
},
"INVALID_PARAMETER": {
"summary": "Invalid parameter",
"value": {
"error": {
"code": "INVALID_PARAMETER",
"message": "Invalid parameter"
}
}
},
"INVALID_SIGNATURE": {
"summary": "Invalid signature",
"value": {
"error": {
"code": "INVALID_SIGNATURE",
"message": "Invalid signature"
}
}
},
"INVALID_USER": {
"summary": "Invalid user",
"value": {
"error": {
"code": "INVALID_USER",
"message": "Invalid user"
}
}
}
}
}
}
}
},
"x-tagGroups": [
{
"name": "Проверка пользователей",
"tags": [
"user-validation"
]
},
{
"name": "Payments",
"tags": [
"payments"
]
},
{
"name": "Игровые сервисы",
"tags": [
"combined-webhooks",
"separate-webhooks",
"personalization"
]
},
{
"name": "Антифрод",
"tags": [
"anti-fraud"
]
},
{
"name": "Subscriptions",
"tags": [
"subscriptions"
]
}
]
}