跳至主要内容

订单支付 Webhook

阿哈利姆的订单支付 Webhook 会通知您的游戏有关游戏枢纽中成功完成的支付，并提供交易的详情。

该 Webhook 通过订单支付事件激活，可在 游戏 → Webhook 中选择。

警告

要向玩家账户添加游戏内商品，请使用 item.add Webhook。 订单支付 Webhook 旨在提供详细数据，适用于 item.add 信息不足的情况。

支付流程图
支付流程图

要求

要使用阿哈利姆的订单支付 Webhook，请按照以下要求配置您的 Webhook 服务器：

  • HTTPS 端点，可接收 POST Webhook 请求。
  • 监听由阿哈利姆生成并 签名 的事件。
  • 处理 Webhook 负载中包含的 idempotency_key，以防止重复处理 Webhook。
  • 如果已成功将购买的商品添加到账户，则响应 2xx 状态码；如有拒绝或错误，则用 4xx 或 5xx 状态码。

配置步骤

  1. 为 order.paid Webhook 处理开发一个函数。
  2. 部署您的端点使其可访问。
  3. 进入您的Aghanim账户后，依次导航至游戏 → Webhook → 新建 Webhook，然后在事件类型列表中选择订单支付选项来注册您的端点。

或者，您也可以使用 Create Webhook API 方法在阿哈利姆中注册您的端点。

Request Schema

下面是一个 order.paid Webhook 请求示例：

POST /your/webhook/uri HTTP/1.1
Content-Type: application/json
Host: your-webhook-endpoint.com
User-Agent: Aghanim/0.1.0
X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812
X-Aghanim-Signature-Timestamp: 1725548450

{
  "event_type": "order.paid",
  "event_data": {
    "amount": 9499,
    "company_id": "com_exTAxmkZQCO",
    "country": "US",
    "created_at": 1725547595,
    "currency": "USD",
    "game_id": "gm_exTAyxPsVwh",
    "revenue_usd": 9099.123,
    "fees": {
      "aghanim_fee_usd": 10.11,
      "payment_system_fee_usd": 15.123,
      "taxes_usd": 481.198933
    },
    "items": [
      {
        "id": "itm_exTBZQmIlDz",
        "name": "Crystals",
        "description": "Reign supreme over your rivals with this massive crystal treasure.",
        "sku": "crystals",
        "quantity": 480000,
        "price": 9499,
        "price_decimal": 94.99,
        "currency": "USD",
        "type": "item",
        "nested_items": null
      }
    ],
    "modified_at": 1725547657,
    "player_id": "2D2R-OP3C",
    "receipt_number": "2409051289614565",
    "status": "paid",
    "user_id": "usr_eymySUreClx",
    "metadata": null
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": "idmpt_aXRlb...JkX2VFS",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "checkout.purchase",
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}

事件 Schema

键名类型描述
event_idstring阿哈利姆生成的唯一事件标识符。
game_idstring您的游戏在阿哈利姆中的唯一标识符。
event_typestring事件的类型， order.paid 在此情境下。
event_timenumber以 Unix 时间戳表示的事件发生日期。
event_dataEventData包含事件特定数据的字段，其中可能包含用于继承对象的各种键值。
idempotency_keystring即使出现重试情况，也能确保 Webhook 操作只执行一次。
request_idstring|null如果事件是通过 API 请求触发的，此字段将包含对应的请求 ID。
sandboxboolean标识事件是否来自沙盒测试环境的指示器。
triggerstring|nullThe trigger that caused the event to be sent.
transaction_idstring阿哈利姆生成的交易标识符。在同一交易过程中触发的多个事件可能共享相同的交易 ID。
contextEventContext|null事件的相关上下文信息。

EventContext Schema

键名类型描述
orderOrderContext|null与事件相关的订单信息（如果适用）。
playerPlayerContext|null（可选）玩家信息。如需启用，请在webhook设置中选择“添加玩家上下文”。

EventData Schema

键名类型描述
idstring阿哈利姆生成的订单唯一标识符。
company_idstring您的企业在阿哈利姆中的唯一标识符。
game_idstring您的游戏在阿哈利姆中的唯一标识符。
user_idstring用户在阿哈利姆游戏枢纽中的唯一标识符。
player_idstring唯一的 用于玩家身份验证的玩家标识符.
statusstring订单状态，可选值包括： created,captured,paid,canceled,refunded,refund_requested.
amountnumber订单金额使用 最小货币单位.
currencystring订单 货币单位.
countrystring付款方式所关联的国家/地区。
created_atnumber以 Unix 时间戳表示的订单创建日期。
modified_atnumber以 Unix 时间戳表示的订单最后修改日期。
itemsItem[]包含已购买商品的详情。
feesFees关于税费的信息。
revenue_usdnumber预期净收入会按预计汇率及支付手续费折算为美元美分。实际金额需与支付平台核账确认，一般于次月 10 日前完成结算。
metadataobject|null自定义的键值对数据对象，用于存储与订单相关的额外信息。
creatorCreator|nullInformation about creator associated with the order.

Item Schema

KeyType描述
idstring阿哈利姆生成的商品唯一标识符。
namestring商品名称。
descriptionstring|null商品描述。
skustring商品的 SKU 标识符，必须确保在游戏系统和阿哈利姆上保持一致。
quantitynumber商品数量。
pricenumber商品价格使用 最小货币单位.
price_decimalnumber商品价格以十进制单位表示。
currencystring商品价格 货币单位.
typestring商品类型，可选值包括： item, bundle.
nested_itemsNestedItem[]|null礼包内包含的所有单独商品组成的数组。
fallback_itemItem|null如果无法向玩家发放主要商品，系统将提供的备选商品。

商品类型 bundle 可以包含多个嵌套商品。
您可以选择处理礼包的通用 SKU，也可以单独处理每个嵌套商品。

NestedItem Schema

键名类型描述
idstring阿哈利姆生成的商品唯一标识符。
namestring商品名称。
descriptionstring|null商品描述。
skustring商品的 SKU 标识符，必须确保在游戏系统和阿哈利姆上保持一致。
quantitynumber商品数量。
typestring商品类型，可选值包括： item, bundle.
nested_itemsNestedItem[]|null礼包内包含的所有单独商品组成的数组。

PlayerContext Schema

键名类型描述
player_idstring|null唯一的 用于玩家身份验证的玩家标识符.
playerobject|null使用复合授权时的玩家ID组件。
attributesAttributes阿哈利姆需要的基本玩家属性。
custom_attributesCustomAttributes自定义玩家属性。

需要技术支持？
联系我们的集成技术团队： integration@aghanim.com

On this page