openapi: 3.1.0
info:
  description: "# 概览\n\nWebhook是系统中发生的事件的通知。当特定事件发生时，艾克索拉会向您的应用程序发送HTTP请求，其中会传输事件数据。它通常是JSON格式的POST请求。\n\n<strong>事件示例：</strong>\n- 用户与商品目录交互\n- 付款或取消订单\n\n当发生设定事件时，艾克索拉会通过Webhook通知您的系统。然后，您可以执行以下操作：\n- 补充用户余额\n- 进行退款\n- 向用户帐户发放或减除新商品\n- 开始提供订阅\n- 怀疑欺诈行为时封禁用户\n\n<b>支付处理Webhook工作流示例：</b>\n\n![支付处理Webhook](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks-general.svg)\n\n<div class=\"note\">\n<p><strong>注：</strong></p><p>根据所使用的解决方案及其集成类型，Webhook集和交互顺序可能与示例中的不同。</p>\n</div>\n\n<b>艾克索拉Webhook集成视频指南：</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>使用艾克索拉产品和解决方案时的Webhook设置：</b>\n\n<table>\n<thead>\n    <tr>\n        <th>产品/解决方案</th>\n        <th>必需/可选</th>\n        <th>Webhook的用途是什么</th>\n    </tr>\n</thead>\n<tbody>\n    <tr>\n        <td>付款</td>\n        <td>必需</td>\n        <td>\n          <ul>\n            <li>用户验证。</li>\n            <li>付款成功或退款时接收交易详情的信息。</li>\n            <li>将购买的商品记入用户帐户，及在订单取消时将商品减除。</li>\n          </ul>\n        </td>\n    </tr>\n    <tr>\n        <td>游戏内商店</td>\n        <td>必需</td>\n        <td>\n          <ul>\n            <li>用户验证。</li>\n            <li>付款成功或退款时接收交易详情的信息。</li>\n            <li>将购买的商品记入用户帐户，及在订单取消时将商品减除。</li>\n          </ul>\n        </td>\n    </tr>\n    <tr>\n        <td>游戏销售</td>\n        <td>可选</td>\n        <td>对于游戏密钥销售，用户验证和商品记入不是必需。如果想接收有关事件的信息（例如付款或订单取消），可以连接webhook。<br />如果连接Webhook，则必须处理所有传入的<a href=\"/zh/webhooks/overview/#section/List-of-required-webhooks\">必需Webhook</a>。\n</td>\n    </tr>\n    <tr>\n        <td>订阅</td>\n        <td>可选</td>\n        <td>接收有关创建、更新或取消订阅的信息。您也可以<a href=\"/doc/subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_information_set_up_via_api\">通过API请求信息</a>。\n</td>\n    </tr>\n    <tr>\n        <td>网页商城</td>\n        <td>必需</td>\n        <td>\n          <ul>\n            <li>用户验证。</li>\n            <li>付款成功或退款时接收交易详情的信息。</li>\n            <li>将购买的商品记入用户帐户，及在订单取消时将商品减除。</li>\n            <li>用户认证（如果使用通过用户ID进行身份认证）。您也可以使用<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\">通过艾克索拉登录管理器进行用户认证</a>。</li>\n          </ul>\n        </td>\n    </tr>\n    <tr>\n        <td>Digital Distribution Hub</td>\n        <td>必需</td>\n        <td>\n          <ul>\n            <li>用户验证。</li>\n            <li>将艾克索拉侧的交易ID与您系统中的交易ID关联。</li>\n            <li>在订单中传输额外交易参数。</li>\n            <li>将购买的商品记入用户帐户，及在订单取消时将商品减除。</li>\n          </ul>\n          <p>请参阅<a href=\"/solutions/ddh/#integration_guide_ddh_webhook\">文档</a>，了解如何为Digital Distribution Hub设置Webhook。</p>\n        </td>\n    </tr>\n    <tr>\n        <td>登录管理器</td>\n        <td>可选</td>\n        <td>\n          <p>接收事件信息：</p>\n          <ul>\n            <li>用户注册/授权</li>\n            <li>用户邮箱地址确认</li>\n            <li>关联用户的社交媒体帐户</li>\n          </ul>\n          <p>有关设置Webhook的详细信息，请参阅<a href=\"/api/login/operation/add-webhook-for-event/\">登录管理器文档</a>。</p>\n        </td>\n    </tr>\n</tbody>\n</table>\n\n# 必需Webhook列表\n如果使用需要与Webhook交互的产品和解决方案，<a href=\"/webhooks/overview/#section/Set-up-webhooks-\nin-Publisher-Account\">请在您的发布商帐户中启用并测试Webhook</a>并<a \nhref=\"/webhooks/overview/#section/Webhook-\nlistener\">设置Webhook处理</a>。当特定事件发生时，Webhook会按顺序发送。因此，如果您不处理其中一个Webhook，则不会发送后续Web\nhook。下面列出了必需Webhook的列表。\n\n## 游戏内商店和付款\n在艾克索拉侧已设置了2种Webhook发送选项，用于处理网站上的商品购买和退货——支付和交易数据信息以及已购商品信息可以分开发送，也可以合并为一个Webhook\n发送。\n\n<b>在合并Webhook中接收信息：</b>\n\n如果您在2025年1月22日之后在<a href=\"https://publisher.xsolla.com/\">发布商帐户</a>注册，您将在<a \nhref=\"/webhooks/operation/successful-order-payment\">订单成功支付</a>(`order_paid`) \n和<a href=\"/webhooks/operation/order-cancellation\">订单取消</a>(`order_canceled`) \nWebhook中收到所有信息。在这种情况下，您无需处理<a \nhref=\"/webhooks/operation/payment\">支付</a>(`payment`)和<a \nhref=\"/webhooks/operation/refund\">退款</a>(`refund`) Webhook。\n\n<b>在单独Webhook中接收信息：</b>\n\n如果您在2025年1月22日或之前在<a \nhref=\"https://publisher.xsolla.com/\">发布商帐户</a>注册，您将收到以下Webhook：\n- <a href=\"/webhooks/operation/payment\">支付</a>(`payment`)和<a \n  href=\"/webhooks/operation/refund\">退款</a>(`refund`) Webhook，包含支付数据和交易详细信息。\n- <a href=\"/webhooks/operation/successful-order-payment-\n  separate\">订单成功支付</a>(`order_paid`)和<a href=\"/webhooks/operation/order-\n  cancellation-separate\">订单取消</a>(`order_canceled`) Webhook，包含已购商品信息。\n\n您需要处理所有收到的Webhook。如需切换到新的合并Webhook接收方式，请联系您的客户成功经理或发送邮件至<a \nhref=\"mailto:csm@xsolla.com\">csm@xsolla.com</a>。\n\n为确保游戏内商店和支付管理功能正常运行，必须实现主要Webhook的处理。\n\n<b>如果接收合并Webhook：</b>\n\n<table>\n<thead>\n    <tr>\n        <th>Webhook名称和类型</th>\n        <th>描述</th>\n    </tr>\n</thead>\n<tbody>\n    <tr>\n        <td>用户验证 &gt; <a href=\"/webhooks/operation/user-validation/\">用户验证</a> (<code>user_validation</code>)</td>\n        <td>在支付流程的不同阶段发送，用于确保用户已在游戏中注册。</td>\n    </tr>\n    <tr>\n        <td>游戏服务 &gt; 合并Webhook &gt; <a href=\"/webhooks/operation/successful-order-payment\">订单成功支付</a>(<code>order_paid</code>)</td>\n        <td>包含支付数据、交易详情和已购商品信息。请使用Webhook中的数据为用户添加商品。</td>\n    </tr>\n    <tr>\n        <td>游戏服务 &gt; 合并Webhook &gt; <a href=\"/webhooks/operation/order-cancellation\">订单取消</a>(<code>order_canceled</code>)</td>\n        <td>包含已取消支付的数据、交易详情和已购商品信息。请使用Webhook中的数据移除已购商品。</td>\n    </tr>\n</tbody>\n</table>\n\n\n<b>如果接收单独Webhook</b>：\n\n<table>\n<thead>\n    <tr>\n        <th>Webhook名称和类型</th>\n        <th>描述</th>\n    </tr>\n</thead>\n<tbody>\n    <tr>\n        <td>用户验证 &gt; <a href=\"/webhooks/operation/user-validation/\">用户验证</a> (<code>user_validation</code>)</td>\n        <td>在支付流程的不同阶段发送，用于确保用户已在游戏中注册。</td>\n    </tr>\n    <tr>\n        <td>付款 &gt; <a href=\"/webhooks/operation/payment\">支付</a>(<code>payment</code>)</td>\n        <td>包含支付数据和交易详细信息。</td>\n    </tr>\n    <tr>\n        <td>游戏服务 &gt; 单独Webhook &gt; <a href=\"/webhooks/operation/successful-order-payment-separate\">订单成功支付</a>(<code>order_paid</code>)</td>\n        <td>包含已购商品信息。请使用Webhook中的数据为用户添加商品。</td>\n    </tr>\n    <tr>\n        <td>付款 &gt; <a href=\"/webhooks/operation/refund\">退款</a> (<code>refund</code>)</td>\n        <td>包含支付数据和交易详细信息。</td>\n    </tr>\n    <tr>\n        <td>游戏服务 &gt; 单独Webhook &gt; <a href=\"/webhooks/operation/order-cancellation-separate\">订单取消</a>(<code>order_canceled</code>)</td>\n        <td>包含已购商品信息和已取消交易的ID。请使用Webhook中的数据移除已购商品。</td>\n    </tr>\n</tbody>\n</table>\n\n如果您的应用程序侧实现了商品目录<a href=\"/doc/in-game-\nstore/features/personalization\">个性化</a>，请设置对<a href=\"/webhooks/operation\n/personalized-partner-catalog\">合作伙伴侧的目录个性化</a>Webhook的处理。\n\n<div class=\"note\">\n<p><strong>注意</strong></p>\n<p>要接收真实支付，您只需<a href=\"/doc/in-game-store/integration-guide/sign-licensing-agreement/\">签署许可协议</a>并实现以下Webhook的处理：</p>\n<p><ul><li>如果接收单独Webhook，则需处理<a href=\"/webhooks/operation/payment\">支付</a>、<a href=\"/webhooks/operation/successful-order-payment-separate\">订单成功支付</a>和<a href=\"/webhooks/operation/user-validation/\">用户验证</a>Webhook</li><li>如果接收合并Webhook，则需处理<a href=\"/webhooks/operation/successful-order-payment\">订单成功支付</a>和<a href=\"/webhooks/operation/user-validation/\">用户验证</a>Webhook</li></ul></p>\n</div>\n\n## 订阅\n要自动管理订阅计划，需要实现主要Webhook的处理：\n- <a href=\"/webhooks/operation/user-validation/\">用户验证</a>(`user_validation`) — \n  在支付过程的不同阶段发送，以确保用户已在游戏中注册。\n- <a href=\"/webhooks/operation/payment\">支付</a>(`payment`) — \n  在支付订单后发送，包含付款数据和交易详细信息。\n- <a href=\"/webhooks/operation/created-\n  subscription/\">创建了订阅</a>(`create_subscription`) — <a \n  href=\"/webhooks/operation/payment\">支付</a>Webhook已成功处理或用户购买了具有试用期的订阅时发送。它包含所购买的订阅\n  的详细信息和用户数据。使用该Webhook数据向用户添加订阅。\n- <a href=\"/webhooks/operation/updated-\n  subscription/\">更新了订阅</a>(`update_subscription`) — 续订或更改订阅以及<a \n  href=\"https://developers.xsolla.com/zh/webhooks/operation/payment\">支付</a>Webhook已成功\n  处理后发送。它包含所购买的订阅的详细信息和用户数据。使用该Webhook数据来延长用户的订阅或更改订阅参数。\n- <a href=\"/webhooks/operation/refund\">退款</a>(`refund`) — \n  订单被取消后发送，包含取消的付款数据和交易详细信息。\n- <a href=\"/webhooks/operation/canceled-\n  subscription/\">取消了订阅</a>(`cancel_subscription`) — <a \n  href=\"/webhooks/operation/refund\">退款</a>Webhook已成功处理或订阅因其他原因被取消时发送。它包含有关订阅和用户数据的\n  信息。使用该Webhook数据扣除用户购买的订阅。\n\n# 在发布商帐户中设置Webhook\n\n## 常规设置\n\n要启用接收Webhook：\n1. 在发布商帐户的项目中，前往<a \n   href=\"https://publisher.xsolla.com/0/projects/0/edit/webhooks/\">项目设置 &gt; \n   Webhook</a>部分。\n2. 在<b>Webhook服务器</b>字段中，指定要接收Webhook的服务器的URL，格式为`https://example.com`。您还可以指定在测试Web\n   hook的工具中找到的URL。\n\n<div class=\"notice\">\n<p><strong>注：</strong></p>\n<p> 请使用HTTPS协议传输数据，不支持HTTP协议。</p>\n</div>\n\n<p></p>\n\n3. 默认情况下会生成用于签署项目Webhook的密钥。如果想生成新的密钥，请单击刷新图标。\n4. 单击<b>启用Webhook</b>。\n\n![Enable \nwebhooks](https://cdn.xsolla.net/developers/current/images/api_docs/enable.png)\n\n<div class=\"note\">\n<p><strong>注：</strong></p>\n<p>要测试Webhook，可以选择任何专用网站（例如<a href=\"https://webhook.site/#!/\">webhook.site</a>）或平台（例如<a href=\"https://ngrok.com/\">ngrok</a>）。</p>\n</div>\n\n<p></p>\n\n<div class=\"notice\">\n<p><strong>注：</strong></p>\n<p>无法同时将Webhook发送到不同的URL。您可以在发布商帐户中执行的操作是先指定一个用于测试的URL，然后将其替换为真实的URL。</p>\n</div>\n\n要禁用接收Webhook：\n1. 在发布商帐户的项目中，前往<a \n   href=\"https://publisher.xsolla.com/0/projects/0/edit/webhooks/\">项目设置 &gt; \n   Webhook</a>部分。\n2. 单击<b>禁用Webhook</b>。\n\n## 高级设置\n\n<a href=\"/webhooks/overview/#section/Test-webhooks-in-Publisher-\nAccount/Store\">付款和商店</a>部分的Webhook提供高级设置。单击<b>获取Webhook</b>按钮后，这些设置将自动显示在<a \nhref=\"/webhooks/overview/#section/Set-up-webhooks-in-Publisher-Account/General-\nsettings\">常规设置</a>区块下方。\n\n<div class=\"note\">\n<p><strong>注意</strong></p>\n<p>如果未显示高级设置，请确保已在常规设置中连接Webhook接收，且您位于<b>测试 &gt; 付款和商店</b>选项卡中。</p>\n</div>\n\n在此部分，您可以设置在Webhook中接收额外信息。要实现此目的，请将相应开关设为启用状态。每个权限的行都会标明设置变更将影响哪些Webhook。\n\n<table>\n<thead>\n    <tr>\n        <th>开关</th>\n        <th>描述</th>\n    </tr>\n</thead>\n<tbody>\n    <tr>\n        <td>显示保存的支付帐户的信息</td>\n        <td>有关保存的支付方式的信息在<code>payment_account</code>自定义对象中传递。</td>\n    </tr>\n    <tr>\n        <td>显示通过保存的支付方式进行的交易的信息</td>\n        <td><p>信息在Webhook的以下自定义参数中传递：</p><ul><li><code>saved_payment_method</code>:<ul><li><code>0</code> — 未使用保存的支付方式</li><li><code>1</code> — 进行当前付款时保存了支付方式</li><li><code>2</code> — 使用了之前保存的支付方式</li></ul></li><li><code>payment_type</code>:<ul><li><code>1</code> — 一次性支付</li><li><code>2</code> — 定期支付</li></ul></li></ul></td>\n    </tr>\n    <tr>\n        <td>将订单对象添加到Webhook</td>\n        <td>有关订单的信息在<a href=\"/webhooks/operation/payment/\">支付</a>Webhook的<code>order</code>对象中传递。</td>\n    </tr>\n    <tr>\n        <td>仅发送不含敏感数据的必要用户参数</td>\n        <td><p>Webhook中仅传递用户的以下信息：</p><ul><li>ID</li><li>国家/地区</li></ul></td>\n    </tr>\n    <tr>\n        <td>发送自定义参数</td>\n        <td><a href=\"/api/pay-station/operation/create-token/\">自定义令牌参数</a>的信息在webhook中传递。</td>\n    </tr>\n    <tr>\n        <td>显示银行卡BIN和后缀码</td>\n        <td><p>Webhook中传递以下银行卡号的信息：</p><ul><li><code>card_bin</code>参数中的前6位数字</li><li><code>card_suffix</code>中的后4位数字</li></ul></td>\n    </tr>\n    <tr>\n        <td>显示银行卡品牌</td>\n        <td>用于付款的银行卡的品牌。例如，Mastercard或Visa。</td>\n    </tr>\n</tbody>\n</table>\n\n![高级设置](https://cdn.xsolla.net/developers/current/images/api_docs/advanced-settings-upd.png)\n\n# 在发布商帐户中测试Webhook\n\n测试Webhook有助于确保己侧和艾克索拉侧的项目设置都正确。\n\n如果Webhook<a href=\"/webhooks/overview/#section/Set-up-webhooks-in-Publisher-\nAccount\">设置</a>成功，Webhook 设置部分下方会显示一个Webhook测试部分。\n\n![Webhook测试部分](https://cdn.xsolla.net/developers/current/images/api_docs/testing.png)\n\n发布商帐户中的测试部分会根据Webhook接收选项而有所不同。\n\n<b>如果接收合并Webhook：</b>\n\n<table>\n<thead>\n    <tr>\n        <th>Webhook测试的选项卡名称</th>\n        <th>Webhook名称和类型</th>\n    </tr>\n</thead>\n<tbody>\n    <tr>\n        <td><b>付款和商店</b></td>\n        <td>用户验证 &gt; <a href=\"/webhooks/operation/user-validation/\">用户验证</a> (<code>user_validation</code>)</td>\n    </tr>\n    <tr>\n        <td></td>\n        <td>游戏服务 &gt; 合并Webhook &gt; <a href=\"/webhooks/operation/successful-order-payment\">订单成功支付</a>(<code>order_paid</code>)</td>\n    </tr>\n    <tr>\n        <td></td>\n        <td>游戏服务 &gt; 合并Webhook &gt; <a href=\"/webhooks/operation/order-cancellation\">订单取消</a>(<code>order_canceled</code>)</td>\n    </tr>\n    <tr>\n        <td><b>订阅</b></td>\n        <td>用户验证 &gt; <a href=\"/webhooks/operation/user-validation/\">用户验证</a> (<code>user_validation</code>)</td>\n    </tr>\n    <tr>\n        <td></td>\n        <td>付款 &gt; <a href=\"/webhooks/operation/payment\">支付</a>(<code>payment</code>)</td>\n    </tr>\n</tbody>\n</table>\n\n\n<b>如果接收单独Webhook</b>：\n\n<table>\n<thead>\n    <tr>\n        <th>Webhook测试的选项卡名称</th>\n        <th>Webhook名称和类型</th>\n    </tr>\n</thead>\n<tbody>\n    <tr>\n        <td><b>商店</b></td>\n        <td>游戏服务 &gt; 单独Webhook &gt; <a href=\"/webhooks/operation/successful-order-payment-separate\">订单成功支付</a>(<code>order_paid</code>)</td>\n    </tr>\n    <tr>\n        <td></td>\n        <td>游戏服务 &gt; 单独Webhook &gt; <a href=\"/webhooks/operation/order-cancellation-separate\">订单取消</a>(<code>order_canceled</code>)</td>\n    </tr>\n    <tr>\n        <td><b>付款</b></td>\n        <td>用户验证 &gt; <a href=\"/webhooks/operation/user-validation/\">用户验证</a> (<code>user_validation</code>)</td>\n    </tr>\n    <tr>\n        <td></td>\n        <td>付款 &gt; <a href=\"/webhooks/operation/payment\">支付</a>(<code>payment</code>)</td>\n    </tr>\n    <tr>\n        <td><b>订阅</b></td>\n        <td>用户验证 &gt; <a href=\"/webhooks/operation/user-validation/\">用户验证</a> (<code>user_validation</code>)</td>\n    </tr>\n    <tr>\n        <td></td>\n        <td>付款 &gt; <a href=\"/webhooks/operation/payment\">支付</a>(<code>payment</code>)</td>\n    </tr>\n</tbody>\n</table>\n\n<div class=\"note\">\n<p><strong>注：</strong></p>\n<p>如果测试部分出现测试未通过的警告，请在您的<a href=\"/webhooks/overview/#section/Webhook-listener\">Webhook侦听器</a>中检查Webhook响应设置。测试结果中指出了测试错误的原因。</p>\n<p><b>示例：</b></p>\n<p>您使用专门的网站<a href=\"https://webhook.site/#!/\">webhook.site</a>来进行测试。</p>\n<p><b>测试对无效签名的响应</b>部分显示了一个错误。</p>\n<p>发生这种情况是因为艾克索拉发送了带有错误签名的Webhook，并期望您的处理程序用一个指出<code>INVALID_SIGNATURE</code>错误代码的<code>4xx</code> HTTP代码进行响应。</p>\n<p><a href=\"https://webhook.site/#!/\">webhook.site</a>对所有Webhook的响应中都发送一个<code>200</code> HTTP代码，包括签名不正确的Webhook。由于无法获取预期的<code>4xx</code>HTTP代码，因此测试结果报错。</p>\n</div>\n\n![测试错误](https://cdn.xsolla.net/developers/current/images/api_docs/test-error.png)\n\n下文将介绍合并Webhook使用场景的测试流程。\n\n## 付款和商店\n\n在<b>付款和商店</b>选项卡中，您可以测试以下Webhook：\n- <a href=\"/webhooks/operation/user-validation/\">用户验证</a>(`user_validation`)\n- <a href=\"/webhooks/operation/successful-order-payment\">订单成功支付</a>(`order_paid`)\n- <a href=\"/webhooks/operation/order-cancellation\">订单取消</a>(`order_canceled`)\n\n要进行测试：\n1. 在Webhook测试部分，前往<b>付款和商店</b>选项卡。\n2. 在下拉菜单中，选择商品类型。如果所选类型的商品未在发布商帐户中设置，请单击：\n   * <b>连接</b> – 如果未连接该类型商品的模块\n   * <b>配置</b> – \n     如果之前连接过模块，但尚未完成设置<br/>单击该按钮后，您将被重定向到与所选商品类型相对应的发布商帐户部分。创建商品后，返回Webhook测试部分并继续下一步\n     。\n3. 填写以下必填字段：<ol type=\"a\"> \n   <li>从下拉列表中选择商品SKU并指定金额。您可以通过单击<b>+</b>号并在新行中添加来选择同一类型的多个商品。</li> \n   <li><b>用户ID</b> — 测试时，可以使用任意字母和数字组合。</li> <li><b>公共用户ID</b> — \n   用户可见的ID，例如电子邮件或昵称。如果在<b>支付中心 &gt; 设置</b>中启用了公共用户ID，则会显示此字段。</li> \n   <li>在<b>艾克索拉订单ID</b>字段中输入任意值。</li> <li><b>艾克索拉发票ID</b> — \n   艾克索拉侧的交易ID。测试时，可以使用任意数字值。</li> <li><b>发票ID</b> — \n   游戏侧的交易ID。测试时，可以使用任意字母和数字组合。这不是成功支付所必需的参数，但您可以通过它将游戏侧的交易ID与艾克索拉侧的交易ID关联起来。</li> \n   <li><b>金额</b> — 支付金额。测试时，可以使用任意数字值。</li> <li><b>货币</b> — 从下拉列表中选择货币。</li> </ol>\n\n4. 单击<b>测试Webhook</b>。\n\n\n系统会将包含指定数据的<a href=\"/webhooks/operation/user-validation/\">用户验证</a>、<a \nhref=\"/webhooks/operation/successful-order-payment\">订单成功支付</a>和<a \nhref=\"/webhooks/operation/order-\ncancellation\">订单取消</a>Webhook发送到提供的URL。每种Webhook类型的测试结果将显示在<b>测试Webhook</b>按钮下方。\n\n如果在您的项目中启用了公共用户ID，还将看到用户搜索检查的结果。\n\n对于每个Webhook，您需要配置处理两种情况：成功的情况和出现错误的情况。\n\n![付款测试部分](https://cdn.xsolla.net/developers/current/images/api_docs/payments-tab.png)\n\n## 订阅\n在<b>订阅</b>选项卡中，您可以测试以下Webhook：\n- <a href=\"/webhooks/operation/user-validation/\">用户验证</a>(`user_validation`)\n- <a href=\"/webhooks/operation/payment\">支付</a>(`payment`)\n\n<div class=\"note\">\n<p><strong>注：</strong></p>\n<p>在发布商帐户中，您只能测试基本的用户验证和支付Webhook。要测试其他Webhook类型，请前往：</p>\n<p><ul><li><a href=\"/doc/subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_set_up_webhooks_test_payment\">测试订阅购买</a></li><li><a href=\"/doc/subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_set_up_webhooks_test_renewal\">测试订阅续订</a></li><li><a href=\"/doc/subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_set_up_webhooks_test_cancelation\">测试订阅取消</a></li></ul></p>\n</div>\n\n<p></p>\n\n<div class=\"note\">\n<p><strong>注：</strong></p>\n<p>要测试Webhook，您应该在<b>发布商帐户&gt;订阅&gt;订阅计划</b>部分中至少有一个<a href=\"/doc/subscriptions/integration-guide/set-up-plan/\">已创建的订阅计划</a>。</p>\n</div>\n\n测试步骤：<ol> <li>在测试部分，前往<b>订阅</b>选项卡。</li> <li>填写以下必填字段：<ol type=\"a\"> \n<li><b>用户ID</b> — 测试时，可以使用任意字母和数字组合。</li> <li><b>艾克索拉发票ID</b> — \n艾克索拉侧的交易ID。测试时，可以使用任意数字值。</li> <li><b>公共用户ID</b> — 用户可见的ID，例如电子邮件或昵称。如果在支付中心 \n&gt; 设置 &gt; 其他设置部分启用了公共用户ID，则会显示此字段。</li> <li><b>货币</b> — 从下拉列表中选择货币。</li> \n<li><b>计划ID</b> — 订阅计划。从下拉列表中选择计划。</li> <li><b>订阅产品</b> — 从下拉列表中选择产品（可选）。</li> \n<li><b>金额</b> — 支付金额。测试时，可以使用任意数字值。</li> <li><b>发票ID</b> — \n游戏侧的交易ID。测试时，可以使用任意字母和数字组合。这不是成功支付所必需的参数，但您可以通过它将游戏侧的交易ID与艾克索拉侧的交易ID关联起来。</li> \n<li><b>试用期</b>。要测试<a href=\"/doc/subscriptions/integration-guide/get-\nsubscription-\ninformation/#guides_subscriptions_get_subscription_set_up_webhooks_sandbox\">购买无试\n用期的订阅或测试</a><a href=\"/doc/subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_set_up_webhooks_test_renewal\"\n>续订</a>，请指定值<code>0</code>。</li> </ol> </li> <li>单击<b>测试Webhook</b>。</li> </ol>\n\n在指定的URL中，您将收到包含所填数据的Webhook。每个Webhook的测试结果（成功场景和错误场景）都在<b>测试Webhook</b>按钮下方显示。\n\n<a id=\"webhook-listener\"></a>\n\n# Webhook侦听器\n\nWebhook侦听器是一个程序代码，允许在指定URL地址接收传入的Webhook、<a href=\"/webhooks/overview/#section\n/Webhook-listener/Generation-of-signature\">生成签名</a>以及<a \nhref=\"/webhooks/overview/#section/Webhook-listener/Sending-responses-to-\nwebhook\">发送响应</a>到艾克索拉Webhook服务器。\n\n<div class=\"note\">\n<p><strong>注：</strong></p>\n<p>您可以使用<a href=\"https://developers.xsolla.com/zh/sdk/php/\">Pay Station PHP SDK 库</a>，它包含用于处理Webhook的现成类。</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\n在您的应用程序侧，实现从以下IP地址接收Webhook：\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\n如集成了<a href=\"/doc/login/\">登录管理器</a> 产品，请另外添加对来自以下IP地址的Webhook的处理：\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\n限制：\n- 应用程序的数据库中不应存在具有相同ID的多个成功交易。\n- 如果Webhook侦听器收到的Webhook的ID已经存在于数据库中，则需返回之前处理该交易的结果。不建议向用户发放重复购买及在数据库中创建重复记录。\n\n## 生成签名\n\n为确保数据传输安全，您必须验证Webhook确实来自艾克索拉服务器，且在传输过程中未被篡改。为此，需要基于请求正文负载生成您自己的签名，并将其与传入请求的`au\nthorization`标头中提供的签名进行比较。如果签名匹配，则Webhook是真实的，可以安全处理。\n\n验证步骤：\n\n1. 从Webhook请求的`authorization`标头中检索签名。标头格式为`Signature <signature_value>`。\n2. 检索JSON格式的Webhook请求正文。<div \n   class=\"notice\"><p><strong>注意</strong></p><p>请完全按照接收到的JSON负载使用。不要解析或重新编码负载，因为这会改变\n   格式并导致签名验证失败。</p></div><p></p>\n\n3. 生成您自己的签名进行比较：<ol type=\"a\"> <li>通过将密钥附加到字符串末尾，将JSON负载与您项目的密钥连接起来。</li> \n   <li>对结果字符串应用SHA-1加密哈希函数。结果将是小写十六进制字符串。</li> </ol>\n4. 将您生成的签名与`authorization`标头中的签名进行比较。如果匹配，则Webhook是真实的。\n\n以下是C#、C++、Go、PHP和Node.js语言的签名生成实现示例。\n\n### 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### 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#签名生成实现示例（一般示例）：\n\n<div class=\"note\">\n<p><strong>注意</strong></p>\n<p>此代码示例兼容.NET Framework 4.0及更高版本，同时支持.NET Core和其他现代.NET版本。签名验证通过<code>ConstantTimeEquals</code>方法实现恒定时间比较，有效防止时序攻击。</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#签名生成实现示例（适用于.NET 5.0及更高版本）：\n\n<div class=\"note\">\n<p><strong>注意</strong></p>\n<p>使用 <code>Convert.ToHexString</code>方法需要.NET 5.0或更高版本。<p></p>若您使用.NET 7.0及更高版本，可选择<code>CryptographicOperations.FixedTimeEquals</code>方法替代<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#签名生成实现示例（适用于.NET 7.0及更高版本）：\n\n<div class=\"note\">\n<p><strong>注意</strong></p>\n<p>若您使用.NET 7.0及更高版本，可选择使用<code>CryptographicOperations.FixedTimeEquals</code>方法。</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++签名生成实现示例：\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签名生成实现示例：\n\n```go\npackage main\nimport (\n\t\"crypto/sha1\"\n    \"crypto/subtle\"\n\t\"encoding/hex\"\n\t\"strings\"\n)\ntype XsollaWebhookSignature struct{}\nfunc (x *XsollaWebhookSignature) ComputeSha1(jsonBody, secretKey string) string {\n\t// Concatenation of the JSON from the request body and the project's secret key\n\tdataToSign := jsonBody + secretKey\n\t// Create SHA1 hash\n\th := sha1.New()\n\th.Write([]byte(dataToSign))\n\tsignature := h.Sum(nil)\n\t// Convert to lowercase hexadecimal string\n\treturn strings.ToLower(hex.EncodeToString(signature))\n}\nfunc (x *XsollaWebhookSignature) VerifySignature(jsonBody, secretKey, receivedSignature string) bool {\n\tcomputedSignature := x.ComputeSha1(jsonBody, secretKey)\n\treceivedSignatureLower := strings.ToLower(receivedSignature)\n\t// Use constant time comparison to prevent timing attacks\n\treturn subtle.ConstantTimeCompare([]byte(computedSignature), []byte(receivedSignatureLower)) == 1\n}\n```\n\n### PHP签名生成实现示例：\n\n```php\n<?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签名生成实现示例：\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## 向Webhook发送响应\n\n要确认收到Webhook，您的服务器必须返回：\n* 如果响应成功，返回`200`、`201`或`204`HTTP代码。\n* 如果未找到指定的用户或传递了无效的签名，返回`400` HTTP代码和<a \n  href=\"/webhooks/overview/#section/错误\">问题描述</a>。如果您的服务器出现临时问题，您的Webhook处理程序还可\n  以返回`5xx`HTTP 代码。\n\n如果艾克索拉服务器未收到<a href=\"/webhooks/operation/successful-order-\npayment\">订单成功支付</a>和<a href=\"/webhooks/operation/order-\ncancellation\">订单取消</a>Webhook的响应，或收到`5xx`代码的响应，系统将按以下计划重新发送Webhook：\n* 尝试2次，间隔5分钟\n* 尝试7次，间隔15分钟\n* 尝试10次，间隔60分钟\n\n在首次尝试后的12小时内最多尝试发送20次Webhook。\n\n<a href=\"/webhooks/operation/payment\">支付</a>和<a \nhref=\"/webhooks/operation/refund\">退款</a>Webhook的重试逻辑说明见相应的Webhook页面。\n\n<div class=\"notice\">\n<p><strong>注意</strong></p>\n<p>如满足以下所有条件，款项仍将退还给用户：<ul><li>退款由艾克索拉发起。</li><li>Webhook响应返回<code>4xx</code>状态码，或在所有重试后未收到响应，或返回<code>5xx</code>状态码。</li></ul></p>\n</div>\n\n如果艾克索拉服务器未收到<a href=\"/webhooks/operation/user-\nvalidation/\">用户验证</a>Webhook的响应，或收到`400`或`5xx`代码的响应，则不会重新发送<a \nhref=\"/webhooks/operation/user-\nvalidation/\">用户验证</a>Webhook。在这种情况下，用户会看到错误提示，且系统不会发送<a \nhref=\"/webhooks/operation/payment\">支付</a>和<a href=\"/webhooks/operation\n/successful-order-payment\">订单成功支付</a>Webhook。\n\n# 错误\n\nHTTP代码400的错误代码：\n\n<table>\n<thead>\n    <tr>\n        <th>代码</th>\n        <th>消息</th>\n    </tr>\n</thead>\n<tbody>\n    <tr>\n        <td>INVALID_USER</td>\n        <td>无效用户</td>\n    </tr>\n    <tr>\n        <td>INVALID_PARAMETER</td>\n        <td>无效参数</td>\n    </tr>\n    <tr>\n        <td>INVALID_SIGNATURE</td>\n        <td>无效签名</td>\n    </tr>\n    <tr>\n        <td>INCORRECT_AMOUNT</td>\n        <td>金额不正确</td>\n    </tr>\n    <tr>\n        <td>INCORRECT_INVOICE</td>\n        <td>发票不正确</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# Webhook列表\n\n<div class=\"note\">\n<p><strong>注：</strong></p>\n<p>通知类型在<code>notification_type</code>参数中发送。</p>\n</div>\n\n<table>\n<thead>\n    <tr>\n        <th>Webhook</th>\n        <th>通知类型</th>\n        <th>描述</th>\n    </tr>\n</thead>\n<tbody>\n    <tr>\n        <td><a href=\"/webhooks/operation/user-validation/\">用户验证</a></td>\n        <td><code>user_validation</code></td>\n        <td>发送以检查用户是否存在于游戏中。</td>\n    </tr>\n    <tr>\n        <td><a href=\"/webhooks/operation/user-search/\">用户搜索</a></td>\n        <td><code>user_search</code></td>\n        <td>发送以根据公共用户ID获取用户信息。</td>\n    </tr>\n    <tr>\n        <td><a href=\"/webhooks/operation/payment/\">支付</a></td>\n        <td><code>payment</code></td>\n        <td>用户完成支付流程时发送。</td>\n    </tr>\n    <tr>\n        <td><a href=\"/webhooks/operation/refund/\">退款</a></td>\n        <td><code>refund</code></td>\n        <td>出于某些原因需要取消支付时发送。</td>\n    </tr>\n    <tr>\n        <td><a href=\"/webhooks/operation/partial-refund/\">部分退款</a></td>\n        <td><code>partial_refund</code></td>\n        <td>出于某些原因需要部分取消支付时发送。</td>\n    </tr>\n    <tr>\n        <td><a href=\"/webhooks/operation/payment-declined/\">付款被拒</a></td>\n        <td><code>ps_declined</code></td>\n        <td>当付款被支付系统拒绝时发送。</td>\n    </tr>\n    <tr>\n        <td><a href=\"https://developers.xsolla.com/zh/webhooks/operation/afs-rejected-transaction/\">AFS拒绝交易</a></td>\n        <td><code>afs_reject</code></td>\n        <td>交易在AFS检查过程中被拒绝时发送。</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/zh/webhooks/operation/afs-rejected-blocklist/\">AFS更新的拦截列表</a></td>\n      <td><code>afs_black_list</code></td>\n      <td>AFS拦截列表发生更新时发送。</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/zh/webhooks/operation/created-subscription/\">创建了订阅</a></td>\n      <td><code>create_subscription</code></td>\n      <td>用户创建订阅时发送。</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/zh/webhooks/operation/updated-subscription/\">更新了订阅</a></td>\n      <td><code>update_subscription</code></td>\n      <td>订阅发生续订或更改时发送。</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/zh/webhooks/operation/canceled-subscription/\">取消了订阅</a></td>\n      <td><code>cancel_subscription</code></td>\n      <td>取消订阅时发送。</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/zh/webhooks/operation/nonrenewing-subscription/\">非续订订阅</a></td>\n      <td><code>non_renewal_subscription</code></td>\n      <td>状态设置为非续订时发送。</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/zh/webhooks/operation/add-payment-account/\">添加支付账户</a></td>\n      <td><code>payment_account_add</code></td>\n      <td>当用户添加或保存支付帐户时发送。</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/zh/webhooks/operation/remove-payment-account/\">删除支付账户</a></td>\n      <td><code>payment_account_remove</code></td>\n      <td>用户从已保存的帐户中删除了支付帐户时发送。</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/zh/webhooks/operation/user-validation-in-webshop\">Web商店中的用户验证</a></td>\n      <td><code>-</code></td>\n      <td>从Web商店网站发送以检查游戏中是否存在该用户。</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/zh/webhooks/operation/personalized-partner-catalog\">合作伙伴侧目录个性化</a></td>\n      <td><code>partner_side_catalog</code></td>\n      <td>用户与商店交互时发送。</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/zh/webhooks/operation/successful-order-payment\">订单成功支付</a></td>\n      <td><code>order_paid</code></td>\n      <td>订单付款后发送。</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/zh/webhooks/operation/order-cancellation\">订单取消</a></td>\n      <td><code>order_canceled</code></td>\n      <td>订单取消时发送。</td>\n    </tr>\n    <tr>\n      <td><a href=\"https://developers.xsolla.com/zh/webhooks/operation/dispute\">争议</a></td>\n      <td><code>dispute</code></td>\n      <td>当提出新争议时发送。</td>\n    </tr>\n</tbody>\n</table>\n"
  title: Webhook
  version: '1.0'
