事件接入 API - 非资金类交易监控

交易是资金本身。事件则是你的平台掌握的其他一切信息：提现之前的那次登录、在两个账户之间转移筹码的那局牌、被重复领取的奖金、一周后才到达的拒付。事件采用统一的信封结构（每个类别均相同），具备设计上的幂等性，并由同一规则引擎评估，该引擎也为你的交易评分。

事件接入默认关闭，需要选择开启。请在 Transactions → Settings → Event monitoring 中开启。在开启之前，不会有任何变化：你现有的交易规则仍只针对交易触发。规则默认只作用于交易，除非你明确纳入事件，否则不会意外创建事件规则。在开启之前，每个写入通道（POST /v3/events/、POST /v3/events/batch/、POST /v3/events/sdk-token/，以及 /v1/events/ 设备通道）都会返回 403 和 {"code": "event_monitoring_disabled"}，且不会存储、补充信息或评估任何内容。读取不受影响。

Endpoints

Endpoint	认证	用途
`POST /v3/events/`	API 密钥	从你的后端提交一个事件
`POST /v3/events/batch/`	API 密钥	单次请求最多提交 500 个事件
`POST /v3/events/sdk-token/`	API 密钥	签发限定范围的设备凭证
`POST /v1/events/`	`X-Monitoring-Token`	从设备 SDK 提交一个事件
`POST /v1/events/batch/`	`X-Monitoring-Token`	提交 SDK 缓冲区刷新后的一批事件
`GET /v3/events/`	API 密钥	列出并筛选事件
`GET /v3/events/{event_uuid}/`	API 密钥	查看单个事件及其规则证据
`GET /v3/events/subjects/{vendor_data}/`	API 密钥	查看单个主体的时间线（见下方 `entity_type`）
`GET /v3/events/enrichment-metrics/`	API 密钥	IP 信息补充缓存的健康状态

/v3/ 通道是服务端通道，与交易 API 其余部分使用相同的 x-api-key 认证。/v1/events/ 通道是设备通道，参见 SDK 事件提交。

事件信封结构

curl -X POST https://verification.didit.me/v3/events/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "login-2026-08-31-000001",
    "event_category": "auth",
    "action_type": "login",
    "occurred_at": "2026-08-31T20:40:31.123Z",
    "time_zone": "UTC",
    "subject": {
      "entity_type": "individual",
      "vendor_data": "user_391"
    },
    "session": { "session_id": "web-session-abc", "sequence": 142 },
    "device_context": {
      "fingerprint": "didit-fp-v2:a8c1",
      "network_context": { "ip_address": "203.0.113.42" }
    },
    "payload": { "method": "password" }
  }'

{
  "event_uuid": "0f2b...",
  "event_id": "login-2026-08-31-000001",
  "status": "ACCEPTED",
  "score": 0,
  "rules_evaluated_count": 6,
  "rules_matched_count": 0,
  "correlation_pending": false,
  "retention_class": "standard",
  "expires_at": "2026-09-30T20:40:31.123Z",
  "idempotent_replay": false,
  "rule_matches": []
}

字段	必填	说明
`event_id`	是	你自己的标识符，在每个应用内唯一。它就是幂等键。
`event_category`	是	以下十个类别之一。
`action_type`	是	开放字符串，最多 128 个字符。
`occurred_at`	是	事件在你的系统中发生的时间。最早可为 7 天前，最晚可为 5 分钟后。
`subject.vendor_data`	是	你的用户 ID。会解析为与交易相同的用户。
`subject.entity_type`	否	`individual`（默认）或 `company`。
`business.vendor_data`	否	事件所属的企业。
`session`	否	`session_id`、`sequence`、`page_url`、`referrer`。
`device_context`	否	`fingerprint`、`persistent_device_id`、`bot_score`，以及 `network_context.ip_address`。
`transaction_context`	否	`amount`、`currency`、`direction`、`payment_reference_id`。
`payload`	否	该类别的领域字段。最多 16 KB。
`custom_values`	否	最多 100 个标量键，规则中可通过 `custom_values.<key>` 引用。

类别

十个一级类别，每个都有类型化校验和托管的规则字段。

