跳到主要内容

服务端通知

服务端通知，是指从世游服务端发起的，到游戏服务端的 server-to-server 的 HTTP 调用。

HTTP 调用的标准由世游定义，游戏服务端负责对通知进行处理。

服务端通知总是使用 HTTP POST。

警告

为了通信的安全性，游戏服务端必须通过 HTTPS 对外服务，且必须支持 TLS 1.2 及以上。

请求鉴权​

服务端通知预期游戏侧对请求进行鉴权的方式，是 HTTP Request Signing。

签名方式请阅读 签名算法。

签名过程中使用的 Game ID 由世游分配。 签名使用的私钥，使用世游为每个游戏项目生成的 Secret Key。

如果请求的签名验证不通过，预期游戏服务端应当返回 HTTP 401 Unauthorized。

危险

游戏侧应当重视 Secret Key 的安全性，将其妥善保管，严格控制密钥的访问权限，并安全地分发至游戏服务器的运行环境。

请注意，Secret Key 一定不能放在客户端。

通知端点​

建议将两个通知端点设置为同一个地址，通过解析 HTTP Request Body 来区分 通知类型，参考示例：

https://webhook.example.com/combo/notifications

通知请求​

通知请求的 Content-Type 总是 application/json。

Request Body 为包含以下属性的 JSON Object。

PropertyTypeDescription
versionstring[1,16]世游服务端通知的版本号。当前版本固定为 1.0。
notification_idstring[1,64]每次通知的唯一 ID。游戏侧可用此值来对通知进行去重。
notification_typestring[1,32]用于标识通知类型，data 中的结构随着通知类型的不同而不同。
dataobject与 notification_type 对应的结构，是一个异构的 JSON Object。

通知响应​

  • 游戏侧收到通知后，需要在 5 秒内响应，否则会认为通知失败，后续会重复发送通知。
  • 相同的通知可能会多次发送给游戏侧，游戏侧必须能正确处理重复的通知（幂等性处理），如果已经处理过，则直接返回成功。
  • 如果游戏侧处理通知成功，应返回 HTTP 200。世游侧会认为此次通知被正常接收。
  • 如果游戏侧处理通知失败，应返回 HTTP 50x 或 HTTP 40x。世游侧会按照 重试策略 自动重新发起通知。
  • 服务端通知从功能上并不要求游戏侧在 Response Body 中返回数据。但建议游戏侧选择在 Response Body 中返回任意的 text/plain 文本内容用于辅助双方调试。

通知类型​

所有通知类型可分为两大类：

订单发货​

通知游戏服务端对订单发货。

此时 notification_type 字段的值为 ship_order。

此时 data 包含以下字段：

PropertyTypeRequiredDescription
order_idstring[1,64]True世游服务端创建的，标识订单的唯一 ID。
reference_idstring[8,64]True游戏侧用于标识创建订单请求的唯一 ID。
combo_idstring[1,64]True发起购买的用户的唯一标识。
product_idstring[1,64]True购买的商品 ID。
quantityintegerTrue购买的商品的数量。
currencystring[3]True订单币种代码。例如 USD CNY。
amountintegerTrue订单金额，单位为分。
contextstring[1,255]False游戏侧创建订单时提供的订单上下文，透传回游戏。
is_sandboxboolFalse标识通知的订单是否是沙盒订单, True 表示是沙盒订单，缺省或者 False 表示非沙盒订单。
信息

订单发货通知地址会使用游戏服务端调用 create-order 时传入的 notify_url。

游戏服务端接收到通知后，主要需要关注以下几点：

  1. 根据 签名算法 计算请求的签名，并验证签名正确性。
  2. 校验 order_id 和 refernence_id 是否存在，以及是否重复发货，如果重复发货，需要游戏服务端进行幂等处理。
  3. 校验订单中的 product_id，quantity，currency，amount 字段，确保订单内容正确。

订单退款​

通知游戏服务端订单已经被退款。

此时 notification_type 字段的值为 refund。

此时 data 包含以下字段：

PropertyTypeRequiredDescription
order_idstring[1,64]True世游服务端创建的，标识订单的唯一 ID。
reference_idstring[8,64]True游戏侧用于标识创建订单请求的唯一 ID。
combo_idstring[1,64]True发起购买的用户的唯一标识。
product_idstring[1,64]True购买的商品 ID。
quantityintegerTrue购买的商品的数量。
currencystring[3]True订单币种代码。例如 USD CNY。
amountintegerTrue订单金额，单位为分。
contextstring[1,255]False游戏侧创建订单时提供的订单上下文，透传回游戏。
is_sandboxboolFalse标识通知的订单是否是沙盒订单, True 表示是沙盒订单，缺省或者 False 表示非沙盒订单。
信息

目前仅支持来自 App Store 的退款通知。

订单退款通知地址会使用游戏服务端调用 create-order 时传入的 notify_url。

游戏侧可能需要对退款通知进行对应处理，例如扣除玩家充值获得的金币、道具等。

退款通知主要有以下用途：

  1. 对账：财务会对游戏侧、世游侧、应用商店侧（例如苹果）三方的支付流水进行对账。
  2. 数据分析：有些玩家可能会通过退款刷道具。针对这种 "恶意" 退款的玩家，游戏侧可以通过数据分析识别出这些玩家，并对其封号。

重试策略​

如果游戏侧在处理通知时未能按预期返回 HTTP 200，则世游服务端会按照以下策略进行重试：

在 168h 中发起最多 90 次重试，通知频率为 15s/30s/1m/2m/4m/8m/16m/32m/1h4m/2h/2h/2h/...

最后于 更新