Xsolla-logo
  • 文档
  • 创建帐户

概览

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

事件示例:

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

当发生设定事件时,艾克索拉会通过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的列表。

游戏内商店/付款

要完整运营一个游戏内商店,需要实现主要Webhook的处理:

  • 用户验证(user_validation) — 在支付过程的不同阶段发送,以确保用户已在游戏中注册。
  • 支付(payment) — 在支付订单后发送,包含付款数据和交易详细信息。
  • 订单支付成功(order_paid) — 支付Webhook已成功处理时发送并包含有关购买的商品和交易ID的信息。使用该We bhook中的数据向用户添加商品。
  • 退款(refund) — 订单被取消后发送,包含取消的付款数据和交易详细信息。
  • 订单取消(order_canceled) —退款Webhook已成功处理时发送,并包含有关所购商品的信息和已取消交易的ID。使用 该Webhook中的数据移除购买的商品。

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

注:

要接收真实付款,只需执行对支付订单支付成功用户验证Webhook的处理,以及签署许可协议

订阅

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

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

在发布商帐户中设置Webhook

要启用接收Webhook:

  1. 发布商帐户中打开您的项目。
  2. 在侧边栏中单击项目设置,然后前往Webhooks选项卡。
  3. Webhook服务器字段中,指定要接收Webhook的服务器的URL,格式为https://example.com。您还可以指定在测试Web hook的工具中找到的URL。
  4. 默认情况下会生成用于签署项目Webhook的密钥。如果想生成新的密钥,请单击刷新图标。
  5. 单击启用Webhook

注:

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

注:

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

要禁用接收Webhook:

  1. 发布商帐户中打开您的项目。
  2. 在侧边栏中单击项目设置,然后前往Webhooks选项卡。
  3. 单击禁用Webhook

在发布商帐户中测试Webhook

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

您可以测试以下Webhook的接收:

Webhook名称 Webhook类型
用户验证 user_validation
支付 payment
订单取消 order_canceled
订单支付成功 order_paid

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

Webhooks testing 
section

注:

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

示例:

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

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

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

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

测试错误

商店

在商店选项卡中,您可以测试以下Webhook:

要进行测试:

  1. 在Webhook测试部分中,前往商店选项卡。
  2. 在下拉菜单中,选择商品类型。如果所选类型的商品未在发布商帐户中设置,请单击:
    • 连接 – 如果未连接该类型商品的模块
    • 配置 – 如果之前连接过模块,但尚未完成设置
      单击该按钮后,您将被重定向到与所选商品类型相对应的发布商帐户部分。创建商品后,返回Webhook测试部分并继续下一步 。
  3. 艾克索拉订单ID字段中输入任意值。
  4. 从下拉列表中选择商品的SKU并注明金额。您可以通过单击+并将它们添加到新行中来选择多个相同类型的商品。
  5. 选择支付订单所用的货币。
  6. 单击测试

包含指定数据的订单支付成功订单取消Webhook将发送到所提供的URL。测试每个Webhook类型的结果在测试Webhook按钮下方显示 。

Store testing 
section

支付

付款选项卡中,您可以测试以下Webhook:

要进行测试:

  1. 在测试部分,前往付款选项卡。
  2. 填写必填字段:

    1. 用户ID — 测试时,您可以使用任意字母和数字的组合。
    2. 公共用户ID — 用户已知的ID,例如电子邮件或昵称。如果您的项目中的支付中心 > 设置 > 其他设置部分启用了公共用户ID,则会显示此字段。
    3. 货币 — 从下拉列表中选择一种货币。
    4. 艾克索拉发票ID — 艾克索拉侧的交易 ID。测试时,您可以使用任何数值。
    5. 金额 — 支付金额。测试时,您可以使用任何数值。
    6. 发票ID — 您游戏侧的交易 ID。测试时,您可以使用任意字母和数字的组合。它不是成功付款的必需参数,但您可以传递它以将己侧的交易ID与艾克索拉侧交易ID关联。
  3. 单击测试Webhook

在指定的URL中,您将收到包含所填数据的Webhook。每个Webhook的测试结果(成功场景和错误场景)都在测试Webhook按钮下方显示。如果 您的项目中启用了公共用户ID,您还将看到用户搜索检查的结果。

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

Payments testing 
section

将URL保存在Webhook服务器字段时可以看到高级设置部分,您可以在其中授予在Webhook中接收详细信息的权限。为此,请将相应的 开关设置为。在每个权限的所在行中,您可以看到受该设置影响的Webhook列表。

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

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

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

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

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

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

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

Advanced settings

订阅

订阅选项卡中,您可以测试以下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/24185.30.21.0/24185.30.23.0/2435 .236.90.9034.102. 38.178

限制:

  • 应用程序的数据库中不应存在具有相同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,您的服务器必须返回:

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

如果没有收到订单支付成功订单取消Webhook的响应或者如果收到包含5xx代码的响应,则根据以下时间表重新发送Webhook:

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

自第一次尝试后12小时内最多可尝试20次发送Webhook。如果对于支付Webhook或退款Webhook未收到响应,或者如果收到带有5xx代码的响应,Webhook也 会以递增的时间间隔重新发送。 12小时内最多进行12次尝试。

注:

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

如果没有收到用户验证Webhook的响应或收到代码为4005xx的响应,将不重新发送用户验证Webhook。在这种情况下,会向用户显示错误,并且不发送支付订单支付成功webhook。

错误

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 用户与商店交互时发送。
订单支付成功 order_paid 订单付款后发送。
订单取消 order_canceled 订单取消时发送。
争议 dispute 当提出新争议时发送。