> ## 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. # Travel Rule 转账操作 API：完成、取消、重新发送、更新 > 通过 Didit 的 Travel Rule 转账 API，用链上哈希完成转账、取消或重新发送转账，或记录资金实际转出的钱包地址。 Travel Rule 转账操作 API 提示词 将提示词复制到剪贴板 \

\`Act on an existing Travel Rule transfer: report the on-chain hash to finish it, cancel it, re-run counterparty routing, replace a refused compliance email, or record the wallet the funds left from.

Endpoint:
PATCH https://verification.didit.me/v3/transactions/{transaction_id}/travel-rule/

Authentication:
Use the x-api-key header with my Didit API key. {transaction_id} is the Didit transaction uuid.

Four mutually exclusive bodies:

1\. Finish (close out after broadcasting on-chain):
\{"payment_txn_id": "0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060"}
\- Requires an OUTBOUND transfer in COMPLETED status - otherwise 409.
\- Moves the transfer (and its INTERNAL-rail counterpart, if any) to FINISHED and stores the hash on the transaction.
\- Over GTR, VerifyVASP or Sygna Bridge, the network learns the hash after the response, with retries (see delivery below).
\- On the TRP rail, Didit also posts the hash to the counterparty's confirmation callback.

2\. Cancel:
\{"action": "cancel"}
\- Allowed from any non-terminal status; moves the transfer (and its INTERNAL-rail counterpart, if any) to CANCELLED.
\- From a terminal status (FINISHED, CANCELLED, EXPIRED) it returns 409.
\- On an outbound TRP transfer, Didit also sends a cancellation to the counterparty.
\- Over GTR, VerifyVASP or Sygna Bridge, the network is told after the response, with retries.

3\. Resend (re-run the routing ladder):
\{"action": "resend"}
\- Allowed only on an OUTBOUND transfer in COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE, or NOT_ENOUGH_COUNTERPARTY_DATA - otherwise 409.
\- Resets the deadline and re-runs routing; a transfer whose destination wallet was declared unhosted moves to UNCONFIRMED_OWNERSHIP.
\- First give Didit a route, for example by registering the destination wallet in your address book (same chain as the transfer, or a blank chain) with the counterparty's travel_address (TRP carries BTC, ETH, and USDC on a named network), or by adding a compliance contact for the counterparty's directory entry with POST /v3/travel-rule/counterparty-contacts/, then resend.
\- Resend reuses the transfer's beneficiary_data, which you cannot change after creation except for the compliance email (body 4), so submit a new transaction to send different beneficiary data.
\- A previously recorded blockchain-analytics attribution is reused - no new lookup, no new charge.
\- Discovery runs again from the first step (internal address book, wallet attribution, network lookup, your VASP hint, then the end user); the transfer's "discovery" list shows what each step found.
\- Queued, not run inside the request: the response shows the transfer back in AWAITING_COUNTERPARTY with a "resend queued" timeline entry, and the outcome arrives as a travel_rule.status.updated webhook. A resend sent while an earlier attempt is still running is sent once that attempt settles.
\- If routing still resolves nothing, the transfer lands back in COUNTERPARTY_VASP_NOT_FOUND.

4\. Update the compliance email (the fix for reason email_undeliverable):
\{"action": "update_compliance_email", "compliance_email": "desk@bene-casp.example"}
\- Allowed only on an OUTBOUND transfer in COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE, or NOT_ENOUGH_COUNTERPARTY_DATA - otherwise 409.
\- A missing or malformed compliance_email returns 400.
\- Stores the address as this transfer's beneficiary_data.counterparty_vasp_email; it belongs to this transfer only and joins no directory entry or contact list.
\- The status does not change and the timeline gains "compliance email updated". The transfer keeps reason email_undeliverable until you send {"action": "resend"}, which sends the request to the new address.

4\. Update the originator wallet (the wallet the funds actually left from):
\{"action": "update_originator_wallet", "wallet_address": "bc1q...", "memo": ""}
\- Outbound transfers only (an inbound transfer -> 409), and never a CANCELLED or EXPIRED one (-> 409).
\- Use it when a withdrawal is broadcast from another address than the one declared, typically a UTXO withdrawal spending whichever addresses held the coins. When the transfer's UTXO inputs are known, wallet_address must be one of them (-> 400 otherwise).
\- Changes the record only: nothing is sent to the counterparty again and the status stays. chain_details.originator becomes the new wallet with source "updated", the timeline records the previous and the new wallet, and the INTERNAL-rail counterpart is updated the same way.

5\. Name the counterparty (when discovery could not):
\{"action": "beneficiary_vasp", "beneficiary_vasp": ""}
\- The id comes from GET /v3/travel-rule/vasps/.
\- Allowed only for an outbound transfer in COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE, or NOT_ENOUGH_COUNTERPARTY_DATA - otherwise 409.
\- Routes the transfer to that VASP and sends it again; automatic discovery never overrides your choice.
\- 400 if beneficiary_vasp is missing or not a valid id, 404 if no directory entry has that id.

What to read from the response:
\- The full transfer object: status, rail, direction, ownership_confirmed, deadline_at, timeline, counterparty_vasp, delivery, discovery, reason, next_actions.
\- delivery: the latest message the transfer owes the other side - kind (SEND, ANSWER, TXID, CANCEL, POLL), status (QUEUED, SENDING, RETRYING, DELIVERED, FAILED), rail, attempts, last_error, next_attempt_at, delivered_at. Failures a network may recover from are retried after 30 s, 2, 10, 30 and 60 minutes; when a first message fails for good the transfer moves to COUNTERPARTY_VASP_NOT_REACHABLE. null when the transfer never owed a message.
\- reason and next_actions say why a COUNTERPARTY_VASP_NOT_FOUND or COUNTERPARTY_VASP_NOT_REACHABLE transfer is stuck and what moves it on: email_undeliverable offers update_compliance_email then resend, delivery_failed offers resend, and a discovery reason offers select_counterparty_vasp, declare_self_hosted, add_vasp_hint and resend. Both are empty for any other status, so they clear once a resend moves the transfer on.

Order of operations for outbound transfers:
submit transaction -> wait for travel_rule.status == "COMPLETED" -> broadcast on-chain -> PATCH with payment_txn_id -> FINISHED.
Never broadcast before COMPLETED.
A transfer sent over TRUST cannot reach COMPLETED, because TRUST sends back nothing Didit can read; it stays AWAITING_COUNTERPARTY until it expires. Over GTR, VerifyVASP and Sygna Bridge, Didit reads the counterparty's answer from the network.
If the message cannot be delivered, the transfer moves to COUNTERPARTY_VASP_NOT_REACHABLE instead.

Failure modes:
\- 400 - the body has none of payment_txn_id or a supported action, update_compliance_email has a missing or malformed compliance_email, or a wallet_address or memo the transfer's chain cannot carry.
\- 409 - action not allowed from the transfer's current status or direction (see the per-action rules above).
\- 400 - action=beneficiary_vasp without a valid beneficiary_vasp.
\- 404 - unknown transaction, no Travel Rule transfer attached, or (action=beneficiary_vasp) no directory entry has that id.

Full guide: /transaction-monitoring/travel-rule#sending-a-transfer and /transaction-monitoring/travel-rule#why-a-transfer-is-stuck.`

