跳至主要内容

Fraud Reported Webhook

When a payment processor reports fraud on a completed payment, Aghanim sends a fraud.reported webhook to notify your game. This event arrives days or weeks after the original charge, when the card network or issuer retroactively flags a payment as fraudulent.

This webhook is activated through the Fraud reported event, selectable in Game → Webhooks.

Requirements

To use the fraud reported webhook from Aghanim, you should have the webhook server configured as follows:

  • HTTPS endpoint, accepting POST webhook requests.
  • Listen for events, generated and signed by Aghanim.
  • Handle the idempotency_key included in the webhook payload to prevent processing duplicate webhooks.
  • Respond with 2xx status codes if the fraud event was processed successfully, and 4xx or 5xx for denial or errors.

Configuration

  1. Develop a function for the fraud.reported webhook processing.
  2. Make your endpoint available.
  3. Register your endpoint within Aghanim account → Game → Webhooks → New Webhook by choosing the Fraud reported event type.

Alternatively, you can register your endpoint within Aghanim using the Create Webhook API method.

Request schema

下面是一个 fraud.reported 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": "fraud.reported",
  "event_data": {
    "id": "frd_aBcDeFgHiJkLmNoPqRs",
    "player_id": "2D2R-OP3C",
    "order_id": "ord_eCacpFwavzi",
    "payment_id": "pmt_eFgYpxryeKXpLKfmZstI",
    "fraud_type": "card_stolen",
    "amount": 9499,
    "currency": "USD",
    "payment_method": "cards",
    "reported_at": 1725547595
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": "idmpt_aXRlb...JkX2VFS",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": null,
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}

事件 Schema

键名类型描述
event_idstring阿哈利姆生成的唯一事件标识符。
game_idstring您的游戏在阿哈利姆中的唯一标识符。
event_typestring事件的类型， fraud.reported 在此情境下。
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事件的相关上下文信息。

The EventData schema

FieldTypeDescription
idstringUnique identifier for the fraud report
player_idstringThe player who made the payment
order_idstringThe order associated with the payment
payment_idstringThe payment that was flagged
fraud_typeenumNormalized fraud category (card_lost, card_stolen, unauthorized_card_use, counterfeit_card, fraudulent_application, other)
amountnumberPayment amount in minor currency units
currencystringPayment currency
payment_methodstringPayment method used (cards, apple_pay, google_pay, etc.)
reported_atintegerUnix timestamp when the fraud was reported by the payment processor
  1. Consider proactive refunds: Fraud reports arrive before formal chargebacks. Proactively refunding via the Refund API can avoid chargeback fees.
  2. Flag the player: Track fraud reports per player. Multiple fraud.reported events for the same player may indicate account compromise or abuse.
  3. Revoke items on refund: If you refund, also revoke the granted items via Item Remove.

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

On this page