交易监控 API：提交交易 Payload 与数据模型

通过创建交易 API 向 Didit 提交交易。每笔交易都包含结构化的主体、支付和上下文数据，规则引擎会实时评估这些数据。

当交易源自终端用户的设备（例如加密货币提现、应用内支付）时，可以考虑使用SDK 交易提交：此时由限定范围的 token 替代 API 密钥，设备信息会自动采集，所需的用户操作（钱包所有权证明、增强验证）会立即触发。

交易类别

每笔交易都有一个 transaction_category，它决定规则和分析如何处理该交易：

类别	描述
`finance`	标准金融交易（存款、提现、转账）
`kyc`	与身份验证相关的事件
`travel_rule`	需要满足 Travel Rule 合规要求的虚拟资产转账
`user_event`	自定义平台事件（登录、资料变更等）
`gambling_bet`	博彩投注或下注
`gambling_limit_change`	玩家存款、亏损或投注限额的变更
`gambling_bonus_change`	奖金发放、兑换或没收
`audit_trail_event`	系统或合规审计事件

交易详情

transaction_details 对象包含财务数据：

字段	类型	描述
`direction`	string	`inbound` 或 `outbound`
`amount`	string	以十进制字符串表示的交易金额（例如 `"1500.50"`）
`currency`	string	ISO 货币代码（例如 `USD`、`EUR`、`BTC`）
`currency_kind`	string	`fiat` 或 `crypto`（别名 `currencyType`）；决定是否触发加密货币筛查
`action_type`	string	由供应商自定义的操作标签（例如 `deposit`、`withdrawal`、`purchase`）
`payment_details`	string	支付的自由文本描述（例如 `"Bank transfer from ABC Corp"`）
`payment_reference_id`	string	外部支付参考标识符。如需进行转账后的加密货币筛查，请使用区块链交易哈希。

主体与交易对手

每笔交易都有一个主体（必填）和一个可选的交易对手。两者使用相同的主体模型：

字段	类型	描述
`entity_type`	string	`person` 或 `company`
`vendor_data`	string	您为该主体设定的标识符，用于将交易关联到用户或企业档案
`full_name`	string	主体的姓名
`first_name`	string	名字
`last_name`	string	姓氏
`date_of_birth`	string	ISO 日期（例如 `1990-01-15`）
`country_code`	string	ISO 3166-1 alpha-2 国家/地区代码
`address`	object or string	包含 `street`、`city`、`state`、`country`、`postal_code` 的结构化地址。也接受纯字符串，例如加密货币交易对手的钱包地址；Didit 会原样保存在该主体上。

当 address 为对象时，Didit 会从 address.country 推导该主体的 country_code。当 address 为字符串时，该主体的 country_code 返回 null。当 vendor_data 与现有用户或企业匹配时，Didit 会自动将交易关联到该实体的档案，从而支持跨会话规则评估和交易频率检查。在响应中，两个主体会通过 parties 数组返回，角色分别为 APPLICANT 和 COUNTERPARTY。

支付方式

为每个主体附加一个 payment_method，用于描述该方的支付工具：

字段	类型	描述
`method_type`	string	`bank_card`、`bank_account`、`e_wallet`、`crypto_wallet`、`unhosted_wallet` 或 `other`（别名 `type`）；`ewallet`、`card` 和 `crypto` 也可作为别名使用，无法识别的值会存储为 `other`
`account_id`	string	账号、钱包地址或卡 token
`issuing_country`	string	签发该支付工具的国家/地区

在 travelRule 交易中，在交易对手的支付方式上设置 method_type: "unhosted_wallet"（别名 type），即表示该交易对手钱包为自托管钱包。启用 Travel Rule 且以应用默认货币计算的金额不低于 threshold_amount 时，转账会直接进入 UNCONFIRMED_OWNERSHIP 状态，并进入所有权证明流程。请参阅已声明的自托管钱包。对于加密货币交易，请在 account_id 中填写钱包地址，并将 currency_kind 设置为 crypto，以便自动执行区块链筛查。方向决定筛查哪个钱包：入账的转账前筛查使用 counterparty.payment_method.account_id 中的发送方钱包；出账筛查使用 counterparty.payment_method.account_id 中的目标钱包。如果您在 transaction_details.payment_reference_id 中提交了区块链哈希，则入账交易筛查需要在 subject.payment_method.account_id 中填写您的服务入金地址，而出账交易筛查需要在 counterparty.payment_method.account_id 中填写目标钱包。

