Xsolla-logo
  • 文档
  • 创建帐户

概览

Webhook是系统中发生的事件的通知。当特定事件发生时，艾克索拉会向您的应用程序发送HTTP请求，其中会传输事件数据。它通常是JSON格式的POST请求。

事件示例：

  • 用户与商品目录交互
  • 付款或取消订单

当发生设定事件时，艾克索拉会通过Webhook通知您的系统。然后，您可以执行以下操作：

  • 补充用户余额
  • 进行退款
  • 向用户帐户发放或减除新商品
  • 开始提供订阅
  • 怀疑欺诈行为时封禁用户

支付处理Webhook工作流示例：

支付处理Webhook

艾克索拉Webhook集成视频指南：

使用艾克索拉产品和解决方案时的Webhook设置：

产品/解决方案 必需/可选 Webhook的用途是什么
付款 必需
  • 用户验证。
  • 付款成功或退款时接收交易详情的信息。
  • 将购买的商品记入用户帐户，及在订单取消时将商品减除。
游戏内商店 必需
  • 用户验证。
  • 付款成功或退款时接收交易详情的信息。
  • 将购买的商品记入用户帐户，及在订单取消时将商品减除。
游戏销售 可选 对于游戏密钥销售，用户验证和商品记入不是必需。如果想接收有关事件的信息（例如付款或订单取消），可以连接webhook。
如果连接Webhook，则必须处理所有传入的必需Webhook。
订阅 可选 接收有关创建、更新或取消订阅的信息。您也可以通过API请求信息。
网页商城 必需
  • 用户验证。
  • 付款成功或退款时接收交易详情的信息。
  • 将购买的商品记入用户帐户，及在订单取消时将商品减除。
  • 用户认证（如果使用通过用户ID进行身份认证）。您也可以使用通过艾克索拉登录管理器进行用户认证。
Digital Distribution Hub 必需
  • 用户验证。
  • 将艾克索拉侧的交易ID与您系统中的交易ID关联。
  • 在订单中传输额外交易参数。
  • 将购买的商品记入用户帐户，及在订单取消时将商品减除。

请参阅文档，了解如何为Digital Distribution Hub设置Webhook。

必需Webhook列表

如果使用需要与Webhook交互的产品和解决方案，请在您的发布商帐户中启用并测试Webhook并设置Webhook处理。当特定事件发生时，Webhook会按顺序发送。因此，如果您不处理其中一个Webhook，则不会发送后续Web hook。下面列出了必需Webhook的列表。

游戏内商店和付款

在艾克索拉侧已设置了2种Webhook发送选项，用于处理网站上的商品购买和退货——支付和交易数据信息以及已购商品信息可以分开发送，也可以合并为一个Webhook 发送。

在合并Webhook中接收信息：

If you registered in Publisher Account after January 22, 2025, you receive all the information in the Successful payment for order (order_paid) and Order cancellation (order_canceled) webhooks. In this case, you do not need to process the Payment (payment) and Refund (refund) webhooks.

在单独Webhook中接收信息：

如果您在2025年1月22日或之前在发布商帐户注册，您将收到以下Webhook：

您需要处理所有收到的Webhook。如需切换到新的合并Webhook接收方式，请联系您的客户成功经理或发送邮件至csm@xsolla.com。

为确保游戏内商店和支付管理功能正常运行，必须实现主要Webhook的处理。

如果接收合并Webhook：

Webhook名称和类型 描述
用户验证 > 用户验证 (user_validation) 在支付流程的不同阶段发送，用于确保用户已在游戏中注册。
Game services > Combined webhooks > Successful payment for order (order_paid) 包含支付数据、交易详情和已购商品信息。请使用Webhook中的数据为用户添加商品。
游戏服务 > 合并Webhook > 订单取消(order_canceled) 包含已取消支付的数据、交易详情和已购商品信息。请使用Webhook中的数据移除已购商品。

如果接收单独Webhook：

Webhook名称和类型 描述
用户验证 > 用户验证 (user_validation) 在支付流程的不同阶段发送，用于确保用户已在游戏中注册。
付款 > 支付(payment) 包含支付数据和交易详细信息。
Game services > Separate webhooks > Successful payment for order (order_paid) 包含已购商品信息。请使用Webhook中的数据为用户添加商品。
付款 > 退款 (refund) 包含支付数据和交易详细信息。
游戏服务 > 单独Webhook > 订单取消(order_canceled) 包含已购商品信息和已取消交易的ID。请使用Webhook中的数据移除已购商品。

