订单取消 Webhook

阿哈利姆通过订单取消通知 Webhook ，在交易被银行或支付系统撤销时立即通知您，并提供该事件的详情。

订单取消 Webhook 需要在游戏 → Webhook 设置菜单中选择激活对应的事件触发器。

警告

当需要从玩家账户中移除游戏内商品时，可以调用 item.remove Webhook。订单取消 Webhook 的主要目的是在 item.remove 功能无法满足需求时，为您提供更加详细的数据信息。

要求

如需接入阿哈利姆的订单取消 Webhook 功能，请按照以下要求配置您的 Webhook 服务器：

HTTPS 端点，可接收 POST Webhook 请求。
监听由阿哈利姆生成并签名的事件。
处理 Webhook 负载中包含的 idempotency_key，以防止重复处理 Webhook。
当您的服务器成功处理订单取消事件时，应返回 2xx 系列状态码；如遇拒绝处理或发生错误的情况，则应返回 4xx 或 5xx 系列状态码。

配置步骤

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

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

触发器值

值	描述
`checkout.cancel`	当订单被取消时（银行或支付系统撤销交易）。
`test`	在 Dashboard 中使用“Send test event”时。

有关 order.canceled 与其他事件类型的关系，请参阅完整的事件与触发器矩阵。

Request Schema

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

