订单退款 Webhook

阿哈利姆通过退款通知 Webhook 机制，在管理员通过阿哈利姆控制面板的交易模块执行退款操作时，及时通知您的游戏系统，并提供该退款事件的完整详情。

退款 Webhook 需要先在游戏 → Webhook 设置菜单中选择激活订单退款事件触发器，才能开始接收相关通知。

警告

当需要从玩家账户中移除游戏内商品时，可以调用 item.remove Webhook。订单退款 Webhook 的主要设计目的是补充 item.remove Webhook 的功能，提供更加完整和详细的退款交易数据。

要求

如需接入阿哈利姆的退款通知系统，请按照以下要求配置您的 Webhook 服务器：

HTTPS 端点，可接收 POST Webhook 请求。
监听由阿哈利姆生成并签名的事件。
当您的服务器成功处理退款事件时，应返回 2xx 系列状态码；如遇请求处理失败或需要拒绝该操作，则应返回 4xx 或 5xx 系列状态码。

配置步骤

为 order.refunded Webhook 处理开发一个函数。
部署您的端点使其可访问。
在您的 Aghanim 账户中注册您的端点 → 游戏 → 网络钩子 → 新建网络钩子 选择 订单退款 事件。

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

Request Schema

下面是一个 order.refunded 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.refunded",
  "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": "水晶",
        "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": "已退款",
    "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.refund",
  "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.refunded",
      "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": "水晶",
            "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": "已退款",
        "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.refund",
      "transaction_id": "whtx_eCacGbJVbvT",
      "context": null,
      "game_id": "gm_exTAyxPsVwh"
    }'
            

事件 Schema

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

EventContext Schema

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

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`	`string`	订单货币单位.
`country`	`string`	付款方式所关联的国家/地区。
`created_at`	`number`	以 Unix 时间戳表示的订单创建日期。
`modified_at`	`number`	以 Unix 时间戳表示的订单最后修改日期。
`items`	`Item[]`	包含已购买商品的详情。
`fees`	`Fees`	关于税费的信息。
`revenue_usd`	`number`	预期净收入会按预计汇率及支付手续费折算为美元美分。实际金额需与支付平台核账确认，一般于次月 10 日前完成结算。
`metadata`	`object\|null`	自定义的键值对数据对象，用于存储与订单相关的额外信息。
`creator`	`Creator\|null`	Information about creator associated with the order.

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`	如果无法向玩家发放主要商品，系统将提供的备选商品。

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

NestedItem Schema

键名	类型	描述
`id`	`string`	阿哈利姆生成的商品唯一标识符。
`name`	`string`	商品名称。
`description`	`string\|null`	商品描述。
`sku`	`string`	商品的 SKU 标识符，必须确保在游戏系统和阿哈利姆上保持一致。
`quantity`	`number`	商品数量。
`type`	`string`	商品类型，可选值包括： `item`, `bundle`.
`nested_items`	`NestedItem[]\|null`	礼包内包含的所有单独商品组成的数组。

PlayerContext Schema

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

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