如果您的应用程序侧实现了商品目录个性化，请设置对合作伙伴侧的目录个性化Webhook的处理。

Note

To receive real payments, you only need to sign the licensing agreement and implement processing of the webhooks:

订阅

要自动管理订阅计划，需要实现主要Webhook的处理：

  • 用户验证(user_validation) — 在支付过程的不同阶段发送，以确保用户已在游戏中注册。
  • 支付(payment) — 在支付订单后发送，包含付款数据和交易详细信息。
  • 创建了订阅(create_subscription) — 支付Webhook已成功处理或用户购买了具有试用期的订阅时发送。它包含所购买的订阅 的详细信息和用户数据。使用该Webhook数据向用户添加订阅。
  • 更新了订阅(update_subscription) — 续订或更改订阅以及支付Webhook已成功 处理后发送。它包含所购买的订阅的详细信息和用户数据。使用该Webhook数据来延长用户的订阅或更改订阅参数。
  • 退款(refund) — 订单被取消后发送，包含取消的付款数据和交易详细信息。
  • 取消了订阅(cancel_subscription) — 退款Webhook已成功处理或订阅因其他原因被取消时发送。它包含有关订阅和用户数据的 信息。使用该Webhook数据扣除用户购买的订阅。

在发布商帐户中设置Webhook

常规设置

要启用接收Webhook：

  1. 在发布商帐户的项目中，前往项目设置 > Webhook部分。
  2. 在Webhook服务器字段中，指定要接收Webhook的服务器的URL，格式为https://example.com。您还可以指定在测试Web hook的工具中找到的URL。

注：

请使用HTTPS协议传输数据，不支持HTTP协议。

  1. 默认情况下会生成用于签署项目Webhook的密钥。如果想生成新的密钥，请单击刷新图标。
  2. 单击启用Webhook。

注：

要测试Webhook，可以选择任何专用网站（例如webhook.site）或平台（例如ngrok）。

注：

无法同时将Webhook发送到不同的URL。您可以在发布商帐户中执行的操作是先指定一个用于测试的URL，然后将其替换为真实的URL。

要禁用接收Webhook：

  1. 在发布商帐户的项目中，前往项目设置 > Webhook部分。
  2. 单击禁用Webhook。

高级设置

付款和商店部分的Webhook提供高级设置。单击获取Webhook按钮后，这些设置将自动显示在常规设置区块下方。

注意

如果未显示高级设置，请确保已在常规设置中连接Webhook接收，且您位于测试 > 付款和商店选项卡中。

在此部分，您可以设置在Webhook中接收额外信息。要实现此目的，请将相应开关设为启用状态。每个权限的行都会标明设置变更将影响哪些Webhook。

开关 描述
显示保存的支付帐户的信息 有关保存的支付方式的信息在payment_account自定义对象中传递。
显示通过保存的支付方式进行的交易的信息

信息在Webhook的以下自定义参数中传递：

  • saved_payment_method:
    • 0 — 未使用保存的支付方式
    • 1 — 进行当前付款时保存了支付方式
    • 2 — 使用了之前保存的支付方式
  • payment_type:
    • 1 — 一次性支付
    • 2 — 定期支付
将订单对象添加到Webhook 有关订单的信息在支付Webhook的order对象中传递。
仅发送不含敏感数据的必要用户参数

Webhook中仅传递用户的以下信息：

  • ID
  • 国家/地区
发送自定义参数 自定义令牌参数的信息在webhook中传递。
显示银行卡BIN和后缀码

Webhook中传递以下银行卡号的信息：

  • card_bin参数中的前6位数字
  • card_suffix中的后4位数字
显示银行卡品牌 用于付款的银行卡的品牌。例如，Mastercard或Visa。

高级设置

在发布商帐户中测试Webhook

测试Webhook有助于确保己侧和艾克索拉侧的项目设置都正确。

如果Webhook设置成功，Webhook 设置部分下方会显示一个Webhook测试部分。

！Webhook测试部分

发布商帐户中的测试部分会根据Webhook接收选项而有所不同。

如果接收合并Webhook：

Webhook测试的选项卡名称 Webhook名称和类型
付款和商店 用户验证 > 用户验证 (user_validation)
Game services > Combined webhooks > Successful payment for order (order_paid)
游戏服务 > 合并Webhook > 订单取消(order_canceled)
订阅 用户验证 > 用户验证 (user_validation)
付款 > 支付(payment)

如果接收单独Webhook：