\
粘贴到 ## OpenAPI ````yaml zh/openapi-25.json PATCH /v3/transactions/{transaction_id}/travel-rule/ 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}/travel-rule/: patch: tags: - Travel Rule summary: 完成、取消、重新发送或更新 Travel Rule 转账的汇款人钱包 description: >- 提供 `payment_txn_id` 以报告链上哈希并将出站 COMPLETED 转账变为 FINISHED（其 INTERNAL 轨道的对应转账也会变为 FINISHED）；提供 `{"action": "cancel"}` 以取消非终态转账；或提供 `{"action": "resend"}` 以对卡在 COUNTERPARTY_VASP_NOT_FOUND、COUNTERPARTY_VASP_NOT_REACHABLE 或 NOT_ENOUGH_COUNTERPARTY_DATA 的出站转账重新路由（请先完善交易对手数据，例如向目标钱包条目添加 travel_address）。resend 仅适用于出站转账。`{"action": "update_compliance_email", "compliance_email": "desk@example.com"}` 用于替换处于这三种状态之一的出站转账的合规邮箱，这是针对 `reason: email_undeliverable` 的修复方案：状态不会改变，下一次 `resend` 会向该地址发送请求。重新发送会进入队列，而不是在请求内同步执行：响应显示转账恢复为 AWAITING_COUNTERPARTY 状态，并带有 `resend queued` 时间线记录以及处于排队状态的 `delivery`，其投递去向会通过 `travel_rule.status.updated` Webhook 送达。当转账通过 GTR、VerifyVASP 或 Sygna Bridge 进行时，网络会在响应之后获悉链上哈希或取消操作，并支持重试；`delivery` 显示该消息的当前状态。`{"action": "update_originator_wallet", "wallet_address": "..."}` 记录出站转账中资金实际流出的钱包，例如 UTXO 提现广播时使用的地址，而非您声明的主钱包。此操作仅修改记录：不会向交易对手再次发送任何内容，状态保持不变。汇款人变更为 `chain_details.originator` 且 `source: updated`，该变更会连同先前与新的钱包一起添加到 `timeline` 中，且转账的 INTERNAL 轨道对应记录也会以相同方式更新。`{"action": "beneficiary_vasp", "beneficiary_vasp": ""}` 用于在自动发现失败时，针对处于 COUNTERPARTY_VASP_NOT_FOUND、COUNTERPARTY_VASP_NOT_REACHABLE 或 NOT_ENOUGH_COUNTERPARTY_DATA 状态的出站转账自行指定交易对手：转账将路由至该 VASP 并重新发送。 operationId: patchTravelRuleTransfer parameters: - name: transaction_id in: path required: true description: 拥有该转账的 Didit 稳定交易 UUID。 schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TravelRuleTransferPatchRequest' examples: Finish: value: payment_txn_id: 0xchainhash Cancel: value: action: cancel Resend: value: action: resend Update compliance email: value: action: update_compliance_email compliance_email: desk@example.com Update originator wallet: value: action: update_originator_wallet wallet_address: bc1qOriginatorInputAddress01 Name the counterparty: value: action: beneficiary_vasp beneficiary_vasp: 9f1c2b34-5d6e-4f70-8a91-b2c3d4e5f607 responses: '200': description: >- 已更新的转账。在执行 `update_compliance_email` 后，其状态保持不变，并保留 `reason: email_undeliverable`，直到下一次 `resend`。 content: application/json: schema: $ref: '#/components/schemas/TravelRuleTransferDetail' '400': description: >- 既未提供 payment_txn_id 也未提供支持的操作，在 `update_compliance_email` 时缺少 `compliance_email` 或其不是有效的邮箱地址，或者对于 `update_originator_wallet`，未提供 wallet_address、钱包或 memo 无法由该转账所在链承载、钱包不是该转账的 UTXO 输入之一，或 `beneficiary_vasp` 缺失或不是有效的名录 VASP id。 content: application/json: examples: No action: value: detail: - >- Provide payment_txn_id, action=cancel, action=resend, action=beneficiary_vasp, action=update_originator_wallet or action=update_compliance_email. Invalid compliance email: value: compliance_email: - Enter a valid email address. '404': description: 未知的交易、该交易没有 Travel Rule 转账，或者（操作 `beneficiary_vasp`）名录条目中不存在该 ID。 '409': description: >- 转账未处于允许此操作的状态（例如完成操作未处于 COMPLETED/出账状态，取消操作已处于终态，或重新发送操作未处于可重新发送状态的出账转账）。对于入账转账以及处于 COUNTERPARTY_VASP_NOT_FOUND、COUNTERPARTY_VASP_NOT_REACHABLE 和 NOT_ENOUGH_COUNTERPARTY_DATA 之外的出账转账，`update_compliance_email` 响应 `409`。对于入账、已取消或已过期的转账，`update_originator_wallet` 响应 `409`。除非转账为出账且处于 COUNTERPARTY_VASP_NOT_FOUND、COUNTERPARTY_VASP_NOT_REACHABLE 或 NOT_ENOUGH_COUNTERPARTY_DATA 状态，否则 `beneficiary_vasp` 响应 `409`。 content: application/json: examples: Cancel from a terminal status: value: detail: Transfer is already in a terminal state. Resend not allowed: value: detail: Transfer cannot be resent from its current state. Finish not allowed: value: detail: >- Transfer must be an outbound transfer in COMPLETED status to finish. Compliance email cannot change: value: detail: >- The compliance email of this transfer cannot change from its current state. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X PATCH https://verification.didit.me/v3/transactions/{transaction_id}/travel-rule/ \ -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \ -d '{"payment_txn_id": "0xchainhash"}' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.transactions.travel_rule.update_transfer( "11111111-2222-3333-4444-555555555555", payment_txn_id="0xchainhash", ) 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.travelRule.updateTransfer("11111111-2222-3333-4444-555555555555", { payment_txn_id: "0xchainhash", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.TravelRule.UpdateTransfer(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleTransferPatchRequest{\n\tPaymentTxnID: didit.String(\"0xchainhash\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.TravelRuleTransferPatchRequest; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.transactions().travelRule().updateTransfer("11111111-2222-3333-4444-555555555555", TravelRuleTransferPatchRequest.builder() .paymentTxnId("0xchainhash") .build()); System.out.println(result); - lang: php label: PHP source: >- transactions->travelRule->updateTransfer('11111111-2222-3333-4444-555555555555', [ 'payment_txn_id' => '0xchainhash', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.transactions.travel_rule.update_transfer( "11111111-2222-3333-4444-555555555555", payment_txn_id: "0xchainhash" ) 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.TravelRule.UpdateTransferAsync("11111111-2222-3333-4444-555555555555", new TravelRuleTransferPatchRequest { PaymentTxnId = "0xchainhash", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: TravelRuleTransferPatchRequest: type: object description: >- 请恰好提供以下之一：payment_txn_id（完成）、action=cancel、action=resend、带有 compliance_email 的 action=update_compliance_email、带有 wallet_address 的 action=update_originator_wallet，或带有 beneficiary_vasp 的 action=beneficiary_vasp。 properties: payment_txn_id: type: string description: 链上交易哈希。要求该转账为处于 COMPLETED 状态的出向转账。 action: type: string enum: - cancel - resend - update_compliance_email - update_originator_wallet - beneficiary_vasp description: >- "cancel" 取消非终态转账。"resend" 对停留在 COUNTERPARTY_VASP_NOT_FOUND、COUNTERPARTY_VASP_NOT_REACHABLE 或 NOT_ENOUGH_COUNTERPARTY_DATA 状态的出向转账重新运行路由。"update_compliance_email" 替换该请求所发送到的合规邮箱（适用于处于这三种状态之一的出向转账）；之后发送 "resend"。"update_originator_wallet" 记录资金实际转出的钱包（`wallet_address`、`memo`）。"beneficiary_vasp" 由您自行指定处于上述状态之一的出向转账的交易对手 VASP（需要 `beneficiary_vasp`）：请求将被路由至该 VASP 并重新发送。 compliance_email: type: string format: email maxLength: 254 description: >- 当 `action: update_compliance_email` 时必填。保存为该笔转账的 `beneficiary_data.counterparty_vasp_email`：仅归属于该笔转账，不加入任何名录条目或联系人列表。 wallet_address: type: string maxLength: 128 description: >- 配合 `action: update_originator_wallet`：资金流出的钱包。当转账的 UTXO 输入已知时，必须是其中之一。 memo: type: string maxLength: 256 description: '配合 `action: update_originator_wallet`：该钱包在 memo 网络上的 memo 或 tag。可选。' beneficiary_vasp: type: string format: uuid description: >- 当 action=beneficiary_vasp 时必填：来自 `GET /v3/travel-rule/vasps/` 的名录 VASP 的 `id`。您的选择优先于所有自动发现步骤，且绝不会被覆盖。 TravelRuleTransferDetail: type: object description: >- 所有权确认以及完成/取消 endpoint 返回的完整转账对象。当入站转账的钱包所有权未确认时，交易对手的 `originator_data` 和 `beneficiary_data` 会被掩码返回（保留每个单词的首字母；钱包、链以及 VASP 路由保持可读），且 `data_masked` 为 true。 properties: uuid: type: string format: uuid status: type: string enum: - AWAITING_COUNTERPARTY - ON_HOLD - COMPLETED - FINISHED - CANCELLED - EXPIRED - COUNTERPARTY_MISMATCHED_DATA - COUNTERPARTY_VASP_NOT_FOUND - COUNTERPARTY_VASP_NOT_REACHABLE - UNCONFIRMED_OWNERSHIP - COUNTERPARTY_VASP_GENERAL_DECLINE - NOT_ENOUGH_COUNTERPARTY_DATA - NOT_APPLICABLE direction: type: string enum: - INBOUND - OUTBOUND rail: type: string nullable: true enum: - INTERNAL - TRP - GTR - TRUST - VERIFYVASP - SYGNA - EMAIL - TEST_VASP - null description: >- 转账路由所使用的通道，如果未选择通道（例如低于阈值、交易对手为自托管钱包、充值后登记或无触达的交易对手），则为 null。INTERNAL 表示双方均为 Didit 应用；EMAIL 表示通过电子邮件发送的提取链接触达交易对手。TEST_VASP 表示由 Didit Test VASP 响应沙盒转账。在 GTR、VERIFYVASP 和 SYGNA 上，Didit 会从网络响应中读取交易对手的回答，或每 5 分钟轮询一次。TRUST 仅支持发送，因此 TRUST 转账将一直保持 AWAITING_COUNTERPARTY 状态直至过期。网络通道仅在您已关联该网络自身会员资格时使用。它在交易创建返回后选定，因此在该响应中为 null。 protocol: type: string nullable: true ivms_version: type: string example: ivms101.2023 required: type: boolean ownership_confirmed: type: boolean nullable: true deadline_at: type: string format: date-time nullable: true timeline: type: array items: type: object properties: status: type: string at: type: string format: date-time detail: type: string name_match: allOf: - $ref: '#/components/schemas/TravelRuleNameMatch' nullable: true description: 该条目决定的姓名比对结果，位于 `detail` 旁边。未比对姓名的条目中不存在该字段。 reason: type: string description: >- 仅在投递失败导致的状态流转条目中存在：`email_undeliverable` 或 `delivery_failed`，即转账的 `reason` 所报告的值。 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。 originator_data: type: object description: 汇款人方。对于入账转账，在所有权确认之前，交易对手的值将被掩码遮盖。 beneficiary_data: type: object description: 收款人方。对于入账转账，在确认所有权之前，交易对手的值将被遮蔽。 name_match: allOf: - $ref: '#/components/schemas/TravelRuleNameMatch' nullable: true description: >- 决定转账的姓名比对结果，在运行比对前为 null。在当事方被脱敏期间，以及在 INTERNAL 交易另一方客户的副本上，`transfer_name`、`compared_name`、`matched_names` 和 `mismatched_names` 将被隐藏。`score` 和 `matched` 可能会不一致：`matched` 遵循严格程度规则，`score` 则是两个全名之间的相似度。 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。 created_at: type: string format: date-time delivery: nullable: true allOf: - $ref: '#/components/schemas/TravelRuleDelivery' description: >- 此转账应发送给对方的最新消息所处的状态。当转账从未需要发送消息时（例如低于 `threshold_amount`、声明的自托管钱包或 sunrise 注册）为 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' TravelRuleNameMatch: type: object nullable: true description: >- 决定转账的姓名比对结果，在运行比对前为 null。在当事方被脱敏期间，以及在 INTERNAL 交易另一方客户的副本上，`transfer_name`、`compared_name`、`matched_names` 和 `mismatched_names` 将被隐藏。`score` 和 `matched` 可能会不一致：`matched` 遵循严格程度规则，`score` 则是两个全名之间的相似度。 properties: score: type: integer minimum: 0 maximum: 100 description: 两个姓名的相似度，0 到 100。当任一姓名为空时为 0。 matched: type: boolean description: >- 姓名是否满足 `strictness`。转账的结果取决于比对每个字段的 `data_match`，因此即使此处为 true，转账状态仍可能为 COUNTERPARTY_MISMATCHED_DATA。 method: type: string enum: - none - exact_token - token_subset - token_containment - sequence_ratio description: >- `matched` 的判定方式：无匹配（`NONE`）、精确 token（`STRICT`）、token 子集（`DEFAULT`）、token 包含（`CONTAINS`）或序列比率（`FUZZY`）。 strictness: type: string enum: - NONE - STRICT - CONTAINS - DEFAULT - FUZZY compared_with: type: string enum: - wallet_holder - counterparty_vasp description: >- wallet_holder：为钱包记录的持有者。counterparty_vasp：交易对手在邮件响应页面上回复的名称，或在沙盒中 Didit Test VASP 回复的名称。 transfer_name: type: string description: 转账上的姓名。 compared_name: type: string description: 用于比对的姓名。 matched_names: type: array items: type: string description: 在 `compared_name` 中找到的 `transfer_name` 词语。 mismatched_names: type: array items: type: string description: >- `compared_name` 中缺失的 `transfer_name` 词语，紧接着是 `transfer_name` 中缺失的 `compared_name` 词语。 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.