> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Didit 支持实时提交交易进行监控，可附带交易方、支付方式、设备和自定义属性。每月包含 1,000 次，之后每次 $0.001。

通过 [创建交易](https://docs.didit.me/zh/management-api/transactions/create.md) API 向 Didit 提交交易。每笔交易都包含结构化的主体、支付和上下文数据，规则引擎会实时评估这些数据。

> [!TIP]
>
> 当交易源自终端用户的设备（例如加密货币提现、应用内支付）时，可以考虑使用[SDK 交易提交](https://docs.didit.me/zh/transaction-monitoring/sdk-transaction-submission.md)：此时由限定范围的 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 | 您为该主体设定的标识符，用于将交易关联到[用户](https://docs.didit.me/zh/management-api/users/list.md)或[企业档案](https://docs.didit.me/zh/business-verification/business-profiles.md) |
| `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` 状态，并进入所有权证明流程。请参阅[已声明的自托管钱包](https://docs.didit.me/zh/transaction-monitoring/travel-rule.md#已声明的自托管钱包)。

对于加密货币交易，请在 `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 的地理经度 |

> [!NOTE]
>
> `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 或渠道。

```json theme={null}
"custom_properties": {
  "product_category": "electronics",
  "merchant_id": "MER456",
  "channel": "mobile_app"
}
```

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

## 请求示例

```bash theme={null}
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 参考](https://docs.didit.me/zh/management-api/transactions/create.md)；带注释的 payload 示例说明请参阅 [响应结构参考](https://docs.didit.me/zh/transaction-monitoring/response-schema.md)。

## 将交易分配给审核员

使用具有 `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 的列表。

```bash theme={null}
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` 过滤[交易列表](https://docs.didit.me/zh/management-api/transactions/list.md)，该参数为逗号分隔的列表，任一值匹配即可：`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}/`](https://docs.didit.me/zh/management-api/transactions/get) 读取交易；或者使用 `transaction.created` Webhook 中与您的 `txn_id` 一同返回的 `transaction_id`（即 Didit uuid）。
请始终在您的系统中生成 `txn_id`（例如您自己的交易数据库 ID、UUID 或确定性哈希值）。

## 历史数据回填

将 `txn_date` 设为过去的时间即可导入历史交易。默认情况下仍会评估规则。如果在批量加载历史数据时希望跳过规则评估，请使用控制台 CSV 导入的 dry-ingest 模式。参阅[集成指南](https://docs.didit.me/zh/transaction-monitoring/integration-guide.md#历史数据导入)。

## 后续步骤

> [card] [规则与评分](https://docs.didit.me/zh/transaction-monitoring/rules.md)
>
> 提交的交易如何根据规则进行评估。

> [card] [响应结构](https://docs.didit.me/zh/transaction-monitoring/response-schema.md)
>
> 带注释的完整响应 payload。

> [card] [加密货币筛查](https://docs.didit.me/zh/transaction-monitoring/aml-screening.md)
>
> 对加密货币交易自动进行钱包和交易筛查。

> [card] [Travel Rule](https://docs.didit.me/zh/transaction-monitoring/travel-rule.md)
>
> 为虚拟资产转账附加 Travel Rule 合规数据。

> [card] [IP 信息补充](https://docs.didit.me/zh/transaction-monitoring/ip-enrichment.md)
>
> 可供规则使用的 IP 派生上下文。

> [card] [API 参考](https://docs.didit.me/zh/management-api/transactions/create.md)
>
> 创建交易 endpoint 的完整请求结构。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.