加密货币筛查覆盖设置

在请求的顶层使用 include_crypto_screening，可以覆盖控制台中交易 > 设置配置的默认值：

值	描述
`true`	对本次交易强制进行加密货币筛查
`false`	跳过本次交易的加密货币筛查
省略或 `null`	使用应用级别的默认值

设备上下文

在主体（以及可选的交易对手）上提供设备信息，以驱动设备情报规则。请求字段为每一方中的 device_context；也接受驼峰式别名 device，SDK 的传输格式即使用该别名。响应会在 parties 数组中的每一方下以 device 返回该信息。

字段	类型	说明
`device_context.fingerprint`	string	唯一的设备指纹
`device_context.persistent_device_id`	string	跨会话稳定的设备标识符（v2 指纹架构）
`device_context.user_agent`	string	浏览器或应用的用户代理字符串
`device_context.browser_family`	string	浏览器系列（例如 `Chrome`、`Firefox`、`Safari`）。必须显式传递，不会从 `user_agent` 推导。用于驱动 `subject_browser_family` 等规则。
`device_context.browser_version`	string	浏览器版本字符串（例如 `131.0`）。必须显式传递。
`device_context.platform`	string	平台标识符（`web`、`ios`、`android`、`macos`、`windows`、`linux`）。必须显式传递，不会从 `user_agent` 推导。用于驱动 `subject_platform` 等规则。
`device_context.os_family`	string	操作系统系列（例如 `iOS`、`Android`、`Windows`）
`device_context.os_version`	string	操作系统版本字符串
`device_context.accept_language`	string	Accept-Language 请求头的值（例如 `en-US,en;q=0.9`）。通过 SDK 时会自动收集。
`device_context.session_id`	string	用户当前会话的标识符。存储在元数据中。驼峰式别名：`sessionId`。
`device_context.session_age_ms`	number	交易发生时用户会话的时长（毫秒）。用于驱动 `subject_session_age_ms` 等规则。
`device_context.network_context.ip_address`	string	客户端地址
`device_context.network_context.ip_country_code`	string	根据 IP 地理定位解析出的国家/地区（ISO 3166-1 alpha-3）
`device_context.network_context.latitude`	number	IP 的地理纬度
`device_context.network_context.longitude`	number	IP 的地理经度

browser_family 和 platform 不会从 user_agent 推导。若要使设备情报规则生效，必须将它们作为顶层键显式放在 device_context 内传递。如果您使用 Didit SDK，这些字段会自动收集。

所有字段均接受驼峰式别名：userAgent、browserFamily、browserVersion、osFamily、osVersion、acceptLang、sessionId、sessionAgeMs。network_context 子对象接受 ip、countryCode3、lat、lon 别名，顶层的 ipInfo 块也会并入 network_context。设备上下文可启用例如以下规则：多账户检测（同一指纹出现在不同主体上）、新浏览器与新 IP 组合检测、低会话时长的高额转账检测，以及基于位置的风险评分。

自定义属性

在 custom_properties 对象中添加任意其他键值对。规则可以在其条件中引用这些字段，适用于传递特定业务上下文，例如商品类别、商户 ID 或渠道。

"custom_properties": {
  "product_category": "electronics",
  "merchant_id": "MER456",
  "channel": "mobile_app"
}

在规则条件中，使用字段路径 custom_values.<key> 引用每个键。例如，上述 payload 与 custom_values.product_category eq "electronics" 匹配。在 Console 规则构建器中，近期摄入的交易中出现过的键会显示在条件字段选择器的 自定义属性 下，同一组中的 输入自定义属性 允许您手动输入任意键（区分大小写）。详情请参阅规则与评分。

请求示例

curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "TXN-20260410-001",
    "transaction_at": "2026-04-10T15:30:00Z",
    "transaction_category": "finance",
    "transaction_details": {
      "direction": "outbound",
      "amount": "1500.50",
      "currency": "EUR",
      "currency_kind": "fiat",
      "action_type": "withdrawal"
    },
    "subject": {
      "entity_type": "person",
      "vendor_data": "user-123",
      "full_name": "John Doe",
      "country_code": "US",
      "payment_method": {
        "method_type": "bank_account",
        "account_id": "DE89370400440532013000",
        "issuing_country": "DE"
      }
    },
    "counterparty": {
      "entity_type": "company",
      "full_name": "John Doe",
      "country_code": "GB"
    },
    "custom_properties": {
      "order_id": "ORD-7891"
    }
  }'