servers:
  - url: https://api.xsolla.com/merchant/v2
tags:
  - name: user-validation
    x-displayName: 用户验证
  - name: payments
    x-displayName: 付款
  - name: game-services
    x-displayName: 游戏服务
  - name: anti-fraud
    x-displayName: 反欺诈
  - name: subscriptions
    x-displayName: 订阅
  - name: combined-webhooks
    x-displayName: 组合Webhook
  - name: separate-webhooks
    x-displayName: 独立Webhook
  - name: personalization
    x-displayName: 个性化Webhook
webhooks:
  add-payment-account:
    post:
      description: >-
        每当用户在游戏内购买商品时添加或保存了一个支付帐户时，艾克索拉向Webhook
        URL发送一个`payment_account_add`类型的Webhook。要接收该Webhook，请联系您的客户成功经理或发送电子邮件至<a
        href="mailto:csm@xsolla.com">csm@xsolla.com</a>。
      operationId: add-payment-account
      requestBody:
        content:
          application/json:
            schema:
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                payment_account:
                  description: 支付帐户详细信息（对象）。
                  properties:
                    country:
                      $ref: '#/components/schemas/payment_account.country'
                    id:
                      $ref: '#/components/schemas/payment_account.id'
                    name:
                      $ref: '#/components/schemas/payment_account.name'
                    payment_method:
                      $ref: '#/components/schemas/payment_account.payment_method'
                    type:
                      $ref: '#/components/schemas/payment_account.type'
                  required:
                    - id
                  type: object
                settings:
                  description: 带有自定义项目设置的对象。
                  properties:
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                  type: object
                user:
                  description: 用户详情（对象）。
                  properties:
                    country:
                      $ref: '#/components/schemas/user.country'
                    email:
                      $ref: '#/components/schemas/user.email'
                    id:
                      $ref: '#/components/schemas/user.id'
                    ip:
                      $ref: '#/components/schemas/user.ip'
                    name:
                      $ref: '#/components/schemas/user.name'
                    zip:
                      $ref: '#/components/schemas/user.zip'
                  required:
                    - id
                  type: object
              required:
                - notification_type
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      summary: 添加支付帐户
      tags:
        - payments
      x-codeSamples:
        - label: CURL
          lang: cURL
          source: >-
            curl -v 'https://your.hostname/your/uri' \

            -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"
                }
            }'
        - label: HTTP
          lang: 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"
                }
            }
  afs-rejected-blocklist:
    post:
      description: >-
        当反欺诈系统的黑名单发生更新（添加或删除了参数）时，艾克索拉会向Webhook
        URL发送一个`afs_black_list`类型的Webhook。参数添加在艾克索拉侧自动执行或根据您的请求执行。删除参数只能根据您的请求才可以进行。要接收此Webhook，请联系您的客户成功经理或发送电子邮件至<a
        href="mailto:csm@xsolla.com">csm@xsolla.com</a>。
      operationId: afs-rejected-blocklist
      requestBody:
        content:
          application/json:
            schema:
              properties:
                event:
                  description: 包含AFS拦截列表事件信息的对象。
                  properties:
                    action:
                      description: 事件类型。
                      enum:
                        - adding
                        - removing
                      type: string
                    date_of_last_action:
                      description: >-
                        [ISO
                        8601](https://en.wikipedia.org/wiki/ISO_8601)格式的最近AFS拦截列表事件时间。
                      type: string
                    parameter:
                      description: 发生事件的参数的名称。
                      enum:
                        - nick
                        - email
                        - ps_account
                        - ip_address
                        - card_issuer
                        - phone
                      type: string
                      x-enumDescriptions:
                        card_issuer: 用户的信用卡发卡银行
                        email: 用户的邮箱地址
                        ip_address: 用户的IP地址
                        nick: 用户的昵称
                        phone: 用户的手机号码
                        ps_account: 用户的账单帐户
                    parameter_value:
                      description: 发生事件的参数的值。
                      type: string
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                    reason:
                      description: 事件的原因。
                      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
                      type: string
                      x-enumDescriptions:
                        by_afs_filters: AFS筛选器（添加）
                        chargeback: 拒付（添加）
                        fraud_activity: 欺诈（添加）
                        friendly_fraud: 友好欺诈（添加）
                        linked_chargeback: 关联拒付（添加）
                        linked_parameter: AFS拦截列表中的关联参数（添加）
                        other_data_in_blacklist: AFS拦截列表中的其他参数（添加）
                        other_forgiveness_reason: 移除的其他原因（移除）
                        partner_request: 根据请求（添加）
                        ps_reported_fraud: 关于欺诈的支付系统通知（添加）
                        removed_by_cs_review: 向艾克索拉技术支持报告后移除（移除）
                        suspicious_activity: 可疑活动（添加）
                        user_reported_fraud: 用户报告欺诈（添加）
                        wrongly_added: 误添加（移除）
                    transaction_id:
                      description: 发生事件的参数关联的交易ID。
                      type: string
                  type: object
                notification_type:
                  $ref: '#/components/schemas/notification_type'
              required:
                - notification_type
                - event
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      summary: 反欺诈黑名单更新
      tags:
        - anti-fraud
      x-codeSamples:
        - label: CURL
          lang: cURL
          source: >-
            curl -v 'https://your.hostname/your/uri' \

            -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"
            }'
        - label: HTTP
          lang: 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"
            }
  afs-rejected-transaction:
    post:
      description: >
        当交易在反欺诈系统检查期间被拒绝时，艾克索拉会向Webhook 

        URL发送一个包含交易详情的`afs_reject`类型的Webhook。要接收该Webhook，请联系您的客户成功经理或发送电子邮件至<a 

        href="mailto:csm@xsolla.com">csm@xsolla.com</a>。


        在发布商帐户中保存 Webhook URL 时，可以授予在 Webhook 中接收详细信息的权限。为此，请在发布商帐户的<a 

        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/store">项目设置
        &gt; 

        Webhooks&gt; 高级设置</a>部分中将以下开关设置为打开状态。


        <div class="note">

        <p><strong>注：</strong></p>

        <p>如果是在2025年1月22日或之前注册的发布商帐户，可在<a
        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/payments">项目设置&gt;
        Webhooks&gt; 测试 &gt; 付款&gt; 高级设置</a> 部分中找到这些开关。</p>

        </div>


        <table>

        <thead>
            <tr>
                <th>开关</th>
                <th>描述</th>
            </tr>
        </thead>

        <tbody>
            <tr>
                <td>显示通过保存的支付方式进行的交易的信息</td>
                <td><p>信息在Webhook的以下自定义参数中传递：</p><ul><li><code>saved_payment_method</code>:<ul><li><code>0</code> — 未使用保存的支付方式</li><li><code>1</code> — 进行当前付款时保存了支付方式</li><li><code>2</code> — 使用了之前保存的支付方式</li></ul></li><li><code>payment_type</code>:<ul><li><code>1</code> — 一次性支付</li><li><code>2</code> — 定期支付</li></ul></li></ul></td>
            </tr>
        </tbody>

        </table>
      operationId: afs-rejected-transaction
      requestBody:
        content:
          application/json:
            schema:
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                refund_details:
                  description: 退款详情（对象）。
                  properties:
                    author:
                      description: 退款申請人。
                      type: string
                    code:
                      description: 代码ID。
                      type: integer
                    reason:
                      description: 退款原因。
                      type: string
                  type: object
                settings:
                  description: 带有自定义项目设置的对象。
                  properties:
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                  type: object
                transaction:
                  description: 交易ID。
                  properties:
                    agreement:
                      description: 协议ID。
                      type: integer
                    dry_run:
                      description: 测试交易。如为测试交易，该参数的值为1；如为真实交易，则不会发送该参数。
                      type: integer
                    external_id:
                      description: 交易外部ID。
                      type: string
                    id:
                      description: 交易ID。
                      type: integer
                  type: object
                user:
                  description: 用户详情（对象）。
                  properties:
                    country:
                      $ref: '#/components/schemas/user.country'
                    email:
                      $ref: '#/components/schemas/user.email'
                    id:
                      $ref: '#/components/schemas/user.id'
                    ip:
                      $ref: '#/components/schemas/user.ip'
                    name:
                      $ref: '#/components/schemas/user.name'
                    phone:
                      description: 用户电话号码（采用国际格式）。
                      type: string
                    zip:
                      $ref: '#/components/schemas/user.zip'
                  required:
                    - id
                  type: object
              required:
                - notification_type
                - transaction
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      summary: 反欺诈系统拒绝了交易
      tags:
        - anti-fraud
      x-codeSamples:
        - label: CURL
          lang: 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"
              }
            }'
        - label: PHP
          lang: 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'
              )
            );
        - label: HTTP
          lang: 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"
              }
            }
  canceled-subscription:
    post:
      description: 取消订阅时，艾克索拉会向Webhook URL发送一个`cancel_subscription`类型的Webhook。
      operationId: canceled-subscription
      requestBody:
        content:
          application/json:
            schema:
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                settings:
                  description: 带有自定义项目设置的对象。
                  properties:
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                  type: object
                subscription:
                  description: 订阅详情（对象）。
                  properties:
                    date_create:
                      $ref: '#/components/schemas/subscription.date_create'
                    date_end:
                      $ref: '#/components/schemas/subscription.date_end'
                    plan_id:
                      $ref: '#/components/schemas/subscription.plan_id'
                    product_id:
                      $ref: '#/components/schemas/subscription.product_id'
                    subscription_id:
                      $ref: '#/components/schemas/subscription.subscription_id'
                    tags:
                      $ref: '#/components/schemas/subscription.tags'
                  type: object
                user:
                  description: 用户详情（对象）。
                  properties:
                    id:
                      $ref: '#/components/schemas/user.id'
                    name:
                      $ref: '#/components/schemas/user.name'
                  required:
                    - id
                  type: object
              required:
                - notification_type
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      summary: 已取消订阅
      tags:
        - subscriptions
      x-codeSamples:
        - label: CURL
          lang: cURL
          source: >-
            curl -v 'https://your.hostname/your/uri' \

            -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"
                    }
                }'
        - label: PHP
          lang: 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',
                )
            );
        - label: HTTP
          lang: 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"
                }
            }
  created-subscription:
    post:
      description: 当用户创建订阅时，艾克索拉会向Webhook URL发送一个`create_subscription`类型的Webhook。
      operationId: created-subscription
      requestBody:
        content:
          application/json:
            schema:
              properties:
                custom_parameters:
                  description: 您的自定义参数。
                  type: object
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                settings:
                  description: 带有自定义项目设置的对象。
                  properties:
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                  type: object
                subscription:
                  description: 订阅详情（对象）。
                  properties:
                    date_create:
                      $ref: '#/components/schemas/subscription.date_create'
                    date_next_charge:
                      $ref: '#/components/schemas/subscription.date_next_charge'
                    is_gift:
                      $ref: '#/components/schemas/subscription.is_gift'
                    plan_id:
                      $ref: '#/components/schemas/subscription.plan_id'
                    product_id:
                      $ref: '#/components/schemas/subscription.product_id'
                    subscription_id:
                      $ref: '#/components/schemas/subscription.subscription_id'
                    tags:
                      $ref: '#/components/schemas/subscription.tags'
                    trial:
                      description: 带有订阅试用期相关数据的对象。
                      properties:
                        type:
                          description: 试用期类型：day。
                          type: string
                        value:
                          description: 试用期时长。
                          type: integer
                      type: object
                  type: object
                user:
                  description: 用户详情（对象）。
                  properties:
                    id:
                      $ref: '#/components/schemas/user.id'
                    name:
                      $ref: '#/components/schemas/user.name'
                  required:
                    - id
                  type: object
              required:
                - notification_type
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      summary: 已创建订阅
      tags:
        - subscriptions
      x-codeSamples:
        - label: CURL
          lang: cURL
          source: >-
            curl -v 'https://your.hostname/your/uri' \

            -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
                    }
                }'
        - label: PHP
          lang: 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,
                )
            );
        - label: HTTP
          lang: 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
                }
            }
  dispute:
    post:
      description: >-
        提起新争议或争议状态发生变化时，艾克索拉会向Webhook
        URL发送一个包含`dispute`类型的Webhook。要接收该Webhook，请联系您的客户成功经理或发送电子邮件至<a
        href="mailto:csm@xsolla.com">csm@xsolla.com</a>。
      operationId: dispute
      requestBody:
        content:
          application/json:
            schema:
              properties:
                action:
                  description: 操作类型。
                  enum:
                    - adding
                    - updating
                  type: string
                  x-enumDescriptions:
                    adding: 提起了新争议。
                    updating: 争议状态发生改变。
                dispute:
                  description: 包含争议信息的对象。
                  properties:
                    incoming_date:
                      $ref: '#/components/schemas/dispute-date'
                    reason:
                      $ref: '#/components/schemas/dispute-reason'
                    status:
                      $ref: '#/components/schemas/dispute-status'
                    type:
                      $ref: '#/components/schemas/dispute-type'
                  required:
                    - incoming_date
                    - reason
                    - type
                    - status
                  type: object
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                settings:
                  description: 包含自定义项目设置信息的对象。
                  properties:
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                  required:
                    - project_id
                    - merchant_id
                  type: object
                transaction:
                  description: 包含交易信息的对象。
                  properties:
                    country_code:
                      $ref: '#/components/schemas/user.country'
                    date_create:
                      $ref: '#/components/schemas/date-create'
                    external_id:
                      $ref: '#/components/schemas/external-id'
                    id:
                      $ref: '#/components/schemas/transaction-id'
                    payment_method:
                      $ref: '#/components/schemas/dispute-payment-method'
                    total:
                      description: 包含交易金额信息的对象。
                      properties:
                        amount:
                          $ref: '#/components/schemas/transaction-total-amount'
                        currency:
                          $ref: '#/components/schemas/currency'
                      required:
                        - amount
                        - currency
                      type: object
                  required:
                    - id
                    - date_create
                    - total
                    - payment_method
                    - country_code
                  type: object
                user:
                  description: 包含用户信息的对象。
                  properties:
                    email:
                      $ref: '#/components/schemas/user.email'
                    id:
                      $ref: '#/components/schemas/user.id'
                  required:
                    - id
                  type: object
              required:
                - notification_type
                - action
                - transaction
                - settings
                - user
                - dispute
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      summary: 争议
      tags:
        - anti-fraud
      x-codeSamples:
        - label: CURL
          lang: cURL
          source: >-
            curl -v 'https://your.hostname/your/uri' \

            -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"
              }
            }'
        - label: HTTP
          lang: 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"
              }
            }
  nonrenewing-subscription:
    post:
      description: >-
        当订阅状态设置为非续订时，艾克索拉会向Webhook
        URL发送一个`non_renewal_subscription`类型的Webhook。要接收该Webhook，请联系您的客户成功经理或发送电子邮件至<a
        href="mailto:csm@xsolla.com">csm@xsolla.com</a>。
      operationId: nonrenewing-subscription
      requestBody:
        content:
          application/json:
            schema:
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                settings:
                  description: 带有自定义项目设置的对象。
                  properties:
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                  required:
                    - project_id
                  type: object
                subscription:
                  description: 订阅详情（对象）。
                  properties:
                    amount:
                      description: 以实际货币表示的价格。
                      format: float
                      type: number
                    currency:
                      $ref: '#/components/schemas/currency'
                    date_create:
                      $ref: '#/components/schemas/subscription.date_create'
                    date_next_charge:
                      description: >-
                        下一账单日期。此为用户订阅设置为不续订之前下一次付款的日期。格式为符合[ISO
                        8601](https://en.wikipedia.org/wiki/ISO_8601)标准的日期和时间。
                      type: string
                    plan_id:
                      $ref: '#/components/schemas/subscription.plan_id'
                    subscription_id:
                      $ref: '#/components/schemas/subscription.subscription_id'
                  type: object
                user:
                  description: 用户详情（对象）。
                  properties:
                    email:
                      $ref: '#/components/schemas/user.email'
                    id:
                      $ref: '#/components/schemas/user.id'
                    name:
                      $ref: '#/components/schemas/user.name'
                  required:
                    - id
                  type: object
              required:
                - notification_type
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      summary: 到期性订阅
      tags:
        - subscriptions
      x-codeSamples:
        - label: CURL
          lang: cURL
          source: >-
            curl -v 'https://your.hostname/your/uri' \

            -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
                    }
                }'
        - label: PHP
          lang: 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
                )
            );
        - label: HTTP
          lang: 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
                }
            }
  order-cancellation:
    post:
      description: |
        当订单被用户、合作伙伴取消或系统自动取消时，艾克索拉会向指定URL发送<code>order_canceled</code> 
        Webhook。此Webhook包含已退回商品的信息、付款数据和已取消订单的详细内容。

        如果付款不成功，则不会发送该Webhook，例如：
        * 打开了支付UI，但用户没有为订单付款
        * 打开了支付UI，但付款过程中出现错误

        推荐的Webhook处理时间为3秒以内。
      operationId: order-cancellation
      requestBody:
        content:
          application/json:
            schema:
              properties:
                billing:
                  description: 交易和付款详细信息。
                  properties:
                    notification_type:
                      $ref: '#/components/schemas/notification_type'
                    payment_details:
                      description: 带有支付详细信息的对象。
                      properties:
                        country_wht:
                          description: 跨境交易在特定国家/地区收取的预扣税（对象）。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                            percent:
                              description: 国家/地区预扣税税率(%)。
                              format: float
                              type: number
                          type: object
                        direct_wht:
                          description: 直接预扣税。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                            percent:
                              description: 直接预扣税税率。
                              format: float
                              type: number
                          type: object
                        payment:
                          description: 带有用户支付相关数据的对象。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                          type: object
                        payment_method_fee:
                          description: 支付系统佣金的大小。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                          type: object
                        payment_method_sum:
                          description: 带有通过支付方式收费的金额相关数据的对象。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                          type: object
                        payout:
                          description: 带有支出详细信息的对象。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                          type: object
                        payout_currency_rate:
                          description: 从支付币种到支出币种的汇率。
                          type: string
                        repatriation_commission:
                          description: 包含汇回本国费用数据的对象，该费用是第三方对艾克索拉收取的费用。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                          type: object
                        sales_tax:
                          description: 销售税（对象；仅适用于美国和加拿大）。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                            percent:
                              description: 销售税税率。
                              format: float
                              type: number
                          type: object
                        user_acquisition_fee:
                          description: 从通过联盟网络和圈内达人完成的购买中扣除的用户获取费用总额（对象）。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                            percent:
                              description: 用户获取费费率(%)。
                              format: float
                              type: number
                          type: object
                        vat:
                          description: 增值税大小（仅适用于欧盟）。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                            percent:
                              description: VAT税率。
                              format: float
                              type: number
                          type: object
                        xsolla_balance_sum:
                          description: 计入艾克索拉余额的金额。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                          type: object
                        xsolla_fee:
                          description: 艾克索拉费用（对象）。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                          type: object
                      type: object
                    purchase:
                      description: 带有购买相关数据的对象。
                      properties:
                        subscription:
                          description: 订阅详情（对象）。
                          properties:
                            amount:
                              $ref: '#/components/schemas/amount-float'
                            currency:
                              $ref: '#/components/schemas/currency'
                            date_create:
                              $ref: '#/components/schemas/subscription.date_create'
                            plan_id:
                              $ref: '#/components/schemas/subscription.plan_id'
                            subscription_id:
                              $ref: >-
                                #/components/schemas/subscription.subscription_id
                            tags:
                              $ref: '#/components/schemas/subscription.tags'
                          type: object
                        total:
                          description: 带有总购买价格相关数据的对象。
                          properties:
                            amount:
                              description: 总购买金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                          type: object
                      required:
                        - total
                      type: object
                    refund_details:
                      description: 退款详情（对象）。
                      properties:
                        author:
                          description: |
                            退款发起人。根据下表传入字段值：

                            <table>
                                <thead>
                                <tr>
                                    <th>退款发起人</th>
                                    <th>字段值</th>
                                </tr>
                                </thead>
                                <tbody>
                                <tr>
                                    <td>游戏（通过API）。</td>
                                    <td>API</td>
                                </tr>
                                <tr>
                                    <td>发布商帐户用户（自动退款）。</td>
                                    <td>用户邮箱</td>
                                </tr>
                                <tr>
                                    <td>发布商帐户用户（通过艾克索拉客户支持的帮助）。</td>
                                    <td>support@xsolla.com</td>
                                </tr>
                                <tr>
                                    <td>艾克索拉（通过艾克索拉客户支持的帮助）。</td>
                                    <td>support@xsolla.com</td>
                                </tr>
                                </tbody>
                            </table>
                          type: string
                        code:
                          description: 代码ID。
                          type: integer
                        reason:
                          description: 退款原因。
                          type: string
                      type: object
                    settings:
                      description: 带有自定义项目设置的对象。
                      properties:
                        merchant_id:
                          $ref: '#/components/schemas/settings.merchant_id'
                        project_id:
                          $ref: '#/components/schemas/settings.project_id'
                      type: object
                    transaction:
                      description: 交易ID。
                      properties:
                        agreement:
                          description: 协议ID。
                          type: integer
                        dry_run:
                          description: 测试交易。如为测试交易，该参数的值为1；如为真实交易，则不会发送该参数。
                          type: integer
                        external_id:
                          description: 交易外部ID。
                          type: string
                        id:
                          description: 交易ID。
                          type: integer
                        payment_method_order_id:
                          description: 支付系统中的付款ID。
                          type: string
                      type: object
                  required:
                    - notification_type
                    - transaction
                    - payment_details
                  type: object
                custom_parameters:
                  description: 附加信息。
                  type: object
                items:
                  description: >
                    用户所购商品的列表。


                    数组中包含的参数集取决于Webhook版本。版本2包含额外参数：`is_free`、`is_bonus`和`is_bundle_content`。要切换版本，请

                    在[更新Webhook设置信息](/zh/api/igs/operation/update-webhook/)
                    API调用的`version`参数中传入版本编号。
                  items:
                    oneOf:
                      - properties:
                          amount:
                            description: 根据商品数量计算的总费用。
                            type: string
                          custom_attributes:
                            description: 包含商品属性和值的JSON对象。
                            type: object
                          is_pre_order:
                            description: 如果为`true`，则该商品为预订商品。
                            type: boolean
                          promotions:
                            $ref: '#/components/schemas/items.promotions'
                          quantity:
                            description: 商品数量。
                            type: integer
                          sku:
                            $ref: '#/components/schemas/items.sku'
                          type:
                            $ref: '#/components/schemas/items.type'
                        required:
                          - sku
                          - type
                          - quantity
                          - amount
                          - promotions
                          - is_pre_order
                        title: version = 1
                        type: object
                      - properties:
                          amount:
                            description: 根据商品数量计算的总费用。
                            type: string
                          custom_attributes:
                            description: 包含商品属性和值的JSON对象。
                            type: object
                          is_bonus:
                            description: 如果为`true`，则该商品为奖励。
                            type: boolean
                          is_bundle_content:
                            description: 如果为`true`，则该商品属于某个捆绑包。
                            type: boolean
                          is_free:
                            description: 如果为`true`，则该商品为免费。
                            type: boolean
                          is_pre_order:
                            description: 如果为`true`，则该商品为预订商品。
                            type: boolean
                          promotions:
                            $ref: '#/components/schemas/items.promotions'
                          quantity:
                            description: 商品数量。
                            type: integer
                          sku:
                            $ref: '#/components/schemas/items.sku'
                          type:
                            $ref: '#/components/schemas/items.type'
                        required:
                          - sku
                          - type
                          - quantity
                          - amount
                          - promotions
                          - is_pre_order
                          - is_free
                          - is_bonus
                          - is_bundle_content
                        title: version = 2
                        type: object
                  type: array
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                order:
                  description: 订单信息。
                  properties:
                    amount:
                      description: 基于所选货币的购物车总价。
                      type: string
                    comment:
                      description: 用户对订单的备注。
                      nullable: true
                      type: string
                    coupons:
                      description: 应用的优惠券。如未应用优惠券，则不会返回该数组。
                      items:
                        properties:
                          code:
                            description: 应用的优惠券的券码。
                            type: string
                          external_id:
                            description: 外部ID。
                            type: string
                        type: object
                      type: array
                    currency:
                      description: >-
                        订单货币。虚拟货币使用SKU，真实货币使用三个字母的[ISO
                        4217](https://en.wikipedia.org/wiki/ISO_4217)代码。
                      type: string
                    currency_type:
                      $ref: '#/components/schemas/currency-type'
                    id:
                      description: 艾克索拉侧用户订单的唯一标识符。
                      type: integer
                    invoice_id:
                      description: 实际货币付款发票ID。虚拟货币付款或免费商品的值为`null`。
                      nullable: true
                      type: string
                    mode:
                      description: 付款模式。对于真实支付，使用`default`；对于测试性支付，使用`sandbox`。
                      enum:
                        - default
                        - sandbox
                      type: string
                    platform:
                      description: >-
                        支付平台。
                        `xsolla`值用于通过艾克索拉进行的支付。其他支付使用游戏发布平台名称对应的值：`playstation_network`、`xbox_live`、`pc_standalone`、`nintendo_shop`、`google_play`、`app_store_ios`、`android_standalone`、`ios_standalone`、`android_other`、`ios_other`、`pc_other`。
                      enum:
                        - xsolla
                        - playstation_network
                        - xbox_live
                        - pc_standalone
                        - nintendo_shop
                        - google_play
                        - app_store_ios
                        - android_standalone
                        - ios_standalone
                        - android_other
                        - ios_other
                        - pc_other
                      nullable: true
                      type: string
                    promocodes:
                      description: 应用的促销码。如未应用促销码，则不会返回该数组。
                      items:
                        properties:
                          code:
                            description: 应用的促销码的代码。
                            type: string
                          external_id:
                            description: 外部ID。
                            type: string
                        type: object
                      type: array
                    promotions:
                      $ref: '#/components/schemas/order.promotions'
                    status:
                      description: 订单状态。
                      type: string
                  required:
                    - id
                    - mode
                    - currency_type
                    - currency
                    - amount
                    - status
                    - platform
                    - comment
                    - invoice_id
                    - promotions
                  type: object
                user:
                  description: 用户信息。
                  properties:
                    country:
                      $ref: '#/components/schemas/user.country'
                    email:
                      description: 用户邮箱地址。
                      type: string
                    external_id:
                      description: 用户ID。
                      type: string
                  required:
                    - external_id
                    - email
                  type: object
              required:
                - notification_type
                - items
                - order
                - user
                - transaction
                - payment_details
      responses:
        '200':
          description: 返回以指示处理成功。
        '400':
          description: 提供的信息出错时返回（例如，缺少必需的参数、授权失败等）。
      summary: 订单取消（包含付款和交易详情）
      tags:
        - combined-webhooks
      x-codeSamples:
        - label: CURL
          lang: cURL
          source: >-
            curl -v 'https://your.hostname/your/uri' \

            -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
                          }
                      }
                }
            }
        - label: HTTP
          lang: 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:
      description: |
        当订单被用户、合作伙伴取消或系统自动取消时，艾克索拉会向指定URL发送<code>order_canceled</code> 
        Webhook。此Webhook包含已退回商品的信息和已取消订单的详细内容。

        如果付款不成功，则不会发送该Webhook，例如：
        * 打开了支付UI，但用户没有为订单付款
        * 打开了支付UI，但付款过程中出现错误

        推荐的Webhook处理时间为3秒以内。
      operationId: order-cancellation-separate
      requestBody:
        content:
          application/json:
            schema:
              properties:
                custom_parameters:
                  description: 附加信息。
                  type: object
                items:
                  description: >
                    用户所购商品的列表。


                    数组中包含的参数集取决于Webhook版本。版本2包含额外参数：`is_free`、`is_bonus`和`is_bundle_content`。要切换版本，请

                    在[更新Webhook设置信息](/zh/api/igs/operation/update-webhook/)
                    API调用的`version`参数中传入版本编号。
                  items:
                    oneOf:
                      - properties:
                          amount:
                            description: 根据商品数量计算的总费用。
                            type: string
                          custom_attributes:
                            description: 包含商品属性和值的JSON对象。
                            type: object
                          is_pre_order:
                            description: 如果为`true`，则该商品为预订商品。
                            type: boolean
                          promotions:
                            $ref: '#/components/schemas/items.promotions'
                          quantity:
                            description: 商品数量。
                            type: integer
                          sku:
                            $ref: '#/components/schemas/items.sku'
                          type:
                            $ref: '#/components/schemas/items.type'
                        required:
                          - sku
                          - type
                          - quantity
                          - amount
                          - promotions
                          - is_pre_order
                        title: version = 1
                        type: object
                      - properties:
                          amount:
                            description: 根据商品数量计算的总费用。
                            type: string
                          custom_attributes:
                            description: 包含商品属性和值的JSON对象。
                            type: object
                          is_bonus:
                            description: 如果为`true`，则该商品为奖励。
                            type: boolean
                          is_bundle_content:
                            description: 如果为`true`，则该商品属于某个捆绑包。
                            type: boolean
                          is_free:
                            description: 如果为`true`，则该商品为免费。
                            type: boolean
                          is_pre_order:
                            description: 如果为`true`，则该商品为预订商品。
                            type: boolean
                          promotions:
                            description: 应用促销。如果未应用促销，则会在参数中传递一个空数组。
                            items:
                              properties:
                                amount_with_discount:
                                  description: 应用折扣后商品总价。
                                  type: string
                                amount_without_discount:
                                  description: 不应用折扣的商品总价。
                                  type: string
                                sequence:
                                  description: 应用促销活动的顺序。
                                  type: integer
                              type: object
                            type: array
                          quantity:
                            description: 商品数量。
                            type: integer
                          sku:
                            $ref: '#/components/schemas/items.sku'
                          type:
                            $ref: '#/components/schemas/items.type'
                        required:
                          - sku
                          - type
                          - quantity
                          - amount
                          - promotions
                          - is_pre_order
                          - is_free
                          - is_bonus
                          - is_bundle_content
                        title: version = 2
                        type: object
                  type: array
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                order:
                  description: 订单信息。
                  properties:
                    amount:
                      description: 基于所选货币的购物车总价。
                      type: string
                    comment:
                      description: 用户对订单的备注。
                      nullable: true
                      type: string
                    coupons:
                      description: 应用的优惠券。如未应用优惠券，则不会返回该数组。
                      items:
                        properties:
                          code:
                            description: 应用的优惠券的券码。
                            type: string
                          external_id:
                            description: 外部ID。
                            type: string
                        type: object
                      type: array
                    currency:
                      description: >-
                        订单货币。虚拟货币使用SKU，真实货币使用三个字母的[ISO
                        4217](https://en.wikipedia.org/wiki/ISO_4217)代码。
                      type: string
                    currency_type:
                      $ref: '#/components/schemas/currency-type'
                    id:
                      description: 艾克索拉侧用户订单的唯一标识符。
                      type: integer
                    invoice_id:
                      description: 实际货币付款发票ID。虚拟货币付款或免费商品的值为`null`。
                      nullable: true
                      type: string
                    mode:
                      description: 付款模式。对于真实支付，使用`default`；对于测试性支付，使用`sandbox`。
                      enum:
                        - default
                        - sandbox
                      type: string
                    platform:
                      description: >-
                        支付平台。
                        `xsolla`值用于通过艾克索拉进行的支付。其他支付使用游戏发布平台名称对应的值：`playstation_network`、`xbox_live`、`pc_standalone`、`nintendo_shop`、`google_play`、`app_store_ios`、`android_standalone`、`ios_standalone`、`android_other`、`ios_other`、`pc_other`。
                      enum:
                        - xsolla
                        - playstation_network
                        - xbox_live
                        - pc_standalone
                        - nintendo_shop
                        - google_play
                        - app_store_ios
                        - android_standalone
                        - ios_standalone
                        - android_other
                        - ios_other
                        - pc_other
                      nullable: true
                      type: string
                    promocodes:
                      description: 应用的促销码。如未应用促销码，则不会返回该数组。
                      items:
                        properties:
                          code:
                            description: 应用的促销码的代码。
                            type: string
                          external_id:
                            description: 外部ID。
                            type: string
                        type: object
                      type: array
                    promotions:
                      $ref: '#/components/schemas/order.promotions'
                    status:
                      description: 订单状态。
                      type: string
                  required:
                    - id
                    - mode
                    - currency_type
                    - currency
                    - amount
                    - status
                    - platform
                    - comment
                    - invoice_id
                    - promotions
                  type: object
                user:
                  description: 用户信息。
                  properties:
                    country:
                      $ref: '#/components/schemas/user.country'
                    email:
                      description: 用户邮箱地址。
                      type: string
                    external_id:
                      description: 用户ID。
                      type: string
                  required:
                    - external_id
                    - email
                  type: object
              required:
                - notification_type
                - items
                - order
                - user
      responses:
        '200':
          description: 返回以指示处理成功。
        '400':
          description: 提供的信息出错时返回（例如，缺少必需的参数、授权失败等）。
      summary: 订单取消（不包含付款和交易详情）
      tags:
        - separate-webhooks
      x-codeSamples:
        - label: CURL
          lang: cURL
          source: >-
            curl -v 'https://your.hostname/your/uri' \

            -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"
                }

            }'
        - label: HTTP
          lang: 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"
                }
            }
  partial-refund:
    post:
      description: >
        进行部分退款后，艾克索拉向Webhook 

        URL发送一个`partial_refund`类型的Webhook并在其中包含已取消交易的详细信息。有关部分退款流程的详细信息请参阅这些[说明](/zh/doc/pay-station/features/refund/#pay_station_features_refund_how_it_works_partial_refund_flow)。


        在发布商帐户中保存 Webhook URL 时，可以授予在 Webhook 中接收详细信息的权限。为此，请在发布商帐户的<a 

        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/store">项目设置
        &gt; 

        Webhooks&gt; 高级设置</a>部分中将以下开关设置为打开状态。


        <div class="note">

        <p><strong>注：</strong></p>

        <p>如果是在2025年1月22日或之前注册的发布商帐户，可在<a
        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/payments">项目设置&gt;
        Webhooks&gt; 测试 &gt; 付款&gt; 高级设置</a> 部分中找到这些开关。</p>

        </div>


        <table>

        <thead>
            <tr>
                <th>开关</th>
                <th>描述</th>
            </tr>
        </thead>

        <tbody>
            <tr>
                <td>显示通过保存的支付方式进行的交易的信息</td>
                <td><p>信息在Webhook的以下自定义参数中传递：</p><ul><li><code>saved_payment_method</code>:<ul><li><code>0</code> — 未使用保存的支付方式</li><li><code>1</code> — 进行当前付款时保存了支付方式</li><li><code>2</code> — 使用了之前保存的支付方式</li></ul></li><li><code>payment_type</code>:<ul><li><code>1</code> — 一次性支付</li><li><code>2</code> — 定期支付</li></ul></li></ul></td>
            </tr>
        </tbody>

        </table>


        退款代码：


        <table>
            <thead>
            <tr>
                <th>代码</th>
                <th>退款理由</th>
                <th>描述</th>
            </tr>
            </thead>
            <tbody>
            <tr>
                <td>1</td>
                <td>Cancellation by the user request / the game request</td>
                <td>用于在发布商帐户中发起取消的情况。</td>
            </tr>
            <tr>
                <td>3</td>
                <td>Integration error</td>
                <td>用于艾克索拉与游戏之间存在集成问题的情况。<br /><b>这种情况下，我们不建议将用户列入黑名单。</b></td>
            </tr>
            <tr>
                <td>5</td>
                <td>Test payment</td>
                <td>用于测试交易然后取消的情况。<br /><b>这种情况下，我们不建议将用户列入黑名单。</b></td>
            </tr>
            <tr>
                <td>7</td>
                <td>Fraud notification from PS</td>
                <td>支付被支付系统拒绝。 支付系统检测到潜在欺诈行为。<br /><b>建议：将该用户添加到黑名单。</b></td>
            </tr>
            <tr>
                <td>9</td>
                <td>Cancellation by the user request</td>
                <td>用于用户请求取消的情况。可能出于某些原因导致用户对游戏或购买产生不满的情况下发生。<br /><b>这种情况下，我们不建议将用户列入黑名单。</b></td>
            </tr>
            <tr>
                <td>10</td>
                <td>Cancellation by the game request</td>
                <td>用于游戏请求取消的情况。<br /><b>这种情况下，我们不建议将用户列入黑名单。</b></td>
            </tr>
            </tbody>
        </table>
      operationId: partial-refund
      requestBody:
        content:
          application/json:
            schema:
              properties:
                custom_parameters:
                  description: 您的自定义参数。
                  type: object
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                payment_details:
                  description: 带有支付详细信息的对象。
                  properties:
                    direct_wht:
                      description: 直接预扣税。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                        percent:
                          description: 直接预扣税税率。
                          format: float
                          type: number
                      type: object
                    payment:
                      description: 带有用户支付相关数据的对象。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    payment_method_fee:
                      description: 支付系统佣金的大小。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    payment_method_sum:
                      description: 带有通过支付方式收费的金额相关数据的对象。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    payout:
                      description: 带有支出详细信息的对象。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    payout_currency_rate:
                      description: 从支付币种到支出币种的汇率。
                      type: string
                    repatriation_commission:
                      description: 包含汇回本国费用数据的对象，该费用是第三方对艾克索拉收取的费用。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    sales_tax:
                      description: 销售税（对象；仅适用于美国和加拿大）。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                        percent:
                          description: 销售税税率。
                          format: float
                          type: number
                      type: object
                    vat:
                      description: 增值税大小（仅适用于欧盟）。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                        percent:
                          description: VAT税率。
                          format: float
                          type: number
                      type: object
                    xsolla_balance_sum:
                      description: 计入艾克索拉余额的金额。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    xsolla_fee:
                      description: 艾克索拉费用（对象）。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                  type: object
                purchase:
                  description: 带有购买相关数据的对象。
                  properties:
                    checkout:
                      description: 带有结账参数相关数据的对象。
                      properties:
                        amount:
                          description: 购买金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    total:
                      description: 带有总购买价格相关数据的对象。
                      properties:
                        amount:
                          description: 部分退款支付金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                  required:
                    - total
                  type: object
                refund_details:
                  description: 退款详情（对象）。
                  properties:
                    author:
                      description: |
                        退款发起人。根据下表传入字段值：

                        <table>
                            <thead>
                            <tr>
                                <th>退款发起人</th>
                                <th>字段值</th>
                            </tr>
                            </thead>
                            <tbody>
                            <tr>
                                <td>游戏（通过API）。</td>
                                <td>API</td>
                            </tr>
                            <tr>
                                <td>发布商帐户用户（自动退款）。</td>
                                <td>用户邮箱</td>
                            </tr>
                            <tr>
                                <td>发布商帐户用户（通过艾克索拉客户支持的帮助）。</td>
                                <td>support@xsolla.com</td>
                            </tr>
                            <tr>
                                <td>艾克索拉（通过艾克索拉客户支持的帮助）。</td>
                                <td>support@xsolla.com</td>
                            </tr>
                            </tbody>
                        </table>
                      type: string
                    code:
                      description: 代码ID。
                      type: integer
                    date:
                      description: 退款日期。
                      type: string
                    reason:
                      description: 退款原因。
                      type: string
                  type: object
                settings:
                  description: 带有自定义项目设置的对象。
                  properties:
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                  type: object
                transaction:
                  description: 交易ID。
                  properties:
                    agreement:
                      description: 协议ID。
                      type: integer
                    date:
                      description: 交易日期。
                      type: string
                    dry_run:
                      description: 测试交易。如为测试交易，该参数的值为1；如为真实交易，则不会发送该参数。
                      type: integer
                    external_id:
                      description: 交易外部ID。
                      type: string
                    id:
                      description: 交易ID。
                      type: integer
                  type: object
                user:
                  description: 用户详情（对象）。
                  properties:
                    country:
                      $ref: '#/components/schemas/user.country'
                    email:
                      $ref: '#/components/schemas/user.email'
                    id:
                      $ref: '#/components/schemas/user.id'
                    ip:
                      $ref: '#/components/schemas/user.ip'
                    name:
                      $ref: '#/components/schemas/user.name'
                    phone:
                      $ref: '#/components/schemas/user.phone'
                    zip:
                      $ref: '#/components/schemas/user.zip'
                  required:
                    - id
                  type: object
              required:
                - notification_type
                - transaction
                - payment_details
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      summary: 部分退款
      tags:
        - payments
      x-codeSamples:
        - label: CURL
          lang: cURL
          source: |-
            curl -v 'https://your.hostname/your/uri' \
            -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
                        }
                    }
                }
            }'
        - label: PHP
          lang: 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
                    )
                )
            );
        - label: HTTP
          lang: 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:
    post:
      description: >
        当用户完成付款时，艾克索拉会向Webhook URL发送一个包含付款详细信息的`payment`类型的Webhook。


        预期响应代码的说明见<b>Responses</b> 部分，您也可以使用其他响应代码：


        <table>
            <thead>
            <tr>
                <th>响应代码</th>
                <th>描述</th>
            </tr>
            </thead>
            <tbody>
            <tr>
                <td><code>200</code>、<code>201</code>、<code>204</code></td>
                <td>成功的响应。</td>
            </tr>
            <tr>
                <td><code>4xx</code></td>
                <td>发生错误。例如，如果未找到指定的用户或传递了无效的签名。</td>
            </tr>
            <tr>
                <td><code>5xx</code></td>
                <td>服务器临时错误。收到此响应后，艾克索拉将自动重试发送Webhook，并逐渐增加尝试间隔，直到监听器确认接收。48小时内最多可重试12次。</td>
            </tr>
            </tbody>
        </table>


        在<a 

        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/store">发布商帐户</a>中保

        存Webhook URL时，还可以设置在Webhook中接收额外信息。


        <div class="note">

        <p><strong>注：</strong></p>

        <p>如果是在2025年1月22日或之前注册的发布商帐户，可在项目的<a
        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/payments">设置&gt;
        Webhooks&gt; 测试 &gt; 付款&gt; 高级设置</a>部分中找到这些开关。</p>

        </div>


        <table>

        <thead>
            <tr>
                <th>开关</th>
                <th>描述</th>
            </tr>
        </thead>

        <tbody>
            <tr>
                <td>显示保存的支付帐户的信息</td>
                <td>有关保存的支付方式的信息在<code>payment_account</code>自定义对象中传递。</td>
            </tr>
            <tr>
                <td>显示通过保存的支付方式进行的交易的信息</td>
                <td><p>信息在Webhook的以下自定义参数中传递：</p><ul><li><code>saved_payment_method</code>:<ul><li><code>0</code> — 未使用保存的支付方式</li><li><code>1</code> — 进行当前付款时保存了支付方式</li><li><code>2</code> — 使用了之前保存的支付方式</li></ul></li><li><code>payment_type</code>:<ul><li><code>1</code> — 一次性支付</li><li><code>2</code> — 定期支付</li></ul></li></ul></td>
            </tr>
            <tr>
                <td>将订单对象添加到Webhook</td>
                <td>有关订单的信息在<a href="/zh/webhooks/operation/payment/">支付</a>Webhook的<code>order</code>对象中传递。</td>
            </tr>
            <tr>
                <td>仅发送不含敏感数据的必要用户参数</td>
                <td><p>Webhook中仅传递用户的以下信息：</p><ul><li>ID</li><li>国家/地区</li></ul></td>
            </tr>
            <tr>
                <td>显示银行卡BIN和后缀码</td>
                <td><p>Webhook中传递以下银行卡号的信息：</p><ul><li><code>card_bin</code>参数中的前6位数字</li><li><code>card_suffix</code>中的后4位数字</li></ul></td>
            </tr>
            <tr>
                <td>显示银行卡品牌</td>
                <td>用于付款的银行卡的品牌。例如，Mastercard或Visa。</td>
            </tr>
        </tbody>

        </table>


        <div class="notice">

        <p><strong>注意</strong></p>

        <p>Webhook中发送的字段集取决于：<ul><li>在发布商帐户中配置的高级设置</li><li>在艾克索拉侧配置的自定义设置</li></ul></p><p>如果您有任何疑问，请联系您的客户成功经理或发送电子邮件至<a
        href="mailto:csm@xsolla.com">csm@xsolla.com</a>。</p>

        </div>
      operationId: payment
      requestBody:
        content:
          application/json:
            schema:
              properties:
                custom_parameters:
                  description: 您的自定义参数。
                  type: object
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                payment_details:
                  description: 带有支付详细信息的对象。
                  properties:
                    country_wht:
                      description: 跨境交易在特定国家/地区收取的预扣税（对象）。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                        percent:
                          description: 国家/地区预扣税税率(%)。
                          format: float
                          type: number
                      type: object
                    direct_wht:
                      description: 直接预扣税。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                        percent:
                          description: 直接预扣税税率。
                          format: float
                          type: number
                      type: object
                    payment:
                      description: 带有用户支付相关数据的对象。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    payment_method_fee:
                      description: 支付系统佣金的大小。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    payment_method_sum:
                      description: 带有通过支付方式收费的金额相关数据的对象。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    payout:
                      description: 带有支出详细信息的对象。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    payout_currency_rate:
                      description: 从支付币种到支出币种的汇率。
                      type: string
                    repatriation_commission:
                      description: 包含汇回本国费用数据的对象，该费用是第三方对艾克索拉收取的费用。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    sales_tax:
                      description: 销售税（对象；仅适用于美国和加拿大）。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                        percent:
                          description: 销售税税率。
                          format: float
                          type: number
                      type: object
                    user_acquisition_fee:
                      description: 从通过联盟网络和圈内达人完成的购买中扣除的用户获取费用总额（对象）。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                        percent:
                          description: 用户获取费费率(%)。
                          format: float
                          type: number
                      type: object
                    vat:
                      description: 增值税大小（仅适用于欧盟）。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                        percent:
                          description: VAT税率。
                          format: float
                          type: number
                      type: object
                    xsolla_balance_sum:
                      description: 计入艾克索拉余额的金额。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    xsolla_fee:
                      description: 艾克索拉费用（对象）。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                  type: object
                purchase:
                  description: 带有购买相关数据的对象。
                  properties:
                    checkout:
                      description: 带有结账参数相关数据的对象。
                      properties:
                        amount:
                          description: 购买金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    coupon:
                      description: 带有优惠券相关数据的对象（如果此交易使用了优惠券）。
                      properties:
                        campaign_code:
                          description: 优惠券营销活动的代码。
                          type: string
                        coupon_code:
                          description: 优惠券代码。
                          type: string
                      type: object
                    gift:
                      description: 礼物详情（对象）。
                      properties:
                        giver_id:
                          description: 送礼人ID。
                          type: string
                        hide_giver_from_receiver:
                          description: 是否对收礼人隐藏送礼人的身份信息。
                          type: string
                        message:
                          description: 送礼人留言。
                          type: string
                        receiver_email:
                          description: 收礼人邮箱。
                          type: string
                        receiver_id:
                          description: 收礼人ID。
                          type: string
                      type: object
                    order:
                      $ref: '#/components/schemas/order'
                      properties:
                        id:
                          description: 订单ID。
                          type: integer
                        lineitems:
                          description: 包含商品信息的参数数组。
                          items:
                            properties:
                              price:
                                description: 包含商品价格信息的对象。
                                properties:
                                  amount:
                                    description: 商品在所选货币下的总价。
                                    format: float
                                    type: number
                                  currency:
                                    description: 商品价格的货币单位。
                                    type: string
                                type: object
                              quantity:
                                description: 商品数量。
                                type: integer
                              sku:
                                description: 商品SKU。
                                type: string
                            type: object
                          type: array
                    promotions:
                      description: 应用于此交易的促销活动。
                      items:
                        properties:
                          id:
                            description: 促销活动 ID。
                            type: integer
                          technical_name:
                            description: 促销活动的技术名称。
                            type: string
                        type: object
                      type: array
                    subscription:
                      description: 订阅详情（对象）。
                      properties:
                        amount:
                          $ref: '#/components/schemas/amount-float'
                        currency:
                          $ref: '#/components/schemas/currency'
                        date_create:
                          $ref: '#/components/schemas/subscription.date_create'
                        date_next_charge:
                          description: >-
                            下次收费的日期。符合[ISO
                            8601](https://en.wikipedia.org/wiki/ISO_8601)标准规定的日期与时间。
                          type: string
                        plan_id:
                          $ref: '#/components/schemas/subscription.plan_id'
                        product_id:
                          description: 产品ID（如果在访问令牌中发送）。
                          type: string
                        subscription_id:
                          $ref: '#/components/schemas/subscription.subscription_id'
                        tags:
                          $ref: '#/components/schemas/subscription.tags'
                      type: object
                    total:
                      description: 带有总购买价格相关数据的对象。
                      properties:
                        amount:
                          description: 总购买金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                  required:
                    - total
                  type: object
                settings:
                  description: 带有自定义项目设置的对象。
                  properties:
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                  type: object
                transaction:
                  description: 交易ID。
                  properties:
                    agreement:
                      description: 协议ID。
                      type: integer
                    dry_run:
                      description: 测试交易。如为测试交易，该参数的值为1；如为真实交易，则不会发送该参数。
                      type: integer
                    external_id:
                      $ref: '#/components/schemas/external-id'
                    id:
                      description: 交易ID。
                      type: integer
                    payment_date:
                      description: 付款日期。
                      type: string
                    payment_method:
                      description: 付款方式ID。
                      type: integer
                    payment_method_name:
                      description: 付款方式名称。
                      type: string
                    payment_method_order_id:
                      description: 支付系统中的付款ID。
                      type: string
                  type: object
                user:
                  description: 用户详情（对象）。
                  properties:
                    country:
                      $ref: '#/components/schemas/user.country'
                    email:
                      $ref: '#/components/schemas/user.email'
                    id:
                      $ref: '#/components/schemas/user.id'
                    ip:
                      $ref: '#/components/schemas/user.ip'
                    name:
                      $ref: '#/components/schemas/user.name'
                    phone:
                      $ref: '#/components/schemas/user.phone'
                    zip:
                      $ref: '#/components/schemas/user.zip'
                  required:
                    - id
                  type: object
              required:
                - notification_type
                - transaction
                - payment_details
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400-payment'
        '500':
          $ref: '#/components/responses/500'
      summary: 支付
      tags:
        - payments
      x-codeSamples:
        - label: CURL
          lang: 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"
                }
            }'
        - label: PHP
          lang: 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
                    )
                )
            );
        - label: HTTP
          lang: 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"
                }
            }
  payment-declined:
    post:
      description: >
        当支付系统拒绝交易时，艾克索拉会将交易详情通过`ps_declined`类型的Webhook发送至您配置的Webhook 

        URL。该Webhook在授权或支付处理阶段发送。此情况下，不会发送[payment](/zh/webhooks/operation/payment/)\ 

        [order_paid](/zh/webhooks/operation/successful-order-payment/) Webhook。


        支付系统拒绝的常见原因：


        * 卡片授权失败（例如，支付系统因技术错误或银行无响应而无法完成授权流程）或被拒（例如，银行已响应但因资金不足或卡片信息无效而拒绝交易）。

        * 3-D Secure验证失败、未完成或用户确认超时。

        * 处理方或收单银行暂时不可用，或因不可逆转的错误（如账户已关闭或卡号无效）而强制拒绝。在不解决根本问题的情况下重试将无法成功完成交易。


        不应与以下情况混淆：


        *
        反欺诈拒绝，这类情况通过[afs_reject](https://developers.xsolla.com/zh/webhooks/operation/afs-rejected-transaction/)
        Webhook报告。

        *
        成功支付后的退款和部分退款，这类情况通过[refund](https://developers.xsolla.com/zh/webhooks/operation/refund/)和[partial_refund](https://developers.xsolla.com/zh/webhooks/operation/partial-refund/)
        webhook报告。


        <div class="note">

        <p><strong>注意</strong></p>

        <p>如需接收<code>ps_declined</code> Webhook，请联系您的客户成功经理或发送邮件至<a
        href="mailto:csm@xsolla.com">csm@xsolla.com</a>。</p>

        </div>
      operationId: payment-declined
      requestBody:
        content:
          application/json:
            schema:
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                refund_details:
                  description: 退款详情（对象）。
                  properties:
                    author:
                      description: |
                        退款发起人。根据下表传入字段值：

                        <table>
                            <thead>
                            <tr>
                                <th>退款发起人</th>
                                <th>字段值</th>
                            </tr>
                            </thead>
                            <tbody>
                            <tr>
                                <td>游戏（通过API）。</td>
                                <td>API</td>
                            </tr>
                            <tr>
                                <td>发布商帐户用户（自动退款）。</td>
                                <td>用户邮箱</td>
                            </tr>
                            <tr>
                                <td>发布商帐户用户（通过艾克索拉客户支持的帮助）。</td>
                                <td>support@xsolla.com</td>
                            </tr>
                            <tr>
                                <td>艾克索拉（通过艾克索拉客户支持的帮助）。</td>
                                <td>support@xsolla.com</td>
                            </tr>
                            </tbody>
                        </table>
                      type: string
                    code:
                      description: 代码ID。
                      type: integer
                    reason:
                      description: 退款原因。
                      type: string
                  type: object
                settings:
                  description: 带有自定义项目设置的对象。
                  properties:
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                  type: object
                transaction:
                  description: 交易ID。
                  properties:
                    dry_run:
                      description: 测试交易。如为测试交易，该参数的值为1；如为真实交易，则不会发送该参数。
                      type: integer
                    external_id:
                      description: 交易外部ID。
                      type: string
                    id:
                      description: 交易ID。
                      type: integer
                    payment_method:
                      description: 付款方式ID。
                      type: integer
                  type: object
                user:
                  description: 用户详情（对象）。
                  properties:
                    country:
                      $ref: '#/components/schemas/user.country'
                    email:
                      $ref: '#/components/schemas/user.email'
                    id:
                      $ref: '#/components/schemas/user.id'
                    ip:
                      $ref: '#/components/schemas/user.ip'
                    name:
                      $ref: '#/components/schemas/user.name'
                  required:
                    - id
                  type: object
              required:
                - notification_type
                - transaction
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400-payment'
        '500':
          $ref: '#/components/responses/500'
      summary: 付款被拒
      tags:
        - payments
      x-codeSamples:
        - label: CURL
          lang: cURL
          source: >-
            curl -v 'https://your.hostname/your/uri' \

            -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"
              }
            }'
        - label: PHP
          lang: 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',
              ),
            );
        - label: HTTP
          lang: 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"
              }
            }
  personalized-partner-catalog:
    post:
      description: >
        当用户与商店交互时，艾克索拉会将包含用户和项目参数的<code>partner_side_catalog</code>
        webhook发送到webhook 

        URL。


        返回适用于该用户的<code>item_id</code>或商品SKU的列表。您也可以在其中包含指定用户对指定商品的可购买次数的信息。此功能允许您控制用户可添加

        到购物车及可购买的商品种类和次数。


        建议<code>partner_side_catalog</code> webhook的处理时间小于3秒。
      operationId: personalized-partner-catalog
      requestBody:
        content:
          application/json:
            schema:
              properties:
                user:
                  description: 用户详情（对象）。
                  properties:
                    country:
                      $ref: '#/components/schemas/user.country'
                    currency:
                      $ref: '#/components/schemas/currency'
                    locale:
                      $ref: '#/components/schemas/locale'
                    user_id:
                      description: 用户ID。如果用户未认证身份，则发送值`null`。
                      type: string
                  required:
                    - user_id
                  type: object
              required:
                - user
      responses:
        '200':
          content:
            application/json:
              example:
                - date_from: '2024-08-11T23:59:59+08:00'
                  date_until: '2024-08-12T23:59:59+08:00'
                  quantity: 0
                  sku: com.xsolla.boots_1
                - date_from: '2024-08-11T23:59:59+08:00'
                  date_until: '2024-08-12T23:59:59+08:00'
                  quantity: null
                  sku: com.xsolla.sword_1
                - quantity: 1
                  sku: com.xsolla.helmet_1
                - content:
                    - description: Description of custom content item
                      image_url: https://example.com/content_image.png
                      name: Custom content item
                      quantity: 5
                  description: Custom description
                  image_url: https://example.com/image.png
                  json_attributes:
                    purchased: 0
                    type: lootbox
                  name: Custom name
                  quantity: null
                  sku: com.xsolla.custom_item_1
                - available: 7
                  sku: com.xsolla.limited_item_1
                  total: 10
              schema:
                items:
                  anyOf:
                    - oneOf:
                        - properties:
                            quantity:
                              $ref: '#/components/schemas/quantity'
                          title: quantity
                        - properties:
                            available:
                              $ref: '#/components/schemas/available'
                            total:
                              $ref: '#/components/schemas/total'
                          title: available
                      properties:
                        content:
                          $ref: '#/components/schemas/bundle_content'
                        date_from:
                          $ref: '#/components/schemas/date_from'
                        date_until:
                          $ref: '#/components/schemas/date_until'
                        description:
                          $ref: '#/components/schemas/description'
                        image_url:
                          $ref: '#/components/schemas/image_url'
                        json_attributes:
                          $ref: '#/components/schemas/json_attributes'
                        name:
                          $ref: '#/components/schemas/name'
                        sku:
                          $ref: '#/components/schemas/sku'
                      required:
                        - sku
                      title: sku
                    - oneOf:
                        - properties:
                            quantity:
                              $ref: '#/components/schemas/quantity'
                          title: quantity
                        - properties:
                            available:
                              $ref: '#/components/schemas/available'
                            total:
                              $ref: '#/components/schemas/total'
                          title: available
                      properties:
                        content:
                          $ref: '#/components/schemas/bundle_content'
                        date_from:
                          $ref: '#/components/schemas/date_from'
                        date_until:
                          $ref: '#/components/schemas/date_until'
                        description:
                          $ref: '#/components/schemas/description'
                        image_url:
                          $ref: '#/components/schemas/image_url'
                        item_id:
                          $ref: '#/components/schemas/item_id'
                        json_attributes:
                          $ref: '#/components/schemas/json_attributes'
                        name:
                          $ref: '#/components/schemas/name'
                      required:
                        - item_id
                      title: item_id
                  type: object
                type: array
          description: 返回对该用户可用的商品列表以及特定用户可以购买特定商品的次数。
        '404':
          description: 找不到用户。
      summary: 合作伙伴侧的目录个性化
      tags:
        - personalization
      x-codeSamples:
        - label: CURL
          lang: 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"
                    }
                }'
        - label: HTTP
          lang: 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"
                }
            }
  refund:
    post:
      description: >
        当支付取消时，艾克索拉会向Webhook URL发送带有`refund`类型的Webhook，其中包含已取消交易的详细信息。


        Webhook重试机制取决于退款发起方：

        * 若退款由您方发起，系统不会重新发送Webhook。无论对Webhook的响应如何，款项都将退还给用户。

        *
        若退款由第三方发起（如支付系统或艾克索拉客户支持团队），且Webhook响应返回`5xx`状态码，系统会按递增间隔重新发送Webhook。最多重试12次，时间范
          围为首次尝试后的48小时内。

        有关退款流程的详细信息，请参阅相关[说明](/zh/doc/pay-station/features/refund/)。


        <div class="notice">

        <p><strong>注意</strong></p>

        <p>如满足以下所有条件，款项仍将退还给用户：<ul><li>退款由艾克索拉发起。</li><li>Webhook响应返回<code>4xx</code>状态码，或在所有重试后未收到响应，或返回<code>5xx</code>状态码。</li></ul></p>

        </div>


        在<a 

        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/store">发布商帐户</a>中保

        存Webhook URL时，还可以设置在Webhook中接收额外信息。


        <div class="note">

        <p><strong>注：</strong></p>

        <p>如果是在2025年1月22日或之前注册的发布商帐户，可在项目的<a
        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/payments">设置&gt;
        Webhooks&gt; 测试 &gt; 付款&gt; 高级设置</a>部分中找到这些开关。</p>

        </div>


        <table>

        <thead>
            <tr>
                <th>开关</th>
                <th>描述</th>
            </tr>
        </thead>

        <tbody>
            <tr>
                <td>显示通过保存的支付方式进行的交易的信息</td>
                <td><p>信息在Webhook的以下自定义参数中传递：</p><ul><li><code>saved_payment_method</code>:<ul><li><code>0</code> — 未使用保存的支付方式</li><li><code>1</code> — 进行当前付款时保存了支付方式</li><li><code>2</code> — 使用了之前保存的支付方式</li></ul></li><li><code>payment_type</code>:<ul><li><code>1</code> — 一次性支付</li><li><code>2</code> — 定期支付</li></ul></li></ul></td>
            </tr>
        </tbody>

        </table>


        退款代码：


        <table>
            <thead>
            <tr>
                <th>代码</th>
                <th>退款理由</th>
                <th>描述</th>
            </tr>
            </thead>
            <tbody>
            <tr>
                <td>1</td>
                <td>Cancellation by the user request / the game request</td>
                <td>用于在发布商帐户中发起取消的情况。</td>
            </tr>
            <tr>
                <td>2</td>
                <td>Chargeback</td>
                <td>交易存在退单的情况。</td>
            </tr>
            <tr>
                <td>3</td>
                <td>Integration error</td>
                <td>用于艾克索拉与游戏之间存在集成问题的情况。<br /><b>这种情况下，我们不建议将用户列入黑名单。</b></td>
            </tr>
            <tr>
                <td>4</td>
                <td>Potential fraud</td>
                <td>存在欺诈嫌疑。<br /><b>建议：将该用户添加到黑名单。</b></td>
            </tr>
            <tr>
                <td>5</td>
                <td>Test payment</td>
                <td>用于测试交易然后取消的情况。<br /><b>这种情况下，我们不建议将用户列入黑名单。</b></td>
            </tr>
            <tr>
                <td>6</td>
                <td>User invoice expired</td>
                <td>用于通过用后付费模式的支付系统进行交易的情况。</td>
            </tr>
            <tr>
                <td>7</td>
                <td>Fraud notification from PS</td>
                <td>支付被支付系统拒绝。 支付系统检测到潜在欺诈行为。<br /><b>建议：将该用户添加到黑名单。</b></td>
            </tr>
            <tr>
                <td>8</td>
                <td>Cancellation by the PS request</td>
                <td>用于支付系统请求取消的情况。<br /><b>这种情况下，我们不建议将用户列入黑名单。</b></td>
            </tr>
            <tr>
                <td>9</td>
                <td>Cancellation by the user request</td>
                <td>用于用户请求取消的情况。可能出于某些原因导致用户对游戏或购买产生不满的情况下发生。<br /><b>这种情况下，我们不建议将用户列入黑名单。</b></td>
            </tr>
            <tr>
                <td>10</td>
                <td>Cancellation by the game request</td>
                <td>用于游戏请求取消的情况。<br /><b>这种情况下，我们不建议将用户列入黑名单。</b></td>
            </tr>
            <tr>
                <td>11</td>
                <td>Account holder called to report fraud</td>
                <td>用于账户持有人通知我们其未进行此交易的情况。</td>
            </tr>
            <tr>
                <td>12</td>
                <td>Friendly fraud</td>
                <td>用于接收到友好型欺诈相关消息的情况。</td>
            </tr>
            <tr>
                <td>13</td>
                <td>Duplicate</td>
                <td>有同一张发票的重复交易。</td>
            </tr>
            </tbody>
        </table>
      operationId: refund
      requestBody:
        content:
          application/json:
            schema:
              properties:
                custom_parameters:
                  description: 您的自定义参数。
                  type: object
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                payment_details:
                  description: 带有支付详细信息的对象。
                  properties:
                    country_wht:
                      description: 跨境交易在特定国家/地区收取的预扣税（对象）。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                        percent:
                          description: 国家/地区预扣税税率(%)。
                          format: float
                          type: number
                      type: object
                    direct_wht:
                      description: 直接预扣税。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                        percent:
                          description: 直接预扣税税率。
                          format: float
                          type: number
                      type: object
                    payment:
                      description: 带有用户支付相关数据的对象。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    payment_method_fee:
                      description: 支付系统佣金的大小。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    payment_method_sum:
                      description: 带有通过支付方式收费的金额相关数据的对象。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    payout:
                      description: 带有支出详细信息的对象。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    payout_currency_rate:
                      description: 从支付币种到支出币种的汇率。
                      type: string
                    repatriation_commission:
                      description: 包含汇回本国费用数据的对象，该费用是第三方对艾克索拉收取的费用。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    sales_tax:
                      description: 销售税（对象；仅适用于美国和加拿大）。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                        percent:
                          description: 销售税税率。
                          format: float
                          type: number
                      type: object
                    user_acquisition_fee:
                      description: 从通过联盟网络和圈内达人完成的购买中扣除的用户获取费用总额（对象）。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                        percent:
                          description: 用户获取费费率(%)。
                          format: float
                          type: number
                      type: object
                    vat:
                      description: 增值税大小（仅适用于欧盟）。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                        percent:
                          description: VAT税率。
                          format: float
                          type: number
                      type: object
                    xsolla_balance_sum:
                      description: 计入艾克索拉余额的金额。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    xsolla_fee:
                      description: 艾克索拉费用（对象）。
                      properties:
                        amount:
                          description: 金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                  type: object
                purchase:
                  description: 带有购买相关数据的对象。
                  properties:
                    checkout:
                      description: 带有结账参数相关数据的对象。
                      properties:
                        amount:
                          description: 购买金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                    subscription:
                      description: 订阅详情（对象）。
                      properties:
                        amount:
                          $ref: '#/components/schemas/amount-float'
                        currency:
                          $ref: '#/components/schemas/currency'
                        date_create:
                          $ref: '#/components/schemas/subscription.date_create'
                        plan_id:
                          $ref: '#/components/schemas/subscription.plan_id'
                        subscription_id:
                          $ref: '#/components/schemas/subscription.subscription_id'
                        tags:
                          $ref: '#/components/schemas/subscription.tags'
                      type: object
                    total:
                      description: 带有总购买价格相关数据的对象。
                      properties:
                        amount:
                          description: 总购买金额。
                          format: float
                          type: number
                        currency:
                          $ref: '#/components/schemas/currency'
                      type: object
                  required:
                    - total
                  type: object
                refund_details:
                  description: 退款详情（对象）。
                  properties:
                    author:
                      description: |
                        退款发起人。根据下表传入字段值：

                        <table>
                            <thead>
                            <tr>
                                <th>退款发起人</th>
                                <th>字段值</th>
                            </tr>
                            </thead>
                            <tbody>
                            <tr>
                                <td>游戏（通过API）。</td>
                                <td>API</td>
                            </tr>
                            <tr>
                                <td>发布商帐户用户（自动退款）。</td>
                                <td>用户邮箱</td>
                            </tr>
                            <tr>
                                <td>发布商帐户用户（通过艾克索拉客户支持的帮助）。</td>
                                <td>support@xsolla.com</td>
                            </tr>
                            <tr>
                                <td>艾克索拉（通过艾克索拉客户支持的帮助）。</td>
                                <td>support@xsolla.com</td>
                            </tr>
                            </tbody>
                        </table>
                      type: string
                    code:
                      description: 代码ID。
                      type: integer
                    reason:
                      description: 退款原因。
                      type: string
                  type: object
                settings:
                  description: 带有自定义项目设置的对象。
                  properties:
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                  type: object
                transaction:
                  description: 交易ID。
                  properties:
                    agreement:
                      description: 协议ID。
                      type: integer
                    dry_run:
                      description: 测试交易。如为测试交易，该参数的值为1；如为真实交易，则不会发送该参数。
                      type: integer
                    external_id:
                      description: 交易外部ID。
                      type: string
                    id:
                      description: 交易ID。
                      type: integer
                    payment_method_order_id:
                      description: 支付系统中的付款ID。
                      type: string
                  type: object
                user:
                  description: 用户详情（对象）。
                  properties:
                    country:
                      $ref: '#/components/schemas/user.country'
                    email:
                      $ref: '#/components/schemas/user.email'
                    id:
                      $ref: '#/components/schemas/user.id'
                    ip:
                      $ref: '#/components/schemas/user.ip'
                    name:
                      $ref: '#/components/schemas/user.name'
                    phone:
                      $ref: '#/components/schemas/user.phone'
                    zip:
                      $ref: '#/components/schemas/user.zip'
                  required:
                    - id
                  type: object
              required:
                - notification_type
                - transaction
                - payment_details
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      summary: 退款
      tags:
        - payments
      x-codeSamples:
        - label: CURL
          lang: cURL
          source: |-
            curl -v 'https://your.hostname/your/uri' \
            -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
                        }
                    }
                }
            }'
        - label: PHP
          lang: 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
                    )
                )
            );
        - label: HTTP
          lang: 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
                    }
                }
            }
  remove-payment-account:
    post:
      description: >-
        用户从保存的支付帐户中删除支付帐户时，艾克索拉会向Webhook
        URL发送一个`payment_account_remove`类型的Webhook。要接收该Webhook，请联系您的客户成功经理或发送电子邮件至<a
        href="mailto:csm@xsolla.com">csm@xsolla.com</a>。
      operationId: remove-payment-account
      requestBody:
        content:
          application/json:
            schema:
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                payment_account:
                  description: 支付帐户详细信息（对象）。
                  properties:
                    id:
                      $ref: '#/components/schemas/payment_account.id'
                    name:
                      $ref: '#/components/schemas/payment_account.name'
                    payment_method:
                      $ref: '#/components/schemas/payment_account.payment_method'
                    type:
                      $ref: '#/components/schemas/payment_account.type'
                  required:
                    - id
                  type: object
                settings:
                  description: 带有自定义项目设置的对象。
                  properties:
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                  type: object
                user:
                  description: 用户详情（对象）。
                  properties:
                    email:
                      $ref: '#/components/schemas/user.email'
                    id:
                      $ref: '#/components/schemas/user.id'
                    name:
                      $ref: '#/components/schemas/user.name'
                  required:
                    - id
                  type: object
              required:
                - notification_type
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      summary: 删除支付帐户
      tags:
        - payments
      x-codeSamples:
        - label: CURL
          lang: cURL
          source: >-
            curl -v 'https://your.hostname/your/uri' \

            -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"
                }
            }'
        - label: HTTP
          lang: 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"
                }
            }
  successful-order-payment:
    post:
      description: >
        当用户订单支付成功时艾克索拉发送<code>order_paid</code> webhook到指定的URL。


        <code>order_paid</code> webhook包含所购商品、付款数据和交易详细信息。


        如果付款不成功，则不会发送<code>order_paid</code> webhook，例如：

        * 打开了支付表单，但用户没有为订单付款

        * 打开了支付表单，但付款过程中出现错误


        建议<code>order_paid</code> webhook的处理时间小于3秒。


        <div class="notice">

        <p><strong>注意</strong></p>

        <p>Webhook中发送的字段集取决于以下设置：<ul><li>您在发布商帐户<a
        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/store">项目设置
        &gt; Webhooks &gt;
        高级设置</a>部分中配置的设置</li><li>您在艾克索拉侧配置的设置</li></ul></p><p>如果您有任何疑问，请联系您的客户成功经理或发送电子邮件至<a
        href="mailto:csm@xsolla.com">csm@xsolla.com</a>。</p>

        </div>


        <b>响应</b>部分描述了预期的回答。您可以使用其他响应代码。根据响应码和自动退款功能的连接，艾克索拉侧的webhook处理逻辑如下：


        <table>
            <thead>
            <tr>
                <th>响应代码</th>
                <th>禁用了自动退款（默认）</th>
                <th>启用了自动退款</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>无操作</td>
                <td>自动退款给用户</td>
            </tr>
            <tr>
                <td><code>200</code>、<code>201</code>、<code>204</code></td>
                <td>无操作</td>
                <td>无操作</td>
            </tr>
            <tr>
                <td>不同代码或对webhook无响应</td>
                <td>在指定的时间间隔内发送多个webhook：2次间隔5分钟的尝试，7次间隔15分钟的尝试，10次间隔60分钟的尝试。</td>
                <td>在指定的时间间隔内发送多个webhook：2次间隔5分钟的尝试，7次间隔15分钟的尝试，10次间隔60分钟的尝试。如果发送了所有webhook后仍未收到成功响应，则会向用户自动退款。</td>
            </tr>
            </tbody>
        </table>


        要连接自动退款功能，请联系您的客户成功经理或发送电子邮件至csm@xsolla.com。
      operationId: successful-order-payment
      requestBody:
        content:
          application/json:
            schema:
              properties:
                billing:
                  description: 交易和付款详细信息。
                  properties:
                    notification_type:
                      $ref: '#/components/schemas/notification_type'
                    payment_details:
                      description: 带有支付详细信息的对象。
                      properties:
                        country_wht:
                          description: 跨境交易在特定国家/地区收取的预扣税（对象）。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                            percent:
                              description: 国家/地区预扣税税率(%)。
                              format: float
                              type: number
                          type: object
                        direct_wht:
                          description: 直接预扣税。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                            percent:
                              description: 直接预扣税税率。
                              format: float
                              type: number
                          type: object
                        payment:
                          description: 带有用户支付相关数据的对象。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                          type: object
                        payment_method_fee:
                          description: 支付系统佣金的大小。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                          type: object
                        payment_method_sum:
                          description: 带有通过支付方式收费的金额相关数据的对象。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                          type: object
                        payout:
                          description: 带有支出详细信息的对象。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                          type: object
                        payout_currency_rate:
                          description: 从支付币种到支出币种的汇率。
                          type: string
                        repatriation_commission:
                          description: 包含汇回本国费用数据的对象，该费用是第三方对艾克索拉收取的费用。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                          type: object
                        sales_tax:
                          description: 销售税（对象；仅适用于美国和加拿大）。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                            percent:
                              description: 销售税税率。
                              format: float
                              type: number
                          type: object
                        user_acquisition_fee:
                          description: 从通过联盟网络和圈内达人完成的购买中扣除的用户获取费用总额（对象）。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                            percent:
                              description: 用户获取费费率(%)。
                              format: float
                              type: number
                          type: object
                        vat:
                          description: 增值税大小（仅适用于欧盟）。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                            percent:
                              description: VAT税率。
                              format: float
                              type: number
                          type: object
                        xsolla_balance_sum:
                          description: 计入艾克索拉余额的金额。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                          type: object
                        xsolla_fee:
                          description: 艾克索拉费用（对象）。
                          properties:
                            amount:
                              description: 金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                          type: object
                      type: object
                    purchase:
                      description: 带有购买相关数据的对象。
                      properties:
                        coupon:
                          description: 带有优惠券相关数据的对象（如果此交易使用了优惠券）。
                          properties:
                            campaign_code:
                              description: 优惠券营销活动的代码。
                              type: string
                            coupon_code:
                              description: 优惠券代码。
                              type: string
                          type: object
                        gift:
                          description: 礼物详情（对象）。
                          properties:
                            giver_id:
                              description: 送礼人ID。
                              type: string
                            hide_giver_from_receiver:
                              description: 是否对收礼人隐藏送礼人的身份信息。
                              type: string
                            message:
                              description: 送礼人留言。
                              type: string
                            receiver_email:
                              description: 收礼人邮箱。
                              type: string
                            receiver_id:
                              description: 收礼人ID。
                              type: string
                          type: object
                        promotions:
                          description: 应用于此交易的促销活动。
                          items:
                            properties:
                              id:
                                description: 促销活动 ID。
                                type: integer
                              technical_name:
                                description: 促销活动的技术名称。
                                type: string
                            type: object
                          type: array
                        subscription:
                          description: 订阅详情（对象）。
                          properties:
                            amount:
                              $ref: '#/components/schemas/amount-float'
                            currency:
                              $ref: '#/components/schemas/currency'
                            date_create:
                              $ref: '#/components/schemas/subscription.date_create'
                            date_next_charge:
                              description: >-
                                下次收费的日期。符合[ISO
                                8601](https://en.wikipedia.org/wiki/ISO_8601)标准规定的日期与时间。
                              type: string
                            plan_id:
                              $ref: '#/components/schemas/subscription.plan_id'
                            product_id:
                              description: 产品ID（如果在访问令牌中发送）。
                              type: string
                            subscription_id:
                              $ref: >-
                                #/components/schemas/subscription.subscription_id
                            tags:
                              $ref: '#/components/schemas/subscription.tags'
                          type: object
                        total:
                          description: 带有总购买价格相关数据的对象。
                          properties:
                            amount:
                              description: 总购买金额。
                              format: float
                              type: number
                            currency:
                              $ref: '#/components/schemas/currency'
                          type: object
                      required:
                        - total
                      type: object
                    settings:
                      description: 带有自定义项目设置的对象。
                      properties:
                        merchant_id:
                          $ref: '#/components/schemas/settings.merchant_id'
                        project_id:
                          $ref: '#/components/schemas/settings.project_id'
                      type: object
                    transaction:
                      description: 交易ID。
                      properties:
                        agreement:
                          description: 协议ID。
                          type: integer
                        dry_run:
                          description: 测试交易。如为测试交易，该参数的值为1；如为真实交易，则不会发送该参数。
                          type: integer
                        external_id:
                          $ref: '#/components/schemas/external-id'
                        id:
                          description: 交易ID。
                          type: integer
                        payment_date:
                          description: 付款日期。
                          type: string
                        payment_method:
                          description: 付款方式ID。
                          type: integer
                        payment_method_name:
                          description: 付款方式名称。
                          type: string
                        payment_method_order_id:
                          description: 支付系统中的付款ID。
                          type: string
                      type: object
                  required:
                    - notification_type
                    - transaction
                    - payment_details
                  type: object
                custom_parameters:
                  description: 附加信息。
                  type: object
                items:
                  description: >
                    用户所购商品的列表。


                    数组中包含的参数集取决于Webhook版本。版本2包含额外参数：`is_free`、`is_bonus`和`is_bundle_content`。要切换版本，请

                    在[更新Webhook设置信息](/zh/api/igs/operation/update-webhook/)
                    API调用的`version`参数中传入版本编号。
                  items:
                    oneOf:
                      - properties:
                          amount:
                            description: 根据商品数量计算的总费用。
                            type: string
                          custom_attributes:
                            description: 包含商品属性和值的JSON对象。
                            type: object
                          is_pre_order:
                            description: 如果为`true`，则该商品为预订商品。
                            type: boolean
                          promotions:
                            $ref: '#/components/schemas/items.promotions'
                          quantity:
                            description: 商品数量。
                            type: integer
                          sku:
                            $ref: '#/components/schemas/items.sku'
                          type:
                            $ref: '#/components/schemas/items.type'
                        required:
                          - sku
                          - type
                          - quantity
                          - amount
                          - promotions
                          - is_pre_order
                        title: version = 1
                        type: object
                      - properties:
                          amount:
                            description: 根据商品数量计算的总费用。
                            type: string
                          custom_attributes:
                            description: 包含商品属性和值的JSON对象。
                            type: object
                          is_bonus:
                            description: 如果为`true`，则该商品为奖励。
                            type: boolean
                          is_bundle_content:
                            description: 如果为`true`，则该商品属于某个捆绑包。
                            type: boolean
                          is_free:
                            description: 如果为`true`，则该商品为免费。
                            type: boolean
                          is_pre_order:
                            description: 如果为`true`，则该商品为预订商品。
                            type: boolean
                          promotions:
                            $ref: '#/components/schemas/items.promotions'
                          quantity:
                            description: 商品数量。
                            type: integer
                          sku:
                            $ref: '#/components/schemas/items.sku'
                          type:
                            $ref: '#/components/schemas/items.type'
                        required:
                          - sku
                          - type
                          - quantity
                          - amount
                          - promotions
                          - is_pre_order
                          - is_free
                          - is_bonus
                          - is_bundle_content
                        title: version = 2
                        type: object
                  type: array
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                order:
                  description: 订单信息。
                  properties:
                    amount:
                      description: 基于所选货币的购物车总价。
                      type: string
                    comment:
                      description: 用户对订单的备注。
                      nullable: true
                      type: string
                    coupons:
                      description: 应用的优惠券。如未应用优惠券，则不会返回该数组。
                      items:
                        properties:
                          code:
                            description: 应用的优惠券的券码。
                            type: string
                          external_id:
                            description: 外部ID。
                            type: string
                        type: object
                      type: array
                    currency:
                      description: >-
                        订单货币。虚拟货币使用SKU，真实货币使用三个字母的[ISO
                        4217](https://en.wikipedia.org/wiki/ISO_4217)代码。
                      type: string
                    currency_type:
                      $ref: '#/components/schemas/currency-type'
                    id:
                      description: 艾克索拉侧用户订单的唯一标识符。
                      type: integer
                    invoice_id:
                      description: 实际货币付款发票ID。虚拟货币付款或免费商品的值为`null`。
                      nullable: true
                      type: string
                    mode:
                      description: 付款模式。对于真实支付，使用`default`；对于测试性支付，使用`sandbox`。
                      enum:
                        - default
                        - sandbox
                      type: string
                    platform:
                      description: 支付平台。 `xsolla`值用于通过艾克索拉进行的支付。其他支付使用与游戏发布平台名称对应的值。
                      enum:
                        - xsolla
                        - playstation_network
                        - xbox_live
                        - pc_standalone
                        - nintendo_shop
                        - google_play
                        - app_store_ios
                        - android_standalone
                        - ios_standalone
                        - android_other
                        - ios_other
                        - pc_other
                      nullable: true
                      type: string
                    promocodes:
                      description: 应用的促销码。如未应用促销码，则不会返回该数组。
                      items:
                        properties:
                          code:
                            description: 应用的促销码的代码。
                            type: string
                          external_id:
                            description: 外部ID。
                            type: string
                        type: object
                      type: array
                    promotions:
                      $ref: '#/components/schemas/order.promotions'
                    status:
                      description: 订单状态。
                      type: string
                  required:
                    - id
                    - mode
                    - currency_type
                    - currency
                    - amount
                    - status
                    - platform
                    - comment
                    - invoice_id
                    - promotions
                  type: object
                user:
                  description: 用户信息。
                  properties:
                    country:
                      $ref: '#/components/schemas/user.country'
                    email:
                      description: 用户邮箱地址。
                      type: string
                    external_id:
                      description: 用户ID。
                      type: string
                  required:
                    - external_id
                    - email
                  type: object
              required:
                - notification_type
                - items
                - order
                - user
                - transaction
                - payment_details
      responses:
        '200':
          description: 返回以指示处理成功。
        '400':
          description: 提供的信息出错时返回（例如，缺少必需的参数、授权失败等）。
      summary: 订单成功支付（包含付款和交易详情）
      tags:
        - combined-webhooks
      x-codeSamples:
        - label: CURL
          lang: cURL
          source: >-
            curl -v 'https://your.hostname/your/uri' \

            -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"
              }
            }
        - label: HTTP
          lang: 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:
      description: |
        当满足以下条件时，艾克索拉将<code>order_paid</code> webhook发送到指定的 URL：
        1. 用户成功支付订单。
        2. 艾克索拉收到成功处理[支付](/zh/webhooks/operation/payment/) Webhook的响应。

        <code>order_paid</code> webhook包含所购商品和交易详细信息。

        如果出现以下情况，则不发送<code>order_paid</code> webhook：
        * 支付不成功，例如：
          * 打开了支付表单，但用户没有为订单付款
          * 打开了支付表单，但付款过程中出现错误
        * 尚未收到成功处理[支付](/zh/webhooks/operation/payment/) Webhook的响应。

        建议<code>order_paid</code> webhook的处理时间小于3秒。

        <b>响应</b>部分描述了预期的回答。您可以使用其他响应代码。根据响应码和自动退款功能的连接，艾克索拉侧的webhook处理逻辑如下：

        <table>
            <thead>
            <tr>
                <th>响应代码</th>
                <th>禁用了自动退款（默认）</th>
                <th>启用了自动退款</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>无操作</td>
                <td>自动退款给用户</td>
            </tr>
            <tr>
                <td><code>200</code>、<code>201</code>、<code>204</code></td>
                <td>无操作</td>
                <td>无操作</td>
            </tr>
            <tr>
                <td>不同代码或对webhook无响应</td>
                <td>在指定的时间间隔内发送多个webhook：2次间隔5分钟的尝试，7次间隔15分钟的尝试，10次间隔60分钟的尝试。</td>
                <td>在指定的时间间隔内发送多个webhook：2次间隔5分钟的尝试，7次间隔15分钟的尝试，10次间隔60分钟的尝试。如果发送了所有webhook后仍未收到成功响应，则会向用户自动退款。</td>
            </tr>
            </tbody>
        </table>

        要连接自动退款功能，请联系您的客户成功经理或发送电子邮件至csm@xsolla.com。
      operationId: successful-order-payment-separate
      requestBody:
        content:
          application/json:
            schema:
              properties:
                custom_parameters:
                  description: 附加信息。
                  type: object
                items:
                  description: >
                    用户所购商品的列表。


                    数组中包含的参数集取决于Webhook版本。版本2包含额外参数：`is_free`、`is_bonus`和`is_bundle_content`。要切换版本，请

                    在[更新Webhook设置信息](/zh/api/igs/operation/update-webhook/)
                    API调用的`version`参数中传入版本编号。
                  items:
                    oneOf:
                      - properties:
                          amount:
                            description: 根据商品数量计算的总费用。
                            type: string
                          custom_attributes:
                            description: 包含商品属性和值的JSON对象。
                            type: object
                          is_pre_order:
                            description: 如果为`true`，则该商品为预订商品。
                            type: boolean
                          promotions:
                            $ref: '#/components/schemas/items.promotions'
                          quantity:
                            description: 商品数量。
                            type: integer
                          sku:
                            $ref: '#/components/schemas/items.sku'
                          type:
                            $ref: '#/components/schemas/items.type'
                        required:
                          - sku
                          - type
                          - quantity
                          - amount
                          - promotions
                          - is_pre_order
                        title: version = 1
                        type: object
                      - properties:
                          amount:
                            description: 根据商品数量计算的总费用。
                            type: string
                          custom_attributes:
                            description: 包含商品属性和值的JSON对象。
                            type: object
                          is_bonus:
                            description: 如果为`true`，则该商品为奖励。
                            type: boolean
                          is_bundle_content:
                            description: 如果为`true`，则该商品属于某个捆绑包。
                            type: boolean
                          is_free:
                            description: 如果为`true`，则该商品为免费。
                            type: boolean
                          is_pre_order:
                            description: 如果为`true`，则该商品为预订商品。
                            type: boolean
                          promotions:
                            $ref: '#/components/schemas/items.promotions'
                          quantity:
                            description: 商品数量。
                            type: integer
                          sku:
                            $ref: '#/components/schemas/items.sku'
                          type:
                            $ref: '#/components/schemas/items.type'
                        required:
                          - sku
                          - type
                          - quantity
                          - amount
                          - promotions
                          - is_pre_order
                          - is_free
                          - is_bonus
                          - is_bundle_content
                        title: version = 2
                        type: object
                  type: array
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                order:
                  description: 订单信息。
                  properties:
                    amount:
                      description: 基于所选货币的购物车总价。
                      type: string
                    comment:
                      description: 用户对订单的备注。
                      nullable: true
                      type: string
                    coupons:
                      description: 应用的优惠券。如未应用优惠券，则不会返回该数组。
                      items:
                        properties:
                          code:
                            description: 应用的优惠券的券码。
                            type: string
                          external_id:
                            description: 外部ID。
                            type: string
                        type: object
                      type: array
                    currency:
                      description: >-
                        订单货币。虚拟货币使用SKU，真实货币使用三个字母的[ISO
                        4217](https://en.wikipedia.org/wiki/ISO_4217)代码。
                      type: string
                    currency_type:
                      $ref: '#/components/schemas/currency-type'
                    id:
                      description: 艾克索拉侧用户订单的唯一标识符。
                      type: integer
                    invoice_id:
                      description: 实际货币付款发票ID。虚拟货币付款或免费商品的值为`null`。
                      nullable: true
                      type: string
                    mode:
                      description: 付款模式。对于真实支付，使用`default`；对于测试性支付，使用`sandbox`。
                      enum:
                        - default
                        - sandbox
                      type: string
                    platform:
                      description: 支付平台。 `xsolla`值用于通过艾克索拉进行的支付。其他支付使用与游戏发布平台名称对应的值。
                      enum:
                        - xsolla
                        - playstation_network
                        - xbox_live
                        - pc_standalone
                        - nintendo_shop
                        - google_play
                        - app_store_ios
                        - android_standalone
                        - ios_standalone
                        - android_other
                        - ios_other
                        - pc_other
                      nullable: true
                      type: string
                    promocodes:
                      description: 应用的促销码。如未应用促销码，则不会返回该数组。
                      items:
                        properties:
                          code:
                            description: 应用的促销码的代码。
                            type: string
                          external_id:
                            description: 外部ID。
                            type: string
                        type: object
                      type: array
                    promotions:
                      $ref: '#/components/schemas/order.promotions'
                    status:
                      description: 订单状态。
                      type: string
                  required:
                    - id
                    - mode
                    - currency_type
                    - currency
                    - amount
                    - status
                    - platform
                    - comment
                    - invoice_id
                    - promotions
                  type: object
                user:
                  description: 用户信息。
                  properties:
                    country:
                      $ref: '#/components/schemas/user.country'
                    email:
                      description: 用户邮箱地址。
                      type: string
                    external_id:
                      description: 用户ID。
                      type: string
                  required:
                    - external_id
                    - email
                  type: object
              required:
                - notification_type
                - items
                - order
                - user
      responses:
        '200':
          description: 返回以指示处理成功。
        '400':
          description: 提供的信息出错时返回（例如，缺少必需的参数、授权失败等）。
      summary: 订单成功支付（不包含付款和交易详情）
      tags:
        - separate-webhooks
      x-codeSamples:
        - label: CURL
          lang: cURL
          source: >-
            curl -v 'https://your.hostname/your/uri' \

            -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"
                }

            }'
        - label: HTTP
          lang: 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"
                }
            }
  updated-subscription:
    post:
      description: >-
        如果订阅中的某些参数（`plan_id`、`date_next_charge`）发生更改，以及每次订阅续订时，艾克索拉都会向Webhook
        URL发送一个`update_subscription`类型的Webhook。
      operationId: updated-subscription
      requestBody:
        content:
          application/json:
            schema:
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                settings:
                  description: 带有自定义项目设置的对象。
                  properties:
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                  type: object
                subscription:
                  description: 订阅详情（对象）。
                  properties:
                    date_next_charge:
                      $ref: '#/components/schemas/subscription.date_next_charge'
                    plan_id:
                      $ref: '#/components/schemas/subscription.plan_id'
                    product_id:
                      $ref: '#/components/schemas/subscription.product_id'
                    subscription_id:
                      $ref: '#/components/schemas/subscription.subscription_id'
                    tags:
                      $ref: '#/components/schemas/subscription.tags'
                  type: object
                user:
                  description: 用户详情（对象）。
                  properties:
                    id:
                      $ref: '#/components/schemas/user.id'
                    name:
                      $ref: '#/components/schemas/user.name'
                  required:
                    - id
                  type: object
              required:
                - notification_type
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      summary: 已更新订阅
      tags:
        - subscriptions
      x-codeSamples:
        - label: CURL
          lang: cURL
          source: >-
            curl -v 'https://your.hostname/your/uri' \

            -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"
                    }
                }'
        - label: PHP
          lang: 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'
                )
            );
        - label: HTTP
          lang: 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"
                }
            }
  user-search:
    post:
      description: >-
        与<nt>User ID</nt>不同，<nt>Public User ID</nt>是唯一标识用户的参数且对用户可知（<nt>Public
        User
        ID</nt>可以是电子邮件、屏幕名称等）。在游戏商店外（例如通过自助终端机）进行购买时，艾克索拉会发送一个`user_search`类型的Webhook。
      operationId: user-search
      requestBody:
        content:
          application/json:
            schema:
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                settings:
                  description: 带有自定义项目设置的对象。
                  properties:
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                  type: object
                user:
                  description: 用户详情（对象）。
                  properties:
                    id:
                      $ref: '#/components/schemas/user.id'
                    public_id:
                      $ref: '#/components/schemas/user.public_id'
                  required:
                    - id
                  type: object
              required:
                - notification_type
                - user
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      summary: 用户搜索
      tags:
        - user-validation
      x-codeSamples:
        - label: CURL
          lang: cURL
          source: >-
            curl -v 'https://your.hostname/your/uri' \

            -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"
                }
            }'
        - label: PHP
          lang: PHP
          source: |-
            <?php

            $request = array(
                'notification_type' => 'user_search',
                'settings' => array(
                  'project_id' => 18404,
                  'merchant_id' => 2340
                ),
                'user' => array(
                    'public_id' => 'email@example.com'
                )
            );
        - label: HTTP
          lang: 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"
                }
            }
  user-validation:
    post:
      description: >
        艾克索拉向Webhook 

        URL发送一个`user_validation`类型的Webhook以验证用户是否已在游戏中注册。该请求作为付款流程的一部分会被多次发送：


        * 用户在支付UI中选择支付方式时

        * 用户在支付表单中输入数据时，如通过PayPal支付时的银行卡数据或邮政编码

        * 用户点击**立即支付**进行付款时

        * 支付过程完成且交易状态变为`done`时


        使用任何支付方式付款时都会发送该请求。


        在发布商帐户中保存 Webhook URL 时，可以授予在 Webhook 中接收详细信息的权限。为此，请在发布商帐户的<a 

        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/store">项目设置
        &gt; 

        Webhooks&gt; 高级设置</a>部分中将所需开关设置为打开状态。


        <div class="note">

        <p><strong>注：</strong></p>

        <p>如果是在2025年1月22日或之前注册的发布商帐户，可在<a
        href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/payments">项目设置&gt;
        Webhooks&gt; 测试 &gt; 付款&gt; 高级设置</a> 部分中找到这些开关。</p>

        </div>


        <table>

        <thead>
            <tr>
                <th>开关</th>
                <th>描述</th>
            </tr>
        </thead>

        <tbody>
            <tr>
                <td>仅发送不含敏感数据的必要用户参数</td>
                <td><p>Webhook中仅传递用户的以下信息：</p><ul><li>ID</li><li>国家/地区</li></ul></td>
            </tr>
            <tr>
                <td>发送自定义参数</td>
                <td><a href="/zh/api/pay-station/operation/create-token/">自定义令牌参数</a>的信息在webhook中传递。</td>
            </tr>
        </tbody>

        </table>
      operationId: user-validation
      requestBody:
        content:
          application/json:
            schema:
              properties:
                notification_type:
                  $ref: '#/components/schemas/notification_type'
                settings:
                  description: 带有自定义项目设置的对象。
                  properties:
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                  type: object
                user:
                  description: 用户详情（对象）。
                  properties:
                    country:
                      $ref: '#/components/schemas/user.country'
                    email:
                      $ref: '#/components/schemas/user.email'
                    id:
                      $ref: '#/components/schemas/user.id'
                    ip:
                      $ref: '#/components/schemas/user.ip'
                    name:
                      $ref: '#/components/schemas/user.name'
                    phone:
                      $ref: '#/components/schemas/user.phone'
                  required:
                    - id
                  type: object
              required:
                - notification_type
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
      summary: 用户验证
      tags:
        - user-validation
      x-codeSamples:
        - label: CURL
          lang: cURL
          source: >-
            curl -v 'https://your.hostname/your/uri' \

            -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"
                }
            }'
        - label: PHP
          lang: 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'
                )
            );
        - label: HTTP
          lang: 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-validation-in-webshop:
    post:
      description: >-
        艾克索拉从网页商城网站发送一个Webhook以检查游戏中是否存在该用户。该Webhook从以下IP地址发送：`34.102.38.178`。
         <div class="note"><strong>注：</strong><br><br>
        Webhook仅用于Web商店中的用户验证。有关在建站器中配置Webhook的更多信息，请参阅这些<a target="_blank"
        href="https://developers.xsolla.com/zh/solutions/web-shop/authentication-and-analytics/set-up-authentication/">说明</a>。</div>
      operationId: user-validation-in-webshop
      requestBody:
        content:
          application/json:
            schema:
              properties:
                settings:
                  description: 带有自定义项目设置的对象。
                  properties:
                    merchant_id:
                      $ref: '#/components/schemas/settings.merchant_id'
                    project_id:
                      $ref: '#/components/schemas/settings.project_id'
                  type: object
                user:
                  description: 用户详情（对象）。
                  properties:
                    country:
                      $ref: '#/components/schemas/user.country'
                    id:
                      $ref: '#/components/schemas/user.id'
                  required:
                    - id
                  type: object
              required:
                - user
      responses:
        '200':
          content:
            application/json:
              example:
                attributes:
                  - key: level
                    value: '2'
                  - key: register_country
                    value: AE
                removingKeys:
                  - company
                user:
                  id: '1234567890'
                  name: test-name
                  picture: https://example.com
              schema:
                properties:
                  attributes:
                    description: >-
                      用于个性化的用户属性。有关详细信息，请参阅<a target="_blank"
                      href="https://developers.xsolla.com/zh/doc/login/features/user-attributes/#login_features_user_attributes">文档</a>。
                    items:
                      properties:
                        key:
                          description: 属性名称。
                          type: string
                        value:
                          description: 属性值。
                      required:
                        - key
                        - value
                    type: array
                  removingKeys:
                    description: 要删除的属性列表。如果在`attributes`参数中指定了相同的属性，则不会被删除。
                    items:
                      type: string
                    type: array
                  user:
                    description: 用户详情（对象）。
                    properties:
                      id:
                        description: 用户ID。
                        type: string
                      name:
                        description: 用户名。
                        type: string
                      picture:
                        description: 用户头像的链接。
                        type: string
                    required:
                      - id
                    type: object
                required:
                  - user
                type: object
          description: 返回用户的信息。
        '404':
          description: 找不到用户。
      summary: Web商店中的用户验证
      tags:
        - user-validation
      x-codeSamples:
        - label: CURL
          lang: 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"
                }
            }'
        - label: HTTP
          lang: 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"
                }
            }
