> ## 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：KYT 交易详情
> 通过 Didit 获取 KYT 交易详情：关联方、支付方式、警报、规则命中、Travel Rule 检查、整改链接及网络快照。
获取交易 API 提示词
将提示词复制到剪贴板
\
\`Fetch the full detail of a Didit monitored transaction through the Management API.
Endpoint:
GET https://verification.didit.me/v3/transactions/{transaction_id}/
Authentication:
Use the x-api-key header with my Didit API key.
Goal:
\- Retrieve every detail of a transaction — linked parties, payment methods, alerts, rule matches, travel-rule checks, remediation links, network snapshots, cost breakdown — so I can render a detail screen or feed a downstream decision.
Path parameter:
\- transaction_id - Didit's transaction uuid (the uuid returned by POST /v3/transactions/).
Your own txn_id is not accepted here and returns 404.
Example call:
curl -X GET "https://verification.didit.me/v3/transactions/{transaction_id}/" \
-H "x-api-key: YOUR_API_KEY"
What to read from the response:
\- uuid, transaction_number, txn_id — identifiers.
\- status, score, severity, decision_reason_code, decision_reason_label — current verdict.
\- direction, amount, currency, currency_type, action_type, payment_details, payment_txn_id - the submitted details as top-level fields (there is no transaction_details object, and currency_type carries the currency_kind you sent).
\- parties - party records with role APPLICANT (the subject) or COUNTERPARTY (the other side) and kind USER, BUSINESS or EXTERNAL, each with entity_type, vendor_data, full_name, address and device.
\- payment_methods - the linked payment methods, each with payment_method_type, account_id and role (for example SOURCE or DESTINATION).
\- cost_breakdown — provider-by-provider cost detail for this transaction.
\- rule_runs / alerts — which rules fired and their outcomes.
\- provider_results - crypto screening (blockchain analytics) results, when a screening ran.
\- travel_rule - the Travel Rule transfer (uuid, status, protocol, required, obligations_count, originator_data, beneficiary_data, metadata, direction, rail, counterparty_vasp, delivery, discovery, reason, next_actions), or null when the transaction has none.
For a COUNTERPARTY_VASP_NOT_FOUND or COUNTERPARTY_VASP_NOT_REACHABLE transfer, reason says why it is stuck and next_actions what moves it on: email_undeliverable offers update_compliance_email then resend, delivery_failed offers resend, and a discovery reason (awaiting_end_user, directory_match_no_route, picked_member_without_proven_wallet, no_directory_match) offers select_counterparty_vasp, declare_self_hosted, add_vasp_hint and resend.
delivery is the newest message the transfer owes the other side (kind, status, rail, attempts, last_error, next_attempt_at, delivered_at), or null; discovery is the trace of where Didit looked for the counterparty.
On an inbound transfer, the counterparty's originator_data and beneficiary_data stay masked (data_masked: true) until wallet ownership is confirmed.
\- tags — Console tags (uuid, name, color).
\- assigned_to_name (the Console reviewer) is not part of this response; the list endpoint GET /v3/transactions/ returns it.
Use cases:
\- Render the Console-equivalent "Transaction detail" screen in your back-office.
\- Reconcile rule outcomes against your own ledger.
\- Poll after a transaction.status.updated webhook to fetch the fresh verdict.
Failure modes:
\- 403 - missing x-api-key (a wrong, revoked or expired key gets 401), or a key without permission for this action ({ "detail": "..." } envelope).
\- 404 - transaction not found in this application, including a transaction that belongs to another application (or deleted via the Console).
\- 429 — rate limited; back off and retry.
Side effects: none. This is a pure read.
For the full integration shape, see /integration/integration-prompt.`
\
粘贴到
## OpenAPI
````yaml zh/openapi-25.json GET /v3/transactions/{transaction_id}/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/transactions/{transaction_id}/:
get:
tags:
- Transactions
summary: 获取交易
description: 获取单笔交易的完整监控记录：各方主体、评分/严重程度、规则执行记录、警报、Travel Rule 结果、补救会话。
operationId: getTransaction
parameters:
- name: transaction_id
in: path
required: true
description: Didit 稳定的交易 UUID（从创建/列出接口返回的 `uuid`，**不是**您的 `txn_id`）。
schema:
type: string
format: uuid
example: abcdef12-3456-7890-abcd-ef1234567890
responses:
'200':
description: 完整交易详情。
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionDetail'
examples:
In review with an alert:
value:
uuid: abcdef12-3456-4890-abcd-ef1234567890
environment: live
transaction_number: 4123
txn_id: your-txn-2026-05-17-001
txn_date: '2026-05-17T08:42:00Z'
zone_id: Europe/Madrid
transaction_type: finance
action_type: withdrawal
direction: OUTBOUND
status: IN_REVIEW
source: LIVE
amount: '1500'
currency: EUR
currency_type: fiat
amount_in_default_currency: '1620.45'
default_currency_code: USD
preferred_currency_amount: '1620.45'
preferred_currency_code: USD
payment_details: Withdrawal to crypto wallet
payment_txn_id: null
score: 78
severity: HIGH
decision_reason_code: WALLET_HIGH_RISK
decision_reason_label: Destination wallet flagged as high risk
vendor_data: user-12345
metadata:
subject:
entity_type: individual
vendor_data: user-12345
full_name: Maria Garcia
address: {}
institution_details: {}
device_context: {}
counterparty: {}
props:
order_id: ord-9988
tags: []
parties:
- uuid: b1111111-2222-4333-8444-555555555555
role: APPLICANT
entity_type: individual
kind: USER
vendor_data: user-12345
full_name: Maria Garcia
first_name: null
last_name: null
country_code: null
dob: null
address: {}
institution_info: {}
device: {}
external_party_snapshot: null
payment_methods: []
documents: []
activities: []
alerts:
- uuid: a7b8c9d0-1234-4abc-9def-567890abcdef
title: Destination wallet flagged as high risk
description: Provider risk score exceeded the configured threshold.
severity: HIGH
status: OPEN
source: RULE
metadata: {}
created_at: '2026-05-17T08:42:12Z'
due_at: null
rule_runs: []
provider_results: []
travel_rule: null
network_snapshot: null
remediation: null
action_required: null
cost_breakdown: null
'403':
description: >-
缺少、无效或已撤销的 API 密钥，或者该密钥无法读取此应用的交易。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回
`401`。
content:
application/json:
examples:
Forbidden:
value:
detail: You do not have permission to perform this action.
'404':
description: 该应用不存在具有此 UUID 的交易（已删除、从未创建、属于另一个应用，或路径片段不是有效的 UUID）。
content:
application/json:
examples:
Not found:
value:
detail: Not found.
'429':
description: 超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。
content:
application/json:
examples:
Throttled:
value:
detail: Request was throttled. Expected available in 30 seconds.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: >-
curl -X GET
'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/'
\
-H 'x-api-key: YOUR_API_KEY'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.transactions.retrieve(
"abcdef12-3456-7890-abcd-ef1234567890",
)
print(result)
- lang: javascript
label: Node.js
source: >-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await
didit.transactions.retrieve("abcdef12-3456-7890-abcd-ef1234567890");
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Retrieve(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import me.didit.Didit;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result =
client.transactions().retrieve("abcdef12-3456-7890-abcd-ef1234567890");
System.out.println(result);
- lang: php
label: PHP
source: >-
transactions->retrieve('abcdef12-3456-7890-abcd-ef1234567890');
print_r($result->toArray());
- lang: ruby
label: Ruby
source: >-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result =
didit.transactions.retrieve("abcdef12-3456-7890-abcd-ef1234567890")
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await
client.Transactions.RetrieveAsync("abcdef12-3456-7890-abcd-ef1234567890");
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
TransactionDetail:
type: object
description: >-
单个交易的完整监控记录，由 `GET /v3/transactions/{transaction_id}/` 和 `POST
/v3/transactions/` 返回。
properties:
uuid:
type: string
format: uuid
description: Didit 稳定的交易标识符。用作后续调用的 `{transaction_id}`。
environment:
type: string
enum:
- live
- sandbox
description: >-
拥有该交易的应用的环境。`sandbox` 交易会被存储，但绝不会被评估、筛查、通知或计费，因此其空的 `rule_runs`
表示“未评估”。
transaction_number:
type: integer
description: 控制台中显示的应用范围内连续交易序号（例如 `4123`）。
txn_id:
type: string
description: 您在创建时提供的 `transaction_id`（最多 128 个字符）。每个应用唯一。
txn_date:
type: string
format: date-time
description: 交易发生的时间（来自 `transaction_at`；默认为提交时间）。
zone_id:
type: string
nullable: true
description: 创建时提供的 IANA 时区标识符。
transaction_type:
type: string
description: >-
存储的顶级类别：`finance`、`kyc`、`travelRule`、`userPlatformEvent`、`gamblingBet`、`gamblingLimitChange`、`gamblingBonusChange`、`auditTrailEvent`。请注意，即使以
snake_case 提交，包含多个单词的值也会以 camelCase 形式返回。
action_type:
type: string
description: 类别内的子类型（例如 `deposit`、`withdrawal`、`transfer`）。未提供时默认为该类别。
direction:
type: string
enum:
- INBOUND
- OUTBOUND
description: >-
相对于主体的方向。无论提交时的大小写如何，均以大写形式存储（输入时接受
`in`/`out`/`inbound`/`outbound`）。
status:
type: string
enum:
- APPROVED
- IN_REVIEW
- DECLINED
- AWAITING_USER
description: 当前监控裁决结果。创建交易时的状态为 `APPROVED`；规则可能会同步将其更改为 `IN_REVIEW`/`DECLINED`。
source:
type: string
enum:
- LIVE
- IMPORTED
description: 记录的生成来源：通过 API 或 SDK 提交的交易为 `LIVE`，通过控制台导入加载的交易为 `IMPORTED`。
amount:
type: string
description: >-
作为十进制字符串的交易金额，已去除末尾零（例如
`"1500"`、`"0.5"`、`"0.123456789012345678"`）。最多 18 位小数。
currency:
type: string
description: >-
`amount` 的货币代码。接受任何 ISO 4217 字母代码（例如 `EUR`、`USD`、`NGN`）以及加密资产符号（例如
`BTC`）。建议使用当前流通的代码。并非每个接受的代码都有汇率：当该代码没有可用汇率时（例如 ISO 会计单位 `XSU`，或
Didit 未定价的加密资产符号），自动换算将失败，并且 `preferred_currency_amount` 将返回
null，除非请求提供了预先换算的 `amount_in_default_currency`。
currency_type:
type: string
nullable: true
description: '`fiat` 或 `crypto`，与在 `currency_kind` 中提交的内容一致。'
amount_in_default_currency:
type: string
nullable: true
description: 您提供的预先换算金额，为去除了末尾零的十进制数字符串。
default_currency_code:
type: string
nullable: true
preferred_currency_amount:
type: string
nullable: true
description: '`amount` 在可用时折算为应用的首选货币。'
preferred_currency_code:
type: string
nullable: true
payment_details:
type: string
nullable: true
description: 提交内容中的自由文本付款参考号或附言。
payment_txn_id:
type: string
nullable: true
description: 来自 `payment_reference_id` 的外部支付系统参考标识（例如区块链交易哈希）。
score:
type: integer
description: 规则累计的风险评分（通常为 0–100）。数值越高 = 风险越大。
severity:
type: string
nullable: true
enum:
- UNKNOWN
- LOW
- MEDIUM
- HIGH
- CRITICAL
description: >-
由规则/提供商设置的分类风险严重程度（`UNKNOWN`、`LOW`、`MEDIUM`、`HIGH`、`CRITICAL`）。在设置该值之前为
`null`。
decision_reason_code:
type: string
nullable: true
description: 当前 `status` 的机器可读原因。
decision_reason_label:
type: string
nullable: true
description: '`decision_reason_code` 的便于人类阅读的标签。'
vendor_data:
type: string
nullable: true
description: 申请人 `vendor_data` 的便捷副本。
metadata:
type: object
description: 创建时提交的 `subject` 和 `counterparty` payload 快照。
props:
type: object
description: >-
您在创建时提供的 `custom_properties`。每个键都可以在规则条件中通过 `custom_values.`
访问。
tags:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
name:
type: string
color:
type: string
description:
type: string
nullable: true
source:
type: string
enum:
- didit
- custom
description: 该标签是 Didit 预设还是自定义标签。
description: 附加到交易的标签（手动或通过规则）。
parties:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
role:
type: string
enum:
- APPLICANT
- REMITTER
- BENEFICIARY
- COUNTERPARTY
description: 当事方角色。创建 endpoint 会分配 `APPLICANT`（主体）和 `COUNTERPARTY`。
entity_type:
type: string
enum:
- individual
- company
- external
- unhostedWallet
kind:
type: string
enum:
- USER
- BUSINESS
- EXTERNAL
description: >-
`USER`/`BUSINESS` 当事方通过 `vendor_data` 关联回 Didit
拥有的实体。`EXTERNAL` 当事方背后没有 Didit 实体。
vendor_data:
type: string
nullable: true
description: 您的内部用户/企业标识符。
full_name:
type: string
nullable: true
first_name:
type: string
nullable: true
last_name:
type: string
nullable: true
country_code:
type: string
nullable: true
description: 来自提交的 `address.country` 的国家/地区代码（通常为 ISO 3166-1 alpha-3）。
dob:
type: string
format: date
nullable: true
description: 来自提交的 `date_of_birth` 的出生日期。
address:
type: object
description: 提交的地址对象。省略时为 `{}`。
institution_info:
type: object
description: 提交的机构详情。省略时为 `{}`。
device:
type: object
description: >-
归一化的设备上下文，在提供了 IP 时包含 network_context 下的服务端 IP
增强数据（地理位置、VPN/数据中心标志）。
properties:
fingerprint:
type: string
description: 唯一设备指纹。
persistent_device_id:
type: string
description: 跨会话的稳定设备标识符（v2 指纹架构）。
user_agent:
type: string
description: 浏览器或应用的 user agent 字符串。
browser_family:
type: string
description: 浏览器家族（例如 Chrome、Firefox、Safari）。
browser_version:
type: string
description: 浏览器版本字符串。
platform:
type: string
description: 平台标识符（web、ios、android、macos、windows、linux）。
os_family:
type: string
description: 操作系统系列（例如 iOS、Android、Windows）。
os_version:
type: string
description: 操作系统版本字符串。
accept_language:
type: string
description: Accept-Language 请求头的值。
session_id:
type: string
description: 会话标识符（存储在元数据中）。
session_age_ms:
type: number
description: 会话时长（毫秒）。
network_context:
type: object
description: 包含 IP 地址和地理位置的网络上下文。
properties:
ip_address:
type: string
description: 客户端 IP 地址。
ip_country_code:
type: string
description: 基于地理位置解析的 IP 所在国家/地区（ISO 3166-1 alpha-3）。
latitude:
type: number
description: 该 IP 的地理纬度。
longitude:
type: number
description: 该 IP 的地理经度。
external_party_snapshot:
type: object
nullable: true
description: '`EXTERNAL` 当事方数据的冻结副本。当该当事方关联到 Didit 用户或企业时为 `null`。'
description: 交易当事方（申请人、交易对手）。
payment_methods:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
payment_method_type:
type: string
enum:
- bank_card
- bank_account
- e_wallet
- crypto_wallet
- unhosted_wallet
- other
label:
type: string
nullable: true
fingerprint:
type: string
nullable: true
description: >-
针对 `type:account_id:issuing_country` 的
SHA-256，用于关联同一工具重复使用情况的稳定标识符。
account_id:
type: string
nullable: true
description: 账户标识符（IBAN、地址、银行卡 token 等）。
issuing_country:
type: string
nullable: true
owner_kind:
type: string
enum:
- USER
- BUSINESS
- EXTERNAL
vendor_data:
type: string
nullable: true
description: 您对所属用户/企业的标识符。
owner_name:
type: string
nullable: true
institution_info:
type: object
details:
type: object
description: 提交的原始 `payment_method` 对象。
external_owner_snapshot:
type: object
nullable: true
role:
type: string
enum:
- SOURCE
- DESTINATION
- FUNDING
- BENEFICIARY
description: >-
此方式在交易中的使用方式。创建 endpoint 会根据交易方向分配
`SOURCE`/`DESTINATION`（出向：主体 = SOURCE；入向：主体 = DESTINATION）。
description: 关联至交易的支付方式。
documents:
type: array
description: 从控制台附加到交易的文件。若无则为 `[]`。
items:
type: object
properties:
uuid:
type: string
format: uuid
label:
type: string
nullable: true
note:
type: string
nullable: true
uploaded_by:
type: string
nullable: true
created_at:
type: string
format: date-time
files:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
file_url:
type: string
format: uri
nullable: true
description: 短期签名下载 URL；请在需要时获取，而不是直接存储。
original_filename:
type: string
nullable: true
file_size:
type: integer
nullable: true
activities:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
activity_type:
type: string
description: >-
例如
`TRANSACTION_CREATED`、`TRANSACTION_NOTE_ADDED`、`TRANSACTION_STATUS_CHANGED`。
source:
type: string
status:
type: string
nullable: true
title:
type: string
nullable: true
description:
type: string
nullable: true
metadata:
type: object
occurred_at:
type: string
format: date-time
description: 活动日志条目（创建、备注、人工审核、状态变更）。
alerts:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
title:
type: string
description:
type: string
nullable: true
severity:
type: string
enum:
- UNKNOWN
- LOW
- MEDIUM
- HIGH
- CRITICAL
status:
type: string
enum:
- OPEN
- INVESTIGATING
- AWAITING_USER
- PENDING_SAR
- SAR_FILED
- RESOLVED
- DISMISSED
source:
type: string
enum:
- RULE
- PROVIDER
- MANUAL
metadata:
type: object
created_at:
type: string
format: date-time
due_at:
type: string
format: date-time
nullable: true
description: 当前始终为空。未结警报是指状态为 `IN_REVIEW` 或 `AWAITING_USER` 的交易。
rule_runs:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
rule:
type: string
format: uuid
description: 已运行规则的 UUID。
rule_title:
type: string
rule_description:
type: string
nullable: true
rule_category:
type: string
matched:
type: boolean
description: 规则条件是否与该交易匹配。仅针对匹配的规则记录运行，因此生产环境中的评估结果始终为 `true`。
is_test:
type: boolean
description: 当规则在 TEST 模式下运行时为 true（对状态/评分无影响）。
mode:
type: string
enum:
- ACTIVE
- DISABLED
- TEST
severity:
type: string
nullable: true
score_delta:
type: integer
description: 由该规则的 `add_score` 操作添加的分数。
status_target:
type: string
nullable: true
description: 由 `change_status` 操作设置的状态（如果有）。
action_summary:
type: string
nullable: true
description: >-
规则执行的操作摘要，以 `; ` 连接（例如 `score +30; change_status:IN_REVIEW;
add_tag:high_risk_country`）。组成部分包括：`score
+N`、`change_status:`、`add_tag:`、`add_note`、`add_to_list`、`open_case`。当规则未执行任何操作时为
`null`。
metadata:
type: object
description: >-
评估详情：`scope_match`、`conditions[]` 和 `aggregations[]`。每个条件条目包含
`field`、`operator`、`expected_value`、从交易中读取的
`current_value`、`matched`、`group_index` 和
`group_logic`。每个聚合条目（频次 / 计数 / 求和）包含
`metric`、`field`、`operator`、`expected_value`、聚合计算得出的
`computed_value`、`window`、`filters`、`matched` 和
`sample_references`；延迟的异步聚合其 `computed_value: null` 且
`deferred: true`。嵌套条件组是一个 `conditions[]` 条目，其 `operator` 为
`any_of` 或 `all_of`，`field` 为 null，且其成员的结果位于其自身的 `conditions`
下。
created_at:
type: string
format: date-time
description: 逐条规则的执行结果：触发了哪条规则，以及产生了怎样的评分影响。
provider_results:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
provider:
type: string
result_type:
type: string
enum:
- FIAT_MONITORING
- WALLET_SCREENING
- TRANSACTION_SCREENING
- TRAVEL_RULE
- NETWORK_GRAPH
- CUSTOM
status:
type: string
severity:
type: string
nullable: true
score:
type: integer
summary:
type: string
nullable: true
payload:
type: object
description: 原始供应商响应 payload。
created_at:
type: string
format: date-time
description: 原始供应商 payload（AML 筛查、区块链分析等）。
travel_rule:
nullable: true
allOf:
- $ref: '#/components/schemas/TransactionTravelRule'
description: >-
Travel Rule 转账或核验。在提交了 `travel_rule_details` 时填充，以及在启用了 Travel Rule
且创建交易时使用了 `transaction_category: travelRule` 时填充（即使没有
`travel_rule_details`，Didit 也会自行发起信息交换）。不存在转账或核验时为
`null`。在入账转账中，交易对手的 `originator_data` 和 `beneficiary_data`
保持掩码状态（`data_masked: true`），直到钱包所有权得到确认。
network_snapshot:
type: object
nullable: true
description: >-
规则引擎使用的相关交易/关联方图谱快照。可以随交易提交的 `network_snapshot`，也可以是 Didit 从成功的 AML
钱包筛查中构建的图谱（会替换提交的快照）。两者均不存在时为 `null`。
properties:
uuid:
type: string
format: uuid
nodes:
type: array
items:
type: object
edges:
type: array
items:
type: object
metrics:
type: object
remediation:
type: object
nullable: true
description: 需要重新验证时向用户提供的补救会话。已被规范字段 `action_required` 取代；保留以向后兼容。
properties:
session_id:
type: string
session_token:
type: string
url:
type: string
format: uri
status:
type: string
action_required:
type: object
nullable: true
description: >-
完成此交易所需的待处理终端用户操作，若无则为 null。Didit SDK
默认会自动启动该操作，并在其完成时刷新交易。共有两种变体，通过 `type`
进行区分：`verification_session`（由规则操作创建的托管验证会话）和
`wallet_ownership`（为需要钱包控制权证明的 Travel Rule 转账自动生成的钱包所有权微件会话，受
`auto_wallet_verification` Travel Rule
设置管控）。当两者均适用时，`wallet_ownership` 具有更高优先级，因为它会阻断 Travel Rule 交互。
oneOf:
- $ref: '#/components/schemas/TransactionVerificationSessionAction'
- $ref: '#/components/schemas/TransactionWalletOwnershipAction'
discriminator:
propertyName: type
mapping:
verification_session: '#/components/schemas/TransactionVerificationSessionAction'
wallet_ownership: '#/components/schemas/TransactionWalletOwnershipAction'
cost_breakdown:
type: object
nullable: true
description: >-
此交易的费用：`total_price` 和 `items`，每项收费一条记录，均包含
`usage_type`、`price`、`details` 和 `created_at`。对同一笔交易重新筛查会产生一个新条目。
TransactionTravelRule:
type: object
description: >-
交易的 Travel Rule 转账，正如 `GET /v3/transactions/{transaction_id}/`、`POST
/v3/transactions/` 的 `201` 以及 `GET /v3/transactions/`
的每行所返回的内容。`direction`、`rail`、`counterparty_vasp`、`delivery`、`discovery`、`reason`
和 `next_actions` 的结构与 `PATCH
/v3/transactions/{transaction_id}/travel-rule/`
相同，因此读取一次交易即可了解其转账受阻的原因以及如何继续推进。
properties:
uuid:
type: string
format: uuid
status:
type: string
protocol:
type: string
nullable: true
required:
type: boolean
obligations_count:
type: integer
originator_data:
type: object
description: 汇款人方。对于入账转账，在所有权确认之前，交易对手的值将被掩码遮盖。
beneficiary_data:
type: object
description: 收款人方。对于入账转账，在确认所有权之前，交易对手的值将被遮蔽。
name_match:
type: object
nullable: true
description: 决定转账的姓名比对结果（分数和严格程度）。在运行比对前为 null。比对的姓名与当事方一同脱敏。
data_match:
$ref: '#/components/schemas/TravelRuleDataMatch'
mismatched_fields:
type: array
items:
type: string
description: '`data_match.mismatched_fields` 的快捷方式。无差异时为空。'
data_unmasked:
$ref: '#/components/schemas/TravelRuleDataUnmasked'
data_masked:
type: boolean
description: 在此响应中交易对手的个人数据被遮蔽时为 True。
metadata:
type: object
direction:
type: string
enum:
- INBOUND
- OUTBOUND
description: 此笔转账属于交易的哪一方。
rail:
type: string
nullable: true
description: >-
转账所走的通道：`INTERNAL`、`TRP`、`GTR`、`TRUST`、`VERIFYVASP`、`SYGNA` 或
`EMAIL`（在沙盒应用上且由 Didit Test VASP 应答时为 `TEST_VASP`），在选定通道前为 `null`。
counterparty_vasp:
type: object
nullable: true
properties:
name:
type: string
lei:
type: string
dd_score:
type: integer
description: 尽职调查评分，范围为 0 到 100，分数越高越好。分值范围与 VASP 名录相同。
dd_score_breakdown:
type: object
description: >-
对 dd_score 的各组件贡献度，每个组件一个对象（对应 VASP 目录中的
jurisdiction、verification、protocol、lei、history、essentials、responsiveness），每个组件均包含
{points, max, reason, detail}。在交易对手完成评估前为 {}。
additionalProperties:
type: object
properties:
points:
type: number
description: 为该组件分配的点数。
max:
type: integer
description: 该组件可赋予的最大分值。
reason:
type: string
description: 组件判定结果的机器可读代码。
detail:
type: string
description: 易于阅读的积分授予原因。
dd_assessed_at:
type: string
format: date-time
nullable: true
description: 尽职调查评估上次运行的时间。在对交易对手进行评估之前为 Null。
description: 交易对手的名录条目；若转账未关联任何条目，则为 `null`。
delivery:
nullable: true
allOf:
- $ref: '#/components/schemas/TravelRuleDelivery'
description: >-
该转账应发送给另一方的最新消息。若无需发送任何消息（例如金额低于 `threshold_amount` 或针对声明的自托管钱包），则为
`null`。
discovery:
type: array
description: Didit 查找交易对手的方式，每个运行的步骤对应一个条目。未运行发现流程时为空，例如对于入站转账。
items:
$ref: '#/components/schemas/TravelRuleDiscoveryStep'
reason:
type: string
description: >-
`COUNTERPARTY_VASP_NOT_FOUND` 或 `COUNTERPARTY_VASP_NOT_REACHABLE`
转账受阻的原因；任何其他状态下为 `""`。首先由失败的投递决定（仅适用于
`COUNTERPARTY_VASP_NOT_REACHABLE`）：`email_undeliverable`（邮件服务商拒绝了合规邮件，且没有可尝试的地址：发送时、发送提醒时或后续报告为永久退信）或
`delivery_failed`（负责投递的通道彻底失败：网络通道拒绝了消息或重试次数耗尽、`TRP` 身份主机未应答，或交易对手的
`TRP` 主机不接受查询）。否则由 `discovery` 追踪记录决定：`awaiting_end_user`（没有任何步骤指定
Didit 可触达的交易对手）、`directory_match_no_route`（某步骤指定了名录中的 VASP，但该 VASP
没有可用路由）、`picked_member_without_proven_wallet`（终端用户选择的 Didit
客户尚未证明对该钱包的控制权），或者在追踪记录未提供其他原因时的
`no_directory_match`。重新发送后转账会继续推进，因此该原因将被清除。参见[转账受阻的原因](/zh/transaction-monitoring/travel-rule#为什么转账会卡住)。
next_actions:
type: array
description: >-
推进转账的操作；除 `COUNTERPARTY_VASP_NOT_FOUND` 或
`COUNTERPARTY_VASP_NOT_REACHABLE` 之外的任何状态均返回
`[]`。`email_undeliverable` 提供 `update_compliance_email`，然后提供
`resend`。`delivery_failed` 提供 `resend`。发现原因提供
`select_counterparty_vasp`、`declare_self_hosted`、`add_vasp_hint` 和
`resend`。
items:
$ref: '#/components/schemas/TravelRuleNextAction'
chain_details:
$ref: '#/components/schemas/TravelRuleChainDetails'
TransactionVerificationSessionAction:
title: Verification session
type: object
properties:
type:
type: string
enum:
- verification_session
url:
type: string
format: uri
description: 供终端用户打开的托管验证 URL。
session_id:
type: string
format: uuid
description: 验证会话 ID。
session_token:
type: string
description: 会话 token，移动端 SDK 用于原生启动流程。
status:
type: string
description: 验证会话状态。
required:
- type
- url
TransactionWalletOwnershipAction:
title: Wallet ownership
type: object
properties:
type:
type: string
enum:
- wallet_ownership
url:
type: string
format: uri
description: >-
托管钱包所有权微件 URL。请在真实浏览器环境中打开：在移动端请使用 SFSafariViewController 或 Chrome
Custom Tab，切勿使用嵌入式 webview。
widget_session_id:
type: string
format: uuid
description: 钱包所有权小部件会话 ID。
expires_at:
type: string
format: date-time
description: 小组件会话过期的时间。
required:
- type
- url
TravelRuleDataMatch:
type: object
nullable: true
description: >-
转账当事方数据与对方已知的钱包持有人信息之间的逐字段比对。该项仅指明字段和结果，绝不包含具体值，因此在交易对手数据被脱敏的同时仍保持可读性。在执行比对前为
null。
properties:
matched:
type: boolean
description: 当比对的字段均无差异时为 true。
mismatched_fields:
type: array
items:
type: string
enum:
- name
- date_of_birth
- address
- account
description: 存在差异的字段。
fields:
type: object
description: >-
针对该参与方实体类型所比对的每个字段对应一个条目（`name`、`date_of_birth`、`address`、`account`；企业没有
`date_of_birth`）。
additionalProperties:
type: object
properties:
result:
type: string
enum:
- matched
- mismatched
- not_compared
description: 当规则为 `NONE` 或任一方该字段均无值时为 `not_compared`。
strictness:
type: string
enum:
- NONE
- STRICT
- CONTAINS
- DEFAULT
- FUZZY
TravelRuleDataUnmasked:
type: object
nullable: true
description: 交易对手数据解除掩码时刻的审计记录。当数据仍处于掩码状态时以及出站转账时为 null。
properties:
at:
type: string
format: date-time
reason:
type: string
enum:
- ownership_confirmed
- wallet_proof
- address_book_match
- own_verified_wallet
- inquiry_approved
- known_payment_method
- travel_address
description: >-
确认股权结构的依据：ownership_confirmed（您通过控制台或 API
进行的确认）、wallet_proof（小组件中的钱包证明，或在创建时设置的 INTERNAL
入站转账）、address_book_match（已验证的地址簿钱包）、own_verified_wallet（您的用户本人的已验证钱包）、inquiry_approved（您对入站
TRP 问讯或 GTR 或 Sygna 消息的批准）、known_payment_method（您的用户已用于付款的钱包）或
travel_address（按钱包分配的 Travel Address 指定了该钱包）。
actor:
type: string
description: 确认此项的主体：控制台用户的邮箱或 API 密钥的标签。自动决策时为空白。
TravelRuleDelivery:
type: object
description: >-
该转账应发送给对方的最新消息所处的状态。Didit
会在创建或修改转账的请求返回后联系交易对手，因此该对象显示该消息是否成功送达：已排队（queued）、正在发送（being
sent）、出错后等待重试（waiting to be retried after an
error）、已投递（delivered）或已失败（failed）。网络仍可能恢复的故障（超时未响应、连接失败、HTTP `408`、`429`
或 `5xx`）会在 30 秒、2 分钟、10 分钟、30 分钟和 1 小时后再次重试。当首条消息（`kind:
SEND`）彻底失败（因为网络拒绝或第 6 次尝试也失败）时，转账状态将变为
`COUNTERPARTY_VASP_NOT_REACHABLE`，并在其 `timeline` 中记录
`last_error`；任何其他彻底失败的消息也会在 `timeline` 中标明。转账的 `status` 始终是交易本身的真实事实来源。
required:
- kind
- status
- rail
- attempts
- last_error
- next_attempt_at
- delivered_at
properties:
kind:
type: string
enum:
- SEND
- ANSWER
- TXID
- CANCEL
- POLL
description: >-
该消息携带的内容。`SEND`：发送给交易对手的首条转账消息（出站；在发送时选择通道）。`ANSWER`：您对发起请求的网络做出的接受或拒绝（入站）。`TXID`：完成转账后的链上交易哈希。`CANCEL`：取消操作（在您取消转账之后）。`POLL`：向支持状态查询的网络发起的查询请求，在转账等待交易对手期间每
5 分钟重复一次。
status:
type: string
enum:
- QUEUED
- SENDING
- RETRYING
- DELIVERED
- FAILED
description: >-
`QUEUED`：等待发送。`SENDING`：正在尝试发送。`RETRYING`：尝试失败，下一次尝试将在
`next_attempt_at` 运行。`DELIVERED`：对方已接收消息。`FAILED`：对方拒绝接收，或最后一次尝试失败。
rail:
type: string
enum:
- INTERNAL
- TRP
- GTR
- TRUST
- VERIFYVASP
- SYGNA
- EMAIL
- ''
description: 承载该消息的通道。在 Didit 为第一条消息选定通道之前为空。
attempts:
type: integer
minimum: 0
description: 截至目前针对该消息进行的尝试次数。非状态轮询的消息最多尝试 6 次。
last_error:
type: string
description: >-
上次尝试遇到的失败类型，无失败时为 `""`：例如 `email undeliverable`、`trp identity
endpoint unreachable` 或 `trp transfer inquiry delivery
failed`。它从不包含交易对手自身的回复，后者保留在转账的 `timeline` 中。
当 GTR 回复错误时，会包含其自身的状态码和消息。绝不包含响应体。
example: email undeliverable
next_attempt_at:
type: string
format: date-time
nullable: true
description: 当消息处于 `QUEUED` 或 `RETRYING` 状态时，下一次尝试运行的时间。
delivered_at:
type: string
format: date-time
nullable: true
description: 对方接收消息的时间。
TravelRuleDiscoveryStep:
type: object
description: Didit 为出站转账执行的交易对手发现中的一个步骤，按执行顺序排列。第一个指定了具有可用路由的 VASP 的步骤将终止链条。
properties:
step:
type: string
enum:
- internal_address_book
- wallet_attribution
- network_lookup
- customer_hint
- end_user
description: >-
`internal_address_book`：已证明拥有目标钱包控制权的另一位 Didit
客户。`wallet_attribution`：钱包的区块链分析归属。`network_lookup`：能够辨明持有该地址之 VASP
的网络。`customer_hint`：您在 `beneficiary_data` 中发送的 VASP 名称、LEI
或司法管辖区。`end_user`：终端用户（或您）选择的交易对手，或选择交易对手的请求。
outcome:
type: string
enum:
- match
- miss
- skipped
description: '`match`：该步骤指明了交易对手。`miss`：已运行但未找到。`skipped`：无法运行，`reason` 说明了原因。'
reason:
type: string
description: >-
机器可读的原因，匹配时为
`""`：`no_proven_internal_wallet`、`attribution_disabled`、`already_attributed`、`no_attributed_entity`、`directory_match_no_route`、`gtr_address_lookup_runs_on_dispatch`、`no_membership`、`network_switched_off`、`no_network_address_lookup`、`no_directory_match`、`awaiting_end_user`
或 `picked_member_without_proven_wallet`。
vasp:
type: string
format: uuid
nullable: true
description: 步骤中指定的目录 VASP（若有指定）。
rail:
type: string
nullable: true
description: 该步骤找到的、可触达该交易对手的通道。
at:
type: string
format: date-time
TravelRuleNextAction:
type: object
description: >-
推动处于 `COUNTERPARTY_VASP_NOT_FOUND` 或 `COUNTERPARTY_VASP_NOT_REACHABLE`
状态的转账继续进行的一项操作。请参阅[转账卡住的原因](/zh/transaction-monitoring/travel-rule#为什么转账会卡住)。
properties:
action:
type: string
enum:
- select_counterparty_vasp
- declare_self_hosted
- add_vasp_hint
- update_compliance_email
- resend
description: >-
`select_counterparty_vasp`：终端用户在钱包所有权组件中选择目标 VASP，或者您通过 PATCH 传入
`action=beneficiary_vasp`。`declare_self_hosted`：终端用户在组件中声明该钱包为自托管钱包。`add_vasp_hint`：通过
VASP 名称、LEI 或 Travel Address（例如目标钱包地址簿条目上的 `travel_address`）告知 Didit
交易对手是谁，然后重新发送。`update_compliance_email` 和 `resend` 是 `PATCH
/v3/transactions/{transaction_id}/travel-rule/` 的 `action`
取值：再次提供交易对手的合规邮箱，并重新运行路由。
url:
type: string
format: uri
description: >-
钱包所有权小组件链接，当转账拥有开启的小组件会话时，出现在 `select_counterparty_vasp` 和
`declare_self_hosted` 状态下。
required:
- action
TravelRuleChainDetails:
type: object
description: >-
当转账涉及的不止是一个地址向另一个地址付款时，该交易所在区块链对其两个钱包的命名方式。对于账户模型区块链上的转账（EVM、Solana、Tron），由于两个地址本身就是钱包，因此该字段为空（`{}`）。匹配、路由和地址簿会优先从此字段读取钱包信息。
properties:
chain:
type: string
description: 规范链，例如 `BTC`、`XRP`，或用于闪电网络转账的 `LIGHTNING`。
shape:
type: string
enum:
- utxo
- memo
- lightning
originator:
$ref: '#/components/schemas/TravelRuleChainSide'
beneficiary:
$ref: '#/components/schemas/TravelRuleChainSide'
utxo:
type: object
description: 在 UTXO 转账中：存储的输入和输出（金额为十进制字符串）以及 Didit 将哪些输出读取为何种内容。
properties:
inputs:
type: array
items:
$ref: '#/components/schemas/TravelRuleUtxoEntry'
outputs:
type: array
items:
$ref: '#/components/schemas/TravelRuleUtxoEntry'
change_output_indexes:
type: array
items:
type: integer
description: 向输入地址回款的输出。
beneficiary_output_index:
type: integer
nullable: true
description: 向收款人付款的输出；若无法明确区分则为 null。
lightning:
type: object
description: >-
在 Lightning 转账中：付款请求的内容。始终包含
`kind`（`bolt11`、`bolt12_offer`、`bolt12_invoice`、`bolt12_invoice_request`、`lnurl`、`lightning_address`、`node_id`
或 `unknown`）；BOLT11 发票会附加
`network`、`payee_node_id`、`payment_hash`、`amount_msat`、`created_at`
和 `expires_at`；BOLT12 字符串附加 `blinded_paths` 和 `payee_node_id`；LNURL
或 Lightning Address 附加其 `domain`。不会通过网络解析任何内容：仅对请求进行解码。
additionalProperties: true
warnings:
type: array
items:
type: string
enum:
- declared_originator_not_an_input
- declared_beneficiary_not_an_output
- beneficiary_output_ambiguous
- beneficiary_output_amount_differs
description: >-
值得关注的 UTXO
不一致性：声明的汇款人不是输入、声明的收款人不是输出、无法区分出单一的收款人输出，或收款人输出支付的金额与交易声明的不一致。
not_applicable_reason:
type: string
enum:
- LIGHTNING_NO_PAYEE_IDENTIFIER
- LIGHTNING_BOLT12_BLINDED_PAYEE
- LIGHTNING_LNURL_NAMES_NO_PAYEE
description: >-
在未指明收款人的出站 Lightning 转账中：转账为何为
`NOT_APPLICABLE`。`LIGHTNING_NO_PAYEE_IDENTIFIER`（请求未指明收款人节点，或无法解码）、`LIGHTNING_BOLT12_BLINDED_PAYEE`（报价通过盲化路径隐藏了收款人）、`LIGHTNING_LNURL_NAMES_NO_PAYEE`（LNURL
指明的是服务而非收款人）。相同的代码会打开转账的最后一条 `timeline` 条目。
TravelRuleChainSide:
type: object
description: Didit 根据链上数据解析出的其中一方钱包。
properties:
address:
type: string
description: >-
钱包。在 memo 网络上为经典地址（XRP X-address 会被拆分为其经典地址和标签）；在闪电网络上为收款人节点 ID
或闪电网络地址。
memo:
type: string
description: 作为钱包一部分的目标标签或 memo；无则为 `""`。
source:
type: string
enum:
- declared
- x_address
- largest_input
- only_non_change_output
- amount_match
- invoice_payee
- updated
description: >-
钱包来源：`declared`（您的请求）、`x_address`（从 XRP X-address
拆分）、`largest_input`（贡献最大的 UTXO 输入地址）、`only_non_change_output`（唯一的非找零
UTXO 输出）、`amount_match`（支付转账金额的那个 UTXO
输出）、`invoice_payee`（闪电网络付款请求中指定的收款人）、`updated`（稍后通过 `action:
update_originator_wallet` 设置）。
TravelRuleUtxoEntry:
type: object
description: UTXO 交易的一个输入或输出，与区块链上记录的一致。
required:
- address
properties:
address:
type: string
maxLength: 128
amount:
type: string
nullable: true
description: 以代币自身为单位的十进制字符串（BTC，而非聪）。可选。
example: '0.0125'
txid:
type: string
maxLength: 128
description: 可选。输入所花费的交易。
vout:
type: integer
nullable: true
minimum: 0
description: 可选。输入所花费的输出索引。
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
您的应用 API 密钥，可在 Business Console 的“开发者 -> API
密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于
IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP
列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF
URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅
https://docs.didit.me/console/api-keys。
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.