设置订单状态跟踪
要将商品发放给用户，需确保付款已成功。
要跟踪所创建订单的状态并进行验证，需在应用程序的服务器侧配置Webhook的处理。
在艾克索拉侧，针对商品购买和退款情况，有两种接收Webhook的方式：付款及交易数据信息和所购商品信息可以分开发送，也可以合并到一个Webhook中。所有新项目默认采用合并Webhook方式。
如需切换到接收合并Webhook的新方式，请联系您的客户成功经理或发送邮件至csm@xsolla.com。
要实现游戏内商店和支付管理的完整功能，必须实现对主要Webhook的处理：
| Webhook名称 | 描述 |
|---|---|
用户验证 > 用户验证(user_validation) | 在支付过程的不同阶段发送，用于确保用户已在游戏中注册。 |
游戏服务 > 合并Webhook > 订单成功支付(order_paid) | 包含支付数据、交易详情和所购商品的信息。使用此Webhook中的数据为用户添加商品。 |
游戏服务 > 合并Webhook > 订单取消(order_canceled) | 包含取消的付款的数据、交易详情和所购商品信息。使用此Webhook中的数据移除购买的商品。 |
下图显示了使用合并Webhook购买商品和退款的过程。
sequenceDiagram
participant User
participant GameClient as Game Client
participant Xsolla
participant GameServer as Game Server
%% Item Purchase
Note over User, GameServer: Item purchase
User ->> GameClient: Logs in
GameClient ->> Xsolla: Sends user authentication request
Xsolla -->> GameClient: Returns JWT / OAuth 2.0 token
GameClient ->> Xsolla: Sends JWT, project ID, pagination parameters
Xsolla -->> GameClient: Returns array of items
GameClient -->> User: Displays storefront
User ->> GameClient: Selects item and clicks Buy
GameClient ->> Xsolla: Creates order request
Xsolla -->> GameClient: Returns payment token
GameClient ->> Xsolla: Opens payment UI URL with received token
Xsolla ->> GameServer: Sends User validation webhook
GameServer -->> Xsolla: Returns success status code
Xsolla -->> User: Displays payment UI
User ->> Xsolla: Chooses payment method and clicks Pay
Xsolla ->> GameServer: Sends Successful payment for order webhook
GameServer ->> GameServer: Grants purchases to user
GameServer -->> Xsolla: Returns success status code
Xsolla -->> User: Shows successful purchase screen
%% Refund / Chargeback
Note over User, GameServer: Refund / Chargeback
User ->> Xsolla: Requests refund or chargeback
Xsolla ->> GameServer: Sends Order cancellation webhook
GameServer ->> GameServer: Removes items from user inventory
GameServer -->> Xsolla: Returns success status code
Xsolla -->> User: Refunds the payment
如您的应用程序侧实现了商品目录个性化，请设置合作伙伴侧目录个性化的处理。
设置Webhook的发送
要在艾克索拉侧配置Webhook：
- 在发布商帐户的项目中前往设置 > Webhook部分。
- 在Webhook服务器字段中，按
https://example.com格式指定接收Webhook的服务器URL。您也可以使用Webhook测试工具中提供的URL。
- 默认会生成一个用于项目Webhook签名的密钥。如要生成新密钥，请点击刷新图标。
- 单击启用Webhook。
添加Webhook监听器
Webhook监听器是一个程序代码，可以在指定的URL地址接收传入的Webhook、生成签名及向艾克索拉Webhook服务器发送响应。
生成签名
接收Webhook时，应确保数据传输的安全性。为此，必须从Webhook数据生成一个签名并确保它与HTTP请求头中发送的签名匹配。
要生成签名：
- 将请求正文中的JSON与项目密钥串联起来。
- 对第一步中得到的字符串应用SHA-1加密散列函数。
向Webhook发送响应
要确认收到Webhook，您的服务器必须返回：
200、201或204HTTP代码（成功响应时）。- 带问题描述的
400HTTP代码（如未找到指定用户或传入的签名无效）。
如您的服务器发生临时问题，您的Webhook处理程序也可以返回5xx代码。
如果艾克索拉服务器未收到对订单成功支付或订单取消Webhook的响应，或收到了包含5xx代码的响应，将根据以下规则重新发送Webhook：
- 间隔5分钟尝试2次
- 间隔15分钟尝试7次
- 间隔60分钟尝试10次
自首次尝试起，12小时内最多尝试发送Webhook20次。
支付和退款Webhook的重试逻辑在各自的Webhook页面中有详细说明。
如果艾克索拉服务器未收到用户验证Webhook的响应，或收到400或5xx代码的响应，将不会重新发送用户验证Webhook。
该情况下会向用户显示一个错误，且不会发送支付和订单成功支付Webhook。
配置Webhook中的商品信息
您可以通过items数组配置在订单成功支付和订单取消Webhook中包含的商品数据。
启用附加参数包含
启用以下附加参数的包含功能以标识：
- 商品是否免费(
is_free) - 商品是否为奖励(
is_bonus) - 商品是否为捆绑包内容(
is_bundle_content)
要接收这些参数，您需要使用更新Webhook设置信息API调用将Webhook切换到版本2。在版本1（默认版本）中，这些参数不可用。
包含附加参数的items数组示例：
- json
1"items": [
2 {
3 "sku": "com.xsolla.item_new_1",
4 "type": "bundle",
5 "is_pre_order": false,
6 "is_free": false,
7 "is_bonus": false,
8 "is_bundle_content": false,
9 "quantity": 1,
10 "amount": "1000",
11 "promotions": []
12 },
13 {
14 "sku": "com.xsolla.gold_1",
15 "type": "virtual_currency",
16 "is_pre_order": false,
17 "is_free": false,
18 "is_bonus": false,
19 "is_bundle_content": true,
20 "quantity": 1500,
21 "amount": "[null]",
22 "promotions": []
23 }
24 ]
禁用捆绑包内容包含
默认情况下，Webhook会将捆绑包中的所有商品作为单独商品列表包含在内。您可以将Webhook配置为仅包含捆绑包本身，而不列出其内容。
在这种情况下，捆绑包中包含的商品不会出现在items数组中。在上面的数组中，SKU为com.xsolla.gold_1的商品（作为捆绑包的一部分）未被包含。
禁用捆绑包内容时的items数组示例：
- json
1
2"items": [
3 {
4 "sku": "com.xsolla.item_new_1",
5 "type": "bundle",
6 "is_pre_order": false,
7 "is_free": false,
8 "is_bonus": false,
9 "is_bundle_content": false,
10 "quantity": 1,
11 "amount": "1000",
12 "promotions": []
13 }
14 ]
如需禁用捆绑包内容包含功能，请联系您的客户成功经理或发送邮件至csm@xsolla.com。
发现了错别字或其他内容错误？ 请选择文本，然后按Ctrl+Enter。