Webhook测试的选项卡名称 Webhook名称和类型
商店 Game services > Separate webhooks > Successful payment for order (order_paid)
游戏服务 > 单独Webhook > 订单取消(order_canceled)
付款 用户验证 > 用户验证 (user_validation)
付款 > 支付(payment)
订阅 用户验证 > 用户验证 (user_validation)
付款 > 支付(payment)

注：

如果测试部分出现测试未通过的警告，请在您的Webhook侦听器中检查Webhook响应设置。测试结果中指出了测试错误的原因。

示例：

您使用专门的网站webhook.site来进行测试。

测试对无效签名的响应部分显示了一个错误。

发生这种情况是因为艾克索拉发送了带有错误签名的Webhook，并期望您的处理程序用一个指出INVALID_SIGNATURE错误代码的4xx HTTP代码进行响应。

webhook.site对所有Webhook的响应中都发送一个200 HTTP代码，包括签名不正确的Webhook。由于无法获取预期的4xxHTTP代码，因此测试结果报错。

测试错误

下文将介绍合并Webhook使用场景的测试流程。

付款和商店

在付款和商店选项卡中，您可以测试以下Webhook：

要进行测试：

  1. 在Webhook测试部分，前往付款和商店选项卡。

  2. 在下拉菜单中，选择商品类型。如果所选类型的商品未在发布商帐户中设置，请单击：

    • 连接 – 如果未连接该类型商品的模块
    • 配置 – 如果之前连接过模块，但尚未完成设置
      单击该按钮后，您将被重定向到与所选商品类型相对应的发布商帐户部分。创建商品后，返回Webhook测试部分并继续下一步 。

  3. 填写以下必填字段：

    1. 从下拉列表中选择商品SKU并指定金额。您可以通过单击+号并在新行中添加来选择同一类型的多个商品。
    2. 用户ID — 测试时，可以使用任意字母和数字组合。
    3. 公共用户ID — 用户可见的ID，例如电子邮件或昵称。如果在支付中心 > 设置中启用了公共用户ID，则会显示此字段。
    4. 在艾克索拉订单ID字段中输入任意值。
    5. 艾克索拉发票ID — 艾克索拉侧的交易ID。测试时，可以使用任意数字值。
    6. 发票ID — 游戏侧的交易ID。测试时，可以使用任意字母和数字组合。这不是成功支付所必需的参数，但您可以通过它将游戏侧的交易ID与艾克索拉侧的交易ID关联起来。
    7. 金额 — 支付金额。测试时，可以使用任意数字值。
    8. 货币 — 从下拉列表中选择货币。

  4. 单击测试Webhook。

User validation, Successful payment for order and Order cancellation webhooks with the specified data are sent to the provided URL. The results of testing each webhook type are displayed below the Test webhooks button.

如果在您的项目中启用了公共用户ID，还将看到用户搜索检查的结果。

对于每个Webhook，您需要配置处理两种情况：成功的情况和出现错误的情况。

！付款测试部分

订阅

在订阅选项卡中，您可以测试以下Webhook：

注：

在发布商帐户中，您只能测试基本的用户验证和支付Webhook。要测试其他Webhook类型，请前往：

注：

要测试Webhook，您应该在发布商帐户>订阅>订阅计划部分中至少有一个已创建的订阅计划。

测试步骤：

  1. 在测试部分，前往订阅选项卡。
  2. 填写以下必填字段：

    1. 用户ID — 测试时，可以使用任意字母和数字组合。
    2. 艾克索拉发票ID — 艾克索拉侧的交易ID。测试时，可以使用任意数字值。
    3. 公共用户ID — 用户可见的ID，例如电子邮件或昵称。如果在支付中心 > 设置 > 其他设置部分启用了公共用户ID，则会显示此字段。
    4. 货币 — 从下拉列表中选择货币。
    5. 计划ID — 订阅计划。从下拉列表中选择计划。
    6. 订阅产品 — 从下拉列表中选择产品（可选）。
    7. 金额 — 支付金额。测试时，可以使用任意数字值。
    8. 发票ID — 游戏侧的交易ID。测试时，可以使用任意字母和数字组合。这不是成功支付所必需的参数，但您可以通过它将游戏侧的交易ID与艾克索拉侧的交易ID关联起来。
    9. 试用期。要测试购买无试 用期的订阅或测试续订，请指定值0。
  3. 单击测试Webhook。