HTTP
cURL

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.canceled",
  "event_data": {
    "amount": 9499,
    "company_id": "com_exTAxmkZQCO",
    "country": "US",
    "created_at": 1725547595,
    "currency": "USD",
    "game_id": "gm_exTAyxPsVwh",
    "id": "ord_eCacpFwavzi",
    "items": [
      {
        "id": "itm_exTBZQmIlDz",
        "name": "Crystals",
        "description": "统治你的对手，拥有这一大堆巨大的水晶财富。",
        "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": "canceled",
    "user_id": "usr_eymySUreClx",
    "metadata": null,
    "creator": null
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": "idmpt_aXRlb...JkX2VFS",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "checkout.cancel",
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}
            

curl "https://your-webhook-endpoint.com/your/webhook/uri" \
    -X POST \
    -H "Content-Type: application/json" \
    -H "User-Agent: Aghanim/0.1.0" \
    -H "X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812" \
    -H "X-Aghanim-Signature-Timestamp: 1725548450" \
    -d '{
      "event_type": "order.canceled",
      "event_data": {
        "amount": 9499,
        "company_id": "com_exTAxmkZQCO",
        "country": "US",
        "created_at": 1725547595,
        "currency": "USD",
        "game_id": "gm_exTAyxPsVwh",
        "id": "ord_eCacpFwavzi",
        "items": [
          {
            "id": "itm_exTBZQmIlDz",
            "name": "Crystals",
            "description": "统治你的对手，拥有这一大堆巨大的水晶财富。",
            "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": "canceled",
        "user_id": "usr_eymySUreClx",
        "metadata": null,
        "creator": null
      },
      "event_time": 1725548450,
      "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
      "idempotency_key": "idmpt_aXRlb...JkX2VFS",
      "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
      "sandbox": false,
      "trigger": "checkout.cancel",
      "transaction_id": "whtx_eCacGbJVbvT",
      "context": null,
      "game_id": "gm_exTAyxPsVwh"
    }'
            

事件 Schema

键名	类型	描述
`event_id`	`string`	阿哈利姆生成的唯一事件标识符。
`game_id`	`string`	您的游戏在阿哈利姆中的唯一标识符。
`event_type`	`string`	事件的类型， `order.canceled` 在此情境下。
`event_time`	`number`	以 Unix 时间戳表示的事件发生日期。
`event_data`	`EventData`	包含事件特定数据的字段，其中可能包含用于继承对象的各种键值。
`idempotency_key`	`string`	即使出现重试情况，也能确保 Webhook 操作只执行一次。
`request_id`	`string\|null`	如果事件是通过 API 请求触发的，此字段将包含对应的请求 ID。
`sandbox`	`boolean`	标识事件是否来自沙盒测试环境的指示器。
`trigger`	`string\|null`	触发该事件发送的触发器。
`transaction_id`	`string`	阿哈利姆生成的交易标识符。在同一交易过程中触发的多个事件可能共享相同的交易 ID。
`context`	`EventContext\|null`	事件的相关上下文信息。

EventContext Schema

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

订单货币与支付货币

一个订单包含两组货币/金额，二者可能不同：

currency + amount — 用户在结账时看到的内容（订单货币及其金额）。
payment_currency + payment_amount — 支付服务商实际收取的内容。

当某笔交易不支持订单货币时，二者会不同：金额会被转换为该国家/地区支付方式默认使用的货币。例如，塞尔维亚的玩家在结账时看到以 RSD 计价，但该笔交易不支持 RSD，因此支付会被转换并以 EUR 收取。结果是 currency = RSD、amount 以 RSD 计，而 payment_currency = EUR、payment_amount 以 EUR 计。

需要处理两种情况：

虚拟货币订单： payment_currency 为哨兵值 VC，而非法定货币的 ISO 4217 代码。
历史订单 在该字段存在之前创建的订单，其 payment_currency 为 null。通常应将该字段视为可选——它是向后兼容的新增字段，可能为 null 或缺失。

EventData Schema

键名	类型	描述
`id`	`string`	阿哈利姆生成的订单唯一标识符。
`company_id`	`string`	您的企业在阿哈利姆中的唯一标识符。
`game_id`	`string`	您的游戏在阿哈利姆中的唯一标识符。
`user_id`	`string`	用户在阿哈利姆游戏枢纽中的唯一标识符。
`player_id`	`string`	唯一的用于玩家身份验证的玩家标识符.
`status`	`string`	订单状态，可选值包括： `created`,`captured`,`paid`,`canceled`,`refunded`,`refund_requested`.
`amount`	`number`	订单金额使用 `currency`, ，以最小货币单位.
`currency`	`string`	结账时向用户显示的订单货币（ISO 4217）。
`payment_amount`	`number\|null`	最终收取的金额，货币单位为 `payment_currency`, 含税，以主要货币单位表示。
`payment_currency`	`string\|null`	支付服务商收取的最终金额的货币（ISO 4217）。可能与以下不同： `currency`.
`country`	`string`	付款方式所关联的国家/地区。
`created_at`	`number`	以 Unix 时间戳表示的订单创建日期。
`modified_at`	`number`	以 Unix 时间戳表示的订单最后修改日期。
`items`	`Item[]`	包含已购买商品的详情。
`fees`	`Fees`	关于税费的信息。
`revenue_usd`	`number`	预期净收入会按预计汇率及支付手续费折算为美元美分。实际金额需与支付平台核账确认，一般于次月 10 日前完成结算。
`metadata`	`object\|null`	自定义的键值对数据对象，用于存储与订单相关的额外信息。
`creator`	`Creator\|null`	与该订单关联的创作者信息。

Item Schema

Key	Type	描述
`id`	`string`	阿哈利姆生成的商品唯一标识符。
`name`	`string`	商品名称。
`description`	`string\|null`	商品描述。
`sku`	`string`	商品的 SKU 标识符，必须确保在游戏系统和阿哈利姆上保持一致。
`quantity`	`number`	商品数量。
`price`	`number`	商品价格使用最小货币单位.
`price_decimal`	`number`	商品价格以十进制单位表示。
`currency`	`string`	商品价格货币单位.
`type`	`string`	商品类型，可选值包括： `item`, `bundle`.
`nested_items`	`NestedItem[]\|null`	礼包内包含的所有单独商品组成的数组。
`fallback_item`	`Item\|null`	如果无法向玩家发放主要商品，系统将提供的备选商品。
`source`	`string`	标识该商品被发放的原因，可选值包括： `order`, `bonus`, `bundle`, `coupon`, `lootbox`, `free_item`, `liveops`, `daily_reward`, `loyalty_reward`, `progression_program`, `rolling_offer`, `pick_one_offer`.
`metadata`	`object\|null`	该商品的自定义键值对，用于支持您端的额外逻辑。

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

NestedItem Schema

键名	类型	描述
`id`	`string`	阿哈利姆生成的商品唯一标识符。
`name`	`string`	商品名称。
`description`	`string\|null`	商品描述。
`sku`	`string`	商品的 SKU 标识符，必须确保在游戏系统和阿哈利姆上保持一致。
`quantity`	`number`	商品数量。
`fallback_item`	`Item\|null`	如果无法向玩家发放主要商品，系统将提供的备选商品。
`metadata`	`object\|null`	该商品的自定义键值对，用于支持您端的额外逻辑。

PlayerContext Schema

键名	类型	描述
`player_id`	`string\|null`	唯一的用于玩家身份验证的玩家标识符.
`player`	`object\|null`	使用复合授权时的玩家ID组件。
`attributes`	`Attributes`	阿哈利姆需要的基本玩家属性。
`custom_attributes`	`CustomAttributes`	自定义玩家属性。

创作者 Schema

键名	类型	描述
`name`	`string`	创作者的名称。
`payout_decimal_usd`	`number`	创作者的支付金额（美元，主要单位）。

需要技术支持？
联系我们的集成技术团队： [email protected]