Xsolla-logo

概览

如果艾克索拉侧发生了预先配置的事件,可通过Webhook收到即时通知。您可以使用Webhook来自动化应用程序的后端和补充功能。

可收到通知的事件示例:

  • 支付,包括购买虚拟货币和物品
  • 定期付款和订阅操作
  • 退款

当配置的事件发生时,艾克索拉会通过webhook通知您的系统。例如,您可以在收到webhook后执行以下操作:

  • 添加到用户的余额
  • 为用户解锁新物品
  • 开始订阅服务
  • 在检测到欺诈后拦截用户

以下是支付处理Webhook工作原理的示例:

支付处理Webhook

设置服务器侧

必须应用以下设置才能使webhook正常工作:

  • 监听以下IP地址的webhook:185.30.20.0/24185.30.21.0/24185.30.23.0/24
  • 应用程序数据库不得包含ID相同的两个成功交易。

注意

如果收到的Webhook的交易ID在数据库中已存在,则监听器应返回该次交易的上次处理结果。不推荐向用户重复扣款或在数据库中创建重复记录。

  • 创建的签名必须与HTTP头中传递的签名相匹配。
  • 如果出现错误,返回代码400(例如,缺少必填参数或扣款失败时)。对于服务器的临时错误,请使用代码 500。

注:

艾克索拉API接受传统HTTP响应代码指示请求是成功还是失败。代码204指示处理成功。

由于网络连接并不总是100%可靠,因此Webhook可能会丢失或延迟。为解决此问题,艾克索拉会重新发送失败的Webhook,直到侦听器收到它们。初始Webhoo k发送之后12小时内会重新发送Webhook,直到侦听器确认接收。最大重试次数为12次。

注:

尽管网络连接可能导致出错,但最有可能导致丢失、延迟或重复Webhook的原因是监听器本身存在逻辑问题。

请求签名

数字签名可实现安全的数据传输。要生成签名:

  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"
      }
    }'

错误

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 状态设置为非续订时发送。
获取游戏密钥 get_pincode 在艾克索拉API需要获取游戏密钥时发送。
用户余额:手动更新 user_balance_operation 手动更改用户余额时发送。操作类型——internal
用户余额:付款 user_balance_operation 当用户付款时发送。操作类型——payment
用户余额:退款 user_balance_operation 当用户取消付款时发送。操作类型——cancellation
用户余额:兑换优惠券 user_balance_operation 当用户在游戏中兑换优惠券以接收虚拟物品或虚拟货币时发送。操作类型——coupon
用户余额:购买 user_balance_operation 当用户在游戏中进行购买时发送。操作类型——inGamePurchase
获取好友 friends_list 当用户发送好友列表请求时发送。
激活密钥 redeem_key 用户激活密钥时发送。
升级退款 upgrade_refund 取消升级时发送。
添加支付账户 payment_account_add 当用户添加或保存支付帐户时发送。
删除支付账户 payment_account_remove 用户从已保存的帐户中删除了支付帐户时发送。