在指定的URL中，您将收到包含所填数据的Webhook。每个Webhook的测试结果（成功场景和错误场景）都在测试Webhook按钮下方显示。

Webhook侦听器

Webhook侦听器是一个程序代码，允许在指定URL地址接收传入的Webhook、生成签名以及发送响应到艾克索拉Webhook服务器。

注：

您可以使用Pay Station PHP SDK 库，它包含用于处理Webhook的现成类。

在应用程序侧，实现从以下IP地址接收Webhook：185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24, 34.102.38.178, 34.94.43.207, 35.236.73.234, 34.94.69.44, 34.102.22.197。

限制：

  • 应用程序的数据库中不应存在具有相同ID的多个成功交易。
  • 如果Webhook侦听器收到的Webhook的ID已经存在于数据库中，则需返回之前处理该交易的结果。不建议向用户发放重复购买及在数据库中创建重复记录。

生成签名

接收Webhook时，应保证数据传输的安全。为此，必须从Webhook数据生成签名，并验证它是否与HTTP请求标头中发送的签名匹配。要生成签名：

  1. 连接请求正文中的JSON和项目的密钥。
  2. 将SHA-1加密哈希函数应用于第一步中获得的字符串。
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
  "notification_type":"user_validation",
  "user":{
      "ip":"127.0.0.1",
      "phone":"18777976552",
      "email":"email@example.com",
      "id":1234567,
      "name":"Xsolla User",
      "country":"US"
  }
}

curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"
      }
    }'

向Webhook发送响应

要确认收到Webhook，您的服务器必须返回：

  • 如果响应成功，返回200、201或204HTTP代码。
  • 如果未找到指定的用户或传递了无效的签名，返回400 HTTP代码和问题描述。如果您的服务器出现临时问题，您的Webhook处理程序还可 以返回5xxHTTP 代码。

If the Xsolla server did not receive a response to Successful payment for order and Order cancellation webhooks or received a response with a 5xx code, the webhooks are resent according to the following schedule:

  • 尝试2次，间隔5分钟
  • 尝试7次，间隔15分钟
  • 尝试10次，间隔60分钟

在首次尝试后的12小时内最多尝试发送20次Webhook。

如果艾克索拉服务器未收到支付Webhook或退款Webhook的响应，或收到5xx代码的响应，系统也会以递增的时间间隔重新发 送Webhook。12小时内最多尝试12次。

注：

如果退款是由艾克索拉发起的，并且收到带有`5xx` HTTP代码的退款Webhook响应，付款仍会被退还。

If the Xsolla server did not receive a response to the User validation webhook or received a response with a code of 400 or 5xx, the User validation webhook is not resent. In this case, the user sees an error and the Payment and Successful payment for order webhooks are not sent.

错误

HTTP代码400的错误代码：

代码 消息
INVALID_USER 无效用户
INVALID_PARAMETER 无效参数
INVALID_SIGNATURE 无效签名
INCORRECT_AMOUNT 金额不正确
INCORRECT_INVOICE 发票不正确 
HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}

Webhook列表

注：

通知类型在notification_type参数中发送。

Webhook 通知类型 描述
用户验证 user_validation 发送以检查用户是否存在于游戏中。
用户搜索 user_search 发送以根据公共用户ID获取用户信息。
支付 payment 用户完成支付流程时发送。
退款 refund 出于某些原因需要取消支付时发送。
部分退款 partial_refund 出于某些原因需要部分取消支付时发送。
AFS拒绝交易 afs_reject 交易在AFS检查过程中被拒绝时发送。
AFS更新的拦截列表 afs_black_list AFS拦截列表发生更新时发送。
创建了订阅 create_subscription 用户创建订阅时发送。
更新了订阅 update_subscription 订阅发生续订或更改时发送。
取消了订阅 cancel_subscription 取消订阅时发送。
非续订订阅 non_renewal_subscription 状态设置为非续订时发送。
添加支付账户 payment_account_add 当用户添加或保存支付帐户时发送。
删除支付账户 payment_account_remove 用户从已保存的帐户中删除了支付帐户时发送。
Web商店中的用户验证 - 从Web商店网站发送以检查游戏中是否存在该用户。
合作伙伴侧目录个性化 partner_side_catalog 用户与商店交互时发送。
Successful payment for order order_paid 订单付款后发送。
订单取消 order_canceled 订单取消时发送。
争议 dispute 当提出新争议时发送。
System statusAll services operational

Privacy Settings

Privacy PolicyEnd User License Agreement© 2006–2025 Xsolla Inc.