向用户发放购买物
使用从艾克索拉收到的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
- 在发布商帐户中打开您的项目，然后前往项目设置 > Webhooks部分。
- 在Webhook服务器字段中指定要接收Webhook的服务器URL，格式为
https://example.com。您也可以指定在工具中找到的URL来用于测试。 - 默认会生成一个用于项目Webhook签名的密钥。如要生成新密钥，请点击刷新图标。
- 单击启用Webhook。
在发布商帐户中测试Webhook
当您在项目中启用Webhook后，发布商帐户的高级设置下方会显示Webhook测试区域。
您可以测试以下Webhook：
| Webhook测试的选项卡名称 | Webhook名称和类型 |
|---|---|
| 付款和商店 | 用户验证 > 用户验证(user_validation) |
游戏服务 > 合并Webhook > 订单成功支付(order_paid) | |
游戏服务 > 合并Webhook > 订单取消(order_canceled) | |
| 订阅 | 用户验证 > 用户验证(user_validation) |
付款 > 支付(payment) | |
| 争议 | 反欺诈 > 争议(dispute) |
在缺少真实值的情况下，可输入任意值。
您还可以测试在沙盒或实时模式下进行购买时的Webhook。退款测试只支持实时模式。
向Webhook发送响应
要确认收到Webhook，您的服务器必须返回：
200、201或204HTTP代码（成功响应时）。- 带问题描述的
400HTTP代码（如未找到指定用户或传入的签名无效）。
如您的服务器发生临时问题，您的Webhook处理程序也可以返回5xx代码。
下一步
配置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。
有用链接
上次更新时间: 2026年1月8日发现了错别字或其他内容错误？ 请选择文本，然后按Ctrl+Enter。
