openapi: 3.1.0
info:
  description: "# Overview\n\nWebhooks are notifications about events occurring in the system. When a specific event occurs, Xsolla sends an HTTP request, in which event data is transmitted, to your application. This is usually a POST request in JSON format.\n\n<strong>Event examples:</strong>\n- user interaction with an item catalog\n- payment or cancellation of an order\n\nWhen a set event happens, Xsolla notifies your system about it via a webhook. As a result, you can perform actions such as:\n- replenish the user's balance\n- make a payment refund\n- credit or debit new items from the user account\n- start providing a subscription\n- block a user in case of a suspicion of fraud\n\n<b>Example of a payment processing webhook workflow:</b>\n\n![Payment processing webhook](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks-general.svg)\n\n<div lang=\"en\" class=\"note\">\n <p><strong>Note</strong></p><p>Depending on the solution used and the type of its integration, the set of webhooks and  sequence of interactions may differ from the provided example.</p>\n</div>\n\n<b>Video guide for Xsolla webhooks integration:</b>\n\n<div style=\"position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; border-radius: 15px; overflow: hidden;\">\n  <iframe src=\"https://player.vimeo.com/video/1034591338\" style=\"position: absolute; top:0; left: 0; width: 100%; height: 100%; border:0; border-radius: 15px;\" allowfullscreen></iframe>\n</div>\n\n\n<b>Webhooks settings when working with Xsolla products and solutions:</b>\n\n<table>\n  <thead>\n    <tr>\n        <th>Product/ Solution</th>\n        <th>Required/ Optional</th>\n        <th>What are webhooks used for</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n        <td>Payments</td>\n        <td>Required</td>\n        <td>\n          <ul>\n            <li>User validation.</li>\n            <li>Receiving information about transaction details in cases of successful payment or payment refund.</li>\n            <li>Crediting purchased items to a user and debiting items in case of order cancellation.</li>\n          </ul>\n        </td>\n    </tr>\n    <tr>\n        <td>In-Game Store</td>\n        <td>Required</td>\n        <td>\n          <ul>\n            <li>User validation.</li>\n            <li>Receiving information about transaction details in cases of successful payment or payment refund.</li>\n            <li>Crediting purchased items to a user and debiting items in case of order cancellation.</li>\n          </ul>\n        </td>\n    </tr>\n    <tr>\n        <td>Game Sales</td>\n        <td>Optional</td>\n        <td>For selling game keys, user validation and crediting of items are not required. You can connect webhooks if you want to receive information about events, such as payment or order cancellation.<br/>If you connect webhooks, it is important to process all incoming <a href=\"/webhooks/overview/#section/List-of-required-webhooks\">required webhooks</a>.\n        </td>\n    </tr>\n    <tr>\n        <td>Subscriptions</td>\n        <td>Optional</td>\n        <td>Receiving information about creation, update, or cancellation of a subscription. Alternatively, you can <a href=\"/doc/subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_information_set_up_via_api\">request information via the API</a>.\n        </td>\n    </tr>\n    <tr>\n        <td>Web Shop</td>\n        <td>Required</td>\n        <td>\n          <ul>\n            <li>User validation.</li>\n            <li>Receiving information about transaction details in cases of successful payment or payment refund.</li>\n            <li>Crediting purchased items to a user and debiting items in case of order cancellation.</li>\n            <li>User authentication, if you use authentication via user ID. Alternatively, you can use <a href=\"/solutions/web-shop/authentication-and-analytics/set-up-authentication/#web_shop_guide_shop_with_auth_set_up_auth_xsolla_login_how_to_get_it\">user authentication via Xsolla Login</a>.</li>\n          </ul>\n        </td>\n    </tr>\n    <tr>\n        <td>Digital Distribution Hub</td>\n        <td>Required</td>\n        <td>\n          <ul>\n            <li>User validation.</li>\n            <li>Linking the transaction ID on Xsolla side with the transaction ID in your system.</li>\n            <li>Transferring additional transaction parameters in the order.</li>\n            <li>Crediting purchased items to the user and debiting items in case of order cancellation.</li>\n          </ul>\n          <p>Refer to the <a href=\"/solutions/ddh/#integration_guide_ddh_webhook\">documentation</a> for detailed information on setting up webhooks for the Digital Distribution Hub.</p>\n        </td>\n    </tr>\n    <tr>\n        <td>Login</td>\n        <td>Optional</td>\n        <td>\n          <p>Receiving event information:</p>\n          <ul>\n            <li>user registration/ authorization</li>\n            <li>user email address confirmation</li>\n            <li>linking a user’s social media account</li>\n          </ul>\n          <p>Refer to the <a href=\"/api/login/operation/add-webhook-for-event/\">Login documentation</a> for detailed information on setting up webhooks.</p>\n        </td>\n    </tr>\n  </tbody>\n</table>\n\n# List of required webhooks\nIf you use products and solutions that require working with webhooks, <a href=\"/webhooks/overview/#section/Set-up-webhooks-in-Publisher-Account\">enable and test the webhooks in your Publisher Account</a> and <a href=\"/webhooks/overview/#section/Webhook-listener\">set up their processing</a>.\nWhen specific events occur, webhooks are sent sequentially.\nTherefore, if you do not process one of the webhooks, subsequent webhooks will not be sent. The list of required webhooks is presented below.\n\n## In-Game Store and Payments\n2 webhook sending options have been set up on Xsolla’s side when purchasing and returning items on the site — information with payment and transaction data and information about purchased items can come separately or can be combined into one webhook.\n\n<b>Receiving information in combined webhooks:</b>\n\nIf you registered in <a href=\"https://publisher.xsolla.com/\">Publisher Account</a> after January 22, 2025, you receive all the information in the <a href=\"/webhooks/operation/successful-order-payment\">Successful payment for order</a> (`order_paid`) and <a href=\"/webhooks/operation/order-cancellation\">Order cancellation</a> (`order_canceled`) webhooks. In this case, you do not need to process the <a href=\"/webhooks/operation/payment\">Payment</a> (`payment`) and <a href=\"/webhooks/operation/refund\">Refund</a> (`refund`) webhooks.\n\n<b>Receiving information in separate webhooks:</b>\n\nIf you registered in <a href=\"https://publisher.xsolla.com/\">Publisher Account</a> on or before January 22, 2025,  you receive the following webhooks:\n- <a href=\"/webhooks/operation/payment\">Payment</a> (`payment`) and <a href=\"/webhooks/operation/refund\">Refund</a> (`refund`) with information about payment data and transaction details.\n- <a href=\"/webhooks/operation/successful-order-payment-separate\">Successful payment for order</a> (`order_paid`) and <a href=\"/webhooks/operation/order-cancellation-separate\">Order cancellation</a> (`order_canceled`) with information about purchased items.\n\nYou need to process all incoming webhooks.\nTo switch to the new option with receiving combined webhooks, contact your Customer Success Managers or email to <a href=\"mailto:csm@xsolla.com\">csm@xsolla.com</a>.\n\nFor the full operation of the in-game store and payment management, it is necessary to implement the processing of the main webhooks.\n\n<b>If you receive combined webhooks</b>:\n\n<table>\n  <thead>\n    <tr>\n        <th>Webhook name and type</th>\n        <th>Description</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n        <td>User validation &gt; <a href=\"/webhooks/operation/user-validation/\">User validation</a> (<code>user_validation</code>)</td>\n        <td>Is sent at different stages of the payment process to ensure the user is registered in the game.</td>\n    </tr>\n    <tr>\n        <td>Game services &gt; Combined webhooks &gt; <a href=\"/webhooks/operation/successful-order-payment\">Successful payment for order</a> (<code>order_paid</code>)</td>\n        <td>It contains payment data, transaction details, and information about purchased items. Use the data from the webhook to add items to the user.</td>\n    </tr>\n    <tr>\n        <td>Game services &gt; Combined webhooks &gt; <a href=\"/webhooks/operation/order-cancellation\">Order cancellation</a> (<code>order_canceled</code>)</td>\n        <td>It contains data of the canceled payment, transaction details, and information about purchased items. Use the data from the webhook to remove the purchased items.</td>\n    </tr>\n  </tbody>\n</table>\n\n\n<b>If you receive separate webhooks</b>:\n\n<table>\n  <thead>\n    <tr>\n        <th>Webhook name and type</th>\n        <th>Description</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n        <td>User validation &gt; <a href=\"/webhooks/operation/user-validation/\">User validation</a> (<code>user_validation</code>)</td>\n        <td>Is sent at different stages of the payment process to ensure the user is registered in the game.</td>\n    </tr>\n    <tr>\n        <td>Payments &gt; <a href=\"/webhooks/operation/payment\">Payment</a> (<code>payment</code>)</td>\n        <td>It contains payment data and transaction details.</td>\n    </tr>\n    <tr>\n        <td>Game services &gt; Separate webhooks &gt; <a href=\"/webhooks/operation/successful-order-payment-separate\">Successful payment for order</a> (<code>order_paid</code>)</td>\n        <td>It contains information about purchased items. Use the data from the webhook to add items to the user.</td>\n    </tr>\n    <tr>\n        <td>Payments &gt; <a href=\"/webhooks/operation/refund\">Refund</a> (<code>refund</code>)</td>\n        <td>It contains payment data and transaction details.</td>\n    </tr>\n    <tr>\n        <td>Game services &gt; Separate webhooks &gt; <a href=\"/webhooks/operation/order-cancellation-separate\">Order cancellation</a> (<code>order_canceled</code>)</td>\n        <td>It contains information about the purchased items and the ID of the canceled transaction. Use the data from the webhook to remove the purchased items.</td>\n    </tr>\n  </tbody>\n</table>\n\nIf item catalog <a href=\"/doc/in-game-store/features/personalization\">personalization</a> is implemented on your application’s side, set up processing of <a href=\"/webhooks/operation/personalized-partner-catalog\">Catalog personalization on the partner’s side</a> webhook.\n\n<div lang=\"en\" class=\"note\">\n <p><strong>Note</strong></p>\n <p>To receive real payments, you only need to <a href=\"/doc/in-game-store/integration-guide/sign-licensing-agreement/\">sign the licensing agreement</a> and implement processing of the webhooks:</p>\n <p><ul><li><a href=\"/webhooks/operation/payment\">Payment</a>, <a href=\"/webhooks/operation/successful-order-payment-separate\">Successful payment for order</a>, and <a href=\"/webhooks/operation/user-validation/\">User validation</a> if you receive separate webhooks</li><li><a href=\"/webhooks/operation/successful-order-payment\">Successful payment for order</a> and <a href=\"/webhooks/operation/user-validation/\">User validation</a> if you receive combined webhooks</li></ul></p>\n</div>\n\n## Subscriptions\nTo automatically manage subscription plans, it is necessary to implement processing of the main webhooks:\n- <a href=\"/webhooks/operation/user-validation/\">User validation</a> (`user_validation`) — is sent at different stages of the payment process to ensure the user is registered in the game.\n- <a href=\"/webhooks/operation/payment\">Payment</a> (`payment`) — is sent when an order is paid and contains payment data and transaction details.\n- <a href=\"/webhooks/operation/created-subscription/\">Created subscription</a> (`create_subscription`) — is sent when a <a href=\"/webhooks/operation/payment\">Payment</a> webhook has been successfully processed or the user has purchased a subscription with a trial period. It contains the details of the purchased subscription and user data. Use the webhook data to add a subscription to the user.\n- <a href=\"/webhooks/operation/updated-subscription/\">Updated subscription</a> (`update_subscription`) — is sent when a subscription is renewed or changed, when a <a href=\"https://developers.xsolla.com/webhooks/operation/payment\">Payment</a> webhook has been successfully processed. It contains the details of the purchased subscription and user data. Use the webhook data to extend the user's subscription or change the subscription parameters.\n- <a href=\"/webhooks/operation/refund\">Refund</a> (`refund`) — is sent when an order is canceled and contains the canceled payment data and transaction details.\n- <a href=\"/webhooks/operation/canceled-subscription/\">Canceled subscription</a> (`cancel_subscription`) — is sent when a <a href=\"/webhooks/operation/refund\">Refund</a> webhook has been successfully processed or the subscription was canceled for another reason. It contains information about the subscription and user data. Use the webhook data to deduct purchased subscriptions from the user.\n\n# Set up webhooks in Publisher Account\n\n## General settings\n\nTo enable receiving webhooks:\n1. In the project in Publisher Account go to <a href=\"https://publisher.xsolla.com/0/projects/0/edit/webhooks/\">Project Settings &gt; Webhooks</a> section.\n2. In the <b>Webhook server</b> field, specify the URL of your server where you want to receive webhooks in the `https://example.com` format. You can also specify the URL you find in a tool for testing webhooks.\n\n<div lang=\"en\" class=\"notice\">\n  <p><strong>Notice</strong></p>\n  <p>To transfer data, HTTPS protocol is required; use of HTTP protocol is not supported.</p>\n</div>\n\n<p></p>\n\n3. A secret key to sign project webhooks is generated by default. If you want to generate a new secret key, click the refresh icon.\n4. Click <b>Enable webhooks</b>.\n\n![Enable webhooks](https://cdn.xsolla.net/developers/current/images/api_docs/enable.png)\n\n<div lang=\"en\" class=\"note\">\n  <p><strong>Note</strong></p>\n  <p>To test webhooks, you can select any dedicated website, such as <a href=\"https://webhook.site/#!/\">webhook.site</a>, or a platform, such as <a href=\"https://ngrok.com/\">ngrok</a>.</p>\n</div>\n\n<p></p>\n\n<div lang=\"en\" class=\"notice\">\n    <p><strong>Notice</strong></p>\n    <p>You can’t simultaneously send webhooks to different URLs. What you can do in Publisher Account is specify a URL for testing first, and then replace it with the real one.</p>\n</div>\n\nTo disable receiving webhooks:\n1.  In the project in Publisher Account go to <a href=\"https://publisher.xsolla.com/0/projects/0/edit/webhooks/\">Project Settings &gt; Webhooks</a> section.\n2. Click <b>Disable webhooks</b>.\n\n## Advanced settings\n\nFor the webhooks in the <a href=\"/webhooks/overview/#section/Test-webhooks-in-Publisher-Account/Store\">Payments and Store</a> section, advanced settings are available.\nThey will automatically appear under the <a href=\"/webhooks/overview/#section/Set-up-webhooks-in-Publisher-Account/General-settings\">General settings</a> block after you click the <b>Get webhooks</b> button.\n\n<div lang=\"en\" class=\"note\">\n  <p><strong>Note</strong></p>\n  <p>If the advanced settings are not displayed, make sure that webhook reception is connected in the general settings and you are on the <b>Testing &gt; Payments and Store</b> tab.</p>\n</div>\n\nIn this section, you can set up the receipt of additional information in webhooks. To do this, set the corresponding switches to the active position. The line of each permission indicates the webhooks that will be affected by changing the settings.\n\n<table>\n  <thead>\n    <tr>\n        <th>Toggle</th>\n        <th>Description</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n        <td>Show info about the saved payment account</td>\n        <td>Information about the saved payment method is passed in the <code>payment_account</code> custom object.</td>\n    </tr>\n    <tr>\n        <td>Show info about transactions via saved payment methods</td>\n        <td><p>Information is passed in the following custom parameters of the webhook:</p><ul><li><code>saved_payment_method</code>:<ul><li><code>0</code> — the saved payment method was not used</li><li><code>1</code> —  the payment method was saved when making the current payment</li><li><code>2</code> — the previously saved payment method is used</li></ul></li><li><code>payment_type</code>:<ul><li><code>1</code> — one-time payment</li><li><code>2</code> — recurring payment</li></ul></li></ul></td>\n    </tr>\n    <tr>\n        <td>Add order object to webhook</td>\n        <td>Information about the order is passed in the <code>order</code> object of the <a href=\"/webhooks/operation/payment/\">Payment</a> webhook.</td>\n    </tr>\n    <tr>\n        <td>Send only necessary user parameters without sensitive data</td>\n        <td><p>Only the following information about the user is passed in the webhook:</p><ul><li>ID</li><li>country</li></ul></td>\n    </tr>\n    <tr>\n        <td>Send custom parameters</td>\n        <td>Information about <a href=\"/api/pay-station/operation/create-token/\">custom token parameters</a> is passed in the webhook.</td>\n    </tr>\n    <tr>\n        <td>Show card BIN and suffix</td>\n        <td><p>The following information about the bank card number is passed in the webhook:</p><ul><li>the first 6 digits in the <code>card_bin</code> parameter</li><li>the last 4 digits in the <code>card_suffix</code></li></ul></td>\n    </tr>\n    <tr>\n        <td>Show card brand</td>\n        <td>The brand of the card used for making the payment. For example, Mastercard or Visa.</td>\n    </tr>\n  </tbody>\n</table>\n\n![Advanced settings](https://cdn.xsolla.net/developers/current/images/api_docs/advanced-settings-upd.png)\n\n# Test webhooks in Publisher Account\n\nTesting webhooks helps to ensure the correct setup of the project both on your side and on Xsolla side.\n\nIf webhooks are <a href=\"/webhooks/overview/#section/Set-up-webhooks-in-Publisher-Account\">set up</a> successfully, a webhooks testing section is displayed below the webhooks setup section.\n\n![Webhooks testing section](https://cdn.xsolla.net/developers/current/images/api_docs/testing.png)\n\nThe testing section in the Publisher Account varies depending on the webhook receiving option.\n\n<b>If you receive combined webhooks</b>:\n\n<table>\n  <thead>\n    <tr>\n        <th>Tab name for webhook testing</th>\n        <th>Webhook name and type</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n        <td><b>Payments and store</b></td>\n        <td>User validation &gt; <a href=\"/webhooks/operation/user-validation/\">User validation</a> (<code>user_validation</code>)</td>\n    </tr>\n    <tr>\n        <td></td>\n        <td>Game services &gt; Combined webhooks &gt; <a href=\"/webhooks/operation/successful-order-payment\">Successful payment for order</a> (<code>order_paid</code>)</td>\n    </tr>\n    <tr>\n        <td></td>\n        <td>Game services &gt; Combined webhooks &gt; <a href=\"/webhooks/operation/order-cancellation\">Order cancellation</a> (<code>order_canceled</code>)</td>\n    </tr>\n    <tr>\n        <td><b>Subscriptions</b></td>\n        <td>User validation &gt; <a href=\"/webhooks/operation/user-validation/\">User validation</a> (<code>user_validation</code>)</td>\n    </tr>\n    <tr>\n        <td></td>\n        <td>Payments &gt; <a href=\"/webhooks/operation/payment\">Payment</a> (<code>payment</code>)</td>\n    </tr>\n  </tbody>\n</table>\n\n\n<b>If you receive separate webhooks</b>:\n\n<table>\n  <thead>\n    <tr>\n        <th>Tab name for webhook testing</th>\n        <th>Webhook name and type</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n        <td><b>Store</b></td>\n        <td>Game services &gt; Separate webhooks &gt; <a href=\"/webhooks/operation/successful-order-payment-separate\">Successful payment for order</a> (<code>order_paid</code>)</td>\n    </tr>\n    <tr>\n        <td></td>\n        <td>Game services &gt; Separate webhooks &gt; <a href=\"/webhooks/operation/order-cancellation-separate\">Order cancellation</a> (<code>order_canceled</code>)</td>\n    </tr>\n    <tr>\n        <td><b>Payments</b></td>\n        <td>User validation &gt; <a href=\"/webhooks/operation/user-validation/\">User validation</a> (<code>user_validation</code>)</td>\n    </tr>\n    <tr>\n        <td></td>\n        <td>Payments &gt; <a href=\"/webhooks/operation/payment\">Payment</a> (<code>payment</code>)</td>\n    </tr>\n    <tr>\n        <td><b>Subscriptions</b></td>\n        <td>User validation &gt; <a href=\"/webhooks/operation/user-validation/\">User validation</a> (<code>user_validation</code>)</td>\n    </tr>\n    <tr>\n        <td></td>\n        <td>Payments &gt; <a href=\"/webhooks/operation/payment\">Payment</a> (<code>payment</code>)</td>\n    </tr>\n  </tbody>\n</table>\n\n<div lang=\"en\" class=\"note\">\n  <p><strong>Note</strong></p>\n  <p>If a warning that the test has not passed appears in the testing section, check the webhook response settings in your <a href=\"/webhooks/overview/#section/Webhook-listener\">webhook listener</a>. The reasons for the errors in testing are indicated in the test results.</p>\n  <p><b>Example:</b></p>\n  <p>You use the specialized site <a href=\"https://webhook.site/#!/\">webhook.site</a> for testing.</p>\n  <p>An error is displayed in the <b>Testing response to invalid signature</b> section.</p>\n  <p>This happens because Xsolla sends a webhook with an incorrect signature and expects your handler to respond with a <code>4xx</code> HTTP code specifying the <code>INVALID_SIGNATURE</code> error code.</p>\n  <p><a href=\"https://webhook.site/#!/\">webhook.site</a> sends a <code>200</code> HTTP code in response to all webhooks, including a webhook with an incorrect signature. The expected <code>4xx</code> HTTP code cannot be obtained, so an error is displayed in the test result.</p>\n</div>\n\n![Testing error](https://cdn.xsolla.net/developers/current/images/api_docs/test-error.png)\n\nThe process of testing for the scenario with combined webhooks is described below.\n\n## Payments and Store\n\nIn the <b>Payments and Store</b> tab, you can test the following webhooks:\n- <a href=\"/webhooks/operation/user-validation/\">User validation</a> (`user_validation`)\n- <a href=\"/webhooks/operation/successful-order-payment\">Successful payment for order</a> (`order_paid`)\n- <a href=\"/webhooks/operation/order-cancellation\">Order cancellation</a> (`order_canceled`)\n\nTo test:\n1. In the webhooks testing section, go to the <b>Payments and Store</b> tab.\n2. In the drop-down menu, select the type of item. If the item of selected type is not set up in Publisher Account, click:\n    * <b>Connect</b> – if the module with items of this type is not connected\n    * <b>Configure</b> – if you connected the module previously, but have not completed the setup\n<br/>When you click the button, you will be redirected to the section of Publisher Account corresponding to the type of the selected item. After creating the item, return to the webhook testing section and proceed to the next step.\n3. Fill in the necessary fields:\n  <ol type=\"a\">\n    <li>Select the items’ SKU from the drop-down list and indicate the amount. You can choose multiple items of the same type by clicking <b>+</b> and adding them in a new line.</li>\n    <li><b>User ID</b> — when testing, you can use any combination of letters and digits.</li>\n    <li><b>Public user ID</b> — ID known to a user, e.g., an email or a nickname. This field is displayed if public user ID is enabled in your project in the <b>Pay Station &gt; Settings</b>.</li>\n    <li>Enter any value in the <b>Xsolla Order ID</b> field.</li>\n    <li><b>Xsolla Invoice ID</b> — transaction ID on Xsolla side. When testing, you can use any numeric value.</li>\n    <li><b>Invoice ID</b> — transaction ID on your game’s side. When testing, you can use any combination of letters and digits. It is not a required parameter for a successful payment, but you can pass it to link the transaction ID on your side to the transaction ID on Xsolla side.</li>\n    <li><b>Amount</b> — payment amount. When testing, you can use any numeric value.</li>\n    <li><b>Currency</b> — select a currency from the drop-down list.</li>\n  </ol>\n\n4. Click <b>Test webhooks</b>.\n\n\n<a href=\"/webhooks/operation/user-validation/\">User validation</a>, <a href=\"/webhooks/operation/successful-order-payment\">Successful payment for order</a> and <a href=\"/webhooks/operation/order-cancellation\">Order cancellation</a> webhooks with the specified data are sent to the provided URL. The results of testing each webhook type are displayed below the <b>Test webhooks</b> button.\n\nIf public user ID is enabled in your project, you will also see the results of a user search check.\n\nFor each webhook, you need to configure processing both scenarios: a successful one and the one with an error.\n\n![Payments testing section](https://cdn.xsolla.net/developers/current/images/api_docs/payments-tab.png)\n\n## Subscriptions\nIn the <b>Subscriptions</b> tab, you can test the following webhooks:\n- <a href=\"/webhooks/operation/user-validation/\">User validation</a> (`user_validation`)\n- <a href=\"/webhooks/operation/payment\">Payment</a> (`payment`)\n\n<div lang=\"en\" class=\"note\">\n  <p><strong>Note</strong></p>\n  <p>In Publisher Account, you can only test basic User Validation and Payment webhooks. To test other webhook types, go to:</p>\n  <p><ul><li><a href=\"/doc/subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_set_up_webhooks_test_payment\">Test subscription purchase</a></li><li><a href=\"/doc/subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_set_up_webhooks_test_renewal\">Test subscription renewal</a></li><li><a href=\"/doc/subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_set_up_webhooks_test_cancelation\">Test subscription cancellation</a></li></ul></p>\n</div>\n\n<p></p>\n\n<div lang=\"en\" class=\"note\">\n  <p><strong>Note</strong></p>\n  <p>To test webhooks, you should have at least one <a href=\"/doc/subscriptions/integration-guide/set-up-plan/\">subscription plan created</a> in the <b>Publisher Account &gt; Subscriptions &gt; Subscription Plans</b> section.</p>\n</div>\n\nTo test:\n<ol>\n  <li>In the testing section, go to the <b>Subscriptions</b> tab.</li>\n  <li>Fill in the necessary fields:\n    <ol type=\"a\">\n      <li><b>User ID</b> — when testing, you can use any combination of letters and digits.</li>\n      <li><b>Xsolla Invoice ID</b> — transaction ID on Xsolla side. When testing, you can use any numeric value.</li>\n      <li><b>Public user ID</b> — ID known to a user, e.g., an email or a nickname. This field is displayed if public user ID is enabled in your project in the Pay Station &gt; Settings &gt; Additional settings section.</li>\n      <li><b>Currency</b> — select a currency from the drop-down list.</li>\n      <li><b>Plan ID</b> — a subscription plan. Choose a plan from the drop-down list.</li>\n      <li><b>Subscription product</b> — choose a product from the drop-down list (optional).</li>\n      <li><b>Amount</b> — payment amount. When testing, you can use any numeric value.</li>\n      <li><b>Invoice ID</b> — transaction ID on your game’s side. When testing, you can use any combination of letters and digits. It is not a required parameter for a successful payment, but you can pass it to link the transaction ID on your side to the transaction ID on Xsolla side.</li>\n      <li><b>Trial period</b>. To test the <a href=\"/doc/subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_set_up_webhooks_sandbox\">purchase of a subscription without a trial period</a> or to test the <a href=\"/doc/subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_set_up_webhooks_test_renewal\">renewal of a subscription</a>, specify the value <code>0</code>.</li>\n    </ol>\n  </li>\n  <li>Click <b>Test webhooks</b>.</li>\n</ol>\n\nIn the specified URL, you will receive webhooks with filled in data. Testing results of each webhook, for both a successful scenario and a scenario with an error, are displayed under the <b>Test webhooks</b> button.\n\n<a id=\"webhook-listener\"></a>\n\n# Webhook listener\n\nWebhook listener is program code that allows receiving incoming webhooks at a specified URL address, <a href=\"/webhooks/overview/#section/Webhook-listener/Generation-of-signature\">generating a signature</a>, and <a href=\"/webhooks/overview/#section/Webhook-listener/Sending-responses-to-webhook\">sending a response</a> to the Xsolla webhook server.\n\n<div lang=\"en\" class=\"note\">\n  <p><strong>Note</strong></p>\n  <p>You can use the <a href=\"https://developers.xsolla.com/sdk/php/\">Pay Station PHP SDK library</a>, which contains ready-made classes for processing webhooks.</p>\n</div>\n\n<!-- IMPORTANT! Changing the list of IP addresses should be coordinated with the administrators. Request for Director of Infrastructure and IT approval in the ticket for changing the IP address list. -->\n\nOn the your application side, implement the reception of webhooks from the following IP addresses:\n- `185.30.20.0/24`\n- `185.30.21.0/24`\n- `185.30.22.0/24`\n- `185.30.23.0/24`\n- `34.102.38.178`\n- `34.94.43.207`\n- `35.236.73.234`\n- `34.94.69.44`\n- `34.102.22.197`\n\nIf you integrated <a href=\"/doc/login/\">Login</a> product, additionally add processing webhooks from the following IP addresses:\n\n- `34.94.0.85`\n- `34.94.14.95`\n- `34.94.25.33`\n- `34.94.115.185`\n- `34.94.154.26`\n- `34.94.173.132`\n- `34.102.48.30`\n- `35.235.99.248`\n- `35.236.32.131`\n- `35.236.35.100`\n- `35.236.117.164`\n\nLimitations:\n- There should not be multiple successful transactions with the same ID in your application's database.\n- If the webhook listener received a webhook with an ID that already exists in the database, you need to return the result of the previous processing of this transaction. It is not recommended to credit the user with a duplicate purchase and create duplicate records in the database.\n\n## Generation of signature\n\nTo ensure secure data transmission, you must verify that the webhook was actually sent from the Xsolla server and hasn't been tampered with during transit. To do this, generate your own signature based on the request body payload and compare it with the signature provided in the `authorization` header of the incoming request. If the signatures match, the webhook is authentic and safe to process.\n\nVerification steps:\n\n1. Retrieve the signature from the `authorization` header of the incoming webhook request. The header format is `Signature <signature_value>`.\n2. Retrieve the webhook request body in JSON format. <div class=\"notice\"><p><strong>Notice</strong></p><p>Use the JSON payload exactly as received. Do not parse or re-encode the payload, as this will alter the formatting and cause signature verification to fail.</p></div><p></p>\n\n3. Generate your own signature for comparison:\n   <ol type=\"a\">\n   <li>Concatenate the JSON payload with your project's secret key by appending the key to the end of the string.</li>\n   <li>Apply the SHA-1 cryptographic hash function to the resulting string. The result will be a lowercase hexadecimal string.</li>\n   </ol>\n4. Compare your generated signature with the one from the `authorization` header. If they match, the webhook is authentic.\n\nBelow you can find signature generation implementation examples for the following languages: C#, C++, Go, PHP, and Node.js.\n\n### Example of a webhook (HTTP):\n\n```http\nPOST /your_uri HTTP/1.1\nhost: your.host\naccept: application/json\ncontent-type: application/json\ncontent-length: 165\nauthorization: Signature 52eac2713985e212351610d008e7e14fae46f902\n{\n  \"notification_type\":\"user_validation\",\n  \"user\":{\n      \"ip\":\"127.0.0.1\",\n      \"phone\":\"18777976552\",\n      \"email\":\"email@example.com\",\n      \"id\":1234567,\n      \"name\":\"Xsolla User\",\n      \"country\":\"US\"\n  }\n}\n```\n\n### Example of a webhook (curl):\n\n```bash\ncurl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-H 'authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \\\n-d '{\n  \"notification_type\":\n    \"user_validation\",\n    \"user\":\n      {\n        \"ip\": \"127.0.0.1\",\n        \"phone\": \"18777976552\",\n        \"email\": \"email@example.com\",\n        \"id\": 1234567,\n        \"name\": \"Xsolla User\",\n        \"country\": \"US\"\n      }\n    }'\n```\n\n### C# example of implementing signature generation (general sample):\n\n<div lang=\"en\" class=\"note\">\n  <p><strong>Note</strong></p>\n  <p>This code sample is compatible with .NET Framework 4.0 and later, as well as with .NET Core and other modern .NET versions. Signature verification uses constant-time comparison via the <code>ConstantTimeEquals</code> method to help prevent timing attacks.</p>\n</div>\n\n```csharp\nusing System;\nusing System.Security.Cryptography;\nusing System.Text;\npublic static class XsollaWebhookSignature\n{\n    public static string ComputeSha1(string jsonBody, string secretKey)\n    {\n        // Concatenation of the JSON from the request body and the project's secret key\n        string dataToSign = jsonBody + secretKey;\n        using (SHA1 sha1 = SHA1.Create())\n        {\n            byte[] hashBytes = sha1.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));\n            // Convert hash bytes to lowercase hexadecimal string\n            var hexString = new StringBuilder(hashBytes.Length * 2);\n            foreach (byte b in hashBytes)\n            {\n                hexString.Append(b.ToString(\"x2\"));\n            }\n            return hexString.ToString();\n        }\n    }\n    public static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature)\n    {\n        string computedSignature = ComputeSha1(jsonBody, secretKey);\n        string receivedSignatureLower = receivedSignature.ToLower();\n        // Use constant-time comparison to prevent timing attacks\n        return ConstantTimeEquals(computedSignature, receivedSignatureLower);\n    }\n    private static bool ConstantTimeEquals(string a, string b)\n    {\n        if (a.Length != b.Length)\n        {\n            return false;\n        }\n        int result = 0;\n        for (int i = 0; i < a.Length; i++)\n        {\n            result |= a[i] ^ b[i];\n        }\n        return result == 0;\n    }\n}\n```\n\n### C# example of implementing signature generation (.NET 5.0 and later):\n\n<div lang=\"en\" class=\"note\">\n  <p><strong>Note</strong></p>\n  <p>To use the <code>Convert.ToHexString</code> method, you need .NET 5.0 and later.<p></p>If you have .NET 7.0 and later, you can also use the <code>CryptographicOperations.FixedTimeEquals</code> method instead of <code>ConstantTimeEquals</code>.</p>\n</div>\n\n```csharp\n// For .NET 5.0 and later, you can use the more concise Convert.ToHexString method:\nusing System;\nusing System.Security.Cryptography;\nusing System.Text;\npublic static class XsollaWebhookSignature\n{\n    public static string ComputeSha1(string jsonBody, string secretKey)\n    {\n        string dataToSign = jsonBody + secretKey;\n        using var sha1 = SHA1.Create();\n        byte[] hashBytes = sha1.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));\n        return Convert.ToHexString(hashBytes).ToLower();\n    }\n    public static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature)\n    {\n        string computedSignature = ComputeSha1(jsonBody, secretKey);\n        string receivedSignatureLower = receivedSignature.ToLower();\n        // Use constant-time comparison to prevent timing attacks\n        return ConstantTimeEquals(computedSignature, receivedSignatureLower);\n    }\n    private static bool ConstantTimeEquals(string a, string b)\n    {\n        if (a.Length != b.Length)\n        {\n            return false;\n        }\n        int result = 0;\n        for (int i = 0; i < a.Length; i++)\n        {\n            result |= a[i] ^ b[i];\n        }\n        return result == 0;\n    }\n}\n```\n\n### C# example of implementing signature generation (.NET 7.0 and later):\n\n<div lang=\"en\" class=\"note\">\n  <p><strong>Note</strong></p>\n  <p>If you have .NET 7.0 and later, you can use the <code>CryptographicOperations.FixedTimeEquals</code> method.</p>\n</div>\n\n```csharp\n// For .NET 7.0+, you can use the built-in CryptographicOperations.FixedTimeEquals:\nusing System.Security.Cryptography;\npublic static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature)\n{\n    string computedSignature = ComputeSha1(jsonBody, secretKey);\n    byte[] computedBytes = Encoding.UTF8.GetBytes(computedSignature);\n    byte[] receivedBytes = Encoding.UTF8.GetBytes(receivedSignature.ToLower());\n    return CryptographicOperations.FixedTimeEquals(computedBytes, receivedBytes);\n}\n```\n\n### C++ example of implementing signature generation:\n\n```c++\n#include <string>\n#include <sstream>\n#include <iomanip>\n#include <openssl/sha.h>\nclass XsollaWebhookSignature {\npublic:\n    static std::string computeSha1(const std::string& jsonBody, const std::string& secretKey) {\n        // Concatenation of the JSON from the request body and the project's secret key\n        std::string dataToSign = jsonBody + secretKey;\n        unsigned char digest[SHA_DIGEST_LENGTH];\n        // Create SHA1 hash\n        SHA1(reinterpret_cast<const unsigned char*>(dataToSign.c_str()),\n             dataToSign.length(), digest);\n        // Convert to lowercase hexadecimal string\n        std::ostringstream hexStream;\n        hexStream << std::hex << std::setfill('0');\n        for (int i = 0; i < SHA_DIGEST_LENGTH; ++i) {\n            hexStream << std::setw(2) << static_cast<unsigned int>(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<?php\nclass XsollaWebhookSignature\n{\n    /**\n     * Compute SHA1 signature from webhook JSON body and secret key\n     *\n     * @param string $jsonBody The raw JSON body from webhook\n     * @param string $secretKey The project's secret key\n     * @return string The lowercase SHA1 signature\n     */\n    public static function computeSha1(string $jsonBody, string $secretKey): string\n    {\n        // Concatenation of the JSON from the request body and the project's secret key\n        $dataToSign = $jsonBody . $secretKey;\n        // Generate SHA1 signature\n        $signature = sha1($dataToSign);\n        return strtolower($signature);\n    }\n    /**\n     * Verify webhook signature using timing-safe comparison\n     *\n     * @param string $jsonBody The raw JSON body from webhook\n     * @param string $secretKey The project's secret key  \n     * @param string $receivedSignature The signature from authorization header\n     * @return bool True if signature is valid, false otherwise\n     */\n    public static function verifySignature(string $jsonBody, string $secretKey, string $receivedSignature): bool\n    {\n        $computedSignature = self::computeSha1($jsonBody, $secretKey);\n        // Use hash_equals for timing-safe comparison\n        return hash_equals($computedSignature, strtolower($receivedSignature));\n    }\n}\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 <a href=\"/webhooks/overview/#section/Errors\">description of the problem</a> 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 <a href=\"/webhooks/operation/successful-order-payment\">Successful payment for order</a> and <a href=\"/webhooks/operation/order-cancellation\">Order cancellation</a> 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 <a href=\"/webhooks/operation/payment\">Payment</a> and <a href=\"/webhooks/operation/refund\">Refund</a> webhooks is described on the respective webhook page.\n\n<div lang=\"en\" class=\"notice\">\n  <p><strong>Notice</strong></p>\n  <p>The payment will still be refunded to the user if all of the following conditions are met:<ul><li>The refund was initiated by Xsolla.</li><li>In response to a webhook, a <code>4xx</code> status code was returned, or no response was received after all retry attempts, or a <code>5xx</code> status code was returned.</li></ul></p>\n</div>\n\nIf the Xsolla server did not receive a response to the <a href=\"/webhooks/operation/user-validation/\">User validation</a> webhook or received a response with a code of `400` or `5xx`, the <a href=\"/webhooks/operation/user-validation/\">User validation</a> webhook is not resent.\nIn this case, the user sees an error and the <a href=\"/webhooks/operation/payment\">Payment</a> and <a href=\"/webhooks/operation/successful-order-payment\">Successful payment for order</a> webhooks are not sent.\n\n# Errors\n\nError codes for HTTP code 400:\n\n<table>\n  <thead>\n    <tr>\n        <th>Code</th>\n        <th>Message</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n        <td>INVALID_USER</td>\n        <td>Invalid user</td>\n    </tr>\n    <tr>\n        <td>INVALID_PARAMETER</td>\n        <td>Invalid parameter</td>\n    </tr>\n    <tr>\n        <td>INVALID_SIGNATURE</td>\n        <td>Invalid signature</td>\n    </tr>\n    <tr>\n        <td>INCORRECT_AMOUNT</td>\n        <td>Incorrect amount</td>\n    </tr>\n    <tr>\n        <td>INCORRECT_INVOICE</td>\n        <td>Incorrect invoice</td>\n    </tr>\n  </tbody>\n</table>\n\n```\nHTTP/1.1 400 Bad Request\n{\n    \"error\":{\n        \"code\":\"INVALID_USER\",\n        \"message\":\"Invalid user\"\n    }\n}\n```\n\n# Webhooks list\n\n<div lang=\"en\" class=\"note\">\n  <p><strong>Note</strong></p>\n  <p>The notification type is sent in the <code>notification_type</code> parameter.</p>\n</div>\n\n<table>\n  <thead>\n    <tr>\n        <th>Webhook</th>\n        <th>Notification type</th>\n        <th>Description</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n        <td><a href=\"/webhooks/operation/user-validation/\">User validation</a></td>\n        <td><code>user_validation</code></td>\n        <td>Sent to check if a user exists in the game.</td>\n    </tr>\n    <tr>\n        <td><a href=\"/webhooks/operation/user-search/\">User search</a></td>\n        <td><code>user_search</code></td>\n        <td>Sent to get user info based on public user ID.</td>\n    </tr>\n    <tr>\n        <td><a href=\"/webhooks/operation/payment/\">Payment</a></td>\n        <td><code>payment</code></td>\n        <td>Sent when a user completes a payment.</td>\n    </tr>\n    <tr>\n        <td><a href=\"/webhooks/operation/refund/\">Refund</a></td>\n        <td><code>refund</code></td>\n        <td>Sent when a payment must be canceled for any reason.</td>\n    </tr>\n    <tr>\n        <td><a href=\"/webhooks/operation/partial-refund/\">Partial refund</a></td>\n        <td><code>partial_refund</code></td>\n        <td>Sent when a payment must be partially canceled for any reason.</td>\n    </tr>\n    <tr>\n        <td><a href=\"/webhooks/operation/payment-declined/\">Declined payment</a></td>\n        <td><code>ps_declined</code></td>\n        <td>Sent when a payment is declined by payment system.</td>\n    </tr>\n    <tr>\n        <td><a href=\"https://developers.xsolla.com/webhooks/operation/afs-rejected-transaction/\">AFS rejected transaction</a></td>\n        <td><code>afs_reject</code></td>\n        <td>Sent when a transaction is declined during an AFS check.</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/webhooks/operation/afs-rejected-blocklist/\">AFS updated blocklist</a></td>\n      <td><code>afs_black_list</code></td>\n      <td>Sent when the AFS blocklist is updated.</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/webhooks/operation/created-subscription/\">Created subscription</a></td>\n      <td><code>create_subscription</code></td>\n      <td>Sent when a user creates a subscription.</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/webhooks/operation/updated-subscription/\">Updated subscription</a></td>\n      <td><code>update_subscription</code></td>\n      <td>Sent when a subscription is renewed or changed.</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/webhooks/operation/canceled-subscription/\">Canceled subscription</a></td>\n      <td><code>cancel_subscription</code></td>\n      <td>Sent when a subscription is canceled.</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/webhooks/operation/nonrenewing-subscription/\">Nonrenewing subscription</a></td>\n      <td><code>non_renewal_subscription</code></td>\n      <td>Sent when status is set to nonrenewing.</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/webhooks/operation/add-payment-account/\">Add payment account</a></td>\n      <td><code>payment_account_add</code></td>\n      <td>Sent when a user adds or saves a payment account.</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/webhooks/operation/remove-payment-account/\">Remove payment account</a></td>\n      <td><code>payment_account_remove</code></td>\n      <td>Sent when a user removes the payment account from saved accounts.</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/webhooks/operation/user-validation-in-webshop\">User validation in Web Shop</a></td>\n      <td><code>-</code></td>\n      <td>Sent from a Web Shop site to check if a user exists in the game.</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/webhooks/operation/personalized-partner-catalog\">Catalog personalization on partner’s side</a></td>\n      <td><code>partner_side_catalog</code></td>\n      <td>Sent when a user interacts with the store.</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/webhooks/operation/successful-order-payment\">Successful payment for order</a></td>\n      <td><code>order_paid</code></td>\n      <td>Sent when an order is paid.</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/webhooks/operation/order-cancellation\">Order cancellation</a></td>\n      <td><code>order_canceled</code></td>\n      <td>Sent when an order is canceled.</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/webhooks/operation/dispute\">Dispute</a></td>\n      <td><code>dispute</code></td>\n      <td>Sent when a new dispute is opened.</td>\n    </tr>\n  </tbody>\n</table>\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:


        * when a user chooses a payment method in the payment UI

        * when a user enters data in the payment form, e.g., bank card data or
        the ZIP code when paying via PayPal

        * when a user clicks **Pay now** to proceed with payment

        * when payment process is completed and the transaction status changes
        to `done`


        The request is sent when paying with any payment methods.


        When 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 <a
        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/store">Project
        settings &gt; Webhooks &gt; Advanced settings</a> section.


        <div lang="en" class="note">
          <p><strong>Note</strong></p>
          <p>If you registered in Publisher Account on or before January 22, 2025, you can find the toggles in the <a href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/payments">Project settings &gt; Webhooks &gt; Testing &gt; Payments &gt; Advanced settings</a> section.</p>
        </div>


        <table>
          <thead>
            <tr>
                <th>Toggle</th>
                <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
                <td>Send only necessary user parameters without sensitive data</td>
                <td><p>Only the following information about the user is passed in the webhook:</p><ul><li>ID</li><li>country</li></ul></td>
            </tr>
            <tr>
                <td>Send custom parameters</td>
                <td>Information about <a href="/api/pay-station/operation/create-token/">custom token parameters</a> is passed in the webhook.</td>
            </tr>
          </tbody>
        </table>
      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' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            13342703ccaca5064ad33ba451d800c5e823db8f' \

            -d '{
                "notification_type":"user_validation",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "user": {
                    "ip": "127.0.0.1",
                    "phone": "18777976552",
                    "email": "email@example.com",
                    "id": "1234567",
                    "name": "John Smith",
                    "country": "US"
                }
            }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'notification_type' => 'user_validation',
                'settings' => array(
                  'project_id' => 18404,
                  'merchant_id' => 2340
                ),
                'user' => array(
                    'ip' => '127.0.0.1',
                    'phone' => '18777976552',
                    'email'=> 'email@example.com',
                    'id'=> '1234567',
                    'country' => 'US'
                )
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host: your.hostname
            accept: application/json
            content-type: application/json
            content-length: 240
            authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

            {
                "notification_type": "user_validation",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "user": {
                    "ip": "127.0.0.1",
                    "phone": "18777976552",
                    "email": "email@example.com",
                    "id": "1234567",
                    "name": "John Smith",
                    "country": "US"
                }
            }
  user-search:
    post:
      summary: User search
      description: >-
        <nt>Public User ID</nt> is a parameter that uniquely identifies the user
        and is known to them, unlike <nt>User ID</nt> (<nt>Public User ID</nt>
        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' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            13342703ccaca5064ad33ba451d800c5e823db8f' \

            -d '{
                "notification_type": "user_search",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "user": {
                    "public_id": "email@example.com"
                }
            }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'notification_type' => 'user_search',
                'settings' => array(
                  'project_id' => 18404,
                  'merchant_id' => 2340
                ),
                'user' => array(
                    'public_id' => 'email@example.com'
                )
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host: your.hostname
            accept: application/json
            content-type: application/json
            content-length: 240
            authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

            {
                "notification_type": "user_search",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "user": {
                    "public_id": "email@example.com"
                }
            }
  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.


        The expected response codes are described in the <b>Responses</b>
        section, but you can use other response codes as well:


        <table>
            <thead>
            <tr>
                <th>Response code</th>
                <th>Description</th>
            </tr>
            </thead>
            <tbody>
            <tr>
                <td><code>200</code>, <code>201</code>, <code>204</code></td>
                <td>A successful response.</td>
            </tr>
            <tr>
                <td><code>4xx</code></td>
                <td>An error occurred. For example, if the specified user was not found or an invalid signature was passed.</td>
            </tr>
            <tr>
                <td><code>5xx</code></td>
                <td>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.</td>
            </tr>
            </tbody>
        </table>


        When you save the webhook URL in <a
        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/store">Publisher
        Account</a>, you can also set up receiving additional information in
        webhooks.


        <div lang="en" class="note">
          <p><strong>Note</strong></p>
          <p>If you registered in Publisher Account on or before January 22, 2025, you can find the toggles in your project in the <a href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/payments">Settings &gt; Webhooks &gt; Testing &gt; Payments &gt; Advanced settings</a> section.</p>
        </div>


        <table>
          <thead>
            <tr>
                <th>Toggle</th>
                <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
                <td>Show info about the saved payment account</td>
                <td>Information about the saved payment method is passed in the <code>payment_account</code> custom object.</td>
            </tr>
            <tr>
                <td>Show info about transactions via saved payment methods</td>
                <td><p>Information is passed in the following custom parameters of the webhook:</p><ul><li><code>saved_payment_method</code>:<ul><li><code>0</code> — the saved payment method was not used</li><li><code>1</code> —  the payment method was saved when making the current payment</li><li><code>2</code> — the previously saved payment method is used</li></ul></li><li><code>payment_type</code>:<ul><li><code>1</code> — one-time payment</li><li><code>2</code> — recurring payment</li></ul></li></ul></td>
            </tr>
            <tr>
                <td>Add order object to webhook</td>
                <td>Information about the order is passed in the <code>order</code> object of the <a href="/webhooks/operation/payment/">Payment</a> webhook.</td>
            </tr>
            <tr>
                <td>Send only necessary user parameters without sensitive data</td>
                <td><p>Only the following information about the user is passed in the webhook:</p><ul><li>ID</li><li>country</li></ul></td>
            </tr>
            <tr>
                <td>Show card BIN and suffix</td>
                <td><p>The following information about the bank card number is passed in the webhook:</p><ul><li>the first 6 digits in the <code>card_bin</code> parameter</li><li>the last 4 digits in the <code>card_suffix</code></li></ul></td>
            </tr>
            <tr>
                <td>Show card brand</td>
                <td>The brand of the card used for making the payment. For example, Mastercard or Visa.</td>
            </tr>
          </tbody>
        </table>


        <div lang="en" class="notice">
          <p><strong>Notice</strong></p>
          <p>The set of fields sent in a webhook depends on:<ul><li>the advanced settings configured in Publisher Account</li><li>the custom settings configured on the Xsolla side</li></ul></p><p>If you have any questions, contact your Customer Success Manager or email to <a href="mailto:csm@xsolla.com">csm@xsolla.com</a>.</p>
        </div>
      tags:
        - payments
      operationId: payment
      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'
                        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.
                    order:
                      $ref: '#/components/schemas/order'
                      properties:
                        id:
                          type: integer
                          description: Order ID.
                        lineitems:
                          type: array
                          description: >-
                            Array of parameters that contain information about
                            the items.
                          items:
                            type: object
                            properties:
                              sku:
                                type: string
                                description: Item SKU.
                              quantity:
                                type: integer
                                description: Item quantity.
                              price:
                                type: object
                                description: >-
                                  Object that contains information about an item
                                  price.
                                properties:
                                  currency:
                                    type: string
                                    description: Currency of the item price.
                                  amount:
                                    type: number
                                    format: float
                                    description: >-
                                      Total price of the item in the selected
                                      currency.
                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: Your custom parameters.
      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' \
            -X POST \
            -d '{
                "notification_type": "payment",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "purchase": {
                    "subscription": {
                        "plan_id": "b5dac9c8",
                        "subscription_id": "10",
                        "product_id": "Demo Product",
                        "date_create": "2014-09-22T19:25:25+04:00",
                        "date_next_charge": "2014-10-22T19:25:25+04:00",
                        "currency": "USD",
                        "amount": 9.99
                    },
                    "checkout": {
                        "currency": "USD",
                        "amount": 50
                    },
                    "total": {
                        "currency": "USD",
                        "amount": 200
                    },
                    "promotions": [{
                        "technical_name": "Demo Promotion",
                        "id": 853
                    }],
                    "coupon": {
                        "coupon_code": "ICvj45S4FUOyy",
                        "campaign_code": "1507"
                    },
                    "order": {
                      "id": 1234
                      "lineitems": [
                      {
                        "sku": "com.xsolla.item_1",
                        "quantity": 1,
                        "price": {
                          "currency": "EUR",
                          "amount": 6.5
                          }
                      }
                      ]
                      }
                },
                "user": {
                    "ip": "127.0.0.1",
                    "phone": "18777976552",
                    "email": "email@example.com",
                    "id": "1234567",
                    "name": "John Smith",
                    "country": "US"
                },
                "transaction": {
                    "id": 1,
                    "external_id": 1,
                    "payment_date": "2014-09-24T20:38:16+04:00",
                    "payment_method": 1,
                    "payment_method_name": "PayPal",
                    "payment_method_order_id": 1234567890123456789,
                    "dry_run": 1,
                    "agreement": 1
                },
                "payment_details": {
                    "payment": {
                        "currency": "USD",
                        "amount": 230
                    },
                    "vat": {
                        "currency": "USD",
                        "amount": 0,
                        "percent": 20
                    },
                    "sales_tax": {
                        "currency": "USD",
                        "amount": 0,
                        "percent": 0
                    },
                    "direct_wht": {
                        "currency": "USD",
                        "amount": 0,
                        "percent": 0
                    },
                    "payout_currency_rate": "1",
                    "payout": {
                        "currency": "USD",
                        "amount": 200
                    },
                    "country_wht": {
                        "currency": "USD",
                        "amount": 2,
                        "percent": 10
                    },
                    "user_acquisition_fee": {
                        "currency": "USD",
                        "amount": 2,
                        "percent": 1
                    },
                    "xsolla_fee": {
                        "currency": "USD",
                        "amount": 10
                    },
                    "payment_method_fee": {
                        "currency": "USD",
                        "amount": 20
                    },
                    "repatriation_commission": {
                        "currency": "USD",
                        "amount": 10
                    }
                },
                "custom_parameters": {
                    "parameter1": "value1",
                    "parameter2": "value2"
                }
            }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'notification_type' => 'payment',
                'settings' => array(
                  'project_id' => 18404,
                  'merchant_id' => 2340
                ),
                'purchase' => array(
                    'total' => array(
                        'currency' => 'USD',
                        'amount' => 9.99
                    )
                ),
                'user' => array(
                    'ip' => '127.0.0.1',
                    'phone' => '18777976552',
                    'email' => 'email@example.com',
                    'id' => '1234567',
                    'country' => 'US'
                ),
                'transaction' => array(
                    'id' => 87654321,
                    'payment_date' => '2014-09-23T19:25:25+04:00',
                    'payment_method' => 1380,
                    'payment_method_name' => 'PayPal'
                    'payment_method_order_id' => 1234567890123456789,
                    'dry_run' => 1
                ),
                'payment_details' => array(
                    'payment' => array(
                        'currency' => 'USD',
                        'amount' => 9.99
                    ),
                    'vat' => array(
                        'currency' => 'USD',
                        'amount' => 0
                    ),
                    'sales_tax' => array(
                        'currency' => 'USD',
                        'amount' => 0
                    ),
                    'direct_wht' => array(
                        'currency' => 'USD',
                        'amount' => 70
                    ),
                    'payout_currency_rate' => '1',
                    'country_wht ' => array(
                        'currency' => 'USD',
                        'amount' => 2,
                        'percent' => 10
                    ),
                    'user_acquisition_fee' => array(
                        'currency' => 'USD',
                        'amount' => 2,
                        'percent' => 1
                    ),
                    'payout' => array(
                        'currency' => 'USD',
                        'amount' => 9.49
                    ),
                    'xsolla_fee' => array(
                        'currency' => 'USD',
                        'amount' => 0.19
                    ),
                    'payment_method_fee' => array(
                        'currency' => 'USD',
                        'amount' => 0.31
                    ),
                    'repatriation_commission' => array(
                        'currency' => 'USD',
                        'amount' => 0.2
                    )
                )
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your_uri HTTP/1.1
            host: your.host
            accept: application/json
            content-type: application/json
            content-length: 1721
            authorization: Signature 34553d151e656110c656696c919f9a10e05de542

            {
                "notification_type": "payment",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "purchase":{
                    "subscription": {
                        "plan_id": "b5dac9c8",
                        "subscription_id": "10",
                        "product_id": "Demo Product",
                        "date_create": "2014-09-22T19:25:25+04:00",
                        "date_next_charge": "2014-10-22T19:25:25+04:00",
                        "currency": "USD",
                        "amount": 9.99
                    },
                    "checkout": {
                        "currency": "USD",
                        "amount": 50
                    },
                    "total": {
                        "currency": "USD",
                        "amount": 200
                    },
                    "promotions": [{
                        "technical_name": "Demo Promotion",
                        "id": 853
                    }],
                    "coupon": {
                        "coupon_code": "ICvj45S4FUOyy",
                        "campaign_code": "1507"
                    },
                    "order": {
                      "id": 1234
                      "lineitems": [
                      {
                        "sku": "com.xsolla.item_1",
                        "quantity": 1,
                        "price": {
                          "currency": "EUR",
                          "amount": 6.5
                          }
                      }
                      ]
                      }
                },
                "user": {
                    "ip": "127.0.0.1",
                    "phone": "18777976552",
                    "email": "email@example.com",
                    "id": "1234567",
                    "name": "John Smith",
                    "country": "US"
                },
                "transaction": {
                    "id": 1,
                    "external_id": 1,
                    "payment_date": "2014-09-24T20:38:16+04:00",
                    "payment_method": 1,
                    "payment_method_name": "PayPal"
                    "payment_method_order_id": 1234567890123456789,
                    "dry_run": 1,
                    "agreement": 1
                },
                "payment_details": {
                    "payment": {
                        "currency": "USD",
                        "amount": 230
                    },
                    "vat": {
                        "currency": "USD",
                        "amount": 0,
                        "percent": 20
                    },
                    "sales_tax": {
                        "currency": "USD",
                        "amount": 0,
                        "percent": 0
                    },
                    "direct_wht": {
                        "currency": "USD",
                        "amount": 0,
                        "percent": 0
                    },
                    "payout_currency_rate": "1",
                    "country_wht": {
                        "currency": "USD",
                        "amount": 2,
                        "percent": 10
                    },
                    "user_acquisition_fee": {
                        "currency": "USD",
                        "amount": 2,
                        "percent": 1
                    },
                    "payout": {
                        "currency": "USD",
                        "amount": 200
                    },
                    "xsolla_fee": {
                        "currency": "USD",
                        "amount": 10
                    },
                    "payment_method_fee": {
                        "currency": "USD",
                        "amount": 20
                    },
                    "repatriation_commission": {
                        "currency": "USD",
                        "amount": 10
                    }
                },
                "custom_parameters": {
                    "parameter1": "value1",
                    "parameter2": "value2"
                }
            }
  refund:
    post:
      summary: Refund
      description: >
        When a payment is canceled, Xsolla sends details of the canceled
        transaction in a webhook with the `refund` type to the webhook URL.


        The webhook retry mechanism depends on who initiated the refund:

        * If the refund was initiated on your side, the webhook isn’t resent.
        The payment is refunded to the user regardless of the response to a
        webhook.

        * If the refund was initiated by a third party — e.g., a payment system
        or Xsolla Customer Support team — and in response to a webhook, a `5xx`
        status code was returned, the webhook is resent at increasing intervals.
        The maximum number of retries is 12 within 48 hours from the first
        attempt.


        For detailed information about the refund process, refer to the
        [instructions](/doc/pay-station/features/refund/).


        <div lang="en" class="notice">
          <p><strong>Notice</strong></p>
          <p>The payment will still be refunded to the user if all of the following conditions are met:<ul><li>The refund was initiated by Xsolla.</li><li>In response to a webhook, a <code>4xx</code> status code was returned, or no response was received after all retry attempts, or a <code>5xx</code> status code was returned.</li></ul></p>
        </div>


        When you save the webhook URL in <a
        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/store">Publisher
        Account</a>, you can also set up receiving additional information in
        webhooks.


        <div lang="en" class="note">
          <p><strong>Note</strong></p>
          <p>If you registered in Publisher Account on or before January 22, 2025, you can find the toggles in your project in the <a href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/payments">Settings &gt; Webhooks &gt; Testing &gt; Payments &gt; Advanced settings</a> section.</p>
        </div>


        <table>
          <thead>
            <tr>
                <th>Toggle</th>
                <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
                <td>Show info about transactions via saved payment methods</td>
                <td><p>Information is passed in the following custom parameters of the webhook:</p><ul><li><code>saved_payment_method</code>:<ul><li><code>0</code> — the saved payment method was not used</li><li><code>1</code> —  the payment method was saved when making the current payment</li><li><code>2</code> — the previously saved payment method is used</li></ul></li><li><code>payment_type</code>:<ul><li><code>1</code> — one-time payment</li><li><code>2</code> — recurring payment</li></ul></li></ul></td>
            </tr>
          </tbody>
        </table>


        Refund codes:


        <table>
            <thead>
            <tr>
                <th>Code</th>
                <th>Reason</th>
                <th>Description</th>
            </tr>
            </thead>
            <tbody>
            <tr>
                <td>1</td>
                <td>Cancellation by the user request / the game request</td>
                <td>Cancellation initiated from Publisher Account.</td>
            </tr>
            <tr>
                <td>2</td>
                <td>Chargeback</td>
                <td>Transaction chargeback requested.</td>
            </tr>
            <tr>
                <td>3</td>
                <td>Integration error</td>
                <td>Issues in integration between Xsolla and the game.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>4</td>
                <td>Potential fraud</td>
                <td>Fraud suspected.<br/><b>Recommendation: Add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>5</td>
                <td>Test payment</td>
                <td>Test transaction followed by cancellation.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>6</td>
                <td>User invoice expired</td>
                <td>Invoice overdue (used for postpaid model).</td>
            </tr>
            <tr>
                <td>7</td>
                <td>Fraud notification from PS</td>
                <td>Payment refused by payment system. Potential fraud detected by PS.<br/><b>Recommendation: Add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>8</td>
                <td>Cancellation by the PS request</td>
                <td>Cancellation requested by payment system.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>9</td>
                <td>Cancellation by the user request</td>
                <td>The user was not satisfied with the game or the purchase for any reason.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>10</td>
                <td>Cancellation by the game request</td>
                <td>Cancellation requested by the game.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>11</td>
                <td>Account holder called to report fraud</td>
                <td>The account owner states that they didn’t make the transaction.</td>
            </tr>
            <tr>
                <td>12</td>
                <td>Friendly fraud</td>
                <td>Friendly fraud reported.</td>
            </tr>
            <tr>
                <td>13</td>
                <td>Duplicate</td>
                <td>Duplicate transaction for the same invoice.</td>
            </tr>
            </tbody>
        </table>
      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:


                        <table>
                            <thead>
                            <tr>
                                <th>Refund initiator</th>
                                <th>Field value</th>
                            </tr>
                            </thead>
                            <tbody>
                            <tr>
                                <td>Game (via API).</td>
                                <td>API</td>
                            </tr>
                            <tr>
                                <td>Publisher Account user (automatic refund).</td>
                                <td>User email</td>
                            </tr>
                            <tr>
                                <td>Publisher Account user (with assistance from Xsolla customer support).</td>
                                <td>support@xsolla.com</td>
                            </tr>
                            <tr>
                                <td>Xsolla (with assistance from Xsolla customer support).</td>
                                <td>support@xsolla.com</td>
                            </tr>
                            </tbody>
                        </table>
                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' \
            -X POST \
            -d '{
                    "notification_type": "refund",
                    "settings": {
                      "project_id": 18404,
                      "merchant_id": 2340
                    },
                    "purchase": {
                        "subscription": {
                            "plan_id": "b5dac9c8",
                            "subscription_id": "10",
                            "date_create": "2014-09-22T19:25:25+04:00",
                            "currency": "USD",
                            "amount": 9.99
                        },
                        "checkout": {
                            "currency": "USD",
                            "amount": 50
                        },
                        "total":{
                            "currency": "USD",
                            "amount": 200
                        }
                    },
                    "user": {
                        "ip": "127.0.0.1",
                        "phone": "18777976552",
                        "email": "email@example.com",
                        "id": "1234567",
                        "name": "John Smith",
                        "country": "US"
                    },
                    "transaction": {
                        "id": 1,
                        "external_id": 1,
                        "dry_run": 1,
                        "agreement": 1
                    },
                    "refund_details": {
                        "code": 4,
                        "reason": "Potential fraud"
                    },
                    "payment_details": {
                        "sales_tax": {
                            "currency": "USD",
                            "amount": 0
                        },
                        "direct_wht": {
                            "currency": "USD",
                            "amount": 0.70
                        },
                        "xsolla_fee": {
                            "currency": "USD",
                            "amount": "10"
                        },
                        "payout": {
                            "currency": "USD",
                            "amount": "200"
                        },
                        "payment_method_fee": {
                            "currency": "USD",
                            "amount": "20"
                        },
                        "payment": {
                            "currency": "USD",
                            "amount": "230"
                        },
                        "repatriation_commission": {
                            "currency": "USD",
                            "amount": 10
                        }
                    }
                }
            }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'notification_type' => 'refund',
                'settings' => array(
                  'project_id' => 18404,
                  'merchant_id' => 2340
                ),
                'purchase' => array(
                    'total' => array(
                        'currency' => 'USD',
                        'amount' => 9.99
                    )
                ),
                'user' => array(
                    'ip' => '127.0.0.1',
                    'phone' => '18777976552',
                    'email' => 'email@example.com',
                    'id' => '1234567',
                    'country' => 'US'
                ),
                'transaction' => array(
                    'id' => 87654321,
                    'payment_date' => '2014-09-23T19:25:25+04:00',
                    'payment_method' => 1380,
                    'dry_run' => 1
                ),
                'refund_details' => array(
                        'code' => 4,
                        'reason' => 'Potential fraud'
                ),
                'payment_details' => array(
                    'payment' => array(
                        'currency' => 'USD',
                        'amount' => 9.99
                    ),
                    'vat' => array(
                        'currency' => 'USD',
                        'amount' => 0
                    ),
                    'sales_tax' => array(
                        'currency' => 'USD',
                        'amount' => 0
                    ),
                    'direct_wht' => array(
                        'currency' => 'USD',
                        'amount' => 70
                    ),
                    'payout_currency_rate' => 1,
                    'payout' => array(
                        'currency' => 'USD',
                        'amount' => 9.49
                    ),
                    'xsolla_fee' => array(
                        'currency' => 'USD',
                        'amount' => 0.19
                    ),
                    'payment_method_fee' => array(
                        'currency' => 'USD',
                        'amount' => 0.31
                    ),
                    'repatriation_commission' => array(
                        'currency' => 'USD',
                        'amount' => 0.2
                    )
                )
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your_uri HTTP/1.1
            host: your.host
            accept: application/json
            content-type: application/json
            content-length: 1220
            authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

            {
                "notification_type": "refund",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "purchase": {
                    "subscription": {
                        "plan_id": "b5dac9c8",
                        "subscription_id": "10",
                        "date_create": "2014-09-22T19:25:25+04:00",
                        "currency": "USD",
                        "amount": 9.99
                    },
                    "checkout": {
                        "currency": "USD",
                        "amount": 50
                    },
                    "total": {
                        "currency": "USD",
                        "amount": 200
                    }
                },
                "user": {
                    "ip": "127.0.0.1",
                    "phone": "18777976552",
                    "email": "email@example.com",
                    "id": "1234567",
                    "name": "John Smith",
                    "country": "US"
                },
                "transaction": {
                    "id": 1,
                    "external_id": 1,
                    "dry_run": 1,
                    "agreement": 1
                },
                "refund_details": {
                    "code": 4,
                    "reason": "Potential fraud"
                },
                "payment_details": {
                    "sales_tax": {
                        "currency": "USD",
                        "amount": 0
                    },
                    "direct_wht": {
                        "currency": "USD",
                        "amount": 0.70
                    },
                    "xsolla_fee": {
                        "currency": "USD",
                        "amount": "10"
                    },
                    "payout": {
                        "currency": "USD",
                        "amount": "200"
                    },
                    "payment_method_fee": {
                        "currency": "USD",
                        "amount": "20"
                    },
                    "payment": {
                        "currency": "USD",
                        "amount": "230"
                    },
                    "repatriation_commission": {
                        "currency": "USD",
                        "amount": 10
                    }
                }
            }
  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).


        When you save the webhook URL in Publisher Account, you can give
        permissions to receive detailed information in webhooks. To do that, set
        the following toggle to active in Publisher Account in the <a
        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/store">Project
        settings &gt; Webhooks &gt; Advanced settings</a> section.


        <div lang="en" class="note">
          <p><strong>Note</strong></p>
          <p>If you registered in Publisher Account on or before January 22, 2025, you can find the toggles in the <a href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/payments">Project settings &gt; Webhooks &gt; Testing &gt; Payments &gt; Advanced settings</a> section.</p>
        </div>


        <table>
          <thead>
            <tr>
                <th>Toggle</th>
                <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
                <td>Show info about transactions via saved payment methods</td>
                <td><p>Information is passed in the following custom parameters of the webhook:</p><ul><li><code>saved_payment_method</code>:<ul><li><code>0</code> — the saved payment method was not used</li><li><code>1</code> —  the payment method was saved when making the current payment</li><li><code>2</code> — the previously saved payment method is used</li></ul></li><li><code>payment_type</code>:<ul><li><code>1</code> — one-time payment</li><li><code>2</code> — recurring payment</li></ul></li></ul></td>
            </tr>
          </tbody>
        </table>


        Refund codes:


        <table>
            <thead>
            <tr>
                <th>Code</th>
                <th>Reason</th>
                <th>Description</th>
            </tr>
            </thead>
            <tbody>
            <tr>
                <td>1</td>
                <td>Cancellation by the user request / the game request</td>
                <td>Cancellation initiated from Publisher Account.</td>
            </tr>
            <tr>
                <td>3</td>
                <td>Integration error</td>
                <td>Issues in integration between Xsolla and the game.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>5</td>
                <td>Test payment</td>
                <td>Test transaction followed by cancellation.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>7</td>
                <td>Fraud notification from PS</td>
                <td>Payment refused by payment system. Potential fraud detected by PS.<br/><b>Recommendation: Add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>9</td>
                <td>Cancellation by the user request</td>
                <td>The user was not satisfied with the game or the purchase for any reason.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            <tr>
                <td>10</td>
                <td>Cancellation by the game request</td>
                <td>Cancellation requested by the game.<br/><b>Recommendation: Do not add the user to blocklist.</b></td>
            </tr>
            </tbody>
        </table>
      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:


                        <table>
                            <thead>
                            <tr>
                                <th>Refund initiator</th>
                                <th>Field value</th>
                            </tr>
                            </thead>
                            <tbody>
                            <tr>
                                <td>Game (via API).</td>
                                <td>API</td>
                            </tr>
                            <tr>
                                <td>Publisher Account user (automatic refund).</td>
                                <td>User email</td>
                            </tr>
                            <tr>
                                <td>Publisher Account user (with assistance from Xsolla customer support).</td>
                                <td>support@xsolla.com</td>
                            </tr>
                            <tr>
                                <td>Xsolla (with assistance from Xsolla customer support).</td>
                                <td>support@xsolla.com</td>
                            </tr>
                            </tbody>
                        </table>
                    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' \
            -X POST \
            -d '{
                    "notification_type": "partial_refund",
                    "settings": {
                      "project_id": 18404,
                      "merchant_id": 2340
                    },
                    "purchase": {
                        "checkout": {
                            "currency": "USD",
                            "amount": 50
                        },
                        "total":{
                            "currency": "USD",
                            "amount": 200
                        }
                    },
                    "user": {
                        "ip": "127.0.0.1",
                        "phone": "18777976552",
                        "email": "email@example.com",
                        "id": "1234567",
                        "name": "John Smith",
                        "country": "US"
                    },
                    "transaction": {
                        "id": 1,
                        "external_id": 1,
                        "dry_run": 1,
                        "agreement": 1,
                        "date": "2022-03-01 10:53:15"
                    },
                    "refund_details": {
                        "author": "email@example.com",
                        "date": "2022-03-01 10:56:48"
                    },
                    "payment_details": {
                        "sales_tax": {
                            "currency": "USD",
                            "amount": 0
                        },
                        "direct_wht": {
                            "currency": "USD",
                            "amount": 0.70
                        },
                        "xsolla_fee": {
                            "currency": "USD",
                            "amount": "10"
                        },
                        "payout": {
                            "currency": "USD",
                            "amount": "200"
                        },
                        "payment_method_fee": {
                            "currency": "USD",
                            "amount": "20"
                        },
                        "payment": {
                            "currency": "USD",
                            "amount": "230"
                        },
                        "repatriation_commission": {
                            "currency": "USD",
                            "amount": 10
                        }
                    }
                }
            }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'notification_type' => 'partial_refund',
                'settings' => array(
                  'project_id' => 18404,
                  'merchant_id' => 2340
                ),
                'purchase' => array(
                    'total' => array(
                        'currency' => 'USD',
                        'amount' => 9.99
                    )
                ),
                'user' => array(
                    'ip' => '127.0.0.1',
                    'phone' => '18777976552',
                    'email' => 'email@example.com',
                    'id' => '1234567',
                    'country' => 'US'
                ),
                'transaction' => array(
                    'id' => 87654321,
                    'payment_date' => '2014-09-23T19:25:25+04:00',
                    'payment_method' => 1380,
                    'dry_run' => 1,
                    'date' => '2022-03-31 10:53:15'
                ),
                'refund_details' => array(
                        'author' => 'email@example.com',
                        'date' => '2022-03-01 10:56:48'
                ),
                'payment_details' => array(
                    'payment' => array(
                        'currency' => 'USD',
                        'amount' => 9.99
                    ),
                    'vat' => array(
                        'currency' => 'USD',
                        'amount' => 0
                    ),
                    'sales_tax' => array(
                        'currency' => 'USD',
                        'amount' => 0
                    ),
                    'direct_wht' => array(
                        'currency' => 'USD',
                        'amount' => 70
                    ),
                    'payout_currency_rate' => 1,
                    'payout' => array(
                        'currency' => 'USD',
                        'amount' => 9.49
                    ),
                    'xsolla_fee' => array(
                        'currency' => 'USD',
                        'amount' => 0.19
                    ),
                    'payment_method_fee' => array(
                        'currency' => 'USD',
                        'amount' => 0.31
                    ),
                    'repatriation_commission' => array(
                        'currency' => 'USD',
                        'amount' => 0.2
                    )
                )
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your_uri HTTP/1.1
            host: your.host
            accept: application/json
            content-type: application/json
            content-length: 1220
            authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

            {
                "notification_type": "partial_refund",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "purchase": {
                    "checkout": {
                        "currency": "USD",
                        "amount": 50
                    },
                    "total": {
                        "currency": "USD",
                        "amount": 200
                    }
                },
                "user": {
                    "ip": "127.0.0.1",
                    "phone": "18777976552",
                    "email": "email@example.com",
                    "id": "1234567",
                    "name": "John Smith",
                    "country": "US"
                },
                "transaction": {
                    "id": 1,
                    "external_id": 1,
                    "dry_run": 1,
                    "agreement": 1,
                    "date": "2022-03-31 10:53:15"
                },
                "refund_details": {
                    "author": "email@example.com",
                    "date": "2022-03-31 10:56:48"
                },
                "payment_details": {
                    "sales_tax": {
                        "currency": "USD",
                        "amount": 0
                    },
                    "direct_wht": {
                        "currency": "USD",
                        "amount": 0.70
                    },
                    "xsolla_fee": {
                        "currency": "USD",
                        "amount": "10"
                    },
                    "payout": {
                        "currency": "USD",
                        "amount": "200"
                    },
                    "payment_method_fee": {
                        "currency": "USD",
                        "amount": "20"
                    },
                    "payment": {
                        "currency": "USD",
                        "amount": "230"
                    },
                    "repatriation_commission": {
                        "currency": "USD",
                        "amount": 10
                    }
                }
            }
  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.

        The webhook is sent during the authorization or payment processing
        stage.

        In this case, the [payment](/webhooks/operation/payment/)\
        [order_paid](/webhooks/operation/successful-order-payment/) webhook is
        not sent.


        Typical reasons for payment system declines:


        * 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).

        * 3-D Secure verification failed, was not completed, or the user
        confirmation timed out.

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


        Should not be confused with:


        * Anti-fraud rejections, which are reported via the
        [afs_reject](https://developers.xsolla.com/webhooks/operation/afs-rejected-transaction/)
        webhook.

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


        <div lang="en" class="note">
          <p><strong>Note</strong></p>
          <p>To receive the <code>ps_declined</code> webhook, contact your Customer Success Manager or email <a href="mailto:csm@xsolla.com">csm@xsolla.com</a>.</p>
        </div>
      tags:
        - payments
      operationId: payment-declined
      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'
                    email:
                      $ref: '#/components/schemas/user.email'
                    id:
                      $ref: '#/components/schemas/user.id'
                    name:
                      $ref: '#/components/schemas/user.name'
                    country:
                      $ref: '#/components/schemas/user.country'
                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.
                    payment_method:
                      type: integer
                      description: Payment method 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:


                        <table>
                            <thead>
                            <tr>
                                <th>Refund initiator</th>
                                <th>Field value</th>
                            </tr>
                            </thead>
                            <tbody>
                            <tr>
                                <td>Game (via API).</td>
                                <td>API</td>
                            </tr>
                            <tr>
                                <td>Publisher Account user (automatic refund).</td>
                                <td>User email</td>
                            </tr>
                            <tr>
                                <td>Publisher Account user (with assistance from Xsolla customer support).</td>
                                <td>support@xsolla.com</td>
                            </tr>
                            <tr>
                                <td>Xsolla (with assistance from Xsolla customer support).</td>
                                <td>support@xsolla.com</td>
                            </tr>
                            </tbody>
                        </table>
      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' \

            -X POST \

            -H 'Accept: application/json' \

            -H 'Content-Type: application/json' \

            -H 'Authorization: Signature
            80543ba63e1e50cf05f15150fe75e7245da9a898' \

            -d '{
              "notification_type": "ps_declined",
              "settings": {
                "project_id": "18404",
                "merchant_id": "2340"
              },
              "user": {
                "ip": "127.0.0.1",
                "email": "email@example.com",
                "id": "1234567",
                "country": "US"
              },
              "transaction": {
                "id": "1",
                "dry_run": "1",
                "payment_method": "1"
              },
              "refund_details": {
                "author": "support@xsolla.com",
                "code": "8",
                "reason": "Cancellation by the PS request",
                "reason_detail": "Insufficient funds"
              }
            }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
              'notification_type' => 'ps_declined',
              'settings' => array(
                'project_id' => '18404',
                'merchant_id' => '2340',
              ),
              'user' => array(
                'ip' => '127.0.0.1',
                'email' => 'email@example.com',
                'id' => '1234567',
                'country' => 'US',
              ),
              'transaction' => array(
                'id' => '1',
                'dry_run' => '1',
                'payment_method' => '1',
              ),
              'refund_details' => array(
                'author' => 'support@xsolla.com',
                'code' => '8',
                'reason' => 'Cancellation by the PS request',
                'reason_detail' => 'Insufficient funds',
              ),
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your_uri HTTP/1.1
            host: your.host
            accept: application/json
            content-type: application/json
            content-length: 338
            authorization: Signature 80543ba63e1e50cf05f15150fe75e7245da9a898

            {
              "notification_type": "ps_declined",
              "settings": {
                "project_id": "18404",
                "merchant_id": "2340"
              },
              "user": {
                "ip": "127.0.0.1",
                "email": "email@example.com",
                "id": "1234567",
                "country": "US"
              },
              "transaction": {
                "id": "1",
                "dry_run": "1",
                "payment_method": "1"
              },
              "refund_details": {
                "author": "support@xsolla.com",
                "code": "8",
                "reason": "Cancellation by the PS request",
                "reason_detail": "Insufficient funds"
              }
            }
  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 <a href="mailto:csm@xsolla.com">csm@xsolla.com</a>.


        When you save the webhook URL in Publisher Account, you can give
        permissions to receive detailed information in webhooks. To do that, set
        the following toggle to active in Publisher Account in the <a
        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/store">Project
        settings &gt; Webhooks &gt; Advanced settings</a> section.


        <div lang="en" class="note">
          <p><strong>Note</strong></p>
          <p>If you registered in Publisher Account on or before January 22, 2025, you can find the toggles in the <a href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/payments">Project settings &gt; Webhooks &gt; Testing &gt; Payments &gt; Advanced settings</a> section.</p>
        </div>


        <table>
          <thead>
            <tr>
                <th>Toggle</th>
                <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
                <td>Show info about transactions via saved payment methods</td>
                <td><p>Information is passed in the following custom parameters of the webhook:</p><ul><li><code>saved_payment_method</code>:<ul><li><code>0</code> — the saved payment method was not used</li><li><code>1</code> —  the payment method was saved when making the current payment</li><li><code>2</code> — the previously saved payment method is used</li></ul></li><li><code>payment_type</code>:<ul><li><code>1</code> — one-time payment</li><li><code>2</code> — recurring payment</li></ul></li></ul></td>
            </tr>
          </tbody>
        </table>
      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.
                    reason:
                      type: string
                      description: Refund reason.
                    author:
                      type: string
                      description: Refund initiator.
      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' \
            -X POST \
            -d '{
              "notification_type": "afs_reject",
              "settings": {
                "project_id": 18404,
                "merchant_id": 2340
              },
              "user": {
                "ip": "127.0.0.1",
                "phone": "18777976552",
                "email": "email@example.com",
                "id": "1234567",
                "name": "John Smith",
                "country": "US"
              },
              "transaction": {
                "id": 1,
                "external_id": 1,
                "dry_run": 1,
                "agreement": 1
              },
              "refund_details": {
                "code": 4,
                "reason": "Potential fraud"
              }
            }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
              'notification_type' => 'afs_reject',
              'settings' => array(
                'project_id' => 18404,
                'merchant_id' => 2340
              ),
              'user' => array(
                'ip' => '127.0.0.1',
                'phone' => '18777976552',
                'email' => 'email@example.com',
                'id' => '1234567',
                'country' => 'US'
              ),
              'transaction' => array(
                'id' => 87654321,
                'payment_method' => 1380,
                'dry_run' => 1
              ),
              'refund_details' => array(
                'code' => 4,
                'reason' => 'Potential fraud'
              )
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your_uri HTTP/1.1
            host: your.host
            accept: application/json
            content-type: application/json
            content-length: 1220
            authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

            {
              "notification_type": "afs_reject",
              "settings": {
                "project_id": 18404,
                "merchant_id": 2340
              },
              "user": {
                "ip": "127.0.0.1",
                "phone": "18777976552",
                "email": "email@example.com",
                "id": "1234567",
                "name": "John Smith",
                "country": "US"
              },
              "transaction": {
                "id": 1,
                "external_id": 1,
                "dry_run": 1,
                "agreement": 1
              },
              "refund_details": {
                "code": 4,
                "reason": "Potential fraud"
              }
            }
  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 <a href="mailto:csm@xsolla.com">csm@xsolla.com</a>.
      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' \

            -X POST \

            -H 'authorization: Signature
            32c64a80d2527dc08906ae1891bac4489509b9f6' \

            -d '{
              "event": {
                "action": "adding",
                "date_of_last_action": "2020-11-27T10:09:05+03:00",
                "parameter": "email",
                "parameter_value": "email@example.com",
                "reason": "ps_reported_fraud",
                "transaction_id": "111111111",
                "project_id": "123456"
              },
              "notification_type": "afs_black_list"
            }'
        - lang: HTTP
          label: HTTP
          source: |
            POST /your_uri HTTP/1.1
            host: your.host
            accept: application/json
            content-type: application/json
            content-length: 233
            authorization: Signature 32c64a80d2527dc08906ae1891bac4489509b9f6

            {
              "event": {
                "action": "adding",
                "date_of_last_action": "2020-11-27T10:09:05+03:00",
                "parameter": "email",
                "parameter_value": "email@example.com",
                "reason": "ps_reported_fraud",
                "transaction_id": "111111111",
                "project_id": "123456"
              },
              "notification_type": "afs_black_list"
            }
  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' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            13342703ccaca5064ad33ba451d800c5e823db8f' \

            -d '{
                    "notification_type": "create_subscription",
                    "settings": {
                      "project_id": 18404,
                      "merchant_id": 2340
                    },
                    "user": {
                        "id": "1234567",
                        "name": "John Smith"
                    },
                    "subscription": {
                        "plan_id": "b5dac9c8",
                        "subscription_id": "10",
                        "product_id": "Demo Product",
                        "date_create": "2014-09-22T19:25:25+04:00",
                        "date_next_charge": "2015-01-22T19:25:25+04:00",
                        "trial": {
                                "value": 90,
                                "type": "day"
                            },
                        "is_gift": true
                    }
                }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'notification_type' => 'create_subscription',
                'settings' => array(
                  'project_id' => 18404,
                  'merchant_id' => 2340
                ),
                'user' => array(
                    'id' => '1234567',
                    'name' => 'John Smith'
                ),
                'subscription' => array(
                    'plan_id' => 'b5dac9c8',
                    'subscription_id' => '10',
                    'product_id' => 'Demo Product',
                    'date_create' => '2014-09-22T19:25:25+04:00',
                    'date_next_charge' => '2015-01-22T19:25:25+04:00',
                    'trial' =>  array(
                            'value' =>  90,
                            'type' =>  'day'
                        ),
                    'is_gift' => true,
                )
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            Host: your.hostname
            accept: application/json
            content-type: application/json
            content-length: 240
            authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

            {
                "notification_type": "create_subscription",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "user": {
                    "id": "1234567",
                    "name": "John Smith"
                },
                "subscription": {
                    "plan_id": "b5dac9c8",
                    "subscription_id": "10",
                    "product_id": "Demo Product",
                    "date_create": "2014-09-22T19:25:25+04:00",
                    "date_next_charge": "2015-01-22T19:25:25+04:00",
                    "trial": {
                            "value": 90,
                            "type": "day"
                        },
                    "is_gift": true
                }
            }
  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' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            13342703ccaca5064ad33ba451d800c5e823db8f' \

            -d '{
                    "notification_type": "update_subscription",
                    "settings": {
                      "project_id": 18404,
                      "merchant_id": 2340
                    },
                    "user": {
                        "id": "1234567",
                        "name": "John Smith"
                    },
                    "subscription": {
                        "plan_id": "b5dac9c8",
                        "subscription_id": "10",
                        "product_id": "Demo Product",
                        "date_next_charge": "2015-01-22T19:25:25+04:00"
                    }
                }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'notification_type' => 'update_subscription',
                'settings' => array(
                  'project_id' => 18404,
                  'merchant_id' => 2340
                ),
                'user' => array(
                    'id' => '1234567',
                    'name' => 'John Smith'
                ),
                'subscription' => array(
                    'plan_id' => 'b5dac9c8',
                    'subscription_id' => '10',
                    'product_id' => 'Demo Product',
                    'date_next_charge' => '2015-01-22T19:25:25+04:00'
                )
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host: your.hostname
            accept: application/json
            content-type: application/json
            content-length: 240
            authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

            {
                "notification_type": "update_subscription",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "user": {
                    "id": "1234567",
                    "name": "John Smith"
                },
                "subscription": {
                    "plan_id": "b5dac9c8",
                    "subscription_id": "10",
                    "product_id": "Demo Product",
                    "date_next_charge": "2015-01-22T19:25:25+04:00"
                }
            }
  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' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            13342703ccaca5064ad33ba451d800c5e823db8f' \

            -d '{
                    "notification_type": "cancel_subscription",
                    "settings": {
                      "project_id": 18404,
                      "merchant_id": 2340
                    },
                    "user": {
                        "id": "1234567",
                        "name": "John Smith"
                    },
                    "subscription": {
                        "plan_id": "b5dac9c8",
                        "subscription_id": "10",
                        "product_id": "Demo Product",
                        "date_create": "2014-09-22T19:25:25+04:00",
                        "date_end": "2015-01-22T19:25:25+04:00"
                    }
                }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'notification_type' => 'cancel_subscription',
                'settings' => array(
                  'project_id' => 18404,
                  'merchant_id' => 2340
                ),
                'user' => array(
                    'id' => '1234567',
                    'name' => 'John Smith'
                ),
                'subscription' => array(
                    'plan_id' => 'b5dac9c8',
                    'subscription_id' => '10',
                    'product_id' => 'Demo Product',
                    'date_create' => '2014-09-22T19:25:25+04:00',
                    'date_end' => '2015-01-22T19:25:25+04:00',
                )
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host: your.hostname
            accept: application/json
            content-type: application/json
            content-length: 240
            authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

            {
                "notification_type": "cancel_subscription",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "user":{
                    "id": "1234567",
                    "name": "John Smith"
                },
                "subscription": {
                    "plan_id": "b5dac9c8",
                    "subscription_id": "10",
                    "product_id": "Demo Product",
                    "date_create": "2014-09-22T19:25:25+04:00",
                    "date_end": "2015-01-22T19:25:25+04:00"
                }
            }
  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 <a
        href="mailto:csm@xsolla.com">csm@xsolla.com</a>.
      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' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            13342703ccaca5064ad33ba451d800c5e823db8f' \

            -d '{
                    "notification_type": "non_renewal_subscription",
                    "settings": {
                      "project_id": 12345,
                      "merchant_id": 1234
                    },
                    "user": {
                        "id": "1234567",
                        "email": "email@example.com"
                    },
                    "subscription": {
                        "plan_id": "a1bcd2e3",
                        "subscription_id": "10",
                        "date_create": "2014-12-22T15:25:25+04:00",
                        "date_next_charge": "2015-01-22T19:25:25+04:00",
                        "currency": "USD",
                        "amount": 0.03
                    }
                }'
        - lang: PHP
          label: PHP
          source: |
            <?php

            $request = array(
                'notification_type' => 'non_renewal_subscription',
                'settings' => array(
                  'project_id' => 12345,
                  'merchant_id' => 1234
                ),
                'user' => array(
                    'id' => '1234567',
                    'email' => 'email@example.com'
                ),
                'subscription' => array(
                    'plan_id' => 'a1bcd2e3',
                    'subscription_id' => '10',
                    'date_create' => '2014-12-22T15:25:25+04:00',
                    'date_next_charge' => '2015-01-22T19:25:25+04:00',
                    'currency' => 'USD',
                    'amount' => 0.03
                )
            );
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host: your.hostname
            accept: application/json
            content-type: application/json
            content-length: 240
            authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

            {
                "notification_type": "non_renewal_subscription",
                "settings": {
                  "project_id": 12345,
                  "merchant_id": 1234
                },
                "user": {
                    "id": "1234567",
                    "email": "email@example.com"
                },
                "subscription": {
                    "plan_id": "a1bcd2e3",
                    "subscription_id": "10",
                    "date_create": "2014-12-22T15:25:25+04:00",
                    "date_next_charge": "2015-01-22T19:25:25+04:00",
                    "currency": "USD",
                    "amount": 0.03
                }
            }
  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 <a
        href="mailto:csm@xsolla.com">csm@xsolla.com</a>.
      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' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \

            -d '{
                "notification_type":"payment_account_add",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "user": {
                    "ip": "127.0.0.1",
                    "email": "email@example.com",
                    "id": "1234567",
                    "name": "John Smith",
                    "country": "US",
                    "zip": "12345"
                },
                "payment_account": {
                    "id": "12345678",
                    "name": "email@example.com",
                    "payment_method": "24",
                    "country": "US",
                    "type": "paypal"
                }
            }'
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host:           your.hostname
            accept:         application/json
            content-length: 255
            content-type:   application/json
            authorization:  Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843

            {
                "notification_type": "payment_account_add",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "user": {
                    "ip": "127.0.0.1",
                    "email": "email@example.com",
                    "id": "1234567",
                    "name": "John Smith",
                    "country": "US",
                    "zip": "12345"
                },
                "payment_account": {
                    "id": "12345678",
                    "name": "email@example.com",
                    "payment_method": "24",
                    "country": "US",
                    "type": "paypal"
                }
            }
  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 <a href="mailto:csm@xsolla.com">csm@xsolla.com</a>.
      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' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \

            -d '{
                "notification_type": "payment_account_remove",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "user": {
                    "email": "email@example.com",
                    "id": "1234567",
                    "name": "John Smith"
                },
                "payment_account": {
                    "id": "12345678",
                    "name": "email@example.com",
                    "payment_method": "24",
                    "type": "paypal"
                }
            }'
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host:           your.hostname
            accept:         application/json
            content-length: 258
            content-type:   application/json
            authorization:  Signature d90d319f05df7b0f86d2485f48e7079f0f752523


            {
                "notification_type": "payment_account_remove",
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "user": {
                    "email": "email@example.com",
                    "id": "1234567",
                    "name": "John Smith"
                },
                "payment_account": {
                    "id": "12345678",
                    "name": "email@example.com",
                    "payment_method": "24",
                    "type": "paypal"
                }
            }
  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`.

        <div class="note"><strong>Note</strong><br><br>

        Webhook is used only for user validation in Web Shop. Refer to these <a
        target="_blank"
        href="https://developers.xsolla.com/solutions/web-shop/authentication-and-analytics/set-up-authentication/">instructions</a>
        for more information about configuring webhooks in Site Builder.</div>
      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.
                      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 <a
                      target="_blank"
                      href="https://developers.xsolla.com/doc/login/features/user-attributes/#login_features_user_attributes">documentation</a>
                      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'
                  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' \
            -X POST \
            -H 'accept: application/json' \
            -H 'content-type: application/json' \
            -d '{
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "user": {
                    "id": "1234567",
                    "country": "US"
                }
            }'
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host: your.hostname
            accept: application/json
            content-type: application/json
            content-length: 240

            {
                "settings": {
                  "project_id": 18404,
                  "merchant_id": 2340
                },
                "user": {
                    "id": "1234567",
                    "country": "US"
                }
            }
  personalized-partner-catalog:
    post:
      summary: Catalog personalization on partner side
      description: >
        Xsolla will send a <code>partner_side_catalog</code> webhook that
        contains the user and project parameters to the webhook URL when a user
        interacts with the store.


        Return a list of <code>item_id</code> 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.


        It is recommended that the processing time of the
        <code>partner_side_catalog</code>  webhook  is less than 3 seconds.
      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' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            d90d319f05df7b0f86d2485f48e7079f0f752523' \

            -d '{
                    "notification_type": "partner_side_catalog",
                    "user": {
                        "user_id": "12345",
                        "country": "US"
                    }
                }'
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host:           your.hostname
            accept:         application/json
            content-type:   application/json
            authorization:  Signature d90d319f05df7b0f86d2485f48e7079f0f752523

            {
                "notification_type": "partner_side_catalog",
                "user": {
                  "user_id": "12345",
                  "country": "US"
                }
            }
  successful-order-payment:
    post:
      summary: Successful payment for order (with payment and transaction details)
      description: >
        Xsolla sends the <code>order_paid</code> webhook to the specified URL
        when the user successfully pays for the order.


        The <code>order_paid</code> webhook contains information about the
        purchased items, payment data and transaction details.


        The <code>order_paid</code> webhook is not sent if the payment is not
        successful, for example:

        * the payment form was opened, but the user did not pay for the order

        * the payment form was opened, but there were errors during the payment


        It is recommended that the processing time of the
        <code>order_paid</code>  webhook  is less than 3 seconds.


        <div lang="en" class="notice">
          <p><strong>Notice</strong></p>
          <p>The set of fields sent in a webhook depends on the following settings:<ul><li>the ones you configured in Publisher Account in the <a href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/store">Project settings &gt; Webhooks &gt; Advanced settings</a> section</li><li>the ones configured on the Xsolla side</li></ul></p><p>If you have any questions, contact your Customer Success Manager or email to <a href="mailto:csm@xsolla.com">csm@xsolla.com</a>.</p>
        </div>


        The expected answers are described in the <b>Responses</b> section.

        You 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:


        <table>
            <thead>
            <tr>
                <th>Response code</th>
                <th>Automatic payment refund is disabled (by default)</th>
                <th>Automatic payment refund is enabled</th>
            </tr>
            </thead>
            <tbody>
            <tr>
                <td><code>400</code>, <code>401</code>, <code>402</code>, <code>403</code>, <code>404</code>, <code>409</code>, <code>422</code>, <code>415</code></td>
                <td>No actions</td>
                <td>Automatic refund to the user</td>
            </tr>
            <tr>
                <td><code>200</code>, <code>201</code>, <code>204</code></td>
                <td>No actions</td>
                <td>No actions</td>
            </tr>
            <tr>
                <td>Different code or no response to webhook</td>
                <td>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.</td>
                <td>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.</td>
            </tr>
            </tbody>
        </table>


        To connect the automatic refund functionality, contact your Customer
        Success Managers or email to csm@xsolla.com.
      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.


                    The 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.
                  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' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \

            -d '{
                "notification_type": "order_paid",
                "items": [
                  {
                    "sku": "com.xsolla.item_1",
                    "type": "virtual_good",
                    "is_pre_order": false,
                    "quantity": 3,
                    "amount": "1000",
                    "promotions": [
                      {
                        "amount_without_discount": "6000",
                        "amount_with_discount": "5000",
                        "sequence": 1
                      },
                      {
                        "amount_without_discount": "5000",
                        "amount_with_discount": "4000",
                        "sequence": 2
                      }
                    ],
                    "custom_attributes":
                      {
                        "purchased": 0,
                        "attr": "value"
                      }
                  },
                  {
                    "sku": "com.xsolla.item_new_1",
                    "type": "bundle",
                    "is_pre_order": false,
                    "quantity": 1,
                    "amount": "1000",
                    "promotions": []
                  },
                  {
                    "sku": "com.xsolla.gold_1",
                    "type": "virtual_currency",
                    "is_pre_order": false,
                    "quantity": 1500,
                    "amount": null,
                    "promotions": []
                  }
                ],
                "order": {
                  "id": 1,
                  "mode": "default",
                  "currency_type": "virtual",
                  "currency": "sku_currency",
                  "amount": "2000",
                  "status": "paid",
                  "platform": "xsolla",
                  "comment": null,
                  "invoice_id": "1",
                  "promotions": [
                    {
                      "amount_without_discount": "4000",
                      "amount_with_discount": "2000",
                      "sequence": 1
                    }
                  ],
                  "promocodes": [
                    {
                      "code": "promocode_some_code",
                      "external_id": "promocode_sku"
                    }
                  ],
                  "coupons": [
                    {
                      "code": "WINTER2021",
                      "external_id": "coupon_sku"
                    }
                  ]
                },
                "user": {
                  "external_id": "id_xsolla_login_1",
                  "email": "gc_user@xsolla.com",
                  "country": "US"
                },
                "billing": {
                  "notification_type": "payment",
                  "settings": {
                    "project_id": 18404,
                    "merchant_id": 2340
                  },
                  "purchase": {
                      "subscription": {
                          "plan_id": "b5dac9c8",
                          "subscription_id": "10",
                          "product_id": "Demo Product",
                          "date_create": "2014-09-22T19:25:25+04:00",
                          "date_next_charge": "2014-10-22T19:25:25+04:00",
                          "currency": "USD",
                          "amount": 9.99
                      },
                      "total": {
                          "currency": "USD",
                          "amount": 200
                      },
                      "promotions": [{
                          "technical_name": "Demo Promotion",
                          "id": 853
                      }],
                      "coupon": {
                          "coupon_code": "ICvj45S4FUOyy",
                          "campaign_code": "1507"
                      }
                    },
                  "transaction": {
                      "id": 1,
                      "external_id": 1,
                      "payment_date": "2014-09-24T20:38:16+04:00",
                      "payment_method": 1,
                      "payment_method_name": "PayPal",
                      "payment_method_order_id": 1234567890123456789,
                      "dry_run": 1,
                      "agreement": 1
                  },
                  "payment_details": {
                      "payment": {
                          "currency": "USD",
                          "amount": 230
                      },
                      "vat": {
                          "currency": "USD",
                          "amount": 0,
                          "percent": 20
                      },
                      "sales_tax": {
                          "currency": "USD",
                          "amount": 0,
                          "percent": 0
                      },
                      "direct_wht": {
                          "currency": "USD",
                          "amount": 0,
                          "percent": 0
                      },
                      "payout_currency_rate": "1",
                      "payout": {
                          "currency": "USD",
                          "amount": 200
                      },
                      "country_wht": {
                          "currency": "USD",
                          "amount": 2,
                          "percent": 10
                      },
                      "user_acquisition_fee": {
                          "currency": "USD",
                          "amount": 2,
                          "percent": 1
                      },
                      "xsolla_fee": {
                          "currency": "USD",
                          "amount": 10
                      },
                      "payment_method_fee": {
                          "currency": "USD",
                          "amount": 20
                      },
                      "repatriation_commission": {
                          "currency": "USD",
                          "amount": 10
                      }
                  }
                }
             ,
              "custom_parameters": {
                "parameter1": "value1",
                "parameter2": "value2"
              }
            }
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host:           your.hostname
            accept:         application/json
            content-length: 258
            content-type:   application/json
            authorization:  Signature d90d319f05df7b0f86d2485f48e7079f0f752523


            {
                "notification_type": "order_paid",
                "items": [
                  {
                    "sku": "com.xsolla.item_1",
                    "type": "virtual_good",
                    "is_pre_order": false,
                    "quantity": 3,
                    "amount": "1000",
                    "promotions": [
                      {
                        "amount_without_discount": "6000",
                        "amount_with_discount": "5000",
                        "sequence": 1
                      },
                      {
                        "amount_without_discount": "5000",
                        "amount_with_discount": "4000",
                        "sequence": 2
                      }
                    ],
                    "custom_attributes":
                      {
                        "purchased": 0,
                        "attr": "value"
                      }
                  },
                  {
                    "sku": "com.xsolla.item_new_1",
                    "type": "bundle",
                    "is_pre_order": false,
                    "quantity": 1,
                    "amount": "1000",
                    "promotions": []
                  },
                  {
                    "sku": "com.xsolla.gold_1",
                    "type": "virtual_currency",
                    "is_pre_order": false,
                    "quantity": 1500,
                    "amount": null,
                    "promotions": []
                  }
                ],
                "order": {
                  "id": 1,
                  "mode": "default",
                  "currency_type": "virtual",
                  "currency": "sku_currency",
                  "amount": "2000",
                  "status": "paid",
                  "platform": "xsolla",
                  "comment": null,
                  "invoice_id": "1",
                  "promotions": [
                    {
                      "amount_without_discount": "4000",
                      "amount_with_discount": "2000",
                      "sequence": 1
                    }
                  ],
                  "promocodes": [
                    {
                      "code": "promocode_some_code",
                      "external_id": "promocode_sku"
                    }
                  ],
                  "coupons": [
                    {
                      "code": "WINTER2021",
                      "external_id": "coupon_sku"
                    }
                  ]
                },
                "user": {
                  "external_id": "id_xsolla_login_1",
                  "email": "gc_user@xsolla.com",
                  "country": "US"
                },
                "billing": {
                  "notification_type": "payment",
                  "settings": {
                    "project_id": 18404,
                    "merchant_id": 2340
                  },
                  "purchase":{
                      "subscription": {
                          "plan_id": "b5dac9c8",
                          "subscription_id": "10",
                          "product_id": "Demo Product",
                          "date_create": "2014-09-22T19:25:25+04:00",
                          "date_next_charge": "2014-10-22T19:25:25+04:00",
                          "currency": "USD",
                          "amount": 9.99
                      },
                      "total": {
                          "currency": "USD",
                          "amount": 200
                      },
                      "promotions": [{
                          "technical_name": "Demo Promotion",
                          "id": 853
                      }],
                      "coupon": {
                          "coupon_code": "ICvj45S4FUOyy",
                          "campaign_code": "1507"
                      }
                  },
                  "transaction": {
                      "id": 1,
                      "external_id": 1,
                      "payment_date": "2014-09-24T20:38:16+04:00",
                      "payment_method": 1,
                      "payment_method_name": "PayPal",
                      "payment_method_order_id": 1234567890123456789,
                      "dry_run": 1,
                      "agreement": 1
                  },
                  "payment_details": {
                      "payment": {
                          "currency": "USD",
                          "amount": 230
                      },
                      "vat": {
                          "currency": "USD",
                          "amount": 0,
                          "percent": 20
                      },
                      "sales_tax": {
                          "currency": "USD",
                          "amount": 0,
                          "percent": 0
                      },
                      "direct_wht": {
                          "currency": "USD",
                          "amount": 0,
                          "percent": 0
                      },
                      "payout_currency_rate": "1",
                      "country_wht": {
                          "currency": "USD",
                          "amount": 2,
                          "percent": 10
                      },
                      "user_acquisition_fee": {
                          "currency": "USD",
                          "amount": 2,
                          "percent": 1
                      },
                      "payout": {
                          "currency": "USD",
                          "amount": 200
                      },
                      "xsolla_fee": {
                          "currency": "USD",
                          "amount": 10
                      },
                      "payment_method_fee": {
                          "currency": "USD",
                          "amount": 20
                      },
                      "repatriation_commission": {
                          "currency": "USD",
                          "amount": 10
                      }
                  }
                },
                "custom_parameters": {
                    "parameter1": "value1",
                    "parameter2": "value2"
                    }
                }
  successful-order-payment-separate:
    post:
      summary: Successful payment for order (without payment and transaction details)
      description: >
        Xsolla sends the <code>order_paid</code> webhook to the specified URL
        when the following conditions are fulfilled:

        1. The user successfully paid for the order.

        2. Xsolla received a response about the successful processing of
        [payment](/webhooks/operation/payment/) webhook.


        The <code>order_paid</code> webhook contains information about the
        purchased items and transaction details.


        The <code>order_paid</code> webhook is not sent if:

        * The payment was not successful, for example:
          * the payment form was opened, but the user did not pay for the order
          * the payment form was opened, but there were errors during the payment
        * The response about the successful processing of the
        [payment](/webhooks/operation/payment/) webhook has not been received.


        It is recommended that the processing time of the
        <code>order_paid</code>  webhook  is less than 3 seconds.


        The expected answers are described in the <b>Responses</b> section.

        You 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:


        <table>
            <thead>
            <tr>
                <th>Response code</th>
                <th>Automatic payment refund is disabled (by default)</th>
                <th>Automatic payment refund is enabled</th>
            </tr>
            </thead>
            <tbody>
            <tr>
                <td><code>400</code>, <code>401</code>, <code>402</code>, <code>403</code>, <code>404</code>, <code>409</code>, <code>422</code>, <code>415</code></td>
                <td>No actions</td>
                <td>Automatic refund to the user</td>
            </tr>
            <tr>
                <td><code>200</code>, <code>201</code>, <code>204</code></td>
                <td>No actions</td>
                <td>No actions</td>
            </tr>
            <tr>
                <td>Different code or no response to webhook</td>
                <td>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.</td>
                <td>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.</td>
            </tr>
            </tbody>
        </table>


        To connect the automatic refund functionality, contact your Customer
        Success Managers or email to csm@xsolla.com.
      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.


                    The 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.
                  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' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \

            -d '{
                "notification_type": "order_paid",
                "items": [
                  {
                    "sku": "com.xsolla.v.item_1",
                    "type": "virtual_good",
                    "is_pre_order": false,
                    "quantity": 3,
                    "amount": "1000",
                    "promotions": [
                      {
                        "amount_without_discount": "6000",
                        "amount_with_discount": "5000",
                        "sequence": 1
                      },
                      {
                        "amount_without_discount": "5000",
                        "amount_with_discount": "4000",
                        "sequence": 2
                      }
                    ],
                    "custom_attributes":
                      {
                        "purchased": 0,
                        "attr": "value"
                      }
                  },
                  {
                    "sku": "com.xsolla.v.item_new_1",
                    "type": "bundle",
                    "is_pre_order": false,
                    "quantity": 1,
                    "amount": "1000",
                    "promotions": []
                  },
                  {
                    "sku": "com.xsolla.gold_1",
                    "type": "virtual_currency",
                    "is_pre_order": false,
                    "quantity": 1500,
                    "amount": "[null]",
                    "promotions": []
                  }
                ],
                "order": {
                  "id": 1,
                  "mode": "default",
                  "currency_type": "virtual",
                  "currency": "sku_currency",
                  "amount": "2000",
                  "status": "paid",
                  "platform": "xsolla",
                  "comment": null,
                  "invoice_id": "1",
                  "promotions": [
                    {
                      "amount_without_discount": "4000",
                      "amount_with_discount": "2000",
                      "sequence": 1
                    }
                  ],
                  "promocodes": [
                    {
                      "code": "promocode_some_code",
                      "external_id": "promocode_sku"
                    }
                  ],
                  "coupons": [
                    {
                      "code": "WINTER2021",
                      "external_id": "coupon_sku"
                    }
                  ]
                },
                "user": {
                  "external_id": "id_xsolla_login_1",
                  "email": "gc_user@xsolla.com",
                  "country": "US"
                }

            }'
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host:           your.hostname
            accept:         application/json
            content-length: 258
            content-type:   application/json
            authorization:  Signature d90d319f05df7b0f86d2485f48e7079f0f752523


            {
                "notification_type": "order_paid",
                "items": [
                  {
                    "sku": "com.xsolla.v.item_1",
                    "type": "virtual_good",
                    "is_pre_order": false,
                    "quantity": 3,
                    "amount": "1000",
                    "promotions": [
                      {
                        "amount_without_discount": "6000",
                        "amount_with_discount": "5000",
                        "sequence": 1
                      },
                      {
                        "amount_without_discount": "5000",
                        "amount_with_discount": "4000",
                        "sequence": 2
                      }
                    ],
                    "custom_attributes":
                      {
                        "purchased": 0,
                        "attr": "value"
                      }
                  },
                  {
                    "sku": "com.xsolla.v.item_new_1",
                    "type": "bundle",
                    "is_pre_order": false,
                    "quantity": 1,
                    "amount": "1000",
                    "promotions": []
                  },
                  {
                    "sku": "com.xsolla.gold_1",
                    "type": "virtual_currency",
                    "is_pre_order": false,
                    "quantity": 1500,
                    "amount": "[null]",
                    "promotions": []
                  }
                ],
                "order": {
                  "id": 1,
                  "mode": "default",
                  "currency_type": "virtual",
                  "currency": "sku_currency",
                  "amount": "2000",
                  "status": "paid",
                  "platform": "xsolla",
                  "comment": null,
                  "invoice_id": "1",
                  "promotions": [
                    {
                      "amount_without_discount": "4000",
                      "amount_with_discount": "2000",
                      "sequence": 1
                    }
                  ],
                  "promocodes": [
                    {
                      "code": "promocode_some_code",
                      "external_id": "promocode_sku"
                    }
                  ],
                  "coupons": [
                    {
                      "code": "WINTER2021",
                      "external_id": "coupon_sku"
                    }
                  ]
                },
                "user": {
                  "external_id": "id_xsolla_login_1",
                  "email": "gc_user@xsolla.com",
                  "country": "US"
                }
            }
  order-cancellation:
    post:
      summary: Order cancellation (with payment and transaction details)
      description: >
        Xsolla sends the <code>order_canceled</code> 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.


        The webhook is not sent if the payment is not successful, for example:

        * the payment UI was opened but the user did not pay for the order

        * the payment UI was opened but there were errors during the payment


        The recommended webhook processing time is within 3 seconds.
      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.


                    The 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.
                  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:


                            <table>
                                <thead>
                                <tr>
                                    <th>Refund initiator</th>
                                    <th>Field value</th>
                                </tr>
                                </thead>
                                <tbody>
                                <tr>
                                    <td>Game (via API).</td>
                                    <td>API</td>
                                </tr>
                                <tr>
                                    <td>Publisher Account user (automatic refund).</td>
                                    <td>User email</td>
                                </tr>
                                <tr>
                                    <td>Publisher Account user (with assistance from Xsolla customer support).</td>
                                    <td>support@xsolla.com</td>
                                </tr>
                                <tr>
                                    <td>Xsolla (with assistance from Xsolla customer support).</td>
                                    <td>support@xsolla.com</td>
                                </tr>
                                </tbody>
                            </table>
                    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' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \

            -d '{
                "notification_type": "order_canceled",
                "items": [
                  {
                    "sku": "com.xsolla.v.item_1",
                    "type": "virtual_good",
                    "is_pre_order": false,
                    "quantity": 3,
                    "amount": "1000",
                    "promotions": [
                      {
                        "amount_without_discount": "6000",
                        "amount_with_discount": "5000",
                        "sequence": 1
                      },
                      {
                        "amount_without_discount": "5000",
                        "amount_with_discount": "4000",
                        "sequence": 2
                      }
                    ],
                    "custom_attributes": {
                        "purchased": 0,
                        "attr": "value"
                      }
                  },
                  {
                    "sku": "com.xsolla.v.item_new_1",
                    "type": "bundle",
                    "is_pre_order": false,
                    "quantity": 1,
                    "amount": "1000",
                    "promotions": []
                  },
                  {
                    "sku": "com.xsolla.gold_1",
                    "type": "virtual_currency",
                    "is_pre_order": false,
                    "quantity": 1500,
                    "amount": null,
                    "promotions": []
                  }
                ],
                "order": {
                  "id": 1,
                  "mode": "default",
                  "currency_type": "virtual",
                  "currency": "sku_currency",
                  "amount": "2000",
                  "status": "paid",
                  "platform": "xsolla",
                  "comment": null,
                  "invoice_id": "1",
                  "promotions": [
                    {
                      "amount_without_discount": "4000",
                      "amount_with_discount": "2000",
                      "sequence": 1
                    }
                  ],
                  "promocodes": [
                    {
                      "code": "promocode_some_code",
                      "external_id": "promocode_sku"
                    }
                  ],
                  "coupons": [
                    {
                      "code": "WINTER2021",
                      "external_id": "coupon_sku"
                    }
                  ]
                },
                "user": {
                  "external_id": "id_xsolla_login_1",
                  "email": "email@example.com",
                  "country": "US"
                },
                "billing": {
                  "notification_type": "refund",
                  "settings": {
                    "project_id": 18404,
                    "merchant_id": 2340
                  },
                  "purchase": {
                          "subscription": {
                              "plan_id": "b5dac9c8",
                              "subscription_id": "10",
                              "date_create": "2014-09-22T19:25:25+04:00",
                              "currency": "USD",
                              "amount": 9.99
                          },
                          "total":{
                              "currency": "USD",
                              "amount": 200
                          }
                      },
                  "transaction": {
                          "id": 1,
                          "external_id": 1,
                          "dry_run": 1,
                          "agreement": 1
                      },
                  "refund_details": {
                          "code": 4,
                          "reason": "Potential fraud"
                      },
                  "payment_details": {
                          "sales_tax": {
                              "currency": "USD",
                              "amount": 0
                          },
                          "direct_wht": {
                              "currency": "USD",
                              "amount": 0.70
                          },
                          "xsolla_fee": {
                              "currency": "USD",
                              "amount": "10"
                          },
                          "payout": {
                              "currency": "USD",
                              "amount": "200"
                          },
                          "payment_method_fee": {
                              "currency": "USD",
                              "amount": "20"
                          },
                          "payment": {
                              "currency": "USD",
                              "amount": "230"
                          },
                          "repatriation_commission": {
                              "currency": "USD",
                              "amount": 10
                          }
                      }
                }
            }
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host:           your.hostname
            accept:         application/json
            content-length: 258
            content-type:   application/json
            authorization:  Signature d90d319f05df7b0f86d2485f48e7079f0f752523


            {
                "notification_type": "order_canceled",
                "items": [
                  {
                    "sku": "com.xsolla.v.item_1",
                    "type": "virtual_good",
                    "is_pre_order": false,
                    "quantity": 3,
                    "amount": "1000",
                    "promotions": [
                      {
                        "amount_without_discount": "6000",
                        "amount_with_discount": "5000",
                        "sequence": 1
                      },
                      {
                        "amount_without_discount": "5000",
                        "amount_with_discount": "4000",
                        "sequence": 2
                      }
                    ],
                    "custom_attributes": {
                        "purchased": 0,
                        "attr": "value"
                      }
                  },
                  {
                    "sku": "com.xsolla.v.item_new_1",
                    "type": "bundle",
                    "is_pre_order": false,
                    "quantity": 1,
                    "amount": "1000",
                    "promotions": []
                  },
                  {
                    "sku": "com.xsolla.gold_1",
                    "type": "virtual_currency",
                    "is_pre_order": false,
                    "quantity": 1500,
                    "amount": null,
                    "promotions": []
                  }
                ],
                "order": {
                  "id": 1,
                  "mode": "default",
                  "currency_type": "virtual",
                  "currency": "sku_currency",
                  "amount": "2000",
                  "status": "paid",
                  "platform": "xsolla",
                  "comment": null,
                  "invoice_id": "1",
                  "promotions": [
                    {
                      "amount_without_discount": "4000",
                      "amount_with_discount": "2000",
                      "sequence": 1
                    }
                  ],
                  "promocodes": [
                    {
                      "code": "promocode_some_code",
                      "external_id": "promocode_sku"
                    }
                  ],
                  "coupons": [
                    {
                      "code": "WINTER2021",
                      "external_id": "coupon_sku"
                    }
                  ]
                },
                "user": {
                  "external_id": "id_xsolla_login_1",
                  "email": "email@example.com",
                  "country": "US"
                },
                "billing": {
                  "notification_type": "refund",
                  "settings": {
                    "project_id": 18404,
                    "merchant_id": 2340
                  },
                  "purchase": {
                      "subscription": {
                          "plan_id": "b5dac9c8",
                          "subscription_id": "10",
                          "date_create": "2014-09-22T19:25:25+04:00",
                          "currency": "USD",
                          "amount": 9.99
                      },
                      "total": {
                          "currency": "USD",
                          "amount": 200
                      }
                  },
                  "transaction": {
                      "id": 1,
                      "external_id": 1,
                      "dry_run": 1,
                      "agreement": 1
                  },
                  "refund_details": {
                      "code": 4,
                      "reason": "Potential fraud"
                  },
                  "payment_details": {
                      "sales_tax": {
                          "currency": "USD",
                          "amount": 0
                      },
                      "direct_wht": {
                          "currency": "USD",
                          "amount": 0.70
                      },
                      "xsolla_fee": {
                          "currency": "USD",
                          "amount": "10"
                      },
                      "payout": {
                          "currency": "USD",
                          "amount": "200"
                      },
                      "payment_method_fee": {
                          "currency": "USD",
                          "amount": "20"
                      },
                      "payment": {
                          "currency": "USD",
                          "amount": "230"
                      },
                      "repatriation_commission": {
                          "currency": "USD",
                          "amount": 10
                      }
                    }
                  }
                }
  order-cancellation-separate:
    post:
      summary: Order cancellation (without payment and transaction details)
      description: >
        Xsolla sends the <code>order_canceled</code> 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.


        The webhook is not sent if the payment was not successful, for example:

        * the payment UI was opened but the user did not pay for the order

        * the payment UI was opened but there were errors during the payment


        The recommended webhook processing time is within 3 seconds.
      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.


                    The 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.
                  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' \

            -X POST \

            -H 'accept: application/json' \

            -H 'content-type: application/json' \

            -H 'authorization: Signature
            d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \

            -d '{
                "notification_type": "order_canceled",
                "items": [
                  {
                    "sku": "com.xsolla.v.item_1",
                    "type": "virtual_good",
                    "is_pre_order": false,
                    "quantity": 3,
                    "amount": "1000",
                    "promotions": [
                      {
                        "amount_without_discount": "6000",
                        "amount_with_discount": "5000",
                        "sequence": 1
                      },
                      {
                        "amount_without_discount": "5000",
                        "amount_with_discount": "4000",
                        "sequence": 2
                      }
                    ],
                    "custom_attributes": {
                        "purchased": 0,
                        "attr": "value"
                      }
                  },
                  {
                    "sku": "com.xsolla.v.item_new_1",
                    "type": "bundle",
                    "is_pre_order": false,
                    "quantity": 1,
                    "amount": "1000",
                    "promotions": []
                  },
                  {
                    "sku": "com.xsolla.gold_1",
                    "type": "virtual_currency",
                    "is_pre_order": false,
                    "quantity": 1500,
                    "amount": "[null]",
                    "promotions": []
                  }
                ],
                "order": {
                  "id": 1,
                  "mode": "default",
                  "currency_type": "virtual",
                  "currency": "sku_currency",
                  "amount": "2000",
                  "status": "paid",
                  "platform": "xsolla",
                  "comment": null,
                  "invoice_id": "1",
                  "promotions": [
                    {
                      "amount_without_discount": "4000",
                      "amount_with_discount": "2000",
                      "sequence": 1
                    }
                  ],
                  "promocodes": [
                    {
                      "code": "promocode_some_code",
                      "external_id": "promocode_sku"
                    }
                  ],
                  "coupons": [
                    {
                      "code": "WINTER2021",
                      "external_id": "coupon_sku"
                    }
                  ]
                },
                "user": {
                  "external_id": "id_xsolla_login_1",
                  "email": "email@example.com",
                  "country": "US"
                }

            }'
        - lang: HTTP
          label: HTTP
          source: |
            POST /your/uri HTTP/1.1
            host:           your.hostname
            accept:         application/json
            content-length: 258
            content-type:   application/json
            authorization:  Signature d90d319f05df7b0f86d2485f48e7079f0f752523


            {
                "notification_type": "order_canceled",
                "items": [
                  {
                    "sku": "com.xsolla.v.item_1",
                    "type": "virtual_good",
                    "is_pre_order": false,
                    "quantity": 3,
                    "amount": "1000",
                    "promotions": [
                      {
                        "amount_without_discount": "6000",
                        "amount_with_discount": "5000",
                        "sequence": 1
                      },
                      {
                        "amount_without_discount": "5000",
                        "amount_with_discount": "4000",
                        "sequence": 2
                      }
                    ],
                    "custom_attributes": {
                        "purchased": 0,
                        "attr": "value"
                      }
                  },
                  {
                    "sku": "com.xsolla.v.item_new_1",
                    "type": "bundle",
                    "is_pre_order": false,
                    "quantity": 1,
                    "amount": "1000",
                    "promotions": []
                  },
                  {
                    "sku": "com.xsolla.gold_1",
                    "type": "virtual_currency",
                    "is_pre_order": false,
                    "quantity": 1500,
                    "amount": "[null]",
                    "promotions": []
                  }
                ],
                "order": {
                  "id": 1,
                  "mode": "default",
                  "currency_type": "virtual",
                  "currency": "sku_currency",
                  "amount": "2000",
                  "status": "paid",
                  "platform": "xsolla",
                  "comment": null,
                  "invoice_id": "1",
                  "promotions": [
                    {
                      "amount_without_discount": "4000",
                      "amount_with_discount": "2000",
                      "sequence": 1
                    }
                  ],
                  "promocodes": [
                    {
                      "code": "promocode_some_code",
                      "external_id": "promocode_sku"
                    }
                  ],
                  "coupons": [
                    {
                      "code": "WINTER2021",
                      "external_id": "coupon_sku"
                    }
                  ]
                },
                "user": {
                  "external_id": "id_xsolla_login_1",
                  "email": "email@example.com",
                  "country": "US"
                }
            }
  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 <a
        href="mailto:csm@xsolla.com">csm@xsolla.com</a>.
      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' \

            -X POST \

            -H 'authorization: Signature
            32c64a80d2527dc08906ae1891bac4489509b9f6' \

            -d '{
              "notification_type": "dispute",
              "action": "adding",
              "transaction": {
                "id": 123456789,
                "date_create": "2023-08-24T10:21:00+04:00",
                "total": {
                  "amount": 1,
                  "currency": "EUR"
                },
                "payment_method": "credit_debit_card"
              },
              "settings": {
                "project_id": 18404,
                "merchant_id": 2340
              },
              "user": {
                "id": "1234567",
                "email": "email@example.com",
                "country_code": "US"
              },
              "dispute": {
                "incoming_date": "2024-01-25T01:02:03+04:00",
                "reason": "not_as_described",
                "type": "retrieval",
                "status": "new"
              }
            }'
        - lang: HTTP
          label: HTTP
          source: |
            POST /your_uri HTTP/1.1
            host: your.host
            accept: application/json
            content-Type: application/json
            content-Length: 578
            authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

            {
              "notification_type": "dispute",
              "action": "adding",
              "transaction": {
                "id": 123456789,
                "date_create": "2023-08-24T10:21:00+04:00",
                "total": {
                  "amount": 1,
                  "currency": "EUR"
                },
                "payment_method": "credit_debit_card"
              },
              "settings": {
                "project_id": 18404,
                "merchant_id": 2340
              },
              "user": {
                "id": "1234567",
                "email": "email@example.com",
                "country_code": "US"
              },
              "dispute": {
                "incoming_date": "2024-01-25T01:02:03+04:00",
                "reason": "not_as_described",
                "type": "retrieval",
                "status": "new"
              }
            }
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 &gt; Webhooks &gt; 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).
    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`.


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


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


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

        For `bundle` type items, including virtual currency packages, the
        `items` array will display:
          - parameters of the bundle or virtual currency package
          - items included in the bundle or currencies included in the package
          
        The `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.
        The array is returned in the following cases:
          - A discount promotion is configured for a specific item.
          - A promo code with the **Discount on selected items** setting is applied.

        If 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.
        The array is returned in the following cases:
          - A promotion affects the total purchase amount, such as a promo code with the **Discount on purchase** setting.
          - 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.

        If 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](/solutions/payments/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: <b>New</b>
        accepted: <b>Accepted</b>
        no_actions_required: <b>In progress</b>
        won: <b>Won</b>
        lost: <b>Lost</b>
  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