类别	典型操作
`auth`	`signup`、`login`、`login_failed`、`logout`、`password_forgot`、`password_reset`、`mfa_reset`、`mfa_challenge`
`session`	`session_started`、`session_ended`、`page_view`、`sdk_loaded`、`device_seen`、`bot_signal_observed`、`sdk_heartbeat`
`gameplay`	`round_started`、`round_completed`、`bet_placed`、`bet_settled`、`cashout`、`limit_change`、`p2p_settlement`
`bonus`	`bonus_claimed`、`bonus_wagered`、`bonus_released`、`promotion_viewed`
`affiliate`	`affiliate_attributed`、`referral_clicked`、`campaign_joined`、`commission_event`
`payment`	`deposit_initiated`、`deposit_completed`、`withdrawal_requested`、`withdrawal_completed`、`withdrawal_address_changed`、`payment_instrument_seen`
`dispute`	`chargeback_opened`、`chargeback_won`、`chargeback_lost`、`refund_issued`、`payment_dispute_updated`
`security`	`login_attempt`、`login_succeeded`、`login_failed`、`password_changed`、`mfa_changed`、`credential_reset`、`country_changed`、`device_changed`、`account_locked`
`responsible_gambling`	`self_exclusion_checked`、`self_exclusion_match`、`re_registration_attempt`、`limit_breach_attempt`、`registry_status_changed`
`custom`	您自行定义的任意操作

auth 是面向产品的宽泛类别；security 是风险等级更高的子集，带有账户接管规则所读取的有序生命周期。

必填 payload 字段

有些操作如果缺少特定字段就无法关联，因此校验会拒绝这些事件，而不是存储无人能关联的证据。

操作	必填字段
`gameplay.p2p_settlement`	`game_id`、`counterparty_vendor_data`、`stake_amount`、`net_result_amount`、`role`，以及 `hand_id` / `round_id` / `match_id` 中的一个
`gameplay.bet_placed`、`gameplay.bet_settled`	`game_id`
`payment.deposit_*`、`payment.withdrawal_completed`、`payment.withdrawal_requested`、`payment.deposit_initiated`	`payment_reference_id`、`amount`、`currency`、`payment_method`、`status`
`payment.withdrawal_address_changed`	`withdrawal_address_hash`
`dispute.chargeback_*`	`payment_reference_id`，以及 `dispute_id` / `chargeback_id` 中的一个
`security.*_changed`	`changed_field`；账户或收款控制变更还需要 `previous_reference_hash` 或 `new_reference_hash`
`session.bot_signal_observed`	`telemetry_schema_version`，以及 `bot_score` 或至少一个遥测指标
`responsible_gambling.self_exclusion_match`	`registry_source`、`exclusion_status`、`identity_match_ref`

只发送引用和哈希，绝不发送原始机密信息。支付工具、提现目标和账户控制变更会以您发送的哈希引用形式存储。切勿发送卡号、完整提现地址、密码哈希或 MFA 密钥。

示例：P2P 结算

{
  "event_id": "p2p-hand-8842-user-391",
  "event_category": "gameplay",
  "action_type": "p2p_settlement",
  "occurred_at": "2026-08-31T12:34:17.392Z",
  "subject": { "vendor_data": "user_391" },
  "payload": {
    "game_id": "poker_holdem",
    "table_id": "table_17",
    "hand_id": "hand_8842",
    "role": "winner",
    "counterparty_vendor_data": "user_812",
    "stake_amount": "250.00",
    "net_result_amount": "240.50",
    "effective_margin": "0.038",
    "operator_ledger_ref": "ledger_998123"
  }
}

示例：拒付

{
  "event_id": "chargeback-cb_921-opened",
  "event_category": "dispute",
  "action_type": "chargeback_opened",
  "occurred_at": "2026-08-31T09:22:05.000Z",
  "subject": { "vendor_data": "user_391" },
  "transaction_context": {
    "amount": "1000.00",
    "currency": "EUR",
    "payment_reference_id": "dep_735"
  },
  "payload": {
    "dispute_id": "disp_498",
    "chargeback_id": "cb_921",
    "reason_code": "fraudulent",
    "liability_shift": false
  }
}

争议生命周期只允许追加：更正应作为新的 dispute 事件提交，而不是修改第一条事件。

幂等性

event_id 在每个应用内唯一，它就是整个幂等性约定。

相同的 event_id，相同的内容：返回 200 和 "idempotent_replay": true，以及最初存储的事件。可以随意重试。
相同的 event_id，不同的内容：返回 409。说明您误用了已有的 ID。

批量

POST /v3/events/batch/ 最多接受500 个事件。批量请求按设计支持部分成功：一条格式错误的页面浏览事件，绝不能导致同批次的拒付事件也失败。

{
  "accepted_count": 2,
  "replayed_count": 0,
  "rejected_count": 1,
  "results": [
    { "index": 0, "outcome": "rejected", "errors": { "occurred_at": ["This field is required."] } },
    { "index": 1, "outcome": "accepted", "event_uuid": "…", "status": "ACCEPTED" },
    { "index": 2, "outcome": "accepted", "event_uuid": "…", "status": "IN_REVIEW" }
  ]
}

只要有任何事件被拒绝，响应为 207 Multi-Status；全部成功则为 201 Created。

