(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 example of implementing signature generation:\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 example of implementing signature generation:\n\n```php\n\n```\n\n### Node.js example of implementing signature generation:\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## Sending responses to webhook\n\nTo confirm receipt of the webhook, your server must return:\n* `200`, `201`, or `204` HTTP code in case of a successful response.\n* `400` HTTP code with description of the problem if the specified user was not found or an invalid signature was passed.\nYour webhook handler may also return a `5xx` HTTP code in case of temporary issues on your server.\n\nIf the Xsolla server did not receive a response to Successful payment for order and Order cancellation webhooks or received a response with a `5xx` code, the webhooks are resent according to the following schedule:\n* 2 attempts with a 5-minute interval\n* 7 attempts with a 15-minute interval\n* 10 attempts with a 60-minute interval\n\nMaximum of 20 attempts to send webhooks are made within 12 hours from the first attempt.\n\nThe retry logic for the Payment and Refund webhooks is described on the respective webhook page.\n\n\n
Notice
\n
The payment will still be refunded to the user if all of the following conditions are met:
- The refund was initiated by Xsolla.
- In response to a webhook, a
4xx status code was returned, or no response was received after all retry attempts, or a 5xx status code was returned.
\n
\n \n \n | Code | \n Message | \n
\n \n \n \n | INVALID_USER | \n Invalid user | \n
\n \n | INVALID_PARAMETER | \n Invalid parameter | \n
\n \n | INVALID_SIGNATURE | \n Invalid signature | \n
\n \n | INCORRECT_AMOUNT | \n Incorrect amount | \n
\n \n | INCORRECT_INVOICE | \n Incorrect invoice | \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# Best practices\n\n## Security\n\nFollow these guidelines:\n\n* Use HTTPS only, with a valid certificate.\n* Always verify the signature against the raw request body — don’t parse or re-encode the data.\n* Don’t pass sensitive data in URLs and avoid exposing technical details in error messages.\n* Exempt the webhook endpoint from [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) middleware — incoming requests from Xsolla don’t include a CSRF token and will be rejected without this setting.\n* Allowlist [Xsolla IP addresses](/webhooks/section/webhook-listener).\n\n\n## Webhook handler architecture\n\nFollow these guidelines:\n\n1. Accept the `POST` request with the body and headers as-is, **without modification**.\n2. [Verify the webhook signature](/webhooks/section/webhook-listener/generation-of-signature) and return the appropriate status code:\n * `4xx` — if the signatures don’t match;\n * `2xx` — in success cases. We recommend returning `204 No Content` **before** executing the main business logic. `200 OK` is also acceptable.\n3. Pass the payload to an async job or queue for further processing.\n4. Implement [idempotency](https://en.wikipedia.org/wiki/Idempotence#Computer_science_meaning). You must ensure your system can handle [receiving the same webhook more than once](/webhooks/section/webhook-listener/sending-responses-to-webhook).\n\n**Flow example:**\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## Idempotency and duplicates\n\nFollow these guidelines:\n\n* Use the transaction ID and/or [external ID](/dev-resources/faq/payments/#faq_payments_q_new_transaction_external_id), order ID as idempotency keys.\n* Store processed IDs and return the previous result if a duplicate is received.\n* Avoid item regranting, duplicate database entries, and double charges.\n* Keep in mind that with sequential delivery, a failure on an earlier event blocks the processing of all subsequent ones.\n\n## System resilience\n\nFollow these guidelines:\n\n* Use queues and async processing for resource-intensive operations such as third-party API calls, billing, and item granting.\n* Set timeouts on the webhook handler (1–3 s). For transient failures, rely on the [Xsolla retry mechanism](/webhooks/section/webhook-listener/sending-responses-to-webhook).\n* Don’t implement retries in the webhook handler — redelivery is handled by Xsolla.\n* Log webhook delivery timestamps and processing statuses; set up alerts for spikes in `5xx` errors and redeliveries.\n* Propagate correlation IDs from the webhook into your logs and monitoring system (APM).\n* Set up error logging and monitoring. For non-recoverable failures, move jobs to a dead-letter queue (DLQ). Develop a secure tool for replaying events that is protected by an idempotency mechanism.\n\n## Implementation examples\n\n**Success purchase — item granted on first attempt:**\n\n\n\n**Duplicate delivery (partner timeout on first attempt):**\n\n\n\n**Refund:**\n\n\n\n**Partner outage**:\n\n\n\n# FAQs\n\n## Do I need to use HTTPS for a webhook protocol?\n\nYes.\n\n## Can I receive payment webhooks at several URLs?\n\nNo. Payment webhooks use the Server-to-Server protocol and are sent to a single URL specified in the [project settings](/webhooks/section/set-up-webhooks-in-publisher-account). If you would like to receive notifications in your game, website, or mobile application, set up sending webhooks on your server to pass data between Xsolla and your game. You can also test webhooks from the developer console.\n\n\n
Note
\n
If you are testing the integration locally, `POST` requests from Xsolla don’t reach URLs like http://localhost:3000/my-webhook-endpoint. Use services such as Ngrok that allow you to create a tunnel for external access, enabling you to receive requests from Xsolla locally. E.g., you can read more about this in the ngrok documentation.
\n
\n
Note
\n
The notification type is sent in the notification_type parameter.
\n
\n \n \n | Webhook | \n Notification type | \n Description | \n
\n \n \n \n | User validation | \n user_validation | \n Sent to check if a user exists in the game. | \n
\n \n | User search | \n user_search | \n Sent to get user info based on public user ID. | \n
\n \n | Payment | \n payment | \n Sent when a user completes a payment. | \n
\n \n | Refund | \n refund | \n Sent when a payment must be canceled for any reason. | \n
\n \n | Partial refund | \n partial_refund | \n Sent when a payment must be partially canceled for any reason. | \n
\n \n | Declined payment | \n ps_declined | \n Sent when a payment is declined by payment system. | \n
\n \n | AFS rejected transaction | \n afs_reject | \n Sent when a transaction is declined during an AFS check. | \n
\n \n | AFS updated blocklist | \n afs_black_list | \n Sent when the AFS blocklist is updated. | \n
\n \n | Created subscription | \n create_subscription | \n Sent when a user creates a subscription. | \n
\n \n | Updated subscription | \n update_subscription | \n Sent when a subscription is renewed or changed. | \n
\n \n | Canceled subscription | \n cancel_subscription | \n Sent when a subscription is canceled. | \n
\n \n | Nonrenewing subscription | \n non_renewal_subscription | \n Sent when status is set to nonrenewing. | \n
\n \n | Add payment account | \n payment_account_add | \n Sent when a user adds or saves a payment account. | \n
\n \n | Remove payment account | \n payment_account_remove | \n Sent when a user removes the payment account from saved accounts. | \n
\n \n | User validation in Web Shop | \n - | \n Sent from a Web Shop site to check if a user exists in the game. | \n
\n \n | Catalog personalization on partner’s side | \n partner_side_catalog | \n Sent when a user interacts with the store. | \n
\n \n | Successful payment for order | \n order_paid | \n Sent when an order is paid. | \n
\n \n | Order cancellation | \n order_canceled | \n Sent when an order is canceled. | \n
\n \n | Dispute | \n dispute | \n Sent when a new dispute is opened. | \n
\n \n
\n",
"title": "Webhooks",
"version": "1.0"
},
"servers": [
{
"url": "https://api.xsolla.com/merchant/v2"
}
],
"tags": [
{
"name": "user-validation",
"x-displayName": "User validation"
},
{
"name": "payments",
"x-displayName": "Payments"
},
{
"name": "game-services",
"x-displayName": "Game services"
},
{
"name": "anti-fraud",
"x-displayName": "Anti-fraud"
},
{
"name": "subscriptions",
"x-displayName": "Subscriptions"
},
{
"name": "combined-webhooks",
"x-displayName": "Combined webhooks"
},
{
"name": "separate-webhooks",
"x-displayName": "Separate webhooks"
},
{
"name": "personalization",
"x-displayName": "Personalization webhook"
}
],
"webhooks": {
"user-validation": {
"post": {
"summary": "User validation",
"description": "Xsolla sends a webhook with the `user_validation` type to the webhook URL to verify that a user is registered in the game. The request is sent multiple times as part of the payment process:\n\n* when a user chooses a payment method in the payment UI\n* when a user enters data in the payment form, e.g., bank card data or the ZIP code when paying via PayPal\n* when a user clicks **Pay now** to proceed with payment\n* when payment process is completed and the transaction status changes to `done`\n\nThe request is sent when paying with any payment methods.\n\nWhen you save the webhook URL in Publisher Account, you can give permissions to receive detailed information in webhooks. To do that, set the necessary toggles to active in Publisher Account in the Project settings > Webhooks > Advanced settings section.\n\n\n\n\n \n \n | Toggle | \n Description | \n
\n \n \n \n | Send only necessary user parameters without sensitive data | \n Only the following information about the user is passed in the webhook: | \n
\n \n | Send custom parameters | \n Information about custom token parameters is passed in the webhook. | \n
\n \n
\n",
"tags": [
"user-validation"
],
"operationId": "user-validation",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"notification_type"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"type": "object",
"description": "Custom project settings (object).",
"properties": {
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
},
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
}
}
},
"user": {
"type": "object",
"description": "User details (object).",
"required": [
"id"
],
"properties": {
"ip": {
"$ref": "#/components/schemas/user.ip"
},
"phone": {
"$ref": "#/components/schemas/user.phone"
},
"email": {
"$ref": "#/components/schemas/user.email"
},
"id": {
"$ref": "#/components/schemas/user.id"
},
"name": {
"$ref": "#/components/schemas/user.name"
},
"country": {
"$ref": "#/components/schemas/user.country"
}
}
}
}
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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}'\n"
},
{
"lang": "PHP",
"label": "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);\n"
},
{
"lang": "HTTP",
"label": "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}\n"
}
]
}
},
"user-search": {
"post": {
"summary": "User search",
"description": "Public User ID is a parameter that uniquely identifies the user and is known to them, unlike User ID (Public User ID can be email, screen name, etc). Xsolla sends a webhook with the `user_search` type when a purchase is made outside the game store (e.g., via cash kiosks).",
"tags": [
"user-validation"
],
"operationId": "user-search",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"notification_type",
"user"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"type": "object",
"description": "Custom project settings (object).",
"properties": {
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
},
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
}
}
},
"user": {
"type": "object",
"description": "User details (object).",
"required": [
"id"
],
"properties": {
"id": {
"$ref": "#/components/schemas/user.id"
},
"public_id": {
"$ref": "#/components/schemas/user.public_id"
}
}
}
}
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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}'\n"
},
{
"lang": "PHP",
"label": "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);\n"
},
{
"lang": "HTTP",
"label": "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}\n"
}
]
}
},
"payment": {
"post": {
"summary": "Payment",
"description": "When a user completes a payment, Xsolla sends payment details in a webhook with the `payment` type to the webhook URL.\n\nThe expected response codes are described in the Responses section, but you can use other response codes as well:\n\n\n \n \n | Response code | \n Description | \n
\n \n \n \n 200, 201, 204 | \n A successful response. | \n
\n \n 4xx | \n An error occurred. For example, if the specified user was not found or an invalid signature was passed. | \n
\n \n 5xx | \n A temporary server error. When this response is received, Xsolla will automatically retry sending the webhook, gradually increasing the interval between attempts until your listener confirms receiving. The maximum number of retries is 12 retry attempts over a 48-hour period. | \n
\n \n
\n\nWhen you save the webhook URL in Publisher Account, you can also set up receiving additional information in webhooks.\n\n\n\n\n \n \n | Toggle | \n Description | \n
\n \n \n \n | Show info about the saved payment account | \n Information about the saved payment method is passed in the payment_account custom object. | \n
\n \n | Show info about transactions via saved payment methods | \n Information is passed in the following custom parameters of the webhook: saved_payment_method:0 — the saved payment method was not used1 — the payment method was saved when making the current payment2 — the previously saved payment method is used
payment_type:1 — one-time payment2 — recurring payment
| \n
\n \n | Add order object to webhook | \n Information about the order is passed in the order object of the Payment webhook. | \n
\n \n | Send only necessary user parameters without sensitive data | \n Only the following information about the user is passed in the webhook: | \n
\n \n | Show card BIN and suffix | \n The following information about the bank card number is passed in the webhook: - the first 6 digits in the
card_bin parameter - the last 4 digits in the
card_suffix
| \n
\n \n | Show card brand | \n The brand of the card used for making the payment. For example, Mastercard or Visa. | \n
\n \n
\n\n\n
Notice
\n
The set of fields sent in a webhook depends on:
- the advanced settings configured in Publisher Account
- the custom settings configured on the Xsolla side
If you have any questions, contact your Customer Success Manager or email to csm@xsolla.com.
\n
\n
Notice
\n
The payment will still be refunded to the user if all of the following conditions are met:
- The refund was initiated by Xsolla.
- In response to a webhook, a
4xx status code was returned, or no response was received after all retry attempts, or a 5xx status code was returned.
\n
\n \n \n | Toggle | \n Description | \n
\n \n \n \n | Show info about transactions via saved payment methods | \n Information is passed in the following custom parameters of the webhook: saved_payment_method:0 — the saved payment method was not used1 — the payment method was saved when making the current payment2 — the previously saved payment method is used
payment_type:1 — one-time payment2 — recurring payment
| \n
\n \n
\n\nRefund codes:\n\n\n \n \n | Code | \n Reason | \n Description | \n
\n \n \n \n | 1 | \n Cancellation by the user request / the game request | \n Cancellation initiated from Publisher Account. | \n
\n \n | 2 | \n Chargeback | \n Transaction chargeback requested. | \n
\n \n | 3 | \n Integration error | \n Issues in integration between Xsolla and the game.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 4 | \n Potential fraud | \n Fraud suspected.
Recommendation: Add the user to blocklist. | \n
\n \n | 5 | \n Test payment | \n Test transaction followed by cancellation.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 6 | \n User invoice expired | \n Invoice overdue (used for postpaid model). | \n
\n \n | 7 | \n Fraud notification from PS | \n Payment refused by payment system. Potential fraud detected by PS.
Recommendation: Add the user to blocklist. | \n
\n \n | 8 | \n Cancellation by the PS request | \n Cancellation requested by payment system.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 9 | \n Cancellation by the user request | \n The user was not satisfied with the game or the purchase for any reason.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 10 | \n Cancellation by the game request | \n Cancellation requested by the game.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 11 | \n Account holder called to report fraud | \n The account owner states that they didn’t make the transaction. | \n
\n \n | 12 | \n Friendly fraud | \n Friendly fraud reported. | \n
\n \n | 13 | \n Duplicate | \n Duplicate transaction for the same invoice. | \n
\n \n
\n",
"tags": [
"payments"
],
"operationId": "refund",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"notification_type",
"transaction",
"payment_details"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"type": "object",
"description": "Custom project settings (object).",
"properties": {
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
},
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
}
}
},
"user": {
"type": "object",
"description": "User details (object).",
"required": [
"id"
],
"properties": {
"ip": {
"$ref": "#/components/schemas/user.ip"
},
"phone": {
"$ref": "#/components/schemas/user.phone"
},
"email": {
"$ref": "#/components/schemas/user.email"
},
"id": {
"$ref": "#/components/schemas/user.id"
},
"name": {
"$ref": "#/components/schemas/user.name"
},
"country": {
"$ref": "#/components/schemas/user.country"
},
"zip": {
"$ref": "#/components/schemas/user.zip"
}
}
},
"purchase": {
"type": "object",
"description": "Purchase details (object).",
"required": [
"total"
],
"properties": {
"checkout": {
"type": "object",
"description": "Checkout details (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Purchase amount."
}
}
},
"subscription": {
"type": "object",
"description": "Subscription details (object).",
"properties": {
"plan_id": {
"$ref": "#/components/schemas/subscription.plan_id"
},
"subscription_id": {
"$ref": "#/components/schemas/subscription.subscription_id"
},
"tags": {
"$ref": "#/components/schemas/subscription.tags"
},
"date_create": {
"$ref": "#/components/schemas/subscription.date_create"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"$ref": "#/components/schemas/amount-float"
}
}
},
"total": {
"type": "object",
"description": "Total price of purchase (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Total payment amount."
}
}
}
}
},
"transaction": {
"type": "object",
"description": "Transaction details (object).",
"properties": {
"id": {
"type": "integer",
"description": "Transaction ID."
},
"external_id": {
"type": "string",
"description": "Transaction external ID."
},
"payment_method_order_id": {
"type": "string",
"description": "Payment ID in the payment system."
},
"dry_run": {
"type": "integer",
"description": "Test transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real."
},
"agreement": {
"type": "integer",
"description": "Agreement ID."
}
}
},
"refund_details": {
"type": "object",
"description": "Refund details (object).",
"properties": {
"code": {
"type": "integer",
"description": "Code ID."
},
"reason": {
"type": "string",
"description": "Refund reason."
},
"author": {
"type": "string",
"description": "Refund initiator. The field value is passed according to the table:\n\n\n \n \n | Refund initiator | \n Field value | \n
\n \n \n \n | Game (via API). | \n API | \n
\n \n | Publisher Account user (automatic refund). | \n User email | \n
\n \n | Publisher Account user (with assistance from Xsolla customer support). | \n support@xsolla.com | \n
\n \n | Xsolla (with assistance from Xsolla customer support). | \n support@xsolla.com | \n
\n \n
\n"
}
}
},
"payment_details": {
"type": "object",
"description": "Payment details (object).",
"properties": {
"payment": {
"type": "object",
"description": "Amount paid by the user (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"payment_method_sum": {
"type": "object",
"description": "Amount debited from the payment system.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"xsolla_balance_sum": {
"type": "object",
"description": "Amount debited from Xsolla balance.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"payout": {
"type": "object",
"description": "Payout details (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"vat": {
"type": "object",
"description": "VAT details (object; EU only).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "VAT rate."
}
}
},
"payout_currency_rate": {
"type": "string",
"description": "Exchange rate between payment and payout currencies."
},
"country_wht": {
"type": "object",
"description": "Withholding tax applied in specific countries due to cross-border transactions (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "Country withholding tax rate, %."
}
}
},
"user_acquisition_fee": {
"type": "object",
"description": "Total amount of user acquisition fees deducted for the purchases made via affiliate networks and influencers (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "User acquisition fee rate, %."
}
}
},
"xsolla_fee": {
"type": "object",
"description": "Xsolla fee (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"payment_method_fee": {
"type": "object",
"description": "Payment system fee.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"sales_tax": {
"type": "object",
"description": "Sales tax (object; USA and Canada only).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "Sales tax rate."
}
}
},
"direct_wht": {
"type": "object",
"description": "Direct withholding tax.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "Direct withholding tax rate."
}
}
},
"repatriation_commission": {
"type": "object",
"description": "Object with data on repatriation costs, imposed on Xsolla by third parties.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
}
}
},
"custom_parameters": {
"type": "object",
"description": "Your custom parameters."
}
}
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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}'\n"
},
{
"lang": "PHP",
"label": "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);\n"
},
{
"lang": "HTTP",
"label": "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}\n"
}
]
}
},
"partial-refund": {
"post": {
"summary": "Partial refund",
"description": "When a partial refund is made, Xsolla sends details of the canceled transaction in a webhook with the `partial_refund` type to the webhook URL. Learn more about the partial refund process in these [instructions](/doc/pay-station/features/refund/#pay_station_features_refund_how_it_works_partial_refund_flow).\n\nWhen you save the webhook URL in Publisher Account, you can give permissions to receive detailed information in webhooks. To do that, set the following toggle to active in Publisher Account in the Project settings > Webhooks > Advanced settings section.\n\n\n\n\n \n \n | Toggle | \n Description | \n
\n \n \n \n | Show info about transactions via saved payment methods | \n Information is passed in the following custom parameters of the webhook: saved_payment_method:0 — the saved payment method was not used1 — the payment method was saved when making the current payment2 — the previously saved payment method is used
payment_type:1 — one-time payment2 — recurring payment
| \n
\n \n
\n\nRefund codes:\n\n\n \n \n | Code | \n Reason | \n Description | \n
\n \n \n \n | 1 | \n Cancellation by the user request / the game request | \n Cancellation initiated from Publisher Account. | \n
\n \n | 3 | \n Integration error | \n Issues in integration between Xsolla and the game.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 5 | \n Test payment | \n Test transaction followed by cancellation.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 7 | \n Fraud notification from PS | \n Payment refused by payment system. Potential fraud detected by PS.
Recommendation: Add the user to blocklist. | \n
\n \n | 9 | \n Cancellation by the user request | \n The user was not satisfied with the game or the purchase for any reason.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 10 | \n Cancellation by the game request | \n Cancellation requested by the game.
Recommendation: Do not add the user to blocklist. | \n
\n \n
\n",
"tags": [
"payments"
],
"operationId": "partial-refund",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"notification_type",
"transaction",
"payment_details"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"type": "object",
"description": "Custom project settings (object).",
"properties": {
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
},
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
}
}
},
"user": {
"type": "object",
"description": "User details (object).",
"required": [
"id"
],
"properties": {
"ip": {
"$ref": "#/components/schemas/user.ip"
},
"phone": {
"$ref": "#/components/schemas/user.phone"
},
"email": {
"$ref": "#/components/schemas/user.email"
},
"id": {
"$ref": "#/components/schemas/user.id"
},
"name": {
"$ref": "#/components/schemas/user.name"
},
"country": {
"$ref": "#/components/schemas/user.country"
},
"zip": {
"$ref": "#/components/schemas/user.zip"
}
}
},
"purchase": {
"type": "object",
"description": "Purchase details (object).",
"required": [
"total"
],
"properties": {
"checkout": {
"type": "object",
"description": "Checkout details (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Purchase amount."
}
}
},
"total": {
"type": "object",
"description": "Total price of purchase (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Partial refund payment amount."
}
}
}
}
},
"transaction": {
"type": "object",
"description": "Transaction details (object).",
"properties": {
"id": {
"type": "integer",
"description": "Transaction ID."
},
"external_id": {
"type": "string",
"description": "Transaction external ID."
},
"dry_run": {
"type": "integer",
"description": "Test transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real."
},
"agreement": {
"type": "integer",
"description": "Agreement ID."
},
"date": {
"type": "string",
"description": "Date of transaction."
}
}
},
"refund_details": {
"type": "object",
"description": "Refund details (object).",
"properties": {
"code": {
"type": "integer",
"description": "Code ID."
},
"reason": {
"type": "string",
"description": "Refund reason."
},
"author": {
"type": "string",
"description": "Refund initiator. The field value is passed according to the table:\n\n\n \n \n | Refund initiator | \n Field value | \n
\n \n \n \n | Game (via API). | \n API | \n
\n \n | Publisher Account user (automatic refund). | \n User email | \n
\n \n | Publisher Account user (with assistance from Xsolla customer support). | \n support@xsolla.com | \n
\n \n | Xsolla (with assistance from Xsolla customer support). | \n support@xsolla.com | \n
\n \n
\n"
},
"date": {
"type": "string",
"description": "Date of refund."
}
}
},
"payment_details": {
"type": "object",
"description": "Payment details (object).",
"properties": {
"payment": {
"type": "object",
"description": "Amount paid by the user (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"payment_method_sum": {
"type": "object",
"description": "Amount debited from the payment system.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"xsolla_balance_sum": {
"type": "object",
"description": "Amount debited from Xsolla balance.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"payout": {
"type": "object",
"description": "Payout details (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"vat": {
"type": "object",
"description": "VAT details (object; EU only).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "VAT rate."
}
}
},
"payout_currency_rate": {
"type": "string",
"description": "Exchange rate between payment and payout currencies."
},
"xsolla_fee": {
"type": "object",
"description": "Xsolla fee (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"payment_method_fee": {
"type": "object",
"description": "Payment system fee.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"sales_tax": {
"type": "object",
"description": "Sales tax (object; USA and Canada only).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "Sales tax rate."
}
}
},
"direct_wht": {
"type": "object",
"description": "Direct withholding tax.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "Direct withholding tax rate."
}
}
},
"repatriation_commission": {
"type": "object",
"description": "Object with data on repatriation costs, imposed on Xsolla by third parties.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
}
}
},
"custom_parameters": {
"type": "object",
"description": "Your custom parameters."
}
}
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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}'\n"
},
{
"lang": "PHP",
"label": "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);\n"
},
{
"lang": "HTTP",
"label": "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}\n"
}
]
}
},
"payment-declined": {
"post": {
"summary": "Declined payment",
"description": "If a transaction is declined by a payment system, Xsolla sends the transaction details in a webhook of the `ps_declined` type to your configured webhook URL.\nThe webhook is sent during the authorization or payment processing stage.\nIn this case, the [payment](/webhooks/operation/payment/)\\ [order_paid](/webhooks/operation/successful-order-payment/) webhook is not sent.\n\nTypical reasons for payment system declines:\n\n* Card authorization failed (for example, the payment system could not complete the authorization process due to a technical error or no response from the bank) or was declined (for example, the bank responded but refused the transaction due to insufficient funds or invalid card details).\n* 3-D Secure verification failed, was not completed, or the user confirmation timed out.\n* The processor or acquiring bank is temporarily unavailable or returns a hard decline due to an irreversible error, such as a closed account or an invalid card number. Retrying without addressing the underlying issue will not result in a successful transaction.\n\nShould not be confused with:\n\n* Anti-fraud rejections, which are reported via the [afs_reject](https://developers.xsolla.com/webhooks/operation/afs-rejected-transaction/) webhook.\n* Refunds and partial refunds after a successful payment, which are reported via the [refund](https://developers.xsolla.com/webhooks/operation/refund/) and [partial_refund](https://developers.xsolla.com/webhooks/operation/partial-refund/) webhooks.\n\n\n
Note
\n
To receive the ps_declined webhook, contact your Customer Success Manager or email csm@xsolla.com.
\n
\n \n \n | Code | \n Reason | \n Description | \n
\n \n \n \n | 1 | \n Cancellation by the user request / the game request | \n Cancellation initiated from Publisher Account. | \n
\n \n | 2 | \n Chargeback | \n Transaction chargeback requested. | \n
\n \n | 3 | \n Integration error | \n Issues in integration between Xsolla and the game.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 4 | \n Potential fraud | \n Fraud suspected.
Recommendation: Add the user to blocklist. | \n
\n \n | 5 | \n Test payment | \n Test transaction followed by cancellation.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 6 | \n User invoice expired | \n Invoice overdue (used for postpaid model). | \n
\n \n | 7 | \n Fraud notification from PS | \n Payment refused by payment system. Potential fraud detected by PS.
Recommendation: Add the user to blocklist. | \n
\n \n | 8 | \n Cancellation by the PS request | \n Cancellation requested by payment system.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 9 | \n Cancellation by the user request | \n The user was not satisfied with the game or the purchase for any reason.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 10 | \n Cancellation by the game request | \n Cancellation requested by the game.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 11 | \n Account holder called to report fraud | \n The account owner states that they didn’t make the transaction. | \n
\n \n | 12 | \n Friendly fraud | \n Friendly fraud reported. | \n
\n \n | 13 | \n Duplicate | \n Duplicate transaction for the same invoice. | \n
\n \n
\n"
},
"reason": {
"type": "string",
"description": "Refund reason."
},
"author": {
"type": "string",
"description": "Refund initiator. The field value is passed according to the table:\n\n\n \n \n | Refund initiator | \n Field value | \n
\n \n \n \n | Game (via API). | \n API | \n
\n \n | Publisher Account user (automatic refund). | \n User email | \n
\n \n | Publisher Account user (with assistance from Xsolla customer support). | \n support@xsolla.com | \n
\n \n | Xsolla (with assistance from Xsolla customer support). | \n support@xsolla.com | \n
\n \n
\n"
}
}
}
}
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400-payment"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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}'\n"
},
{
"lang": "PHP",
"label": "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);\n"
},
{
"lang": "HTTP",
"label": "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}\n"
}
]
}
},
"afs-rejected-transaction": {
"post": {
"summary": "Anti-fraud system rejected transaction",
"description": "When a transaction is declined during an Anti-fraud system check, Xsolla sends transaction details in the webhook with the `afs_reject` type to the webhook URL. To receive this webhook, contact your Customer Success Manager or email csm@xsolla.com.\n\nWhen you save the webhook URL in Publisher Account, you can give permissions to receive detailed information in webhooks. To do that, set the following toggle to active in Publisher Account in the Project settings > Webhooks > Advanced settings section.\n\n\n\n\n \n \n | Toggle | \n Description | \n
\n \n \n \n | Show info about transactions via saved payment methods | \n Information is passed in the following custom parameters of the webhook: saved_payment_method:0 — the saved payment method was not used1 — the payment method was saved when making the current payment2 — the previously saved payment method is used
payment_type:1 — one-time payment2 — recurring payment
| \n
\n \n
\n",
"tags": [
"anti-fraud"
],
"operationId": "afs-rejected-transaction",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"notification_type",
"transaction"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"type": "object",
"description": "Custom project settings (object).",
"properties": {
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
},
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
}
}
},
"user": {
"type": "object",
"description": "User details (object).",
"required": [
"id"
],
"properties": {
"ip": {
"$ref": "#/components/schemas/user.ip"
},
"phone": {
"type": "string",
"description": "User phone."
},
"email": {
"$ref": "#/components/schemas/user.email"
},
"id": {
"$ref": "#/components/schemas/user.id"
},
"name": {
"$ref": "#/components/schemas/user.name"
},
"country": {
"$ref": "#/components/schemas/user.country"
},
"zip": {
"$ref": "#/components/schemas/user.zip"
}
}
},
"transaction": {
"type": "object",
"description": "Transaction details (object).",
"properties": {
"id": {
"type": "integer",
"description": "Transaction ID."
},
"external_id": {
"type": "string",
"description": "Transaction external ID."
},
"dry_run": {
"type": "integer",
"description": "Test transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real."
},
"agreement": {
"type": "integer",
"description": "Agreement ID."
}
}
},
"refund_details": {
"type": "object",
"description": "Refund details (object).",
"properties": {
"code": {
"type": "integer",
"description": "Code ID.\n\n\n \n \n | Code | \n Reason | \n Description | \n
\n \n \n \n | 1 | \n Cancellation by the user request / the game request | \n Cancellation initiated from Publisher Account. | \n
\n \n | 2 | \n Chargeback | \n Transaction chargeback requested. | \n
\n \n | 3 | \n Integration error | \n Issues in integration between Xsolla and the game.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 4 | \n Potential fraud | \n Fraud suspected.
Recommendation: Add the user to blocklist. | \n
\n \n | 5 | \n Test payment | \n Test transaction followed by cancellation.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 6 | \n User invoice expired | \n Invoice overdue (used for postpaid model). | \n
\n \n | 7 | \n Fraud notification from PS | \n Payment refused by payment system. Potential fraud detected by PS.
Recommendation: Add the user to blocklist. | \n
\n \n | 8 | \n Cancellation by the PS request | \n Cancellation requested by payment system.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 9 | \n Cancellation by the user request | \n The user was not satisfied with the game or the purchase for any reason.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 10 | \n Cancellation by the game request | \n Cancellation requested by the game.
Recommendation: Do not add the user to blocklist. | \n
\n \n | 11 | \n Account holder called to report fraud | \n The account owner states that they didn’t make the transaction. | \n
\n \n | 12 | \n Friendly fraud | \n Friendly fraud reported. | \n
\n \n | 13 | \n Duplicate | \n Duplicate transaction for the same invoice. | \n
\n \n
\n"
},
"reason": {
"type": "string",
"description": "Refund reason."
},
"author": {
"type": "string",
"description": "Refund initiator. The field value is passed according to the table:\n\n\n \n \n | Refund initiator | \n Field value | \n
\n \n \n \n | Game (via API). | \n API | \n
\n \n | Publisher Account user (automatic refund). | \n User email | \n
\n \n | Publisher Account user (with assistance from Xsolla customer support). | \n support@xsolla.com | \n
\n \n | Xsolla (with assistance from Xsolla customer support). | \n support@xsolla.com | \n
\n \n
\n"
}
}
}
}
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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}'\n"
},
{
"lang": "PHP",
"label": "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);\n"
},
{
"lang": "HTTP",
"label": "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}\n"
}
]
}
},
"afs-rejected-blocklist": {
"post": {
"summary": "Anti-fraud blocklist update",
"description": "When the Anti-fraud system blocklist is updated (add or remove a parameter), Xsolla sends a webhook with the `afs_black_list` type to the webhook URL. The parameter addition is performed automatically on the Xsolla side or on request. Parameter removal is possible only on request. To receive this webhook, contact your Customer Success Manager or email csm@xsolla.com.",
"tags": [
"anti-fraud"
],
"operationId": "afs-rejected-blocklist",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"notification_type",
"event"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"event": {
"type": "object",
"description": "Object with information about AFS blocklist event.",
"properties": {
"action": {
"type": "string",
"description": "Type of event.",
"enum": [
"adding",
"removing"
]
},
"reason": {
"type": "string",
"description": "Cause of event.",
"enum": [
"chargeback",
"fraud_activity",
"suspicious_activity",
"ps_reported_fraud",
"linked_chargeback",
"partner_request",
"friendly_fraud",
"user_reported_fraud",
"linked_parameter",
"other_data_in_blacklist",
"by_afs_filters",
"wrongly_added",
"removed_by_cs_review",
"other_forgiveness_reason"
],
"x-enumDescriptions": {
"chargeback": "chargeback (addition)",
"fraud_activity": "fraud (addition)",
"suspicious_activity": "suspicious activity (addition)",
"ps_reported_fraud": "payment system notification about fraud (addition)",
"linked_chargeback": "chargeback relation (addition)",
"partner_request": "on request (addition)",
"friendly_fraud": "friendly fraud (addition)",
"user_reported_fraud": "user report about fraud (addition)",
"linked_parameter": "linked parameter in AFS blocklist (addition)",
"other_data_in_blacklist": "other parameters in AFS blocklist (addition)",
"by_afs_filters": "AFS filter (addition)",
"wrongly_added": "added by mistake (removing)",
"removed_by_cs_review": "removed after reporting to Xsolla technical support (removing)",
"other_forgiveness_reason": "other reason for removing (removing)"
}
},
"parameter": {
"type": "string",
"description": "Name of parameter by which event occurred.",
"enum": [
"nick",
"email",
"ps_account",
"ip_address",
"card_issuer",
"phone"
],
"x-enumDescriptions": {
"nick": "user’s nickname",
"email": "user’s email address",
"ps_account": "user’s billing account",
"ip_address": "user’s IP address",
"card_issuer": "user’s credit card issuing bank",
"phone": "user’s phone number"
}
},
"parameter_value": {
"type": "string",
"description": "Value of parameter by which event occurred."
},
"date_of_last_action": {
"type": "string",
"description": "Time of the latest AFS blocklist event in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format."
},
"transaction_id": {
"type": "string",
"description": "Transaction ID associated with the parameter by which the event occurred."
},
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
}
}
}
}
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "CURL",
"source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-H 'authorization: Signature 32c64a80d2527dc08906ae1891bac4489509b9f6' \\\n-d '{\n \"event\": {\n \"action\": \"adding\",\n \"date_of_last_action\": \"2020-11-27T10:09:05+03:00\",\n \"parameter\": \"email\",\n \"parameter_value\": \"email@example.com\",\n \"reason\": \"ps_reported_fraud\",\n \"transaction_id\": \"111111111\",\n \"project_id\": \"123456\"\n },\n \"notification_type\": \"afs_black_list\"\n}'\n"
},
{
"lang": "HTTP",
"label": "HTTP",
"source": "POST /your_uri HTTP/1.1\nhost: your.host\naccept: application/json\ncontent-type: application/json\ncontent-length: 233\nauthorization: Signature 32c64a80d2527dc08906ae1891bac4489509b9f6\n\n{\n \"event\": {\n \"action\": \"adding\",\n \"date_of_last_action\": \"2020-11-27T10:09:05+03:00\",\n \"parameter\": \"email\",\n \"parameter_value\": \"email@example.com\",\n \"reason\": \"ps_reported_fraud\",\n \"transaction_id\": \"111111111\",\n \"project_id\": \"123456\"\n },\n \"notification_type\": \"afs_black_list\"\n}\n"
}
]
}
},
"created-subscription": {
"post": {
"summary": "Created subscription",
"description": "When a user creates a subscription, Xsolla sends a webhook with the `create_subscription` type to the webhook URL.",
"tags": [
"subscriptions"
],
"operationId": "created-subscription",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"notification_type"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"type": "object",
"description": "Custom project settings (object).",
"properties": {
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
},
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
}
}
},
"user": {
"type": "object",
"description": "User details (object).",
"required": [
"id"
],
"properties": {
"id": {
"$ref": "#/components/schemas/user.id"
},
"name": {
"$ref": "#/components/schemas/user.name"
}
}
},
"subscription": {
"type": "object",
"description": "Subscription details (object).",
"properties": {
"plan_id": {
"$ref": "#/components/schemas/subscription.plan_id"
},
"tags": {
"$ref": "#/components/schemas/subscription.tags"
},
"subscription_id": {
"$ref": "#/components/schemas/subscription.subscription_id"
},
"product_id": {
"$ref": "#/components/schemas/subscription.product_id"
},
"date_create": {
"$ref": "#/components/schemas/subscription.date_create"
},
"date_next_charge": {
"$ref": "#/components/schemas/subscription.date_next_charge"
},
"trial": {
"type": "object",
"description": "Trial period (object).",
"properties": {
"value": {
"type": "integer",
"description": "Trial period."
},
"type": {
"type": "string",
"description": "Trial period type: day."
}
}
},
"is_gift": {
"$ref": "#/components/schemas/subscription.is_gift"
}
}
},
"custom_parameters": {
"type": "object",
"description": "Your custom parameters."
}
}
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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 }'\n"
},
{
"lang": "PHP",
"label": "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);\n"
},
{
"lang": "HTTP",
"label": "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}\n"
}
]
}
},
"updated-subscription": {
"post": {
"summary": "Updated subscription",
"description": "If some parameters in the subscription (`plan_id`, `date_next_charge`) were changed, and in the case of every subscription renewal, Xsolla sends a webhook with the `update_subscription` type to the webhook URL.",
"tags": [
"subscriptions"
],
"operationId": "updated-subscription",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"notification_type"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"type": "object",
"description": "Custom project settings (object).",
"properties": {
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
},
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
}
}
},
"user": {
"type": "object",
"description": "User details (object).",
"required": [
"id"
],
"properties": {
"id": {
"$ref": "#/components/schemas/user.id"
},
"name": {
"$ref": "#/components/schemas/user.name"
}
}
},
"subscription": {
"type": "object",
"description": "Subscription details (object).",
"properties": {
"plan_id": {
"$ref": "#/components/schemas/subscription.plan_id"
},
"tags": {
"$ref": "#/components/schemas/subscription.tags"
},
"subscription_id": {
"$ref": "#/components/schemas/subscription.subscription_id"
},
"product_id": {
"$ref": "#/components/schemas/subscription.product_id"
},
"date_next_charge": {
"$ref": "#/components/schemas/subscription.date_next_charge"
}
}
}
}
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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 }'\n"
},
{
"lang": "PHP",
"label": "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);\n"
},
{
"lang": "HTTP",
"label": "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}\n"
}
]
}
},
"canceled-subscription": {
"post": {
"summary": "Canceled subscription",
"description": "When a subscription is canceled, Xsolla sends a webhook with the `cancel_subscription` type to the webhook URL.",
"tags": [
"subscriptions"
],
"operationId": "canceled-subscription",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"notification_type"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"type": "object",
"description": "Custom project settings (object).",
"properties": {
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
},
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
}
}
},
"user": {
"type": "object",
"description": "User details (object).",
"required": [
"id"
],
"properties": {
"id": {
"$ref": "#/components/schemas/user.id"
},
"name": {
"$ref": "#/components/schemas/user.name"
}
}
},
"subscription": {
"type": "object",
"description": "Subscription details (object).",
"properties": {
"plan_id": {
"$ref": "#/components/schemas/subscription.plan_id"
},
"tags": {
"$ref": "#/components/schemas/subscription.tags"
},
"subscription_id": {
"$ref": "#/components/schemas/subscription.subscription_id"
},
"product_id": {
"$ref": "#/components/schemas/subscription.product_id"
},
"date_create": {
"$ref": "#/components/schemas/subscription.date_create"
},
"date_end": {
"$ref": "#/components/schemas/subscription.date_end"
}
}
}
}
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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 }'\n"
},
{
"lang": "PHP",
"label": "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);\n"
},
{
"lang": "HTTP",
"label": "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}\n"
}
]
}
},
"nonrenewing-subscription": {
"post": {
"summary": "Nonrenewing subscription",
"description": "When a subscription status is set to nonrenewing, Xsolla sends a webhook with the `non_renewal_subscription` type to the webhook URL. To receive this webhook, contact your Customer Success Manager or email csm@xsolla.com.",
"tags": [
"subscriptions"
],
"operationId": "nonrenewing-subscription",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"notification_type"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"type": "object",
"description": "Custom project settings (object).",
"required": [
"project_id"
],
"properties": {
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
},
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
}
}
},
"user": {
"type": "object",
"description": "User details (object).",
"required": [
"id"
],
"properties": {
"id": {
"$ref": "#/components/schemas/user.id"
},
"name": {
"$ref": "#/components/schemas/user.name"
},
"email": {
"$ref": "#/components/schemas/user.email"
}
}
},
"subscription": {
"type": "object",
"description": "Subscription details (object).",
"properties": {
"plan_id": {
"$ref": "#/components/schemas/subscription.plan_id"
},
"subscription_id": {
"$ref": "#/components/schemas/subscription.subscription_id"
},
"date_create": {
"$ref": "#/components/schemas/subscription.date_create"
},
"date_next_charge": {
"type": "string",
"description": "Next billing date. This is the date when a next payment was expected before user subscription was set to non-renew. Date and time per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Price in real currency."
}
}
}
}
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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 }'\n"
},
{
"lang": "PHP",
"label": "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);\n"
},
{
"lang": "HTTP",
"label": "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}\n"
}
]
}
},
"add-payment-account": {
"post": {
"summary": "Add payment account",
"description": "Xsolla sends a webhook with the `payment_account_add` type to the webhook URL whenever a user adds a payment account or saves a payment account when purchasing something inside the game. To receive this webhook, contact your Customer Success Manager or email csm@xsolla.com.",
"tags": [
"payments"
],
"operationId": "add-payment-account",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"notification_type"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"type": "object",
"description": "Custom project settings (object).",
"properties": {
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
},
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
}
}
},
"user": {
"type": "object",
"description": "User details (object).",
"required": [
"id"
],
"properties": {
"ip": {
"$ref": "#/components/schemas/user.ip"
},
"email": {
"$ref": "#/components/schemas/user.email"
},
"id": {
"$ref": "#/components/schemas/user.id"
},
"name": {
"$ref": "#/components/schemas/user.name"
},
"country": {
"$ref": "#/components/schemas/user.country"
},
"zip": {
"$ref": "#/components/schemas/user.zip"
}
}
},
"payment_account": {
"type": "object",
"description": "Payment account details (object).",
"required": [
"id"
],
"properties": {
"id": {
"$ref": "#/components/schemas/payment_account.id"
},
"name": {
"$ref": "#/components/schemas/payment_account.name"
},
"payment_method": {
"$ref": "#/components/schemas/payment_account.payment_method"
},
"country": {
"$ref": "#/components/schemas/payment_account.country"
},
"type": {
"$ref": "#/components/schemas/payment_account.type"
}
}
}
}
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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_add\",\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 \"name\": \"John Smith\",\n \"country\": \"US\",\n \"zip\": \"12345\"\n },\n \"payment_account\": {\n \"id\": \"12345678\",\n \"name\": \"email@example.com\",\n \"payment_method\": \"24\",\n \"country\": \"US\",\n \"type\": \"paypal\"\n }\n}'\n"
},
{
"lang": "HTTP",
"label": "HTTP",
"source": "POST /your/uri HTTP/1.1\nhost: your.hostname\naccept: application/json\ncontent-length: 255\ncontent-type: application/json\nauthorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843\n\n{\n \"notification_type\": \"payment_account_add\",\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 \"name\": \"John Smith\",\n \"country\": \"US\",\n \"zip\": \"12345\"\n },\n \"payment_account\": {\n \"id\": \"12345678\",\n \"name\": \"email@example.com\",\n \"payment_method\": \"24\",\n \"country\": \"US\",\n \"type\": \"paypal\"\n }\n}\n"
}
]
}
},
"remove-payment-account": {
"post": {
"summary": "Remove payment account",
"description": "When a user removes the payment account from saved accounts, Xsolla sends a webhook with the `payment_account_remove` type to the webhook URL. To receive this webhook, contact your Customer Success Manager or email csm@xsolla.com.",
"tags": [
"payments"
],
"operationId": "remove-payment-account",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"notification_type"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"type": "object",
"description": "Custom project settings (object).",
"properties": {
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
},
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
}
}
},
"user": {
"type": "object",
"description": "User details (object).",
"required": [
"id"
],
"properties": {
"email": {
"$ref": "#/components/schemas/user.email"
},
"id": {
"$ref": "#/components/schemas/user.id"
},
"name": {
"$ref": "#/components/schemas/user.name"
}
}
},
"payment_account": {
"type": "object",
"description": "Payment account details (object).",
"required": [
"id"
],
"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"
}
}
}
}
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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}'\n"
},
{
"lang": "HTTP",
"label": "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}\n"
}
]
}
},
"user-validation-in-webshop": {
"post": {
"summary": "User validation in Web Shop",
"description": "Xsolla sends a webhook from a Web Shop site to check if a user exists in the game. The webhook is sent from the following IP address: `34.102.38.178`.\nNote\nWebhook is used only for user validation in Web Shop. Refer to these
instructions for more information about configuring webhooks in Site Builder.
",
"tags": [
"user-validation"
],
"operationId": "user-validation-in-webshop",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"user"
],
"properties": {
"settings": {
"type": "object",
"description": "Custom project settings (object).",
"properties": {
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
},
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
}
}
},
"user": {
"type": "object",
"description": "User details (object).",
"required": [
"id"
],
"properties": {
"id": {
"$ref": "#/components/schemas/user.id"
},
"country": {
"$ref": "#/components/schemas/user.country"
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Return information about user.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"user"
],
"properties": {
"user": {
"type": "object",
"description": "User details (object).",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "User ID."
},
"appPlayerId": {
"$ref": "#/components/schemas/appPlayerId"
},
"picture": {
"type": "string",
"description": "Link to user avatar."
},
"name": {
"type": "string",
"description": "User name."
}
}
},
"attributes": {
"type": "array",
"description": "User attributes used for personalization. Refer to the documentation for detailed information.",
"items": {
"required": [
"key",
"value"
],
"properties": {
"key": {
"type": "string",
"description": "Attribute name."
},
"value": {
"description": "Attribute value."
}
}
}
},
"removingKeys": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of attributes which you want to delete. If you specify the same attribute in `attributes` parameter, it will not be deleted."
}
}
},
"example": {
"user": {
"id": "1234567890",
"appPlayerId": "cuid12345",
"picture": "https://example.com",
"name": "test-name"
},
"attributes": [
{
"key": "level",
"value": "2"
},
{
"key": "register_country",
"value": "AE"
}
],
"removingKeys": [
"company"
]
}
}
}
},
"404": {
"description": "User not found."
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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}'\n"
},
{
"lang": "HTTP",
"label": "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}\n"
}
]
}
},
"personalized-partner-catalog": {
"post": {
"summary": "Catalog personalization on partner side",
"description": "Xsolla will send a partner_side_catalog webhook that contains the user and project parameters to the webhook URL when a user interacts with the store.\n\nReturn a list of item_id or item SKU that are available to the user in response. In this case, you can also include information that a particular user can buy a certain product a specified number of times. This feature allows you to control the number and type of products that the user can add to the cart and buy.\n\nIt is recommended that the processing time of the partner_side_catalog webhook is less than 3 seconds.\n",
"tags": [
"personalization"
],
"operationId": "personalized-partner-catalog",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"user"
],
"properties": {
"user": {
"type": "object",
"description": "User details (object).",
"required": [
"user_id"
],
"properties": {
"user_id": {
"type": "string",
"description": "User ID. If the user is not authenticated, the value `null` is sent."
},
"country": {
"$ref": "#/components/schemas/user.country"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"locale": {
"$ref": "#/components/schemas/locale"
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Return a list of items available to user and number of times a particular user can buy a certain item.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"anyOf": [
{
"title": "sku",
"required": [
"sku"
],
"properties": {
"sku": {
"$ref": "#/components/schemas/sku"
},
"date_from": {
"$ref": "#/components/schemas/date_from"
},
"date_until": {
"$ref": "#/components/schemas/date_until"
},
"name": {
"$ref": "#/components/schemas/name"
},
"description": {
"$ref": "#/components/schemas/description"
},
"image_url": {
"$ref": "#/components/schemas/image_url"
},
"json_attributes": {
"$ref": "#/components/schemas/json_attributes"
},
"content": {
"$ref": "#/components/schemas/bundle_content"
}
},
"oneOf": [
{
"title": "quantity",
"properties": {
"quantity": {
"$ref": "#/components/schemas/quantity"
}
}
},
{
"title": "available",
"properties": {
"available": {
"$ref": "#/components/schemas/available"
},
"total": {
"$ref": "#/components/schemas/total"
}
}
}
]
},
{
"title": "item_id",
"required": [
"item_id"
],
"properties": {
"item_id": {
"$ref": "#/components/schemas/item_id"
},
"date_from": {
"$ref": "#/components/schemas/date_from"
},
"date_until": {
"$ref": "#/components/schemas/date_until"
},
"name": {
"$ref": "#/components/schemas/name"
},
"description": {
"$ref": "#/components/schemas/description"
},
"image_url": {
"$ref": "#/components/schemas/image_url"
},
"json_attributes": {
"$ref": "#/components/schemas/json_attributes"
},
"content": {
"$ref": "#/components/schemas/bundle_content"
}
},
"oneOf": [
{
"title": "quantity",
"properties": {
"quantity": {
"$ref": "#/components/schemas/quantity"
}
}
},
{
"title": "available",
"properties": {
"available": {
"$ref": "#/components/schemas/available"
},
"total": {
"$ref": "#/components/schemas/total"
}
}
}
]
}
]
}
},
"example": [
{
"sku": "com.xsolla.boots_1",
"quantity": 0,
"date_from": "2024-08-11T23:59:59+08:00",
"date_until": "2024-08-12T23:59:59+08:00"
},
{
"sku": "com.xsolla.sword_1",
"quantity": null,
"date_from": "2024-08-11T23:59:59+08:00",
"date_until": "2024-08-12T23:59:59+08:00"
},
{
"sku": "com.xsolla.helmet_1",
"quantity": 1
},
{
"sku": "com.xsolla.custom_item_1",
"quantity": null,
"name": "Custom name",
"description": "Custom description",
"image_url": "https://example.com/image.png",
"json_attributes": {
"type": "lootbox",
"purchased": 0
},
"content": [
{
"name": "Custom content item",
"description": "Description of custom content item",
"image_url": "https://example.com/content_image.png",
"quantity": 5
}
]
},
{
"sku": "com.xsolla.limited_item_1",
"available": 7,
"total": 10
}
]
}
}
},
"404": {
"description": "User not found."
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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 d90d319f05df7b0f86d2485f48e7079f0f752523' \\\n-d '{\n \"notification_type\": \"partner_side_catalog\",\n \"user\": {\n \"user_id\": \"12345\",\n \"country\": \"US\"\n }\n }'\n"
},
{
"lang": "HTTP",
"label": "HTTP",
"source": "POST /your/uri HTTP/1.1\nhost: your.hostname\naccept: application/json\ncontent-type: application/json\nauthorization: Signature d90d319f05df7b0f86d2485f48e7079f0f752523\n\n{\n \"notification_type\": \"partner_side_catalog\",\n \"user\": {\n \"user_id\": \"12345\",\n \"country\": \"US\"\n }\n}\n"
}
]
}
},
"successful-order-payment": {
"post": {
"summary": "Successful payment for order (with payment and transaction details)",
"description": "Xsolla sends the order_paid webhook to the specified URL when the user successfully pays for the order.\n\nThe order_paid webhook contains information about the purchased items, payment data and transaction details.\n\nThe order_paid webhook is not sent if the payment is not successful, for example:\n* the payment form was opened, but the user did not pay for the order\n* the payment form was opened, but there were errors during the payment\n\nIt is recommended that the processing time of the order_paid webhook is less than 3 seconds.\n\n\n
Notice
\n
The set of fields sent in a webhook depends on the following settings:
If you have any questions, contact your Customer Success Manager or email to csm@xsolla.com.
\n
\n \n \n | Response code | \n Automatic payment refund is disabled (by default) | \n Automatic payment refund is enabled | \n
\n \n \n \n 400, 401, 402, 403, 404, 409, 422, 415 | \n No actions | \n Automatic refund to the user | \n
\n \n 200, 201, 204 | \n No actions | \n No actions | \n
\n \n | Different code or no response to webhook | \n Multiple webhooks are sent within a specified time interval: 2 attempts with a 5-minute interval, 7 attempts with a 15-minute interval, 10 attempts with a 60-minute interval. | \n Multiple webhooks are sent within a specified time interval: 2 attempts with a 5-minute interval, 7 attempts with a 15-minute interval, 10 attempts with a 60-minute interval. If all webhooks are sent but a successful response is not received, an automatic refund is issued to the user. | \n
\n \n
\n\nTo connect the automatic refund functionality, contact your Customer Success Managers or email to csm@xsolla.com.\n",
"tags": [
"combined-webhooks"
],
"operationId": "successful-order-payment",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"notification_type",
"items",
"order",
"user",
"transaction",
"payment_details"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"items": {
"type": "array",
"description": "List of items purchased by the user.\n\nThe set of parameters included in the array depends on the webhook version. Version 2 includes additional parameters: `is_free`, `is_bonus`, and `is_bundle_content`. To switch the version, pass its number in the `version` parameter in the [Update information about webhook settings](/api/igs/operation/update-webhook/) API call.\n",
"items": {
"oneOf": [
{
"type": "object",
"title": "version = 1",
"required": [
"sku",
"type",
"quantity",
"amount",
"promotions",
"is_pre_order"
],
"properties": {
"sku": {
"$ref": "#/components/schemas/items.sku"
},
"type": {
"$ref": "#/components/schemas/items.type"
},
"quantity": {
"type": "integer",
"description": "Quantity of items."
},
"amount": {
"type": "string",
"description": "Total cost of items based on their quantity."
},
"promotions": {
"$ref": "#/components/schemas/items.promotions"
},
"is_pre_order": {
"type": "boolean",
"description": "If `true`, the item is pre-order."
},
"custom_attributes": {
"type": "object",
"description": "A JSON object containing item attributes and values."
}
}
},
{
"type": "object",
"title": "version = 2",
"required": [
"sku",
"type",
"quantity",
"amount",
"promotions",
"is_pre_order",
"is_free",
"is_bonus",
"is_bundle_content"
],
"properties": {
"sku": {
"$ref": "#/components/schemas/items.sku"
},
"type": {
"$ref": "#/components/schemas/items.type"
},
"quantity": {
"type": "integer",
"description": "Quantity of items."
},
"amount": {
"type": "string",
"description": "Total cost of items based on their quantity."
},
"promotions": {
"$ref": "#/components/schemas/items.promotions"
},
"is_pre_order": {
"type": "boolean",
"description": "If `true`, the item is pre-order."
},
"is_free": {
"type": "boolean",
"description": "If `true`, the item free."
},
"is_bonus": {
"type": "boolean",
"description": "If `true`, the item is a bonus."
},
"is_bundle_content": {
"type": "boolean",
"description": "If `true`, the item belongs to a bundle."
},
"custom_attributes": {
"type": "object",
"description": "A JSON object containing item attributes and values."
}
}
}
]
}
},
"order": {
"type": "object",
"description": "Information about the order.",
"required": [
"id",
"mode",
"currency_type",
"currency",
"amount",
"status",
"platform",
"comment",
"invoice_id",
"promotions"
],
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier of the user's order on the Xsolla’s side."
},
"mode": {
"type": "string",
"description": "Payment mode. `default` is used for real payments; `sandbox` for test payments.",
"enum": [
"default",
"sandbox"
]
},
"currency_type": {
"$ref": "#/components/schemas/currency-type"
},
"currency": {
"type": "string",
"description": "Currency of order. Virtual currency uses the SKU and real currency uses a three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code."
},
"amount": {
"type": "string",
"description": "The total cost of a cart based on the chosen currency."
},
"status": {
"type": "string",
"description": "Order status."
},
"platform": {
"type": "string",
"nullable": true,
"description": "Payment platform. The `xsolla` value is used for payments via Xsolla. For other payments, the value corresponding to the name of the game publishing platform is used.",
"enum": [
"xsolla",
"playstation_network",
"xbox_live",
"pc_standalone",
"nintendo_shop",
"google_play",
"app_store_ios",
"android_standalone",
"ios_standalone",
"android_other",
"ios_other",
"pc_other"
]
},
"comment": {
"type": "string",
"nullable": true,
"description": "User’s commentary to the order."
},
"invoice_id": {
"type": "string",
"nullable": true,
"description": "Real currency payments invoice ID. Virtual currency payments or free items have a `null` value."
},
"promotions": {
"$ref": "#/components/schemas/order.promotions"
},
"coupons": {
"type": "array",
"description": "Applied coupons. If the coupon isn’t applied, the array doesn’t return.",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "The code of an applied coupon."
},
"external_id": {
"type": "string",
"description": "External ID."
}
}
}
},
"promocodes": {
"type": "array",
"description": "Applied promocodes. If the promocode isn’t applied, the array doesn’t return.",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "The code of an applied promocode."
},
"external_id": {
"type": "string",
"description": "External ID."
}
}
}
}
}
},
"user": {
"type": "object",
"description": "User information.",
"required": [
"external_id",
"email"
],
"properties": {
"external_id": {
"type": "string",
"description": "User ID."
},
"email": {
"type": "string",
"description": "User email address."
},
"country": {
"$ref": "#/components/schemas/user.country"
}
}
},
"billing": {
"type": "object",
"description": "Transaction and payment details.",
"required": [
"notification_type",
"transaction",
"payment_details"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"type": "object",
"description": "Custom project settings (object).",
"properties": {
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
},
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
}
}
},
"purchase": {
"type": "object",
"description": "Purchase details (object).",
"required": [
"total"
],
"properties": {
"subscription": {
"type": "object",
"description": "Subscription details (object).",
"properties": {
"plan_id": {
"$ref": "#/components/schemas/subscription.plan_id"
},
"subscription_id": {
"$ref": "#/components/schemas/subscription.subscription_id"
},
"product_id": {
"type": "string",
"description": "Product ID (if sent in the access token)."
},
"tags": {
"$ref": "#/components/schemas/subscription.tags"
},
"date_create": {
"$ref": "#/components/schemas/subscription.date_create"
},
"date_next_charge": {
"type": "string",
"description": "Next billing date. Date and time per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"$ref": "#/components/schemas/amount-float"
}
}
},
"gift": {
"type": "object",
"description": "Gift details (object).",
"properties": {
"giver_id": {
"type": "string",
"description": "Giver ID."
},
"receiver_id": {
"type": "string",
"description": "Gift recipient ID."
},
"receiver_email": {
"type": "string",
"description": "Gift recipient email."
},
"message": {
"type": "string",
"description": "Message from the giver."
},
"hide_giver_from_receiver": {
"type": "string",
"description": "Whether to hide the giver identity from the recipient."
}
}
},
"total": {
"type": "object",
"description": "Total price of purchase (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Total payment amount."
}
}
},
"promotions": {
"type": "array",
"description": "Promotions applied to this transaction.",
"items": {
"type": "object",
"properties": {
"technical_name": {
"type": "string",
"description": "Technical name of the promotion."
},
"id": {
"type": "integer",
"description": "Promotion ID."
}
}
}
},
"coupon": {
"type": "object",
"description": "Coupon details (object; if a coupon was used when creating the subscription).",
"properties": {
"coupon_code": {
"type": "string",
"description": "Coupon code."
},
"campaign_code": {
"type": "string",
"description": "Campaign code."
}
}
}
}
},
"transaction": {
"type": "object",
"description": "Transaction details (object).",
"properties": {
"id": {
"type": "integer",
"description": "Transaction ID."
},
"external_id": {
"$ref": "#/components/schemas/external-id"
},
"payment_date": {
"type": "string",
"description": "Date of payment."
},
"payment_method": {
"type": "integer",
"description": "Payment method ID."
},
"payment_method_name": {
"type": "string",
"description": "Payment method name."
},
"payment_method_order_id": {
"type": "string",
"description": "Payment ID in the payment system."
},
"dry_run": {
"type": "integer",
"description": "Test transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real."
},
"agreement": {
"type": "integer",
"description": "Agreement ID."
}
}
},
"payment_details": {
"type": "object",
"description": "Payment details (object).",
"properties": {
"payment": {
"type": "object",
"description": "Amount paid by the user (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"payment_method_sum": {
"type": "object",
"description": "Amount debited from the payment system.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"xsolla_balance_sum": {
"type": "object",
"description": "Amount debited from Xsolla balance.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"payout": {
"type": "object",
"description": "Payout details (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"vat": {
"type": "object",
"description": "VAT details (object; EU only).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "VAT rate."
}
}
},
"payout_currency_rate": {
"type": "string",
"description": "Exchange rate between payment and payout currencies."
},
"country_wht": {
"type": "object",
"description": "Withholding tax applied in specific countries due to cross-border transactions (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "Country withholding tax rate, %."
}
}
},
"user_acquisition_fee": {
"type": "object",
"description": "Total amount of user acquisition fees deducted for the purchases made via affiliate networks and influencers (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "User acquisition fee rate, %."
}
}
},
"xsolla_fee": {
"type": "object",
"description": "Xsolla fee (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"payment_method_fee": {
"type": "object",
"description": "Payment system fee.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"sales_tax": {
"type": "object",
"description": "Sales tax (object; USA and Canada only).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "Sales tax rate."
}
}
},
"direct_wht": {
"type": "object",
"description": "Direct withholding tax.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "Direct withholding tax rate."
}
}
},
"repatriation_commission": {
"type": "object",
"description": "Object with data on repatriation costs, imposed on Xsolla by third parties.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
}
}
}
}
},
"custom_parameters": {
"type": "object",
"description": "Additional information."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Return to indicate successful processing."
},
"400": {
"description": "Return in case of an error in the provided information (e.g., a required parameter missing, failed authorization, etc.)."
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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}\n"
},
{
"lang": "HTTP",
"label": "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 }\n"
}
]
}
},
"successful-order-payment-separate": {
"post": {
"summary": "Successful payment for order (without payment and transaction details)",
"description": "Xsolla sends the order_paid webhook to the specified URL when the following conditions are fulfilled:\n1. The user successfully paid for the order.\n2. Xsolla received a response about the successful processing of [payment](/webhooks/operation/payment/) webhook.\n\nThe order_paid webhook contains information about the purchased items and transaction details.\n\nThe order_paid webhook is not sent if:\n* The payment was not successful, for example:\n * the payment form was opened, but the user did not pay for the order\n * the payment form was opened, but there were errors during the payment\n* The response about the successful processing of the [payment](/webhooks/operation/payment/) webhook has not been received.\n\nIt is recommended that the processing time of the order_paid webhook is less than 3 seconds.\n\nThe expected answers are described in the Responses section.\nYou can use other response codes. Depending on the response code and the connection of the automatic payment refund functionality, the webhook processing logic on Xsolla’s side is as follows:\n\n\n \n \n | Response code | \n Automatic payment refund is disabled (by default) | \n Automatic payment refund is enabled | \n
\n \n \n \n 400, 401, 402, 403, 404, 409, 422, 415 | \n No actions | \n Automatic refund to the user | \n
\n \n 200, 201, 204 | \n No actions | \n No actions | \n
\n \n | Different code or no response to webhook | \n Multiple webhooks are sent within a specified time interval: 2 attempts with a 5-minute interval, 7 attempts with a 15-minute interval, 10 attempts with a 60-minute interval. | \n Multiple webhooks are sent within a specified time interval: 2 attempts with a 5-minute interval, 7 attempts with a 15-minute interval, 10 attempts with a 60-minute interval. If all webhooks are sent but a successful response is not received, an automatic refund is issued to the user. | \n
\n \n
\n\nTo connect the automatic refund functionality, contact your Customer Success Managers or email to csm@xsolla.com.\n",
"tags": [
"separate-webhooks"
],
"operationId": "successful-order-payment-separate",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"notification_type",
"items",
"order",
"user"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"items": {
"type": "array",
"description": "List of items purchased by the user.\n\nThe set of parameters included in the array depends on the webhook version. Version 2 includes additional parameters: `is_free`, `is_bonus`, and `is_bundle_content`. To switch the version, pass its number in the `version` parameter in the [Update information about webhook settings](/api/igs/operation/update-webhook/) API call.\n",
"items": {
"oneOf": [
{
"type": "object",
"title": "version = 1",
"required": [
"sku",
"type",
"quantity",
"amount",
"promotions",
"is_pre_order"
],
"properties": {
"sku": {
"$ref": "#/components/schemas/items.sku"
},
"type": {
"$ref": "#/components/schemas/items.type"
},
"quantity": {
"type": "integer",
"description": "Quantity of items."
},
"amount": {
"type": "string",
"description": "Total cost of items based on their quantity."
},
"promotions": {
"$ref": "#/components/schemas/items.promotions"
},
"is_pre_order": {
"type": "boolean",
"description": "If `true`, the item is pre-order."
},
"custom_attributes": {
"type": "object",
"description": "A JSON object containing item attributes and values."
}
}
},
{
"type": "object",
"title": "version = 2",
"required": [
"sku",
"type",
"quantity",
"amount",
"promotions",
"is_pre_order",
"is_free",
"is_bonus",
"is_bundle_content"
],
"properties": {
"sku": {
"$ref": "#/components/schemas/items.sku"
},
"type": {
"$ref": "#/components/schemas/items.type"
},
"quantity": {
"type": "integer",
"description": "Quantity of items."
},
"amount": {
"type": "string",
"description": "Total cost of items based on their quantity."
},
"promotions": {
"$ref": "#/components/schemas/items.promotions"
},
"is_pre_order": {
"type": "boolean",
"description": "If `true`, the item is pre-order."
},
"is_free": {
"type": "boolean",
"description": "If `true`, the item free."
},
"is_bonus": {
"type": "boolean",
"description": "If `true`, the item is a bonus."
},
"is_bundle_content": {
"type": "boolean",
"description": "If `true`, the item belongs to a bundle."
},
"custom_attributes": {
"type": "object",
"description": "A JSON object containing item attributes and values."
}
}
}
]
}
},
"order": {
"type": "object",
"description": "Information about the order.",
"required": [
"id",
"mode",
"currency_type",
"currency",
"amount",
"status",
"platform",
"comment",
"invoice_id",
"promotions"
],
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier of the user's order on the Xsolla’s side."
},
"mode": {
"type": "string",
"description": "Payment mode. `default` is used for real payments; `sandbox` for test payments.",
"enum": [
"default",
"sandbox"
]
},
"currency_type": {
"$ref": "#/components/schemas/currency-type"
},
"currency": {
"type": "string",
"description": "Currency of order. Virtual currency uses the SKU and real currency uses a three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code."
},
"amount": {
"type": "string",
"description": "The total cost of a cart based on the chosen currency."
},
"status": {
"type": "string",
"description": "Order status."
},
"platform": {
"type": "string",
"nullable": true,
"description": "Payment platform. The `xsolla` value is used for payments via Xsolla. For other payments, the value corresponding to the name of the game publishing platform is used.",
"enum": [
"xsolla",
"playstation_network",
"xbox_live",
"pc_standalone",
"nintendo_shop",
"google_play",
"app_store_ios",
"android_standalone",
"ios_standalone",
"android_other",
"ios_other",
"pc_other"
]
},
"comment": {
"type": "string",
"nullable": true,
"description": "User’s commentary to the order."
},
"invoice_id": {
"type": "string",
"nullable": true,
"description": "Real currency payments invoice ID. Virtual currency payments or free items have a `null` value."
},
"promotions": {
"$ref": "#/components/schemas/order.promotions"
},
"coupons": {
"type": "array",
"description": "Applied coupons. If the coupon isn’t applied, the array doesn’t return.",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "The code of an applied coupon."
},
"external_id": {
"type": "string",
"description": "External ID."
}
}
}
},
"promocodes": {
"type": "array",
"description": "Applied promocodes. If the promocode isn’t applied, the array doesn’t return.",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "The code of an applied promocode."
},
"external_id": {
"type": "string",
"description": "External ID."
}
}
}
}
}
},
"user": {
"type": "object",
"description": "User information.",
"required": [
"external_id",
"email"
],
"properties": {
"external_id": {
"type": "string",
"description": "User ID."
},
"email": {
"type": "string",
"description": "User email address."
},
"country": {
"$ref": "#/components/schemas/user.country"
}
}
},
"custom_parameters": {
"type": "object",
"description": "Additional information."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Return to indicate successful processing."
},
"400": {
"description": "Return in case of an error in the provided information (e.g., a required parameter missing, failed authorization, etc.)."
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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}'\n"
},
{
"lang": "HTTP",
"label": "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}\n"
}
]
}
},
"order-cancellation": {
"post": {
"summary": "Order cancellation (with payment and transaction details)",
"description": "Xsolla sends the order_canceled webhook to the specified URL when the payment is canceled by the user, partner, or automatically. The webhook contains information about returned items, payment data and details of the canceled order.\n\nThe webhook is not sent if the payment is not successful, for example:\n* the payment UI was opened but the user did not pay for the order\n* the payment UI was opened but there were errors during the payment\n\nThe recommended webhook processing time is within 3 seconds.\n",
"tags": [
"combined-webhooks"
],
"operationId": "order-cancellation",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"notification_type",
"items",
"order",
"user",
"transaction",
"payment_details"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"items": {
"type": "array",
"description": "List of items purchased by the user.\n\nThe set of parameters included in the array depends on the webhook version. Version 2 includes additional parameters: `is_free`, `is_bonus`, and `is_bundle_content`. To switch the version, pass its number in the `version` parameter in the [Update information about webhook settings](/api/igs/operation/update-webhook/) API call.\n",
"items": {
"oneOf": [
{
"type": "object",
"title": "version = 1",
"required": [
"sku",
"type",
"quantity",
"amount",
"promotions",
"is_pre_order"
],
"properties": {
"sku": {
"$ref": "#/components/schemas/items.sku"
},
"type": {
"$ref": "#/components/schemas/items.type"
},
"quantity": {
"type": "integer",
"description": "Quantity of items."
},
"amount": {
"type": "string",
"description": "Total cost of items based on their quantity."
},
"promotions": {
"$ref": "#/components/schemas/items.promotions"
},
"is_pre_order": {
"type": "boolean",
"description": "If `true`, the item is pre-order."
},
"custom_attributes": {
"type": "object",
"description": "A JSON object containing item attributes and values."
}
}
},
{
"type": "object",
"title": "version = 2",
"required": [
"sku",
"type",
"quantity",
"amount",
"promotions",
"is_pre_order",
"is_free",
"is_bonus",
"is_bundle_content"
],
"properties": {
"sku": {
"$ref": "#/components/schemas/items.sku"
},
"type": {
"$ref": "#/components/schemas/items.type"
},
"quantity": {
"type": "integer",
"description": "Quantity of items."
},
"amount": {
"type": "string",
"description": "Total cost of items based on their quantity."
},
"promotions": {
"$ref": "#/components/schemas/items.promotions"
},
"is_pre_order": {
"type": "boolean",
"description": "If `true`, the item is pre-order."
},
"is_free": {
"type": "boolean",
"description": "If `true`, the item free."
},
"is_bonus": {
"type": "boolean",
"description": "If `true`, the item is a bonus."
},
"is_bundle_content": {
"type": "boolean",
"description": "If `true`, the item belongs to a bundle."
},
"custom_attributes": {
"type": "object",
"description": "A JSON object containing item attributes and values."
}
}
}
]
}
},
"order": {
"type": "object",
"description": "Information about the order.",
"required": [
"id",
"mode",
"currency_type",
"currency",
"amount",
"status",
"platform",
"comment",
"invoice_id",
"promotions"
],
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier of the user's order on the Xsolla’s side."
},
"mode": {
"type": "string",
"description": "Payment mode. `default` is used for real payments; `sandbox` for test payments.",
"enum": [
"default",
"sandbox"
]
},
"currency_type": {
"$ref": "#/components/schemas/currency-type"
},
"currency": {
"type": "string",
"description": "Currency of order. Virtual currency uses the SKU and real currency uses a three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code."
},
"amount": {
"type": "string",
"description": "The total cost of a cart based on the chosen currency."
},
"status": {
"type": "string",
"description": "Order status."
},
"platform": {
"type": "string",
"nullable": true,
"description": "Payment platform. The `xsolla` value is used for payments via Xsolla. For other payments, the value corresponding to the name of the game publishing platform is used: `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"
]
},
"comment": {
"type": "string",
"nullable": true,
"description": "User’s commentary to the order."
},
"invoice_id": {
"type": "string",
"nullable": true,
"description": "Real currency payments invoice ID. Virtual currency payments or free items have a `null` value."
},
"promotions": {
"$ref": "#/components/schemas/order.promotions"
},
"coupons": {
"type": "array",
"description": "Applied coupons. If the coupon isn’t applied, the array doesn’t return.",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "The code of an applied coupon."
},
"external_id": {
"type": "string",
"description": "External ID."
}
}
}
},
"promocodes": {
"type": "array",
"description": "Applied promocodes. If the promocode isn’t applied, the array doesn’t return.",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "The code of an applied promocode."
},
"external_id": {
"type": "string",
"description": "External ID."
}
}
}
}
}
},
"user": {
"type": "object",
"description": "User information.",
"required": [
"external_id",
"email"
],
"properties": {
"external_id": {
"type": "string",
"description": "User ID."
},
"email": {
"type": "string",
"description": "User email address."
},
"country": {
"$ref": "#/components/schemas/user.country"
}
}
},
"billing": {
"type": "object",
"description": "Transaction and payment details.",
"required": [
"notification_type",
"transaction",
"payment_details"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"settings": {
"type": "object",
"description": "Custom project settings (object).",
"properties": {
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
},
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
}
}
},
"purchase": {
"type": "object",
"description": "Purchase details (object).",
"required": [
"total"
],
"properties": {
"subscription": {
"type": "object",
"description": "Subscription details (object).",
"properties": {
"plan_id": {
"$ref": "#/components/schemas/subscription.plan_id"
},
"subscription_id": {
"$ref": "#/components/schemas/subscription.subscription_id"
},
"tags": {
"$ref": "#/components/schemas/subscription.tags"
},
"date_create": {
"$ref": "#/components/schemas/subscription.date_create"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"$ref": "#/components/schemas/amount-float"
}
}
},
"total": {
"type": "object",
"description": "Total price of purchase (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Total payment amount."
}
}
}
}
},
"transaction": {
"type": "object",
"description": "Transaction details (object).",
"properties": {
"id": {
"type": "integer",
"description": "Transaction ID."
},
"external_id": {
"type": "string",
"description": "Transaction external ID."
},
"payment_method_order_id": {
"type": "string",
"description": "Payment ID in the payment system."
},
"dry_run": {
"type": "integer",
"description": "Test transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real."
},
"agreement": {
"type": "integer",
"description": "Agreement ID."
}
}
},
"refund_details": {
"type": "object",
"description": "Refund details (object).",
"properties": {
"code": {
"type": "integer",
"description": "Code ID."
},
"reason": {
"type": "string",
"description": "Refund reason."
},
"author": {
"type": "string",
"description": "Refund initiator. The field value is passed according to the table:\n\n\n \n \n | Refund initiator | \n Field value | \n
\n \n \n \n | Game (via API). | \n API | \n
\n \n | Publisher Account user (automatic refund). | \n User email | \n
\n \n | Publisher Account user (with assistance from Xsolla customer support). | \n support@xsolla.com | \n
\n \n | Xsolla (with assistance from Xsolla customer support). | \n support@xsolla.com | \n
\n \n
\n"
}
}
},
"payment_details": {
"type": "object",
"description": "Payment details (object).",
"properties": {
"payment": {
"type": "object",
"description": "Amount paid by the user (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"payment_method_sum": {
"type": "object",
"description": "Amount debited from the payment system.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"xsolla_balance_sum": {
"type": "object",
"description": "Amount debited from Xsolla balance.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"payout": {
"type": "object",
"description": "Payout details (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"vat": {
"type": "object",
"description": "VAT details (object; EU only).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "VAT rate."
}
}
},
"payout_currency_rate": {
"type": "string",
"description": "Exchange rate between payment and payout currencies."
},
"country_wht": {
"type": "object",
"description": "Withholding tax applied in specific countries due to cross-border transactions (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "Country withholding tax rate, %."
}
}
},
"user_acquisition_fee": {
"type": "object",
"description": "Total amount of user acquisition fees deducted for the purchases made via affiliate networks and influencers (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "User acquisition fee rate, %."
}
}
},
"xsolla_fee": {
"type": "object",
"description": "Xsolla fee (object).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"payment_method_fee": {
"type": "object",
"description": "Payment system fee.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
},
"sales_tax": {
"type": "object",
"description": "Sales tax (object; USA and Canada only).",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "Sales tax rate."
}
}
},
"direct_wht": {
"type": "object",
"description": "Direct withholding tax.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
},
"percent": {
"type": "number",
"format": "float",
"description": "Direct withholding tax rate."
}
}
},
"repatriation_commission": {
"type": "object",
"description": "Object with data on repatriation costs, imposed on Xsolla by third parties.",
"properties": {
"currency": {
"$ref": "#/components/schemas/currency"
},
"amount": {
"type": "number",
"format": "float",
"description": "Amount."
}
}
}
}
}
}
},
"custom_parameters": {
"type": "object",
"description": "Additional information."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Return to indicate successful processing."
},
"400": {
"description": "Return in case of an error in the provided information (e.g., a required parameter missing, failed authorization, etc.)."
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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}\n"
},
{
"lang": "HTTP",
"label": "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 }\n"
}
]
}
},
"order-cancellation-separate": {
"post": {
"summary": "Order cancellation (without payment and transaction details)",
"description": "Xsolla sends the order_canceled webhook to the specified URL when the payment was canceled by the user, partner, or automatically. The webhook contains information about returned items and details of the canceled order.\n\nThe webhook is not sent if the payment was not successful, for example:\n* the payment UI was opened but the user did not pay for the order\n* the payment UI was opened but there were errors during the payment\n\nThe recommended webhook processing time is within 3 seconds.\n",
"tags": [
"separate-webhooks"
],
"operationId": "order-cancellation-separate",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"notification_type",
"items",
"order",
"user"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"items": {
"type": "array",
"description": "List of items purchased by the user.\n\nThe set of parameters included in the array depends on the webhook version. Version 2 includes additional parameters: `is_free`, `is_bonus`, and `is_bundle_content`. To switch the version, pass its number in the `version` parameter in the [Update information about webhook settings](/api/igs/operation/update-webhook/) API call.\n",
"items": {
"oneOf": [
{
"type": "object",
"title": "version = 1",
"required": [
"sku",
"type",
"quantity",
"amount",
"promotions",
"is_pre_order"
],
"properties": {
"sku": {
"$ref": "#/components/schemas/items.sku"
},
"type": {
"$ref": "#/components/schemas/items.type"
},
"quantity": {
"type": "integer",
"description": "Quantity of items."
},
"amount": {
"type": "string",
"description": "Total cost of items based on their quantity."
},
"promotions": {
"$ref": "#/components/schemas/items.promotions"
},
"is_pre_order": {
"type": "boolean",
"description": "If `true`, the item is pre-order."
},
"custom_attributes": {
"type": "object",
"description": "A JSON object containing item attributes and values."
}
}
},
{
"type": "object",
"title": "version = 2",
"required": [
"sku",
"type",
"quantity",
"amount",
"promotions",
"is_pre_order",
"is_free",
"is_bonus",
"is_bundle_content"
],
"properties": {
"sku": {
"$ref": "#/components/schemas/items.sku"
},
"type": {
"$ref": "#/components/schemas/items.type"
},
"quantity": {
"type": "integer",
"description": "Quantity of items."
},
"amount": {
"type": "string",
"description": "Total cost of items based on their quantity."
},
"promotions": {
"type": "array",
"description": "Applied promotions. If a promotion wasn’t applied, an empty array is passed in the parameter.",
"items": {
"type": "object",
"properties": {
"amount_without_discount": {
"type": "string",
"description": "Total cost of items without a discount."
},
"amount_with_discount": {
"type": "string",
"description": "Total cost of items with a discount."
},
"sequence": {
"type": "integer",
"description": "Order of promotions application."
}
}
}
},
"is_pre_order": {
"type": "boolean",
"description": "If `true`, the item is pre-order."
},
"is_free": {
"type": "boolean",
"description": "If `true`, the item free."
},
"is_bonus": {
"type": "boolean",
"description": "If `true`, the item is a bonus."
},
"is_bundle_content": {
"type": "boolean",
"description": "If `true`, the item belongs to a bundle."
},
"custom_attributes": {
"type": "object",
"description": "A JSON object containing item attributes and values."
}
}
}
]
}
},
"order": {
"type": "object",
"description": "Information about the order.",
"required": [
"id",
"mode",
"currency_type",
"currency",
"amount",
"status",
"platform",
"comment",
"invoice_id",
"promotions"
],
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier of the user's order on the Xsolla’s side."
},
"mode": {
"type": "string",
"description": "Payment mode. `default` is used for real payments; `sandbox` for test payments.",
"enum": [
"default",
"sandbox"
]
},
"currency_type": {
"$ref": "#/components/schemas/currency-type"
},
"currency": {
"type": "string",
"description": "Currency of order. Virtual currency uses the SKU and real currency uses a three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code."
},
"amount": {
"type": "string",
"description": "The total cost of a cart based on the chosen currency."
},
"status": {
"type": "string",
"description": "Order status."
},
"platform": {
"type": "string",
"nullable": true,
"description": "Payment platform. The `xsolla` value is used for payments via Xsolla. For other payments, the value corresponding to the name of the game publishing platform is used: `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"
]
},
"comment": {
"type": "string",
"nullable": true,
"description": "User’s commentary to the order."
},
"invoice_id": {
"type": "string",
"nullable": true,
"description": "Real currency payments invoice ID. Virtual currency payments or free items have a `null` value."
},
"promotions": {
"$ref": "#/components/schemas/order.promotions"
},
"coupons": {
"type": "array",
"description": "Applied coupons. If the coupon isn’t applied, the array doesn’t return.",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "The code of an applied coupon."
},
"external_id": {
"type": "string",
"description": "External ID."
}
}
}
},
"promocodes": {
"type": "array",
"description": "Applied promocodes. If the promocode isn’t applied, the array doesn’t return.",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "The code of an applied promocode."
},
"external_id": {
"type": "string",
"description": "External ID."
}
}
}
}
}
},
"user": {
"type": "object",
"description": "User information.",
"required": [
"external_id",
"email"
],
"properties": {
"external_id": {
"type": "string",
"description": "User ID."
},
"email": {
"type": "string",
"description": "User email address."
},
"country": {
"$ref": "#/components/schemas/user.country"
}
}
},
"custom_parameters": {
"type": "object",
"description": "Additional information."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Return to indicate successful processing."
},
"400": {
"description": "Return in case of an error in the provided information (e.g., a required parameter missing, failed authorization, etc.)."
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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}'\n"
},
{
"lang": "HTTP",
"label": "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}\n"
}
]
}
},
"dispute": {
"post": {
"summary": "Dispute",
"description": "When a new dispute is opened or a dispute changes its status, Xsolla sends a webhook with the `dispute` type to the webhook URL. To receive this webhook, contact your Customer Success Manager or email csm@xsolla.com.",
"tags": [
"anti-fraud"
],
"operationId": "dispute",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"notification_type",
"action",
"transaction",
"settings",
"user",
"dispute"
],
"properties": {
"notification_type": {
"$ref": "#/components/schemas/notification_type"
},
"action": {
"type": "string",
"description": "Action type.",
"enum": [
"adding",
"updating"
],
"x-enumDescriptions": {
"adding": "A new dispute has been opened.",
"updating": "A dispute’s status has changed."
}
},
"transaction": {
"type": "object",
"description": "Object with information about the transaction.",
"required": [
"id",
"date_create",
"total",
"payment_method",
"country_code"
],
"properties": {
"id": {
"$ref": "#/components/schemas/transaction-id"
},
"external_id": {
"$ref": "#/components/schemas/external-id"
},
"date_create": {
"$ref": "#/components/schemas/date-create"
},
"total": {
"type": "object",
"description": "Object with information about transaction amount.",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"$ref": "#/components/schemas/transaction-total-amount"
},
"currency": {
"$ref": "#/components/schemas/currency"
}
}
},
"payment_method": {
"$ref": "#/components/schemas/dispute-payment-method"
},
"country_code": {
"$ref": "#/components/schemas/user.country"
}
}
},
"settings": {
"type": "object",
"description": "Object with information about custom project settings.",
"required": [
"project_id",
"merchant_id"
],
"properties": {
"project_id": {
"$ref": "#/components/schemas/settings.project_id"
},
"merchant_id": {
"$ref": "#/components/schemas/settings.merchant_id"
}
}
},
"user": {
"type": "object",
"description": "Object with information about a user.",
"required": [
"id"
],
"properties": {
"id": {
"$ref": "#/components/schemas/user.id"
},
"email": {
"$ref": "#/components/schemas/user.email"
}
}
},
"dispute": {
"type": "object",
"description": "Object with information about the dispute.",
"required": [
"incoming_date",
"reason",
"type",
"status"
],
"properties": {
"incoming_date": {
"$ref": "#/components/schemas/dispute-date"
},
"reason": {
"$ref": "#/components/schemas/dispute-reason"
},
"type": {
"$ref": "#/components/schemas/dispute-type"
},
"status": {
"$ref": "#/components/schemas/dispute-status"
}
}
}
}
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"400": {
"$ref": "#/components/responses/400"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"x-codeSamples": [
{
"lang": "cURL",
"label": "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}'\n"
},
{
"lang": "HTTP",
"label": "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}\n"
}
]
}
}
},
"components": {
"schemas": {
"notification_type": {
"type": "string",
"description": "Notification type."
},
"settings.project_id": {
"type": "integer",
"description": "Project ID. You can find this parameter in your [Publisher Account](https://publisher.xsolla.com/) next to the name of the project."
},
"settings.merchant_id": {
"type": "integer",
"description": "Merchant ID."
},
"user.ip": {
"type": "string",
"description": "User IP."
},
"user.phone": {
"type": "string",
"description": "User phone."
},
"user.email": {
"type": "string",
"description": "User email."
},
"user.id": {
"type": "string",
"description": "User ID."
},
"user.name": {
"type": "string",
"description": "Username."
},
"user.country": {
"type": "string",
"description": "User’s country. Two-letter uppercase [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code."
},
"user.public_id": {
"type": "string",
"description": "Public user ID."
},
"user.zip": {
"type": "string",
"description": "User’s ZIP or postal code."
},
"currency": {
"type": "string",
"description": "Currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)."
},
"subscription.plan_id": {
"type": "string",
"description": "Plan ID (external if the plan was created via API)."
},
"subscription.subscription_id": {
"type": "integer",
"description": "Subscription ID in Xsolla database."
},
"subscription.tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Plan tags."
},
"subscription.date_create": {
"type": "string",
"description": "Subscription creation date. Date and time per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
},
"amount-float": {
"type": "number",
"format": "float",
"description": "Price in real currency."
},
"order": {
"type": "object",
"description": "Object that contains information about an order. To receive this information, set the **Add order object to webhook** toggle to **On** in [Publisher Account](https://publisher.xsolla.com/) in the **Project settings > Webhooks > Advanced settings** section."
},
"external-id": {
"type": "string",
"description": "Transaction external ID. Refer to the [FAQs](/doc/pay-station/references/faq/#faq_payments_q_new_transaction_external_id) for detailed information."
},
"subscription.product_id": {
"type": "string",
"description": "Product ID (if sent in the access token)."
},
"subscription.date_next_charge": {
"type": "string",
"description": "Next billing date. Date and time per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
},
"subscription.is_gift": {
"type": "boolean",
"description": "Whether the subscription was gifted. The parameter is passed only if the value is `true`."
},
"subscription.date_end": {
"type": "string",
"description": "Subscription termination date. Date and time per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
},
"payment_account.id": {
"type": "string",
"description": "Payment account ID."
},
"payment_account.name": {
"type": "string",
"description": "The payment account name in the payment system (e.g., payment card number, email)."
},
"payment_account.payment_method": {
"type": "integer",
"description": "Payment method ID."
},
"payment_account.country": {
"type": "string",
"description": "Country of the payment account. For example, the country of the bank issuing the card or the country specified when creating a PayPal account. Two-letter uppercase [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code."
},
"payment_account.type": {
"type": "string",
"description": "Type of payment account (e.g., card, PayPal)."
},
"appPlayerId": {
"type": "string",
"description": "User ID assigned by the app owner at the time of user registration (customer user ID).\nNote
Xsolla passes this data in the custom_parameters object of the call for getting a payment token.
\n"
},
"locale": {
"type": "string",
"description": "User language. Two-letter lowercase [language code](https://developers.xsolla.com/doc/pay-station/features/localization/)."
},
"quantity": {
"type": "integer",
"deprecated": true,
"description": "Number of items a single user can purchase. To set an unlimited quantity, pass `null`. To make the item unavailable for purchase but visible in the catalog, pass `0`.\n\nIf you use this parameter, the purchase limit information is not displayed in the catalog. To display purchase limit information in the catalog (e.g., `7/10`), pass the `available` and `total` pair instead of `quantity`."
},
"available": {
"type": "integer",
"description": "Remaining number of items the user can purchase.\n\nTo display purchase limit information in the catalog (e.g., `7/10`), pass the `available` and `total` pair."
},
"total": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Maximum number of items a single user can purchase.\n\nTo display purchase limit information in the catalog (e.g., `7/10`), pass the `available` and `total` pair."
},
"sku": {
"type": "string",
"description": "The unique ID of the item you specified in your Publisher Account. You should pass either the `sku` or `item_id`."
},
"date_from": {
"type": "string",
"description": "Date when the item is available for sale. Formatted according to the [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) standard."
},
"date_until": {
"type": "string",
"description": "Date when the item become unavailable for sale. Formatted according to the [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) standard."
},
"name": {
"type": "string",
"maxLength": 255,
"description": "Item name for displaying in the catalog. It overwrites the name stored in an item."
},
"description": {
"type": "string",
"maxLength": 255,
"description": "Item description for displaying in catalog. It overwrites description stored in an item."
},
"image_url": {
"type": "string",
"format": "uri",
"maxLength": 255,
"description": "Image URL for displaying in the catalog. It overwrites the image URL stored in an item. Only HTTPS protocol is supported. If the URL doesn't comply with the requirements, it will be ignored."
},
"json_attributes": {
"type": "object",
"format": "json",
"maxLength": 500,
"description": "A JSON object containing item attributes and values. It overwrites [custom_attributes](https://developers.xsolla.com/webhooks/operation/successful-order-payment/#!path=items/0/custom_attributes&t=request) stored in an item. If JSON doesn't comply with the requirements or it's longer than maximum length, it will be ignored."
},
"bundle_content": {
"type": "array",
"description": "Array of objects with bundle content for displaying in catalog. It can be used only for bundle type [partner_side_content](https://developers.xsolla.com/api/shop-builder/operation/admin-create-bundle/).",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"description": "Item name for displaying in catalog as part of the bundle. If not provided, an empty string is passed."
},
"description": {
"type": "string",
"maxLength": 255,
"description": "Item description for displaying in catalog as part of the bundle. If not provided, `null` value is passed."
},
"image_url": {
"type": "string",
"format": "uri",
"maxLength": 255,
"description": "Item image URL for displaying in catalog as part of the bundle. Only HTTPS protocol is supported. If not provided, `null` value is passed."
},
"quantity": {
"type": "integer",
"minimum": 1,
"default": 1,
"description": "Quantity of the item in the bundle."
}
}
}
},
"item_id": {
"type": "integer",
"description": "Unique item ID on Xsolla's side. You should pass either the `sku` or `item_id`."
},
"items.sku": {
"type": "string",
"description": "Unique ID of the item. For items with the `game_key` type, a value in `sku_drm` format is used."
},
"items.type": {
"type": "string",
"description": "Items type.\nFor `bundle` type items, including virtual currency packages, the `items` array will display:\n - parameters of the bundle or virtual currency package\n - items included in the bundle or currencies included in the package\n \nThe `value_point` type is used in [loyalty points](/solutions/loyalty-as-service/) operations – when points are spent or awarded.",
"enum": [
"virtual_good",
"virtual_currency",
"game_key",
"bundle",
"value_point"
]
},
"items.promotions": {
"type": "array",
"description": "Applied promotions for specific items in the order.\nThe array is returned in the following cases:\n - A discount promotion is configured for a specific item.\n - A promo code with the **Discount on selected items** setting is applied.\n\nIf no item-level promotions are applied, an empty array is returned.",
"items": {
"type": "object",
"properties": {
"amount_without_discount": {
"type": "string",
"description": "Total cost of items without a discount."
},
"amount_with_discount": {
"type": "string",
"description": "Total cost of items with a discount."
},
"sequence": {
"type": "integer",
"description": "Order of promotions application."
}
}
}
},
"currency-type": {
"type": "string",
"description": "Payment currency type. For a free order, `unknown` value is specified.",
"enum": [
"real",
"virtual",
"unknown",
"loyalty_point"
],
"x-enumDescriptions": {
"real": "real currency",
"virtual": "virtual currency",
"unknown": "free order",
"loyalty_point": "loyalty points"
}
},
"order.promotions": {
"type": "array",
"description": "Applied promotions for the entire order.\nThe array is returned in the following cases:\n - A promotion affects the total purchase amount, such as a promo code with the **Discount on purchase** setting.\n - No discount is applied to the purchase, but bonus items are added to the order. In this case, the values for the cost with discount ([amount_with_discount](/webhooks/#operation/order-cancellation!path=order/promotions/amount_with_discount&t=request)) and without discount ([amount_without_discount](/webhooks/#operation/order-cancellation!path=order/promotions/amount_without_discount&t=request)) are returned and identical, since no discount is applied.\n\nIf no order-level promotions are applied, an empty array is returned.",
"items": {
"type": "object",
"properties": {
"amount_without_discount": {
"type": "string",
"description": "Total cost of items without a discount."
},
"amount_with_discount": {
"type": "string",
"description": "Total cost of items with a discount."
},
"sequence": {
"type": "integer",
"description": "Order of promotions application."
}
}
}
},
"transaction-id": {
"type": "integer",
"description": "Transaction ID."
},
"date-create": {
"type": "string",
"description": "Payment date."
},
"transaction-total-amount": {
"type": "number",
"format": "float",
"description": "Payment amount."
},
"dispute-payment-method": {
"type": "string",
"description": "Payment method.",
"enum": [
"credit_debit_card",
"paypal"
],
"x-enumDescriptions": {
"credit_debit_card": "Credit or debit card",
"paypal": "PayPal"
}
},
"dispute-date": {
"type": "string",
"description": "Date of the dispute opening according to the [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) standard."
},
"dispute-reason": {
"type": "string",
"description": "Reason for opening the dispute. Refer to [documentation](/payment-ui-and-flow/anti-fraud/chargeback/#payments_chargeback_reasons) for description of groups of 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"
]
},
"dispute-type": {
"type": "string",
"description": "Dispute type.",
"enum": [
"1st_time_chargeback",
"2nd_time_chargeback",
"arbitration",
"retrieval",
"representment",
"chargeback_reversal",
"representment_reversal",
"reimbursement",
"dispute",
"chargeback",
"claim",
"reimbursement_reversal",
"inquiry",
"other"
],
"x-enumDescriptions": {
"1st_time_chargeback": "1st time chargeback.",
"2nd_time_chargeback": "2nd time chargeback (pre-arbitration).",
"arbitration": "Resolving a dispute between the issuing bank and the merchant when the 1st time chargeback and the 2nd time chargeback were rejected.",
"retrieval": "A cardholder has requested payment details from the bank.",
"representment": "The chargeback management team has sent the evidence to the payment system.",
"chargeback_reversal": "Chargeback has been revoked.",
"representment_reversal": "Chargeback has been revoked.",
"reimbursement": "Refund has been made.",
"dispute": "A cardholder has requested payment details from the bank.",
"chargeback": "1st time chargeback.",
"claim": "A dispute between a customer and a merchant in PayPal.",
"reimbursement_reversal": "Chargeback has been revoked.",
"inquiry": "A cardholder has requested payment details from the bank.",
"other": "Used for chargeback types not covered by any other type."
}
},
"dispute-status": {
"type": "string",
"description": "Dispute status.",
"enum": [
"new",
"accepted",
"no_actions_required",
"won",
"lost"
],
"x-enumDescriptions": {
"new": "New",
"accepted": "Accepted",
"no_actions_required": "In progress",
"won": "Won",
"lost": "Lost"
}
}
},
"responses": {
"204": {
"description": "Return to indicate successful processing."
},
"400": {
"description": "Return in case of an error in the provided information (e.g., a required parameter missing, failed authorization, etc.).",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
}
},
"x-examples": {
"application/json": {
"INVALID_USER": {
"summary": "Invalid user",
"value": {
"error": {
"code": "INVALID_USER",
"message": "Invalid user"
}
}
},
"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"
}
}
},
"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"
}
}
}
}
}
},
"500": {
"description": "Return to indicate temporary errors with your servers."
},
"400-payment": {
"description": "Return in case of an error in the provided information (e.g., a required parameter missing, failed authorization, etc.). In this case, the user’s money is debited, but the purchase fails. To make a refund, contact Xsolla customer support at support@xsolla.com.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
}
},
"x-examples": {
"application/json": {
"INVALID_USER": {
"summary": "Invalid user",
"value": {
"error": {
"code": "INVALID_USER",
"message": "Invalid user"
}
}
},
"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"
}
}
},
"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"
}
}
}
}
}
}
}
},
"x-tagGroups": [
{
"name": "User validation",
"tags": [
"user-validation"
]
},
{
"name": "Payments",
"tags": [
"payments"
]
},
{
"name": "Game services",
"tags": [
"combined-webhooks",
"separate-webhooks",
"personalization"
]
},
{
"name": "Anti-fraud",
"tags": [
"anti-fraud"
]
},
{
"name": "Subscriptions",
"tags": [
"subscriptions"
]
}
]
}