设置订单状态跟踪
要将商品发放给用户，需确保付款已成功。
要跟踪所创建订单的状态并进行验证，需在应用程序的服务器侧配置Webhook的处理。
艾克索拉侧设置了两种接收商品购买和退款Webhook的方式——付款及交易数据信息和所购商品信息可以分开发送，也可以合并到一个Webhook中。
如需切换到接收合并Webhook的新方式，请联系您的客户成功经理或发送邮件至csm@xsolla.com。
要实现游戏内商店和支付管理的完整功能，必须实现对主要Webhook的处理：
| Webhook名称 | 描述 |
|---|---|
用户验证 > 用户验证(user_validation) | 在支付过程的不同阶段发送，用于确保用户已在游戏中注册。 |
付款 > 支付(payment) | 包含支付数据和交易详情。 |
游戏服务 > 单独Webhook > 订单成功支付(order_paid) | 包含所购商品的信息和交易详情。使用此Webhook中的数据为用户添加商品。 |
付款 > 退款(refund) | 包含支付数据和交易详情。 |
游戏服务 > 单独Webhook > 订单取消(order_canceled) | 包含所购商品及取消的交易的ID信息。使用此Webhook的数据移除购买的商品。 |
下图显示了使用单独Webhook购买商品和退款的过程。
如您的应用程序侧实现了商品目录个性化，请设置合作伙伴侧目录个性化的处理。
设置Webhook的发送
要在艾克索拉侧配置Webhook：
- 在发布商帐户中打开您的项目，前往项目设置 > Webhooks部分。
- 在Webhook服务器字段中，指定艾克索拉要向其发送Webhook的URL。
https://example.com格式指定您服务器的URL。请使用HTTPS协议传输数据，不支持HTTP协议。- 单击启用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的响应，或收到5xx代码的响应，也将尝试重新发送Webhook且重试的间隔逐渐拉长。12小时内最多尝试12次。
如果艾克索拉服务器未收到用户验证Webhook的响应，或收到400或5xx代码的响应，将不会重新发送用户验证Webhook。
该情况下会向用户显示一个错误，且不会发送支付和订单成功支付Webhook。
配置Webhook中的商品信息
您可以通过items数组配置在订单成功支付和订单取消Webhook中包含的商品数据。
启用附加参数包含
启用以下附加参数的包含功能以标识：
- 商品是否免费(
is_free) - 商品是否为奖励(
is_bonus) - 商品是否为捆绑包内容(
is_bundle_content)
要接收这些参数，您需要使用更新Webhook设置信息API调用将Webhook切换到版本2。在版本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 {
15 "sku": "com.xsolla.gold_1",
16 "type": "virtual_currency",
17 "is_pre_order": false,
18 "is_free": false,
19 "is_bonus": false,
20 "is_bundle_content": true,
21 "quantity": 1500,
22 "amount": "[null]",
23 "promotions": []
24 }
25 ],
禁用捆绑包内容包含
默认情况下，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。
概览
艾克索拉事件API让您能够使用GetUpdates服务直接在应用程序客户端接收和处理支付信息，而无需在服务器上使用Webhook。如果您希望加快和简化集成过程，无需配置和维护服务器来处理支付Webhook，建议使用此集成方案。
游戏与艾克索拉的交互流程：
如何设置
要通过API从艾克索拉接收事件：
- 在您的发布商帐户项目中，前往项目设置 > Webhooks部分。
- 单击使用API。设置将自动保存。
- 从应用程序客户端向
https://getupdate.xsolla.com/events发送请求以获取支付信息。有关详细信息，请参阅API参考。在响应中，您将收到与支付Webhook格式相同的支付数据。 - 如果支付成功，向用户发放购买的商品。
API参考
获取用户未处理的事件列表
- http
1GET https://getupdate.xsolla.com/events
安全认证：Bearer User JWT令牌
响应示例：
- json
1{
2 "events": [
3 {
4 "id": 49, // event_id
5 "status": 0,
6 "created_at": "2025-04-03T21:21:27Z",
7 "data": {
8 "notification_type": "payment",
9 "purchase": {
10 "order": {
11 "id": 000000001,
12 "lineitems": [
13 {
14 "quantity": 1,
15 "sku": "skill"
16 }
17 ]
18 }
19 },
20 ...
21 }
22 }
23 ]
24}
标记事件为已处理
- http
1POST https://getupdate.xsolla.com/events/<event_id>/processed
event_id是从获取用户未处理的事件列表API调用响应中获取的events.id参数。
安全认证：Bearer User JWT令牌
发现了错别字或其他内容错误？ 请选择文本，然后按Ctrl+Enter。
