> ## 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 de ações de transferência Travel Rule
> Com a API da Didit, finalize uma transferência Travel Rule com o hash on-chain, cancele, reenvie ou registre a carteira de origem dos fundos.
Prompt da API de ações de transferências da Travel Rule
Copiar o prompt para a área de transferência
\
\`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.`
\
Colar em
## OpenAPI
````yaml pt-br/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 de verificação de identidade. Autentique-se com o cabeçalho x-api-key.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/transactions/{transaction_id}/travel-rule/:
patch:
tags:
- Travel Rule
summary: >-
Concluir, cancelar, reenviar ou atualizar a carteira do remetente de uma
transferência Travel Rule
description: >-
Informe `payment_txn_id` para reportar o hash on-chain e mover uma
transferência de saída em COMPLETED para FINISHED (a transferência
correspondente no trilho INTERNAL também passa para FINISHED),
`{"action": "cancel"}` para cancelar uma transferência que não esteja em
status final, ou `{"action": "resend"}` para rotear novamente uma
transferência de saída parada em COUNTERPARTY_VASP_NOT_FOUND,
COUNTERPARTY_VASP_NOT_REACHABLE ou NOT_ENOUGH_COUNTERPARTY_DATA (melhore
antes os dados da contraparte, por exemplo, adicionando um
travel_address à entrada da carteira de destino). resend se aplica
somente a transferências de saída. `{"action":
"update_compliance_email", "compliance_email": "desk@example.com"}`
substitui o e-mail de conformidade de uma transferência de saída em um
desses três status, a correção para `reason: email_undeliverable`: o
status não muda, e o próximo `resend` envia a requisição para esse
endereço. Um resend é colocado na fila, não executado dentro da
requisição: a resposta mostra a transferência de volta em
AWAITING_COUNTERPARTY com uma entrada `resend queued` na linha do tempo
e uma `delivery` na fila, e o destino dela chega como um webhook
`travel_rule.status.updated`. Quando a transferência passou pela GTR,
VerifyVASP ou Sygna Bridge, a rede toma conhecimento do hash on-chain ou
do cancelamento após a resposta, com novas tentativas; `delivery` mostra
a situação dessa mensagem. `{"action": "update_originator_wallet",
"wallet_address": "..."}` registra a carteira da qual os fundos
realmente saíram em uma transferência de saída, por exemplo, o endereço
a partir do qual um saque UTXO foi transmitido, e não a carteira
principal que você declarou. Isso altera apenas o registro: nada é
reenviado à contraparte e o status permanece o mesmo. O remetente passa
a ser `chain_details.originator` com `source: updated`, a alteração é
adicionada à `timeline` com a carteira anterior e a nova, e a
transferência correspondente no trilho INTERNAL é atualizada da mesma
forma. `{"action": "beneficiary_vasp", "beneficiary_vasp": ""}` permite que você mesmo indique a contraparte quando a
descoberta não conseguiu, em uma transferência de saída em
COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE ou
NOT_ENOUGH_COUNTERPARTY_DATA: a transferência é roteada para esse VASP e
enviada novamente.
operationId: patchTravelRuleTransfer
parameters:
- name: transaction_id
in: path
required: true
description: UUID estável da transação na Didit à qual a transferência pertence.
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: >-
A transferência atualizada. Após `update_compliance_email`, o status
permanece inalterado e ela mantém `reason: email_undeliverable` até
o próximo `resend`.
content:
application/json:
schema:
$ref: '#/components/schemas/TravelRuleTransferDetail'
'400':
description: >-
Nem payment_txn_id nem uma ação suportada foi informada,
`compliance_email` está ausente ou não é um endereço de e-mail em
`update_compliance_email`, ou, em `update_originator_wallet`, não há
wallet_address, há uma carteira ou memo que a chain da transferência
não comporta, ou uma carteira que não é uma das entradas UTXO da
transferência, ou `beneficiary_vasp` está ausente ou não é um ID de
VASP válido do diretório.
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: >-
Transação desconhecida, a transação não tem transferência de Travel
Rule ou (ação `beneficiary_vasp`) nenhuma entrada do diretório tem
esse id.
'409':
description: >-
A transferência não está em um estado que permita esta operação (por
exemplo, não está COMPLETED/de saída para finish, já está em estado
final para cancel, ou não é uma transferência de saída com status
que permita reenvio para resend). `update_compliance_email` responde
`409` para uma transferência de entrada e para uma de saída fora de
COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE e
NOT_ENOUGH_COUNTERPARTY_DATA. `update_originator_wallet` responde
`409` para uma transferência de entrada, cancelada ou expirada.
`beneficiary_vasp` responde `409`, a menos que a transferência seja
de saída e esteja em COUNTERPARTY_VASP_NOT_FOUND,
COUNTERPARTY_VASP_NOT_REACHABLE ou NOT_ENOUGH_COUNTERPARTY_DATA.
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: >-
Informe exatamente um destes: payment_txn_id (finalizar), action=cancel,
action=resend, action=update_compliance_email com compliance_email,
action=update_originator_wallet com wallet_address ou
action=beneficiary_vasp com beneficiary_vasp.
properties:
payment_txn_id:
type: string
description: >-
O hash da transação on-chain. Exige que a transferência seja uma
transferência de saída com status COMPLETED.
action:
type: string
enum:
- cancel
- resend
- update_compliance_email
- update_originator_wallet
- beneficiary_vasp
description: >-
"cancel" cancela uma transferência que ainda não está em estado
final. "resend" executa novamente o roteamento de uma transferência
de saída parada em COUNTERPARTY_VASP_NOT_FOUND,
COUNTERPARTY_VASP_NOT_REACHABLE ou NOT_ENOUGH_COUNTERPARTY_DATA.
"update_compliance_email" substitui o e-mail de conformidade para o
qual a requisição é enviada, em uma transferência de saída em um
desses três status; envie "resend" em seguida.
"update_originator_wallet" registra a carteira da qual os fundos
realmente saíram (`wallet_address`, `memo`). "beneficiary_vasp"
permite que você mesmo indique o VASP da contraparte (exige
`beneficiary_vasp`) para uma transferência de saída em um desses
status: ela é roteada para esse VASP e enviada novamente.
compliance_email:
type: string
format: email
maxLength: 254
description: >-
Obrigatório com `action: update_compliance_email`. Armazenado como
`beneficiary_data.counterparty_vasp_email` desta transferência:
pertence apenas a esta transferência e não é adicionado a nenhuma
entrada do diretório nem a nenhuma lista de contatos.
wallet_address:
type: string
maxLength: 128
description: >-
Com `action: update_originator_wallet`: a carteira de onde os fundos
saíram. Quando as entradas UTXO da transferência são conhecidas, ela
deve ser uma delas.
memo:
type: string
maxLength: 256
description: >-
Com `action: update_originator_wallet`: o memo ou tag da carteira em
uma rede que usa memo. Opcional.
beneficiary_vasp:
type: string
format: uuid
description: >-
Obrigatório com action=beneficiary_vasp: o `id` de um VASP do
diretório, obtido em `GET /v3/travel-rule/vasps/`. Sua escolha tem
prioridade sobre todas as etapas de descoberta automática, que nunca
a substituem.
TravelRuleTransferDetail:
type: object
description: >-
Objeto de transferência completo retornado pelos endpoints de
confirmação de propriedade e de finalização/cancelamento. Enquanto a
propriedade da carteira de uma transferência recebida não for
confirmada, os campos `originator_data` e `beneficiary_data` da
contraparte são retornados mascarados (a primeira letra de cada palavra
é mantida; a carteira, a blockchain e o roteamento do VASP continuam
legíveis) e `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: >-
O canal pelo qual a transferência foi roteada, ou null quando nenhum
canal foi selecionado (por exemplo, abaixo do limiar, uma carteira
autocustodiada da contraparte, um registro após o depósito ou
nenhuma contraparte alcançável). INTERNAL significa que ambos os
lados são aplicações da Didit; EMAIL significa que a contraparte foi
alcançada por um link de retirada enviado por e-mail. TEST_VASP
significa que o Didit Test VASP respondeu à transferência no
sandbox. Em GTR, VERIFYVASP e SYGNA, a Didit lê a resposta da
contraparte a partir da resposta da rede ou consultando-a a cada 5
minutos. TRUST apenas envia, portanto uma transferência TRUST
permanece em AWAITING_COUNTERPARTY até expirar. Um canal de rede só
é usado quando você conectou sua própria associação a essa rede. Ele
é escolhido depois que a criação da transação retorna, por isso é
null nessa resposta.
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: >-
A comparação de nomes que esta entrada decidiu, ao lado de
`detail`. Ausente nas entradas que não compararam nenhum nome.
reason:
type: string
description: >-
Presente somente na entrada de uma transição causada por uma
falha de entrega: `email_undeliverable` ou `delivery_failed`,
o valor que o `reason` da transferência informa.
counterparty_vasp:
type: object
nullable: true
properties:
name:
type: string
lei:
type: string
dd_score:
type: integer
description: >-
Pontuação de due diligence de 0 a 100, em que valores maiores
são melhores. Mesma escala do diretório de VASPs.
dd_score_breakdown:
type: object
description: >-
Contribuições de cada componente para o dd_score, um objeto por
componente, como no diretório de VASPs (jurisdiction,
verification, protocol, lei, history, essentials,
responsiveness), cada um com {points, max, reason, detail}. {}
até que a contraparte tenha sido avaliada.
additionalProperties:
type: object
properties:
points:
type: number
description: Pontos atribuídos a este componente.
max:
type: integer
description: Pontuação máxima que este componente pode conceder.
reason:
type: string
description: Código legível por máquina do veredito do componente.
detail:
type: string
description: Motivo legível dos pontos atribuídos.
dd_assessed_at:
type: string
format: date-time
nullable: true
description: >-
Quando a avaliação de devida diligência foi executada pela
última vez. Nulo até que a contraparte tenha sido avaliada.
originator_data:
type: object
description: >-
Parte remetente. Em uma transferência de entrada, os valores da
contraparte ficam mascarados até que a propriedade seja confirmada.
beneficiary_data:
type: object
description: >-
Parte beneficiária. Em uma transferência recebida, os valores da
contraparte ficam mascarados até que a propriedade seja confirmada.
name_match:
allOf:
- $ref: '#/components/schemas/TravelRuleNameMatch'
nullable: true
description: >-
A comparação de nomes que decidiu a transferência, ou nula até que
uma seja executada. Enquanto as partes estão mascaradas, e na cópia
do outro cliente de uma troca INTERNAL, `transfer_name`,
`compared_name`, `matched_names` e `mismatched_names` ficam ocultos.
`score` e `matched` podem divergir: `matched` segue o rigor,
enquanto `score` é a similaridade entre os dois nomes completos.
data_match:
$ref: '#/components/schemas/TravelRuleDataMatch'
mismatched_fields:
type: array
items:
type: string
description: >-
Atalho para `data_match.mismatched_fields`. Vazio quando nada
difere.
data_unmasked:
$ref: '#/components/schemas/TravelRuleDataUnmasked'
data_masked:
type: boolean
description: >-
True enquanto os dados pessoais da contraparte estão mascarados
nesta resposta.
created_at:
type: string
format: date-time
delivery:
nullable: true
allOf:
- $ref: '#/components/schemas/TravelRuleDelivery'
description: >-
Situação da mensagem mais recente que esta transferência deve à
outra parte. Nulo quando a transferência nunca deveu uma mensagem
(por exemplo, abaixo de `threshold_amount`, em uma carteira
autocustodiada declarada ou em um registro de sunrise).
discovery:
type: array
description: >-
Como a Didit procurou a contraparte, com uma entrada por etapa
executada. Vazio quando nenhuma descoberta foi executada, por
exemplo, em uma transferência de entrada.
items:
$ref: '#/components/schemas/TravelRuleDiscoveryStep'
reason:
type: string
description: >-
Motivo pelo qual uma transferência `COUNTERPARTY_VASP_NOT_FOUND` ou
`COUNTERPARTY_VASP_NOT_REACHABLE` está parada; `""` para qualquer
outro status. Uma falha de entrega decide primeiro, apenas em
`COUNTERPARTY_VASP_NOT_REACHABLE`: `email_undeliverable` (o provedor
de e-mail recusou o e-mail de conformidade e não resta nenhum
endereço para tentar: no envio, em um lembrete ou como uma devolução
permanente informada depois) ou `delivery_failed` (o canal que fazia
a entrega falhou definitivamente: um canal de rede recusou a
mensagem ou esgotou as novas tentativas, um host de identidade `TRP`
não respondeu ou o host `TRP` da contraparte não aceitou a
consulta). Caso contrário, o rastro de `discovery` decide:
`awaiting_end_user` (nenhuma etapa indicou uma contraparte que a
Didit consiga alcançar), `directory_match_no_route` (uma etapa
indicou um VASP do diretório que não tem rota),
`picked_member_without_proven_wallet` (o usuário final escolheu um
cliente da Didit que não comprovou o controle da carteira) ou
`no_directory_match` quando o rastro não indica nenhum outro motivo.
Um reenvio faz a transferência avançar, e o motivo é então limpo.
Veja [Por que uma transferência está
parada](/pt-br/transaction-monitoring/travel-rule#por-que-uma-transferência-fica-travada).
next_actions:
type: array
description: >-
O que faz a transferência avançar; `[]` para qualquer status que não
seja `COUNTERPARTY_VASP_NOT_FOUND` ou
`COUNTERPARTY_VASP_NOT_REACHABLE`. `email_undeliverable` oferece
`update_compliance_email` e depois `resend`. `delivery_failed`
oferece `resend`. Um motivo de descoberta oferece
`select_counterparty_vasp`, `declare_self_hosted`, `add_vasp_hint` e
`resend`.
items:
$ref: '#/components/schemas/TravelRuleNextAction'
chain_details:
$ref: '#/components/schemas/TravelRuleChainDetails'
TravelRuleNameMatch:
type: object
nullable: true
description: >-
A comparação de nomes que decidiu a transferência, ou nula até que uma
seja executada. Enquanto as partes estão mascaradas, e na cópia do outro
cliente de uma troca INTERNAL, `transfer_name`, `compared_name`,
`matched_names` e `mismatched_names` ficam ocultos. `score` e `matched`
podem divergir: `matched` segue o rigor, enquanto `score` é a
similaridade entre os dois nomes completos.
properties:
score:
type: integer
minimum: 0
maximum: 100
description: >-
Similaridade entre os dois nomes completos, de 0 a 100. É 0 quando
qualquer um dos nomes está em branco.
matched:
type: boolean
description: >-
Se os nomes atendem a `strictness`. O resultado da transferência
segue `data_match`, que compara todos os campos, então uma
transferência pode ser COUNTERPARTY_MISMATCHED_DATA mesmo quando
este valor é verdadeiro.
method:
type: string
enum:
- none
- exact_token
- token_subset
- token_containment
- sequence_ratio
description: >-
Como `matched` foi decidido: none (`NONE`), exact_token (`STRICT`),
token_subset (`DEFAULT`), token_containment (`CONTAINS`) ou
sequence_ratio (`FUZZY`).
strictness:
type: string
enum:
- NONE
- STRICT
- CONTAINS
- DEFAULT
- FUZZY
compared_with:
type: string
enum:
- wallet_holder
- counterparty_vasp
description: >-
wallet_holder: o titular registrado para a carteira.
counterparty_vasp: o nome que a contraparte informou na página de
resposta por e-mail, ou a resposta do Didit Test VASP no sandbox.
transfer_name:
type: string
description: O nome na transferência.
compared_name:
type: string
description: O nome com o qual ele foi comparado.
matched_names:
type: array
items:
type: string
description: Palavras de `transfer_name` encontradas em `compared_name`.
mismatched_names:
type: array
items:
type: string
description: >-
Palavras de `transfer_name` ausentes em `compared_name` e, em
seguida, palavras de `compared_name` ausentes em `transfer_name`.
TravelRuleDataMatch:
type: object
nullable: true
description: >-
Comparação campo a campo entre os dados das partes da transferência e o
que o outro lado sabe sobre o titular da carteira. Ela indica campos e
resultados, nunca valores, por isso continua legível enquanto os dados
da contraparte estão mascarados. Nulo até que uma comparação seja
executada.
properties:
matched:
type: boolean
description: True quando nenhum campo comparado é diferente.
mismatched_fields:
type: array
items:
type: string
enum:
- name
- date_of_birth
- address
- account
description: Os campos que diferem.
fields:
type: object
description: >-
Uma entrada por campo comparado para o tipo de entidade da parte
(`name`, `date_of_birth`, `address`, `account`; uma empresa não tem
`date_of_birth`).
additionalProperties:
type: object
properties:
result:
type: string
enum:
- matched
- mismatched
- not_compared
description: >-
`not_compared` quando a regra é `NONE` ou um dos lados não tem
valor para o campo.
strictness:
type: string
enum:
- NONE
- STRICT
- CONTAINS
- DEFAULT
- FUZZY
TravelRuleDataUnmasked:
type: object
nullable: true
description: >-
Registro de auditoria do momento em que os dados da contraparte foram
desmascarados. É nulo enquanto os dados ainda estão mascarados e em
transferências de saída.
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: >-
O que confirmou a propriedade: ownership_confirmed (sua confirmação
pelo console ou pela API), wallet_proof (uma prova de carteira no
widget ou uma transferência de entrada INTERNAL, definida quando é
criada), address_book_match (uma carteira verificada do catálogo de
endereços), own_verified_wallet (a carteira verificada do próprio
usuário), inquiry_approved (sua aprovação de uma consulta TRP de
entrada ou de uma mensagem GTR ou Sygna), known_payment_method (uma
carteira com a qual seu usuário já pagou) ou travel_address (o
travel address por carteira identificou a carteira).
actor:
type: string
description: >-
Quem confirmou: o e-mail do usuário do console ou o rótulo da chave
de API. Em branco para uma decisão automática.
TravelRuleDelivery:
type: object
description: >-
Situação da mensagem mais recente que a transferência deve à outra
parte. A Didit contata a contraparte depois que a requisição que criou
ou alterou a transferência retorna, então este objeto indica se essa
mensagem foi entregue: na fila, em envio, aguardando nova tentativa após
um erro, entregue ou com falha. Uma falha da qual a rede ainda pode se
recuperar (sem resposta a tempo, falha de conexão, HTTP `408`, `429` ou
`5xx`) é tentada novamente após 30 segundos, 2 minutos, 10 minutos, 30
minutos e 1 hora. Quando uma primeira mensagem (`kind: SEND`) falha
definitivamente, porque a rede a recusou ou porque a sexta tentativa
também falhou, a transferência passa para
`COUNTERPARTY_VASP_NOT_REACHABLE` com `last_error` em sua `timeline`;
qualquer outra mensagem que falhe definitivamente é registrada na
`timeline`. O `status` da transferência continua sendo a fonte da
verdade sobre a troca em si.
required:
- kind
- status
- rail
- attempts
- last_error
- next_attempt_at
- delivered_at
properties:
kind:
type: string
enum:
- SEND
- ANSWER
- TXID
- CANCEL
- POLL
description: >-
O que a mensagem transporta. `SEND`: a primeira mensagem da
transferência para a contraparte (de saída; o canal é escolhido no
momento do envio). `ANSWER`: sua aceitação ou recusa, devida à rede
que fez a solicitação (de entrada). `TXID`: o hash da transação
on-chain, depois que você conclui a transferência. `CANCEL`: o
cancelamento, depois que você cancela a transferência. `POLL`: uma
consulta de status a uma rede que oferece esse recurso, repetida a
cada 5 minutos enquanto a transferência aguarda a contraparte.
status:
type: string
enum:
- QUEUED
- SENDING
- RETRYING
- DELIVERED
- FAILED
description: >-
`QUEUED`: aguardando envio. `SENDING`: uma tentativa está em
andamento. `RETRYING`: uma tentativa falhou e a próxima será
executada em `next_attempt_at`. `DELIVERED`: o outro lado recebeu a
mensagem. `FAILED`: o outro lado a recusou, ou a última tentativa
falhou.
rail:
type: string
enum:
- INTERNAL
- TRP
- GTR
- TRUST
- VERIFYVASP
- SYGNA
- EMAIL
- ''
description: >-
O canal que transporta a mensagem. Fica vazio até que a Didit
escolha um para uma primeira mensagem.
attempts:
type: integer
minimum: 0
description: >-
Tentativas feitas até agora para esta mensagem. Uma mensagem que não
seja uma consulta de status é tentada no máximo 6 vezes.
last_error:
type: string
description: >-
O tipo de falha que a última tentativa encontrou, `""` quando não
houve nenhuma: por exemplo `email undeliverable`, `trp identity
endpoint unreachable` ou `trp transfer inquiry delivery failed`.
Nunca inclui a resposta da própria contraparte, que fica na
`timeline` da transferência.
Quando o GTR responde com um erro, o código de status e a mensagem
dele são incluídos. Os corpos de resposta nunca são incluídos.
example: email undeliverable
next_attempt_at:
type: string
format: date-time
nullable: true
description: >-
Quando a próxima tentativa é executada enquanto a mensagem está
`QUEUED` ou `RETRYING`.
delivered_at:
type: string
format: date-time
nullable: true
description: Quando o outro lado recebeu a mensagem.
TravelRuleDiscoveryStep:
type: object
description: >-
Uma etapa da descoberta de contraparte que a Didit executou para uma
transferência de saída, na ordem em que as executou. A primeira etapa
que identifica um VASP com rota encerra a cadeia.
properties:
step:
type: string
enum:
- internal_address_book
- wallet_attribution
- network_lookup
- customer_hint
- end_user
description: >-
`internal_address_book`: outro cliente da Didit que comprovou o
controle da carteira de destino. `wallet_attribution`: a atribuição
da carteira feita por análise de blockchain. `network_lookup`: uma
rede capaz de informar qual VASP detém o endereço. `customer_hint`:
o nome do VASP, o LEI ou a jurisdição que você enviou em
`beneficiary_data`. `end_user`: a contraparte que o usuário final
(ou você) escolheu, ou o pedido para escolher uma.
outcome:
type: string
enum:
- match
- miss
- skipped
description: >-
`match`: a etapa identificou uma contraparte. `miss`: ela foi
executada e não encontrou nenhuma. `skipped`: ela não pôde ser
executada, e `reason` informa o motivo.
reason:
type: string
description: >-
Motivo legível por máquina, `""` quando há correspondência:
`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` ou `picked_member_without_proven_wallet`.
vasp:
type: string
format: uuid
nullable: true
description: O VASP do diretório indicado pela etapa, quando ela indicou um.
rail:
type: string
nullable: true
description: O canal que alcança essa contraparte, quando a etapa encontrou um.
at:
type: string
format: date-time
TravelRuleNextAction:
type: object
description: >-
Algo que faz avançar uma transferência `COUNTERPARTY_VASP_NOT_FOUND` ou
`COUNTERPARTY_VASP_NOT_REACHABLE`. Consulte [Por que uma transferência
está
parada](/pt-br/transaction-monitoring/travel-rule#por-que-uma-transferência-fica-travada).
properties:
action:
type: string
enum:
- select_counterparty_vasp
- declare_self_hosted
- add_vasp_hint
- update_compliance_email
- resend
description: >-
`select_counterparty_vasp`: o usuário final escolhe o VASP de
destino no widget de propriedade da carteira, ou você faz um PATCH
com `action=beneficiary_vasp`. `declare_self_hosted`: o usuário
final declara no widget que a carteira é autocustodiada.
`add_vasp_hint`: informe à Didit quem é a contraparte, com um nome
de VASP, um LEI ou um travel address (por exemplo, um
`travel_address` na entrada do catálogo de endereços da carteira de
destino) e depois reenvie. `update_compliance_email` e `resend` são
valores de `action` de `PATCH
/v3/transactions/{transaction_id}/travel-rule/`: informe novamente o
e-mail de conformidade da contraparte e execute o roteamento outra
vez.
url:
type: string
format: uri
description: >-
O link do widget de propriedade da carteira, em
`select_counterparty_vasp` e `declare_self_hosted`, enquanto a
transferência tiver uma sessão de widget aberta.
required:
- action
TravelRuleChainDetails:
type: object
description: >-
Como a blockchain da transferência identifica suas duas carteiras,
quando isso vai além de um endereço pagando a outro. Vazio (`{}`) para
uma transferência em blockchain baseada em contas (EVM, Solana, Tron),
em que os dois endereços são as próprias carteiras. A correspondência, o
roteamento e o catálogo de endereços leem as carteiras primeiro a partir
daqui.
properties:
chain:
type: string
description: >-
Blockchain canônica, por exemplo, `BTC`, `XRP` ou `LIGHTNING` para
uma transferência Lightning.
shape:
type: string
enum:
- utxo
- memo
- lightning
originator:
$ref: '#/components/schemas/TravelRuleChainSide'
beneficiary:
$ref: '#/components/schemas/TravelRuleChainSide'
utxo:
type: object
description: >-
Em uma transferência UTXO: as entradas e saídas conforme armazenadas
(valores como strings decimais) e como a Didit interpretou cada
saída.
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: Saídas que pagam de volta a um endereço de entrada.
beneficiary_output_index:
type: integer
nullable: true
description: >-
A saída que paga o beneficiário; null quando nenhuma pôde ser
distinguida.
lightning:
type: object
description: >-
Em uma transferência Lightning: o que a requisição de pagamento
informa. Sempre `kind` (`bolt11`, `bolt12_offer`, `bolt12_invoice`,
`bolt12_invoice_request`, `lnurl`, `lightning_address`, `node_id` ou
`unknown`); uma fatura BOLT11 acrescenta `network`, `payee_node_id`,
`payment_hash`, `amount_msat`, `created_at` e `expires_at`; uma
string BOLT12, `blinded_paths` e `payee_node_id`; uma LNURL ou um
Lightning Address, o respectivo `domain`. Nada é resolvido pela
rede: a requisição é apenas decodificada.
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: >-
Inconsistências de UTXO que merecem atenção: o remetente declarado
não é uma entrada, o beneficiário declarado não é uma saída, não foi
possível distinguir uma única saída do beneficiário, ou a saída do
beneficiário paga um valor diferente do informado na transação.
not_applicable_reason:
type: string
enum:
- LIGHTNING_NO_PAYEE_IDENTIFIER
- LIGHTNING_BOLT12_BLINDED_PAYEE
- LIGHTNING_LNURL_NAMES_NO_PAYEE
description: >-
Em uma transferência Lightning de saída cuja requisição de pagamento
não indica nenhum beneficiário: o motivo pelo qual a transferência é
`NOT_APPLICABLE`. `LIGHTNING_NO_PAYEE_IDENTIFIER` (a requisição não
indica nenhum nó beneficiário ou não pôde ser decodificada),
`LIGHTNING_BOLT12_BLINDED_PAYEE` (a oferta oculta o beneficiário
atrás de blinded paths), `LIGHTNING_LNURL_NAMES_NO_PAYEE` (uma LNURL
indica um serviço, não um beneficiário). O mesmo código abre a
última entrada de `timeline` da transferência.
TravelRuleChainSide:
type: object
description: >-
A carteira de uma das partes, conforme a Didit a resolveu a partir dos
dados da blockchain.
properties:
address:
type: string
description: >-
A carteira. Em uma rede com memo, o endereço clássico (um X-address
da XRP é dividido em endereço clássico e tag); na Lightning, o ID do
nó do beneficiário ou o Lightning Address.
memo:
type: string
description: >-
A destination tag ou o memo que faz parte da carteira; `""` para
nenhum.
source:
type: string
enum:
- declared
- x_address
- largest_input
- only_non_change_output
- amount_match
- invoice_payee
- updated
description: >-
Origem da carteira: `declared` (sua requisição), `x_address`
(extraída de um X-address do XRP), `largest_input` (o endereço de
entrada UTXO que mais contribuiu), `only_non_change_output` (a única
saída UTXO que não é troco), `amount_match` (a única saída UTXO que
paga o valor da transferência), `invoice_payee` (o beneficiário
indicado em uma solicitação de pagamento Lightning), `updated`
(definida posteriormente com `action: update_originator_wallet`).
TravelRuleUtxoEntry:
type: object
description: >-
Uma entrada ou saída de uma transação UTXO, conforme registrada na
blockchain.
required:
- address
properties:
address:
type: string
maxLength: 128
amount:
type: string
nullable: true
description: >-
String decimal na própria unidade da moeda (BTC, não satoshis).
Opcional.
example: '0.0125'
txid:
type: string
maxLength: 128
description: Opcional. A transação que uma entrada gasta.
vout:
type: integer
nullable: true
minimum: 0
description: Opcional. O índice da saída que uma entrada gasta.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Chave de API da sua aplicação, em Developers -> API keys no Business
Console. A chave principal tem acesso total. Uma chave nomeada pode ter
escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada
a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a
uma data de validade. 401 significa que a chave está errada, revogada ou
expirada; 403 significa que nenhuma chave foi enviada, que a chave não
tem acesso a este recurso ou ação, ou que a requisição veio de um
endereço fora da sua lista de IPs; 404 em uma rota de sessão significa
que a sessão está fora dos fluxos ou status da chave. Uma chave sem
acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave
sem permissão de escrita em sessões recebe links e tokens de sessão como
null. Consulte https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.