状态

状态	含义
`ACCEPTED`	已存储。没有任何规则改变其状态（这是大多数事件的正常结果）。
`APPROVED`	规则已运行，分数仍低于您的审核阈值。
`IN_REVIEW`	规则使其分数超过审核阈值，或直接设置了该状态。
`DECLINED`	规则拒绝了该事件。

correlation_pending: true 表示仍需运行一条跨主体规则；它会在几分钟内完成，事件的状态和分数会就地更新。参见异步规则。

保留

事件的数量远高于交易，因此每个事件到达时都会归入一个保留类别。

类别	默认热数据保留期	归入此类的事件
`low_value`	14 天	页面浏览、心跳、设备可见性信号、机器人遥测、促销浏览
`standard`	30 天	认证、会话、游戏、奖金、联盟营销、自定义
`risk_relevant`	90 天	安全和负责任博彩事件，以及任何被规则命中的事件
`monetary_or_compliance`	交易保留期	支付和争议事件

由此表得出两条规则：

命中规则的事件属于证据，因此会自动提升为 risk_relevant。
支付和争议事件沿用交易保留期。它们永远不会按事件计划过期，且各类别的覆盖设置无法缩短其保留期。

可在 Transactions → Settings → Event monitoring 中按应用覆盖三个可过期类别的保留期（每类 1-730 天）。

IP 丰富信息

事件与交易一样，带有相同的 IP 信息补充，包括国家、ASN、VPN/代理和数据中心标记。信息补充按每个唯一 IP 地址解析，而不是按事件解析。一个会话从同一地址触发 200 次页面浏览时，该地址只解析一次。低价值遥测走得更远：只有当其他事件已经解析过该地址时，它才会读取补充信息。它绝不会自行触发查询。 GET /v3/events/enrichment-metrics/ 会返回结果，控制台也会在事件列表上方显示相同的数字：

{
  "events_ingested": 128450,
  "enrichment_lookups": 41230,
  "enrichment_cache_hits": 40118,
  "enrichment_provider_calls": 1112,
  "enrichment_skipped_low_value": 74320,
  "unique_ips_seen": 1112,
  "cache_hit_rate": 0.973,
  "unique_ip_ratio": 0.0087,
  "provider_calls_per_1k_events": 8.65,
  "period_days": 30
}

读取事件

curl "https://verification.didit.me/v3/events/?event_category=payment&event_category=dispute&matched_only=true" \
  -H "x-api-key: YOUR_API_KEY"

筛选参数：event_category、action_type、status、retention_class、subject_vendor_data、business_vendor_data、session_id、device_fingerprint、ip_address、game_id、round_id、affiliate_code、payment_reference_id、counterparty_vendor_data、matched_only、occurred_from、occurred_to、search。多值筛选需要重复参数（如 ?status=A&status=B）。

单个主体的时间线

curl "https://verification.didit.me/v3/events/subjects/acct_9931/?entity_type=company" \
  -H "x-api-key: YOUR_API_KEY"

vendor_data 仅在同一实体类型内唯一：同一个 ID 可能同时对应一个用户和一家企业，Didit 会将它们视为两个不同的主体。entity_type 用于指定你要查询的对象：individual（默认值）或 company。如果使用企业 ID 时省略该参数，返回的是个人的时间线，而不是两者都返回。同样的列表筛选参数也适用于此。 GET /v3/events/{event_uuid}/ 会额外返回 payload、设备上下文、IP 信息富化、该主体缓存的风险信号，以及每个规则匹配结果及其证据，包括每个匹配字段是由服务端推导、由 SDK 推导，还是由客户提供。 DELETE /v3/events/{event_uuid}/delete/ 用于删除单个事件。被删除的事件将不再出现在任何读取接口的返回结果中，且删除操作不可撤销。

下一步

事件规则

基于事件数据的速率、比率、序列和关联规则。

入门

功能

参考

控制台

事件接入 API - 非资金类交易监控

Endpoints

事件信封结构

类别

必填 payload 字段

示例：P2P 结算

示例：拒付

幂等性

批量

状态

保留

IP 丰富信息

读取事件

单个主体的时间线

下一步

事件规则

SDK 事件提交

​Endpoints

​事件信封结构

​类别

​必填 payload 字段

​示例：P2P 结算

​示例：拒付

​幂等性

​批量

​状态

​保留

​IP 丰富信息

​读取事件

​单个主体的时间线

​下一步

事件规则

SDK 事件提交

Endpoints

事件信封结构

类别

必填 payload 字段

示例：P2P 结算

示例：拒付

幂等性

批量

状态

保留

IP 丰富信息

读取事件

单个主体的时间线

下一步