components:
  schemas:
    notification_type:
      description: 通知类型。
      type: string
    payment_account.country:
      description: >-
        支付帐户的国家/地区。例如，发卡银行所在国家/地区或创建PayPal帐户时指定的国家/地区。使用符合[ISO 3166-1
        alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)标准的两个大写字母国家/地区代码。
      type: string
    payment_account.id:
      description: 支付帐户ID。
      type: string
    payment_account.name:
      description: 支付帐户在付款系统中的名称（例如支付卡卡号、邮箱等）。
      type: string
    payment_account.payment_method:
      description: 付款方式ID。
      type: integer
    payment_account.type:
      description: 支付帐户类型（例如银行卡、PayPal等）。
      type: string
    settings.merchant_id:
      description: 商户ID。
      type: integer
    settings.project_id:
      description: 项目编号。您可以在您的[发布商帐户](https://publisher.xsolla.com/)项目名称旁边。
      type: integer
    user.country:
      description: >-
        用户所在国家/地区。使用[ISO 3166-1 alpha-2
        标准](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)规定的2字母组合表示国家/地区。
      type: string
    user.email:
      description: 用户电子邮件。
      type: string
    user.id:
      description: 用户ID。
      type: string
    user.ip:
      description: 用户 IP 地址。
      type: string
    user.name:
      description: 用户名。
      type: string
    user.zip:
      description: 邮编。
      type: string
    subscription.date_create:
      description: 订阅的创建日期。符合 [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)标准规定的日期与时间。
      type: string
    subscription.date_end:
      description: 订阅结束的日期。符合[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)标准规定的日期与时间。
      type: string
    subscription.plan_id:
      description: 计划ID（如果计划通过API创建，则为外部ID）。
      type: string
    subscription.product_id:
      description: 产品ID（如果在访问令牌中发送）。
      type: string
    subscription.subscription_id:
      description: 艾克索拉数据库的订阅ID。
      type: integer
    subscription.tags:
      description: 计划标签。
      items:
        type: string
      type: array
    subscription.date_next_charge:
      description: 下次收费的日期。符合[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)标准规定的日期与时间。
      type: string
    subscription.is_gift:
      description: 订阅是否为赠送。仅当值为`true`时发送此参数。
      type: boolean
    dispute-date:
      description: 符合[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)标准的争议提出日期。
      type: string
    dispute-reason:
      description: >-
        提出争议的原因。关于原因组的描述，请参考[文档](/zh/solutions/payments/anti-fraud/chargeback/#payments_chargeback_reasons)。
      enum:
        - non_receipt
        - not_as_described
        - duplicate_processing
        - paid_by_other_means
        - incorrect_amount
        - credit_not_processed
        - general
        - fraud
        - cancelled_recurring
        - cancelled_merchandise
        - late_presentment
        - no_authorization
        - problem_with_remittance
        - other
      type: string
    dispute-status:
      description: 争议状态。
      enum:
        - new
        - accepted
        - no_actions_required
        - won
        - lost
      type: string
      x-enumDescriptions:
        accepted: <b>已接受</b>
        lost: <b>败</b>
        new: <b>新</b>
        no_actions_required: <b>进行中</b>
        won: <b>胜</b>
    dispute-type:
      description: 争议类型。
      enum:
        - 1st_time_chargeback
        - 2nd_time_chargeback
        - arbitration
        - retrieval
        - representment
        - chargeback_reversal
        - representment_reversal
        - reimbursement
        - dispute
        - chargeback
        - claim
        - reimbursement_reversal
        - inquiry
        - other
      type: string
      x-enumDescriptions:
        1st_time_chargeback: 第一次拒付。
        2nd_time_chargeback: 第二次拒付（仲裁前）。
        arbitration: 解决第一次拒付和第二次拒付被拒绝时发卡行与商户之间的争议。
        chargeback: 第一次拒付。
        chargeback_reversal: 已撤销拒付。
        claim: 客户与商家在PayPal中的争议。
        dispute: 持卡人已向银行索取付款详细信息。
        inquiry: 持卡人已向银行索取付款详细信息。
        other: 用于任何其他类型未覆盖的拒付类型。
        reimbursement: 已退款。
        reimbursement_reversal: 已撤销拒付。
        representment: 拒付管理团队已将证据发送至支付系统。
        representment_reversal: 已撤销拒付。
        retrieval: 持卡人已向银行索取付款详细信息。
    date-create:
      description: 支付日期。
      type: string
    external-id:
      description: >-
        交易外部ID。详细信息请参阅[常见问答](/zh/doc/pay-station/references/faq/#faq_payments_q_new_transaction_external_id)。
      type: string
    transaction-id:
      description: 交易ID。
      type: integer
    dispute-payment-method:
      description: 支付方式。
      enum:
        - credit_debit_card
        - paypal
      type: string
      x-enumDescriptions:
        credit_debit_card: 信用卡或借记卡
        paypal: PayPal
    transaction-total-amount:
      description: 付款金额。
      format: float
      type: number
    currency:
      description: 货币。符合[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)的三字母货币代码。
      type: string
    amount-float:
      description: 以实际货币表示的价格。
      format: float
      type: number
    items.promotions:
      description: |-
        对订单中的特定商品应用促销活动。
        在下列情况下返回该数组：
          - 特定商品配置了折扣促销。
          - 使用了具有**对所选商品提供折扣**设置的促销码。

        如果没有应用任何商品级促销活动，则返回一个空数组。
      items:
        properties:
          amount_with_discount:
            description: 应用折扣后商品总价。
            type: string
          amount_without_discount:
            description: 不应用折扣的商品总价。
            type: string
          sequence:
            description: 应用促销活动的顺序。
            type: integer
        type: object
      type: array
    items.sku:
      description: 项目的唯一ID。对于`game_key`类型的商品，使用`sku_drm`格式的值。
      type: string
    items.type:
      description: |-
        商品类型。
        对于`bundle`类型商品，包括虚拟货币套餐，`items`数组将显示：
        - 捆绑包或虚拟货币套餐的参数
         - 捆绑包中包含的商品或套餐中包含的货币
          
        `value_point`类型用于[忠诚积分](/zh/solutions/loyalty-as-service/)操作，即积分被消费或奖励时。
      enum:
        - virtual_good
        - virtual_currency
        - game_key
        - bundle
        - value_point
      type: string
    currency-type:
      description: 支付货币类型。对于免费订单，则值指定为`unknown`。
      enum:
        - real
        - virtual
        - unknown
        - loyalty_point
      type: string
      x-enumDescriptions:
        loyalty_point: 忠诚积分
        real: 真实货币
        unknown: 免费订单
        virtual: 虚拟货币
    order.promotions:
      description: |-
        对整个订单应用促销活动。
        在下列情况下返回该数组：
          - 促销活动会影响总订单金额，例如具有**对购买项提供折扣**设置的促代码。
          - 购买时不享受折扣，但订单中会添加赠品。在这种情况下，由于未应用折扣，将返回含折扣的价格([amount_with_discount](/zh/webhooks/#operation/order-cancellation!path=order/promotions/amount_with_discount&t=request))和不含折扣的价格值([amount_without_discount](/zh/webhooks/#operation/order-cancellation!path=order/promotions/amount_without_discount&t=request))且两个值相同。

        如果未应用任何订单级促销活动，将返回一个空数组。
      items:
        properties:
          amount_with_discount:
            description: 应用折扣后商品总价。
            type: string
          amount_without_discount:
            description: 不应用折扣的商品总价。
            type: string
          sequence:
            description: 应用促销活动的顺序。
            type: integer
        type: object
      type: array
    user.phone:
      description: 用户电话号码（采用国际格式）。
      type: string
    order:
      description: >-
        包含订单信息的对象。要接收此信息，请在[发布商帐户](https://publisher.xsolla.com/)的**项目设置
        &gt;Webhooks &gt; 高级设置**部分中将**将订单对象添加到Webhook**开关设置为**开**。
      type: object
    locale:
      description: >-
        用户语言。2字母（小写字母）[语言代码](https://developers.xsolla.com/zh/doc/pay-station/features/localization/)。
      type: string
    quantity:
      deprecated: true
      description: >-
        单个用户可购买的商品数量。传入`null`表示不限数量，传入`0`表示商品在商品目录中可见但无法购买。


        使用此参数时，购买数限制信息不会显示在商品目录中。如需显示购买数限制信息(如"7/10")，请传入`available`和`total`参数对，而非`quantity`参数。
      type: integer
    available:
      description: |-
        用户剩余可购买数量。

        如需在商品目录中显示购买数限制信息(如"7/10")，请传入`available`和`total`参数对。
      type: integer
    total:
      description: |-
        单个用户可购买的商品数量上限。

        如需在商品目录中显示购买数限制信息(如"7/10")，请传入`available`和`total`参数对。
      exclusiveMinimum: 0
      type: integer
    bundle_content:
      description: >-
        包含捆绑包内容的对象数组，用于在目录中显示。仅适用于捆绑包类型[partner_side_content](https://developers.xsolla.com/zh/api/shop-builder/operation/admin-create-bundle/)。
      items:
        properties:
          description:
            description: 商品描述，作为捆绑包的一部分在目录中显示。如果没有提供，则传递值`null`。
            maxLength: 255
            type: string
          image_url:
            description: 商品图片URL，作为捆绑包的一部分在目录中显示。仅支持HTTPS协议。如果没有提供，则传递值`null`。
            format: uri
            maxLength: 255
            type: string
          name:
            description: 商品名称，作为捆绑包的一部分在目录中显示。如果没有提供，则传递空字符串。
            maxLength: 255
            type: string
          quantity:
            default: 1
            description: 该商品在捆绑包中的数量。
            minimum: 1
            type: integer
        type: object
      type: array
    date_from:
      description: >-
        商品上架的日期。格式需符合[RFC
        3339](https://datatracker.ietf.org/doc/html/rfc3339)标准。
      type: string
    date_until:
      description: >-
        商品下架的日期。格式需符合[RFC
        3339](https://datatracker.ietf.org/doc/html/rfc3339)标准。
      type: string
    description:
      description: 用于在目录中显示的商品描述。它会覆盖商品中存储的描述。
      maxLength: 255
      type: string
    image_url:
      description: 用于在目录中显示的图片的URL。它将覆盖存储在商品中的图片URL。仅支持HTTPS协议。如果URL不符合要求，则会被忽略。
      format: uri
      maxLength: 255
      type: string
    json_attributes:
      description: >-
        包含商品属性和值的JSON对象。它会覆盖商品中存储的[custom_attributes](https://developers.xsolla.com/zh/webhooks/operation/successful-order-payment/#!path=items/0/custom_attributes&t=request)。如果JSON数据不符合要求或者超过最大长度，则会被忽略。
      format: json
      maxLength: 500
      type: object
    name:
      description: 用于在目录中显示的商品名称。它会覆盖商品中存储的名称。
      maxLength: 255
      type: string
    sku:
      description: 在发布商帐户中指定的商品的唯一 ID。应传入`sku`或`item_id`。
      type: string
    item_id:
      description: 艾克索拉侧的唯一商品ID。应传入`sku`或`item_id`。
      type: integer
    user.public_id:
      description: 公共用户ID。
      type: string
  responses:
    '204':
      description: 返回以指示处理成功。
    '400':
      content:
        application/json:
          schema:
            properties:
              error:
                properties:
                  code:
                    type: string
                  message:
                    type: string
                type: object
            type: object
      description: 提供的信息出错时返回（例如，缺少必需的参数、授权失败等）。
      x-examples:
        application/json:
          INCORRECT_AMOUNT:
            summary: Incorrect amount
            value:
              error:
                code: INCORRECT_AMOUNT
                message: Incorrect amount
          INCORRECT_INVOICE:
            summary: Incorrect invoice
            value:
              error:
                code: INCORRECT_INVOICE
                message: Incorrect invoice
          INVALID_PARAMETER:
            summary: Invalid parameter
            value:
              error:
                code: INVALID_PARAMETER
                message: Invalid parameter
          INVALID_SIGNATURE:
            summary: Invalid signature
            value:
              error:
                code: INVALID_SIGNATURE
                message: Invalid signature
          INVALID_USER:
            summary: Invalid user
            value:
              error:
                code: INVALID_USER
                message: Invalid user
    '500':
      description: 返回以指示您的服务器存在的暂时性错误。
    400-payment:
      content:
        application/json:
          schema:
            properties:
              error:
                properties:
                  code:
                    type: string
                  message:
                    type: string
                type: object
            type: object
      description: >-
        提供的信息有错误（例如，缺少必需的参数、授权失败等）时返回。在这种情况下，用户的钱已扣，但是购买失败。要退款，请发送邮件至support@xsolla.com联系艾克索拉客户支持。
      x-examples:
        application/json:
          INCORRECT_AMOUNT:
            summary: Incorrect amount
            value:
              error:
                code: INCORRECT_AMOUNT
                message: Incorrect amount
          INCORRECT_INVOICE:
            summary: Incorrect invoice
            value:
              error:
                code: INCORRECT_INVOICE
                message: Incorrect invoice
          INVALID_PARAMETER:
            summary: Invalid parameter
            value:
              error:
                code: INVALID_PARAMETER
                message: Invalid parameter
          INVALID_SIGNATURE:
            summary: Invalid signature
            value:
              error:
                code: INVALID_SIGNATURE
                message: Invalid signature
          INVALID_USER:
            summary: Invalid user
            value:
              error:
                code: INVALID_USER
                message: Invalid user
x-tagGroups:
  - name: 用户验证
    tags:
      - user-validation
  - name: 付款
    tags:
      - payments
  - name: 游戏服务
    tags:
      - combined-webhooks
      - separate-webhooks
      - personalization
  - name: 反欺诈
    tags:
      - anti-fraud
  - name: 订阅
    tags:
      - subscriptions