响应

API 会返回已创建的交易及其初始评估结果：

字段	类型	说明
`uuid`	string	Didit 的唯一交易标识符
`txn_id`	string	您提供的交易 ID
`status`	string	`APPROVED`、`IN_REVIEW`、`DECLINED` 或 `AWAITING_USER`
`score`	number	所有匹配规则的累计风险评分
`severity`	string	匹配规则中的最高严重等级（`LOW`、`MEDIUM`、`HIGH`、`CRITICAL`）
`decision_reason_code`	string	状态决策的机器可读原因代码
`decision_reason_label`	string	决策的人类可读说明

完整的请求和响应结构请参阅 API 参考；带注释的 payload 示例说明请参阅响应结构参考。

将交易分配给审核员

使用具有 write:transactions 权限的 API 密钥，将待审核交易分配给应用的某位成员，或取消分配。每次变更都会以 TRANSACTION_ASSIGNED 的形式记录在交易时间线上。

调用	用途
`POST /v3/transactions/{transaction_uuid}/assign/`	分配一笔交易。
`POST /v3/transactions/assign/`	将最多 500 笔交易分配给一位成员。

两种调用都接受 assignee_email，即已登录 Didit 的应用成员的邮箱。传递 null 或空字符串即可取消分配。批量调用还接受 transaction_ids，即 1 至 500 个交易 UUID 的列表。

curl -X POST "https://verification.didit.me/v3/transactions/assign/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_ids": ["<transaction-uuid>"], "assignee_email": "analyst@example.com"}'

单笔调用返回 uuid、transaction_number、assignee 和 changed（当交易已经分配给该审核员时为 false）。若交易在应用中不存在，则返回 404。批量调用返回 transactions（每项结构与上述相同）、updated_count 和 not_found_transaction_ids。使用 assignee 过滤交易列表，该参数为逗号分隔的列表，任一值匹配即可：me、unassigned、rules（仅由规则决定，不涉及审核员）或成员邮箱。

幂等性

txn_id（即您发送的 transaction_id）在每个应用中都是唯一的。重复提交已存在的 transaction_id 会返回 400，并在 transaction_id 字段上返回 A transaction with this transaction_id already exists.；两个完全相同的请求并发时，第二个请求会收到 409。两种响应都不会返回已存在的交易。要安全地重试，请将针对重复 transaction_id 的 400 或 409 视为“已创建”，然后查询已存在的交易，而不是重新提交：使用第一次响应中的 uuid，通过 GET /v3/transactions/{uuid}/ 读取交易；或者使用 transaction.created Webhook 中与您的 txn_id 一同返回的 transaction_id（即 Didit uuid）。请始终在您的系统中生成 txn_id（例如您自己的交易数据库 ID、UUID 或确定性哈希值）。

历史数据回填

将 txn_date 设为过去的时间即可导入历史交易。默认情况下仍会评估规则。如果在批量加载历史数据时希望跳过规则评估，请使用控制台 CSV 导入的 dry-ingest 模式。参阅集成指南。

后续步骤

规则与评分

提交的交易如何根据规则进行评估。

响应结构

带注释的完整响应 payload。

加密货币筛查

对加密货币交易自动进行钱包和交易筛查。

Travel Rule

为虚拟资产转账附加 Travel Rule 合规数据。

IP 信息补充

可供规则使用的 IP 派生上下文。

API 参考

创建交易 endpoint 的完整请求结构。

入门

功能

参考

控制台

交易监控 API：提交交易 Payload 与数据模型

交易类别

交易详情

主体与交易对手

支付方式

加密货币筛查覆盖设置

设备上下文

自定义属性

请求示例

响应

将交易分配给审核员

幂等性

历史数据回填

后续步骤

规则与评分

响应结构

加密货币筛查

Travel Rule

IP 信息补充

API 参考

​交易类别

​交易详情

​主体与交易对手

​支付方式

​加密货币筛查覆盖设置

​设备上下文

​自定义属性

​请求示例

​响应

​将交易分配给审核员

​幂等性

​历史数据回填

​后续步骤

规则与评分

响应结构

加密货币筛查

Travel Rule

IP 信息补充

API 参考

交易类别

交易详情

主体与交易对手

支付方式

加密货币筛查覆盖设置

设备上下文

自定义属性

请求示例

响应

将交易分配给审核员

幂等性

历史数据回填

后续步骤