跳至主要内容

支付 Webhooks

当玩家尝试支付订单时，会创建一个支付。 阿哈利姆的支付事件 Webhook 将通知您的游戏与订单相关的任何支付状态更改，并提供所有可能状态的详细信息以供分析和跟踪。

此Webhooks通过支付事件事件激活，可在游戏 → Webhooks中选择。

如果玩家多次尝试支付但未成功或未完成，单个订单可以关联多个支付。

处理重复支付事件

当付款详细信息（金额、佣金、税款）在初步事件后更新时，可能会多次发送相同付款ID的支付事件。 即使付款状态保持不变，这种情况也会发生，因为这些更新会影响收入跟踪和分析。

处理支付事件时：

  • 使用 idempotency_key 来识别重复事件
  • 忽略重复事件或使用最新付款信息更新记录
  • 不要抛出错误，因为这将根据重试计划触发 webhook 重试
  • 请注意，对同一订单的多次支付尝试将具有不同的支付ID (id 字段)，而不是重复事件

支付状态

支付 Webhook 会在以下任一支付状态下触发：

  • succeeded – 支付成功完成并从用户账户中扣款
  • canceled – 用户在支付过程中取消了支付
  • chargeback – 支付因退款请求被取消
  • declined – 支付方法被拒，支付无法完成
  • dispute – 用户针对该支付向支付方式发起了争议
  • expired – 支付因未及时完成而过期
  • pending – 支付由用户发起，等待完成
  • refunded – 支付已退款且款项已返还给用户
  • rejected – 支付被标记为潜在欺诈且未处理
  • voided – 在转账之前支付即被作废

要求

要使用阿哈利姆的支付事件 Webhook，您需要按以下方式配置 Webhook 服务器：

  • HTTPS 端点，接受 POST webhook 请求。
  • 监听 Aghanim 生成并签名的事件。
  • 处理 Webhook 负载中包含的 idempotency_key，以防止重复处理 Webhook。
  • 如果支付事件成功处理，响应 2xx 状态码，错误或拒绝则响应 4xx 或 5xx。

配置步骤

  1. 为 payment.* webhook 处理开发一个函数。
  2. 使您的端点可用。
  3. 在Aghanim账户内注册您的端点，路径为 → 游戏 → Webhooks → 新建Webhook，选择支付事件类型。

或者，您可以使用 Create Webhook API 方法在 Aghanim 内注册您的端点。

Request schema

下面是一个 payment.succeeded 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": "payment.succeeded",
  "event_data": {
    "id": "pmt_eFgYpxryeKXpLKfmZstI",
    "order_id": "ord_eCacpFwavzi",
    "receipt_number": "2409051289614565",
    "status": "succeeded",
    "amount": 9499,
    "currency": "USD",
    "payment_method": "cards",
    "created_at": 1725547595,
    "modified_at": 1725547657,
    "metadata": null,
    "decline_reason_code": null,
    "decline_reason": null,
    "three_d_secure_result": "authenticated",
    "three_d_secure_flow": "challenge"
  },
  "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事件的类型， payment.succeeded 在此情境下。
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。
contextobject|null事件的相关上下文信息。

EventData Schema

字段名类型描述
idstring支付的唯一标识符。
order_idstring关联订单的唯一标识符。
receipt_numberstring人类可读的收据编号。
statusenum当前支付状态 (成功、取消、退款请求、拒绝、争议、过期、待处理、已退款、已拒绝、已作废)。
amountnumber按 小额货币单位 计算的支付金额。
currencystring支付 货币。
payment_method字符串使用的支付方式（卡、apple_pay、google_pay、paypal等）
created_atinteger支付创建时的 Unix 时间戳。
modified_atinteger支付最后修改时的 Unix 时间戳。
metadata对象\无
decline_reasonstring\null
decline_reason_codestring\null
three_d_secure_resultstring\null
three_d_secure_flowstring\null

Event Types

根据支付状态变化触发以下事件类型的 Webhook：

  • payment.succeeded
  • payment.canceled
  • payment.chargeback
  • payment.declined
  • payment.dispute
  • payment.expired
  • payment.pending
  • payment.refunded
  • payment.rejected
  • payment.voided

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

On this page