API da Travel Rule da FATF: Conformidade para VASPs

A Didit executa a troca entre ordenante e beneficiário prevista pelo FATF/EU Transfer of Funds Regulation (TFR) para transferências de ativos virtuais: procura um canal que alcance a VASP contraparte, negocia os dados necessários através do mesmo, acompanha a troca ao longo de um ciclo de vida de 13 estados e informa-o quando a troca tiver sido concluída para que possa libertar fundos on-chain.

Visão geral

A Travel Rule do GAFI (Recomendação 16), implementada na UE como o Regulamento relativo às Transferências de Fundos (TFR), exige que um Prestador de Serviços de Ativos Virtuais remetente (o VASP ordenante) recolha e transmita informações do ordenante e do beneficiário ao VASP destinatário (o VASP beneficiário) antes da liquidação de uma transferência de ativos virtuais. Ao contrário da maioria das jurisdições, o TFR da UE aplica-se sem montante mínimo - todas as transferências de criptoativos estão abrangidas, e não apenas as transferências acima de um limiar de comunicação. O produto Travel Rule da Didit é uma troca gerida, não apenas um campo de dados:

Submete uma transferência com transaction_category: "travelRule".
A Didit tenta as vias por ordem de prioridade para contactar o VASP da contraparte, executa a troca através da primeira que a alcance e, caso o outro lado devolva um nome de beneficiário, compara-o com o que enviou.
Só quando a troca atinge o estado COMPLETED é que deve difundir a transferência on-chain.
Em seguida, comunica o hash da transação on-chain à Didit para fechar a troca como FINISHED.

Sete vias são disponibilizadas nesta versão, tentadas por estrita ordem de prioridade - a primeira que conseguir contactar a contraparte é a utilizada:

Prioridade	Via	Como funciona
1	`INTERNAL`	Utilizada quando outro cliente da Didit comprovou o controlo da carteira do beneficiário com uma mensagem assinada ou um depósito de teste. A Didit cria uma transferência de entrada correspondente na aplicação desse cliente e negoceia a troca inteiramente dentro da plataforma - sem qualquer chamada de rede externa. Instantânea.
2	`TRP`	Integração nativa com o protocolo aberto Travel Rule Protocol (TRP / OpenVASP). Utilizada quando a transferência inclui um Travel Address, o registo da carteira de destino no livro de endereços armazena um, ou o VASP da contraparte é identificado no diretório com um endpoint TRP. Suporta os ativos listados em identificadores de ativos TRP. A Didit troca dados do ordenante e do beneficiário máquina a máquina, sem necessidade de troca de e-mails.
3	`GTR`	Rede Global Travel Rule (GTR). A contraparte é resolvida através de um `counterparty_gtr_vasp_code` explícito ou de uma entrada de diretório que contenha um. A Didit lê a resposta da contraparte a partir da resposta da GTR ou através da consulta periódica do estado do pedido a cada 5 minutos enquanto a transferência aguarda.
4	`TRUST`	Rede TRUST. A contraparte é resolvida através de `counterparty_trust_membership_id` ou de uma entrada de diretório que contenha um. Apenas envio: a TRUST não devolve nada que a Didit possa ler, pelo que a transferência aguarda em `AWAITING_COUNTERPARTY` até expirar.
5	`VERIFYVASP`	Rede VerifyVASP. A contraparte é resolvida através de `counterparty_verifyvasp_id` ou de uma entrada de diretório que contenha um. A Didit lê a resposta da contraparte através da consulta periódica do estado da verificação a cada 5 minutos.
6	`SYGNA`	Rede Sygna Bridge (adquirida pela VerifyVASP em 2026, ainda em funcionamento para membros existentes). Implementação nativa do protocolo Sygna - IVMS101 encriptado com ECIES e pedidos de permissão assinados. A contraparte é resolvida através de `counterparty_sygna_vasp_code` ou de uma entrada de diretório que contenha um. A resposta de aceitação ou recusa da contraparte conclui ou recusa a transferência: a Didit consulta periodicamente o estado da transferência a cada 5 minutos e também recebe a resposta no seu callback Sygna assim que o servidor TRP público da Didit estiver ativo.
7	`EMAIL`	Solução de recurso utilizada quando nenhuma via de protocolo ou rede consegue contactar a contraparte e o utilizador indica o respetivo contacto de conformidade em `counterparty_vasp_email`, ou a entrada da contraparte no diretório tiver um contacto de conformidade. A Didit envia por e-mail a esse contacto uma ligação de recolha de utilização única para que possa confirmar ou recusar a troca sem ter uma conta Didit. Esta é a solução principal para o problema do período de transição - contrapartes que ainda não são contactáveis em nenhuma rede.

As vias de rede (GTR, TRUST, VERIFYVASP, SYGNA) requerem uma adesão à rede do lado emissor e, atualmente, essa adesão tem de ser a sua própria. Associe as credenciais da sua adesão no Marketplace da consola (categoria Redes da Travel Rule), e as suas transferências serão processadas sob a sua própria identidade de rede. A Didit não detém atualmente qualquer adesão de plataforma para nenhuma das quatro redes e está a fazer onboarding como fornecedor nessas redes. Até que esse onboarding esteja concluído, platform_available é false para as quatro, o modo didit das definições (encaminhamento através da adesão de plataforma da Didit) não está disponível para nenhuma rede, e disabled_networks não tem nada para desativar. Uma adesão que o próprio utilizador ligue tem sempre precedência sobre uma adesão de plataforma. Nenhuma adesão a redes está incluída por defeito, incluindo a GTR. Ativar a Travel Rule não ativa a GTR, a TRUST, a VerifyVASP nem a Sygna. Consulte Obter definições da Travel Rule para ver os modos de networks em vigor da sua aplicação e Redes da Travel Rule para saber o que cada rede alcança atualmente. Se as quatro indicarem unavailable, nenhuma conseguirá encaminhar uma troca: associe a sua própria adesão no Marketplace ou utilize uma contraparte contactável por INTERNAL, TRP ou EMAIL. Ao guardar uma adesão, o código de participante tem de ser o seu: guardar a adesão resulta numa resposta 400 se o código for o código da própria Didit nessa rede, ou um código que a adesão de outra aplicação já detenha. Uma adesão à GTR necessita da sua chave privada ed25519 (base64), cuja chave pública está registada no portal da GTR: esta encripta os dados pessoais que envia e desencripta os dados que recebe. Uma adesão à VerifyVASP aponta para o seu próprio VerifyVASP Enclave: o URL é o do seu Enclave e o token é aquele que o seu Enclave apresenta à Didit. Mesmo com a sua própria adesão, uma via de rede só encaminha uma transferência se os respetivos beneficiary_data contiverem o ID da contraparte nessa rede (counterparty_gtr_vasp_code, counterparty_trust_membership_id, counterparty_verifyvasp_id ou counterparty_sygna_vasp_code), ou se a entrada da contraparte no diretório a listar nessa rede (consulte Rotas). O campo platform_available indica se a adesão da plataforma está configurada, não sendo uma verificação em tempo real do estado da rede. Da mesma forma, connected significa que as credenciais da sua adesão foram guardadas e passaram na validação local; a primeira troca em tempo real verifica-as junto da rede. Um modo didit ou own não garante que a contraparte seja contactável nem assegura uma entrega bem-sucedida. Com a sua própria adesão, a Didit lê a resposta da contraparte através de GTR, VERIFYVASP e SYGNA a partir da resposta da rede ou consultando a rede a cada 5 minutos, o que conclui ou recusa a transferência. O TRUST apenas envia: uma transferência enviada através deste permanece em AWAITING_COUNTERPARTY até decorrer confirmation_timeout_hours, passando depois para EXPIRED e aplicando-se o seu timeout_outcome. A receção de uma transferência que outro VASP lhe envie através de uma rede ainda não está ativa e nenhuma troca através de uma rede foi ainda concluída numa rede de produção: consulte Redes da Travel Rule. Outras redes - CODE (a aliança coreana), TRISA, Notabene e Veriscope - estão listadas no Marketplace da consola como blocos para solicitar acesso. A Didit ainda não tem integração com as mesmas, pelo que nenhuma transferência pode ser encaminhada através delas atualmente. Quando nenhuma das sete vias consegue resolver uma contraparte, a Didit executa mais um passo de resolução antes de desistir: atribuição por análise de blockchain. A carteira de destino é pesquisada em dados de análise de blockchain; quando a carteira pertence a uma exchange ou custodiante conhecido, a Didit regista o VASP atribuído na transferência, adiciona-o ao diretório e volta a executar as vias uma vez com o novo nome. Consulte Atribuição por análise de blockchain para obter informações sobre o comportamento completo e os preços. Uma transferência cujo destino seja declarado como uma carteira autocustodiada ignora todas as sete vias - não existe um VASP de contraparte com o qual trocar informações - e avança diretamente para a prova de propriedade da carteira pelo utilizador final.

A Didit também opera a vertente da troca direcionada para a contraparte: endpoints públicos de identidade e consulta TRP que outros VASP chamam para entrar em contacto consigo, endpoints de callback e o fluxo de recolha por e-mail. Nunca os chama diretamente - são infraestrutura gerida -, mas a página Interoperabilidade da Travel Rule documenta cada um deles para que os VASP de contraparte se possam ligar a si. Interage com a Travel Rule apenas através dos endpoints /v3/ descritos nesta página.

O que é executado ao submeter uma transferência

As verificações são executadas dentro da única chamada POST /v3/transactions/ - no momento em que recebe a resposta, a triagem já foi executada, a transferência está armazenada e as regras foram avaliadas. A troca em si tem início após a resposta: a Didit escolhe o rail e contacta a contraparte fora do seu pedido, para que nenhuma rede ou contraparte possa tornar a criação mais lenta ou fazê-la falhar. Cada alteração de estado posterior chega como um webhook travel_rule.status.updated que indica o rail, e o objeto de transferência devolvido pelos endpoints de transferência da Travel Rule contém um campo delivery que mostra se a mensagem foi entregue com sucesso. Não existe nenhum pipeline para consultar ciclicamente (polling); as partes assíncronas são a troca, a resposta da contraparte e qualquer ação do utilizador final. Passo a passo:

Validação e vinculação do sujeito. O payload é validado. Um transaction_id já utilizado na sua aplicação é rejeitado com 400, e quando dois pedidos concorrem com o mesmo ID, um deles recebe 409. O subject é associado ao perfil de utilizador ou empresa através de vendor_data, para que a transferência apareça nesse perfil para monitorização. Um vendor_data do sujeito ou da contraparte presente na lista de bloqueio é rejeitado com 400, e nenhuma transação é criada. Carteiras, contas bancárias, IPs e dispositivos na lista de bloqueio são verificados no passo 6 e fazem com que a transação seja recusada nesse passo, após a execução do encaminhamento.
Enriquecimento de dispositivo e rede. Os IPs das partes são geo-enriquecidos e qualquer contexto de dispositivo (automático no envio via SDK) é normalizado no grafo de dispositivos - o mesmo grafo alimentado pelas sessões de KYC, para que a associação “relacionado por dispositivo” funcione transversalmente no onboarding e nas transações.
Triagem cripto. Para transferências cripto com monitorização ativada, a carteira relevante (ou o hash on-chain) é submetida a triagem em ferramentas de análise de blockchain antes de qualquer troca - exposição a sanções, proximidade a mixers, fundos roubados. Consulte Triagem de cripto e carteiras.
Transferência Travel Rule. O motor de troca verifica o limiar e respeita uma declaração de carteira autocustodiada, armazenando depois a transferência: NOT_APPLICABLE abaixo do seu limiar, UNCONFIRMED_OWNERSHIP para uma carteira autocustodiada declarada, COMPLETED quando a outra carteira é a sua própria carteira verificada e AWAITING_COUNTERPARTY caso contrário, com o respetivo rail ainda vazio. Cada alteração de estado coloca em fila um evento travel_rule.status.updated, e a Didit envia-o após o transaction.created da transação (passo 7).
Emissão da sessão de comprovação de propriedade da carteira. Se a transferência exigir comprovação de controlo por parte do utilizador final e auto_wallet_verification estiver ativado, é gerada uma sessão de widget de propriedade de carteira devolvida em action_required.
Avaliação de regras. Todas as regras ativas são executadas - o pacote de regras TFR da UE reage ao estado da transferência definido no passo 4, as suas regras personalizadas consultam o resultado da triagem do passo 3, e uma regra pode reter a transação (IN_REVIEW), recusá-la ou exigir verificação reforçada (step-up) (AWAITING_USER).
Faturação e notificação. Uma transação de saída é faturada numa única linha: a linha da Travel Rule quando iniciou uma troca, e a Triagem de Transações caso contrário. Uma transferência recebida não acarreta nenhuma das tarifas, e uma aplicação em sandbox nunca é cobrada. A resposta é devolvida e transaction.created é disparado para os seus destinos de webhook, seguido pelos eventos travel_rule.status.updated do passo 4.
Encaminhamento, após a resposta. A Didit percorre os sete rails por ordem de prioridade; se nenhum resolver, a atribuição por análise de blockchain identifica a contraparte e os rails são executados novamente uma vez. O primeiro rail acessível processa a troca: a transferência permanece em AWAITING_COUNTERPARTY nesse rail enquanto a contraparte responde, liquida de imediato quando uma contraparte INTERNAL é correspondida (COMPLETED ou COUNTERPARTY_MISMATCHED_DATA), ou passa para COUNTERPARTY_VASP_NOT_FOUND quando nenhum rail alcança a contraparte. Cada alteração dispara travel_rule.status.updated, e as suas regras são executadas novamente sempre que o estado ou o rail mudarem. Uma transferência que o encaminhamento deixe em COUNTERPARTY_VASP_NOT_FOUND obtém a sua sessão do widget de propriedade de carteira nesse momento (quando auto_wallet_verification estiver ativado); consulte-a a partir de action_required da transação com Get transaction.

Como cada passo corresponde às suas obrigações

Passo do pipeline	Obrigação cumprida
Dados do ordenante fornecidos em `originator_data`	Informações precisas do ordenante (GAFI/FATF R.16; Regulamento TFR da UE Art.º 14). Nos rails que transmitem dados de pessoas (`INTERNAL`, `TRP` e os rails de rede), a Didit transmite a identidade verificada quando o sujeito é um utilizador com uma verificação KYC da Didit aprovada (consulte Dados verificados e proveniência) e, caso contrário, exatamente os `originator_data` que enviar.
Troca pelos rails antes da liquidação	Informações do ordenante e do beneficiário transmitidas ao VASP da contraparte antes da liquidação da transferência (GAFI/FATF R.16; Regulamento TFR da UE Art.º 14-16)
Correspondência do nome do beneficiário	Verificação de que os dados do beneficiário correspondem ao destino (obrigações do CASP beneficiário segundo o Art.º 16 do Regulamento TFR da UE)
Comprovação de propriedade de carteira autocustodiada	A obrigação do Regulamento TFR da UE relativa a carteiras autocustodiadas - verificar a propriedade de um endereço não alojado em vez de realizar a troca com um VASP
Triagem cripto + pacote de regras TFR da UE	Procedimentos baseados no risco para transferências com informações em falta ou incompletas e controlos de exposição a sanções
Exigência de `COMPLETED` antes da transmissão	Os fundos não são libertados até que a troca esteja concluída - a essência da regra
Encerramento `FINISHED` com o hash on-chain + cronologia	Conservação de registos: cada transferência inclui a sua cronologia completa de negociação para auditoria

Nota sobre testes. As aplicações em sandbox ignoram a avaliação de regras e a faturação, e não enviam webhooks transaction.created ou transaction.status.updated. As transações em sandbox permanecem APPROVED, a menos que uma transferência Travel Rule prestes a expirar aplique o seu timeout_outcome, e nada é cobrado. O motor de troca da Travel Rule é executado em aplicações em sandbox quando a Travel Rule está ativada, contra uma única contraparte: cada troca de saída segue para o Didit Test VASP no rail TEST_VASP, que responde dentro da Didit com o cenário que escolher, para que a transferência fique concluída, seja recusada, apresente divergência de dados, fique inacessível, expire ou aguarde pela comprovação de propriedade da carteira. Nenhuma mensagem de conformidade chega a um VASP de contraparte real, e os webhooks travel_rule.status.updated são entregues com environment: sandbox. Numa transferência recebida, o VASP de teste pode enviar-lhe uma transferência (Trigger Test VASP Inbound Transfer), e o registo (POST /v3/travel-rule/inbound/) é liquidado com base no livro de endereços da sua carteira tal como numa aplicação em produção - ON_HOLD, UNCONFIRMED_OWNERSHIP, COUNTERPARTY_MISMATCHED_DATA ou COMPLETED seguido de FINISHED. Consulte Testar a Travel Rule em sandbox.

Ciclo de vida

Cada transferência tem um status selecionado a partir de 13 valores. A troca começa em AWAITING_COUNTERPARTY no caso normal, em NOT_APPLICABLE quando o montante está abaixo do seu threshold_amount ou um pedido de pagamento Lightning não indica nenhum beneficiário (consulte Lightning), ou em UNCONFIRMED_OWNERSHIP quando o destino foi declarado como uma carteira autocustodiada, e termina num dos estados terminais: FINISHED, CANCELLED ou EXPIRED. A transferência executa a sua própria máquina de estados, separada do estado de análise da transação subjacente. O estado de uma troca nunca altera o estado da transação por si só, com uma exceção: uma expiração aplica o seu timeout_outcome configurado (ou uma política de sunrise ou de não resposta quando aplicável). Em vez disso, as suas regras voltam a ser executadas em cada transição, pelo que as regras do TFR da UE ou qualquer regra baseada em travel_rule_status podem mover a transação, por exemplo para IN_REVIEW. Uma transferência que necessite de comprovativo de controlo da carteira por parte do utilizador final adiciona um bloco action_required à transação, mas o seu status permanece tal como as suas regras o deixaram. Leia o estado da troca a partir de travel_rule.status; leia o veredito de permissão / suspensão / recusa a partir do próprio status da transação. Cada transição (e cada estado reportado passivamente) é também refletida nos valores personalizados da transação para que as regras possam basear-se nela: custom_values.travel_rule_status (estado canónico), custom_values.travel_rule_rail (o canal que transportou a troca, vazio até que um seja selecionado) e custom_values.travel_rule_regime (derivado da jurisdiction das suas definições: SG → singapore, GB → uk, e qualquer código de membro da UE ou do EEE como DE ou FR → eu; códigos não mapeados são gravados em minúsculas, por exemplo US → us. Um props.travel_rule_regime submetido por si prevalece sempre sobre o valor derivado).

Estado	Significado
`AWAITING_COUNTERPARTY`	A transferência aguarda a sua contraparte: primeiro enquanto a Didit escolhe a rede e envia a troca, logo após a criação, e depois enquanto a contraparte responde. A `delivery` da transferência indica se a mensagem foi entregue com sucesso. O `TRUST` apenas envia, pelo que uma transferência através dele permanece aqui até expirar.
`UNCONFIRMED_OWNERSHIP`	A transferência está a aguardar o comprovativo de controlo da carteira. É alcançado quando a carteira da contraparte foi declarada como autocustodiada na submissão (de saída ou de entrada), ou quando uma transferência de entrada corresponde a uma entrada do livro de endereços cuja propriedade ainda não foi verificada. Avança através do widget de propriedade da carteira ou de `POST .../travel-rule/ownership/`.
`ON_HOLD`	A Didit define-o apenas em transferências de entrada: a carteira de destino de um registo pós-depósito ou de uma consulta `TRP` de entrada não está no seu livro de endereços, ou uma consulta `TRP` de entrada aguarda a sua decisão (a aceitação automática está desativada ou a resposta automática não pôde ser entregue). Resolva-o com `POST .../travel-rule/ownership/`. Não altera o estado da transação por si só; a regra de biblioteca opcional `travel-rule-pending-action` move essas transações para `AWAITING_USER`.
`COMPLETED`	A troca foi concluída com sucesso: a contraparte (ou, numa transferência de entrada, você) aprovou-a, ou as verificações que a Didit executa nesse percurso foram aprovadas (correspondência do nome do beneficiário, comprovativo de propriedade da carteira). É seguro transmitir a transferência on-chain.
`FINISHED`	A troca é finalizada com o hash da transação on-chain. Numa transferência de saída, reporta o hash através de `PATCH .../travel-rule/`. Numa transferência de entrada, a Didit define-o quando o depósito já foi liquidado (registo pós-depósito), quando o ordenante confirma uma transferência `TRP`, ou quando o lado de saída `INTERNAL` termina.
`CANCELLED`	Cancelada manualmente com `action: "cancel"` a partir de qualquer estado não terminal, ou cancelada pelo ordenante de uma transferência `TRP` de entrada.
`EXPIRED`	Decorreu o período de `confirmation_timeout_hours` enquanto estava em `AWAITING_COUNTERPARTY`. Um processo de limpeza periódico (a cada 15 minutos) expira a transferência e aplica o seu `timeout_outcome` configurado à transação subjacente: `REJECT` recusa-a, `HOLD` move-a para análise, `PROCEED` deixa-a inalterada. A sua política de sunrise ou de não resposta substitui o `timeout_outcome` quando aplicável.
`COUNTERPARTY_MISMATCHED_DATA`	O nome do beneficiário não cumpriu a `name_matching_strictness` configurada em relação ao outro lado: o nome devolvido pela contraparte ou o `holder_name` da entrada correspondente no livro de endereços.
`COUNTERPARTY_VASP_NOT_FOUND`	Nenhum dos sete canais - nem a alternativa de atribuição por análise de blockchain - conseguiu resolver um VASP de contraparte acessível para esta transferência. Qualquer entidade atribuída continua registada na transferência e no diretório. Nas transferências de saída, a Didit cria automaticamente uma sessão do widget de propriedade da carteira (quando `auto_wallet_verification` está ativo) para que a transferência ainda possa ser concluída como uma transferência de carteira autocustodiada. `reason` e `next_actions` explicam o motivo e o que permite avançar: consulte Por que motivo uma transferência está bloqueada.
`COUNTERPARTY_VASP_NOT_REACHABLE`	Foi identificado um VASP de contraparte, mas o canal selecionado não conseguiu efetuar a entrega: não foi possível contactar o seu endpoint de identidade ou de consulta `TRP`, a identidade reportada não correspondeu a `counterparty_vasp_lei` ou `counterparty_vasp_name`, uma rede recusou a mensagem ou não a aceitou após seis tentativas (consulte Entrega e novas tentativas), ou o fornecedor de correio eletrónico recusou o e-mail de conformidade. `reason` distingue estes casos e `next_actions` indica o que permite avançar a transferência: consulte Por que motivo uma transferência está bloqueada. Tente novamente com `action: "resend"` assim que estiver novamente acessível.
`COUNTERPARTY_VASP_GENERAL_DECLINE`	A contraparte recusou a troca: propriedade negada, recolha por e-mail recusada ou uma rejeição `TRP` ou Sygna.
`NOT_ENOUGH_COUNTERPARTY_DATA`	Uma consulta `TRP` de entrada não identificou o beneficiário nem pelo nome nem pelo endereço da carteira, pelo que a Didit não conseguiu associá-lo ao seu livro de endereços. Nem o endpoint de propriedade nem `resend` aceitam tal transferência de entrada: só é possível cancelá-la, e cancelar não responde à consulta da contraparte. A Didit nunca define este estado numa transferência de saída; se o registar manualmente numa, `action: "resend"` executa novamente o encaminhamento.
`NOT_APPLICABLE`	O montante da transferência ficou abaixo do `threshold_amount` configurado, um pedido de pagamento de saída por Lightning não indica nenhum beneficiário (`chain_details.not_applicable_reason` explica o motivo), ou registou este estado manualmente com a Travel Rule desativada (incluindo os valores legados `UNKNOWN` e `EXEMPT`, consulte abaixo).

Nunca transmita para a rede antes de COMPLETED. Libertar fundos on-chain enquanto uma transferência está em AWAITING_COUNTERPARTY, UNCONFIRMED_OWNERSHIP, ou em qualquer estado de discrepância/recusa anula o propósito da troca de informações. Condicione o seu passo de transmissão a status == "COMPLETED", e depois chame PATCH .../travel-rule/ com o payment_txn_id resultante para transitar para FINISHED.

As transições, de relance (CANCELLED é adicionalmente acessível a partir de qualquer estado não terminal com action: "cancel"):

Entrega e tentativas

A Didit envia, fora do pedido que a originou, todas as mensagens que uma transferência tem de enviar, e tenta novamente até que a outra parte a receba. O objeto de transferência devolvido por Concluir, cancelar ou reenviar, Confirmar propriedade e registo de sunrise inclui a mais recente em delivery, tal como o objeto travel_rule embutido da transação; fica a null quando a transferência nunca exigiu uma mensagem.

Campo	Significado
`kind`	`SEND` (a primeira mensagem para a contraparte), `ANSWER` (a sua aceitação ou recusa, devida à rede que solicitou), `TXID` (o hash on-chain, após concluir a transferência), `CANCEL` (após a cancelar), ou `POLL` (uma consulta de estado a uma rede que o disponibilize, a cada 5 minutos enquanto a transferência aguarda a contraparte).
`status`	`QUEUED`, `SENDING`, `RETRYING`, `DELIVERED`, ou `FAILED`.
`rail`	O canal que transporta a mensagem; vazio até que a Didit tenha escolhido um para a primeira mensagem.
`attempts`	Tentativas realizadas até ao momento.
`last_error`	O motivo da falha da última tentativa, vazio se nenhuma falhou. Um motivo breve que indica o passo e o tipo de falha, por exemplo `sygna permission request failed: HTTP 503` ou `sygna status query failed: no answer in time`; quando a GTR responde com um erro, o seu próprio código de estado e mensagem são incluídos. Os corpos de resposta nunca são incluídos.
`next_attempt_at`	Quando a próxima tentativa é executada, enquanto a mensagem está em `QUEUED` ou `RETRYING`.
`delivered_at`	Quando a outra parte recebeu a mensagem.

Uma falha da qual a rede ainda possa recuperar (falta de resposta atempada, falha de ligaçã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 falha definitivamente - a rede recusou-a, ou a sexta tentativa falhou também - a transferência transita para COUNTERPARTY_VASP_NOT_REACHABLE com last_error na sua timeline, e pode tentar novamente com action: "resend". Qualquer outra mensagem que falhe definitivamente é registada na timeline. delivery nunca substitui o status da transferência: leia a troca de informações a partir de status, e utilize delivery para verificar por que motivo uma transferência ainda está em espera.

Valores de estado legados

Se já enviava travel_rule_details.status antes desta versão, esses valores continuam a funcionar e são mapeados automaticamente. As grafias em camelCase de qualquer estado (por exemplo counterpartyVaspNotFound) também são aceites, tanto no envio como em valores de condição de regra, e são normalizadas para a forma canónica:

Valor legado	Mapeado para
`UNKNOWN`	`NOT_APPLICABLE`
`COMPLIANT`	`COMPLETED`
`PENDING_ACTION`	`ON_HOLD`
`PENDING_COUNTERPARTY`	`AWAITING_COUNTERPARTY`
`FAILED`	`CANCELLED`
`EXEMPT`	`NOT_APPLICABLE`

Configuração

Configure o seu perfil de VASP e a política de negociação uma vez por aplicação com GET/PUT /v3/travel-rule/settings/.

curl -X GET https://verification.didit.me/v3/travel-rule/settings/ \
  -H "x-api-key: YOUR_API_KEY"

{
  "is_enabled": false,
  "jurisdiction": "EU",
  "name_matching_strictness": "DEFAULT",
  "confirmation_timeout_hours": 48,
  "timeout_outcome": "HOLD",
  "threshold_amount": "0.00",
  "inbound_auto_accept": true,
  "allow_self_declaration": true,
  "allow_screenshot_proof": true,
  "auto_wallet_verification": true,
  "vasp_attribution_enabled": true,
  "counterparty_screening_enabled": false,
  "sunrise_policy": "",
  "sunrise_jurisdictions": ["CO", "KH", "VN"],
  "non_responsive_policy": "",
  "legal_name": "",
  "lei": "",
  "compliance_email": "",
  "is_discoverable": true,
  "travel_address": "",
  "disabled_networks": [],
  "networks": {
    "gtr": { "rail": "GTR", "mode": "unavailable", "platform_available": false, "connected": false },
    "trust": { "rail": "TRUST", "mode": "unavailable", "platform_available": false, "connected": false },
    "verifyvasp": { "rail": "VERIFYVASP", "mode": "unavailable", "platform_available": false, "connected": false },
    "sygna": { "rail": "SYGNA", "mode": "unavailable", "platform_available": false, "connected": false }
  }
}

curl -X PUT https://verification.didit.me/v3/travel-rule/settings/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "is_enabled": true,
    "legal_name": "Origin CASP SL",
    "jurisdiction": "EU",
    "name_matching_strictness": "DEFAULT",
    "confirmation_timeout_hours": 48,
    "timeout_outcome": "HOLD",
    "is_discoverable": true
  }'

O PUT é uma atualização parcial - envie apenas os campos que pretende alterar.

Campo	Tipo	Descrição
`is_enabled`	boolean	Ativa o fluxo gerido de negociação para transações `travelRule` de saída desta aplicação. Requer um `legal_name` não vazio (já armazenado ou incluído no mesmo pedido) - caso contrário, o pedido devolve `400`.
`legal_name`	string	A denominação social do seu VASP. Mostrada à contraparte na página de recolha por e-mail e devolvida no diretório de VASP.
`lei`	string	O seu identificador de entidade jurídica, devolvido no diretório de VASP.
`jurisdiction`	string	O código de jurisdição operacional do seu VASP, até 8 carateres (predefinição `"EU"`).
`name_matching_strictness`	string	`NONE`, `STRICT`, `CONTAINS`, `DEFAULT` ou `FUZZY` - consulte abaixo.
`confirmation_timeout_hours`	integer	Horas que uma transferência `AWAITING_COUNTERPARTY` pode aguardar antes de expirar automaticamente. Mínimo `1`, predefinição `48`.
`timeout_outcome`	string	O que acontece à transação subjacente quando uma transferência expira: `HOLD` coloca-a em análise, `REJECT` recusa-a, `PROCEED` mantém o seu estado inalterado. Predefinição `HOLD`. `sunrise_policy` e `non_responsive_policy` têm precedência quando uma delas se aplica.
`sunrise_policy`	string	`HOLD`, `REJECT`, `PROCEED` ou `""` (predefinição) para seguir `timeout_outcome`: o que faz uma transferência expirada quando a sua contraparte é uma entrada do diretório numa jurisdição listada em `sunrise_jurisdictions`. Consulte Políticas de adaptação e de não resposta.
`non_responsive_policy`	string	`HOLD`, `REJECT`, `PROCEED` ou `""` (predefinição) para seguir `timeout_outcome`: o que faz uma transferência expirada quando a sua contraparte é uma entrada do diretório cuja capacidade de resposta é `UNRESPONSIVE`. `sunrise_policy` aplica-se primeiro quando ambas forem aplicáveis.
`sunrise_jurisdictions`	string[]	Apenas de leitura. Os países que a Didit trata como estando num período de adaptação da Travel Rule, atualmente `["CO", "KH", "VN"]`. Qualquer outra jurisdição segue `timeout_outcome`.
`compliance_email`	string	E-mail de contacto de conformidade para o seu perfil de VASP. A rede Didit lista o seu perfil apenas após este endereço ser confirmado através de uma ligação enviada por e-mail; alterá-lo requer uma nova confirmação.
`is_discoverable`	boolean	Indica se o seu perfil de VASP pode ser listado na rede Didit: encontrado em `GET /v3/travel-rule/vasps/` por outros clientes da Didit e contactado através do canal INTERNAL. A listagem tem condições adicionais; `didit_network` nas definições indica quais estão em falta. Predefinição `true`.
`inbound_auto_accept`	boolean	Quando for `true`, um pedido `TRP` de entrada cuja carteira do beneficiário seja uma entrada verificada no seu livro de endereços e cujo nome coincida é aprovado automaticamente. Quando for `false`, aguarda em `ON_HOLD` pela sua decisão. Outros caminhos de entrada não leem esta definição. Predefinição `true`.
`allow_self_declaration`	boolean	Quando for `true`, o widget de propriedade da carteira oferece a autodeclaração como método de prova, e você pode criar entradas no livro de endereços de carteiras com `self_declared: true`. Predefinição `true`.
`allow_screenshot_proof`	boolean	Quando for `true`, o widget de propriedade da carteira oferece o carregamento de capturas de ecrã como método de prova de propriedade. Uma captura de ecrã nunca verifica a carteira por si só: a sua equipa de conformidade analisa-a e confirma a transferência. Mais fraca do que a assinatura criptográfica - desative-a onde a sua política exigir prova ao nível de uma assinatura. Predefinição `true`.
`auto_wallet_verification`	boolean	Quando for `true`, uma transferência de saída que necessite de prova de controlo da carteira pelo utilizador final gera automaticamente uma sessão do widget de propriedade da carteira vinculada à transação e apresenta-a no bloco `action_required` da transação - os SDKs da Didit iniciam-na automaticamente na submissão do lado do cliente. Predefinição `true`.
`counterparty_screening_enabled`	boolean	Triagem de VASPs de contraparte opcional para sanções e notícias adversas, faturada por triagem ao preço da Triagem AML para empresas. Quando for `true`, a Didit faz a triagem da contraparte que uma troca de saída alcança quando a troca é iniciada, reutilizando uma triagem com menos de 30 dias. Predefinição `false`: nada é analisado ou faturado.
`vasp_attribution_enabled`	boolean	Quando for `true`, uma transferência de saída que nenhum canal consiga encaminhar é atribuída através de análise de blockchain - a carteira de destino é resolvida para o respetivo VASP proprietário, a entidade é adicionada ao diretório e os canais são executados novamente uma vez com o nome atribuído. Predefinição `true`.
`threshold_amount`	string (decimal)	Montante mínimo de transferência que aciona uma troca gerida, na moeda predefinida da sua aplicação: a Didit compara-o com o montante da transferência convertido para essa moeda (ou com o `amount_in_default_currency` que enviar), e não com o montante na moeda da própria transferência. As transferências abaixo deste valor passam diretamente para `NOT_APPLICABLE` e nunca são negociadas. Se a Didit não conseguir converter o montante, o limiar não é aplicado e a transferência é trocada. As aplicações em sandbox não convertem montantes, pelo que aí o limiar só se aplica quando envia `amount_in_default_currency`. Predefinição `0.00` - correspondendo ao modelo sem montante mínimo do TFR da UE, pelo que todas as transferências são verificadas, independentemente do valor.
`ownership_validation_mode`	string	`FULL`, `SIMPLIFIED` ou `AUTOMATED` - quanto comprovativo é necessário para validar a propriedade de uma carteira. Consulte Modos de validação de propriedade. Predefinição `AUTOMATED`.
`simplified_validation_threshold`	string (decimal)	No modo `SIMPLIFIED`, uma transferência abaixo deste montante aceita uma autodeclaração. Predefinição `0.00`.
`data_sharing_fields`	object	Os campos que envia sobre os seus próprios utilizadores, por tipo de entidade. Consulte Partilha de dados.
`matching_rules`	object	Com que rigor cada campo dos dados da contraparte é comparado, por tipo de entidade. Consulte Correspondência por campo.
`disabled_networks`	string[]	Redes (`GTR`, `TRUST`, `VERIFYVASP`, `SYGNA`) pelas quais as suas transferências NÃO devem ser encaminhadas através da adesão da plataforma Didit. Uma rede à qual tenha associado a sua própria adesão (Marketplace da consola) nunca é afetada por esta lista. A Didit ainda não possui nenhuma adesão de plataforma, pelo que a lista não tem qualquer efeito no encaminhamento atualmente (uma rede listada reporta `mode: off`). Predefinição `[]`.
`networks`	object	Só de leitura. Estado por rede indexado por `gtr` / `trust` / `verifyvasp` / `sygna`: `{rail, mode, platform_available, connected}` onde `mode` é `own` (a sua adesão associada), `didit` (adesão da plataforma Didit, ainda não disponível em nenhuma rede), `off` (desativada por si) ou `unavailable`.
`travel_address`	string	Só de leitura. O Travel Address próprio do seu VASP - o endpoint de consulta `TRP` de entrada codificado que outros VASP utilizam para o contactar. Preenchido assim que a Travel Rule for ativada, por exemplo `ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeS5uNDp3dGW3bweBWLKws442chRsyNxmmJnyWc7frxjjSeABVsYR11UuBePkw6E`.

Rigor da correspondência de nomes

Valor	Comportamento
`NONE`	Qualquer nome de beneficiário é aceite - nenhuma comparação é efetuada.
`STRICT`	Os conjuntos de tokens normalizados de ambos os nomes têm de ser exatamente iguais.
`CONTAINS`	As palavras de um dos nomes aparecem todas no outro, independentemente de serem poucas.
`DEFAULT`	Cada token do nome mais curto tem de aparecer no nome mais longo (correspondência por subconjunto), e o nome mais curto necessita de pelo menos dois tokens, exceto se ambos os nomes forem idênticos.
`FUZZY`	O rácio de semelhança entre as strings normalizadas completas tem de ser de pelo menos `0.85`.

Modos de validação de propriedade

ownership_validation_mode determina o nível de comprovação da propriedade de uma carteira necessário antes de uma transferência poder basear-se nela:

Modo	Comportamento
`FULL`	É sempre exigido um comprovativo: uma mensagem assinada, um depósito de teste ou uma captura de ecrã revista. A declaração do utilizador final nunca é considerada. O widget não disponibiliza `SELF_DECLARATION`; iniciá-la resulta em `403`, e uma entrada no livro de endereços criada com `self_declared: true` responde com `400`.
`SIMPLIFIED`	Uma autodeclaração é aceite enquanto a transferência estiver abaixo de `simplified_validation_threshold`; acima deste valor, é exigido um comprovativo. Uma transferência de entrada (uma consulta TRP, uma mensagem de rede ou um depósito reportado por si) é avaliada pelo seu montante convertido para a moeda predefinida da sua aplicação à taxa atual. Um ativo sem taxa de câmbio, bem como qualquer transferência de uma aplicação em sandbox, é considerado como estando acima do limiar.
`AUTOMATED`	O livro de endereços e os comprovativos anteriores do utilizador final são suficientes por si só, autodeclarações incluídas enquanto `allow_self_declaration` for `true`. Esta é a predefinição e o comportamento de todas as aplicações antes de estes modos existirem.

Uma carteira fica associada a cada utilizador final assim que for verificada. Em FULL e SIMPLIFIED, uma transferência posterior apenas reutiliza a carteira quando for suportada por um comprovativo que o modo aceite para essa transferência. Quando inbound_auto_accept não encontra nenhuma carteira no livro de endereços para corresponder, uma carteira de criptomoeda registada por si nas transações de exatamente um utilizador final identifica o titular. A Didit adiciona essa carteira ao livro de endereços do utilizador final como a sua autodeclaração, verificada exceto se o modo for FULL. Nunca adiciona uma carteira que o livro de endereços já liste sob outro nome da mesma cadeia (eth e ethereum), incluindo uma registada como pertencente a outro VASP. As verificações de endereço que outros VASP efetuam antes do envio (através de GTR, Sygna e VerifyVASP) também seguem o modo: sob FULL, uma carteira que o utilizador final apenas tenha declarado não é reportada como sendo sua.

Partilha de dados

data_sharing_fields escolhe quais os campos que a Didit envia à contraparte sobre os seus próprios utilizadores, separadamente para particulares e empresas:

{
  "data_sharing_fields": {
    "individual": ["name", "wallet_address", "address", "date_of_birth"],
    "company": ["name", "wallet_address", "address"]
  }
}

Os particulares podem partilhar name, wallet_address, address, national_id, customer_identification, date_of_birth e place_of_birth. As empresas utilizam os primeiros cinco.
name e wallet_address são sempre enviados.
Um tipo de entidade que nunca tenha configurado partilha todos os campos. Uma lista vazia é também uma escolha: partilha apenas o nome e a carteira.
Um PUT faz a intercalação por tipo de entidade, pelo que enviar individual não altera a escolha armazenada para company.
Uma escolha que não consiga satisfazer as obrigações do ordenante do regime da sua jurisdiction (EU TFR ou Recomendação 16 do GAFI/FATF), incluindo uma lista vazia, é recusada com 400. Os erros surgem sob data_sharing_fields, indexados pelo tipo de entidade.

Correspondência por campo

matching_rules define o nível de rigor com que cada campo dos dados da contraparte é comparado com os dados que possui:

{
  "matching_rules": {
    "individual": { "name": "DEFAULT", "date_of_birth": "STRICT", "address": "NONE", "account": "STRICT" },
    "company": { "name": "FUZZY", "address": "NONE", "account": "STRICT" }
  }
}

Cada valor é NONE, STRICT, CONTAINS, DEFAULT ou FUZZY. Predefinições: name segue name_matching_strictness, date_of_birth e address são NONE, e account é STRICT. Um campo omitido mantém a respetiva predefinição, e um campo que o tipo de entidade não compara (uma empresa não tem date_of_birth) é recusado com 400.

Limiares por jurisdição

threshold_amount existe porque o âmbito de aplicação da Travel Rule varia consoante o regulador. A Didit tem como predefinição 0.00 - a posição da UE - pelo que é trocada informação relativamente a todas as transferências, a menos que aumente este valor deliberadamente:

Regime	Limiar	Notas
UE - Regulamento das Transferências de Fundos (UE) 2023/1113	Sem mínimo	Todas as transferências de criptoativos entre CASP estão abrangidas. A propriedade de uma carteira autocustodiada tem de ser verificada para transferências superiores a 1000 EUR.
Recomendação 16 do GAFI/FATF (referencial global)	1000 USD/EUR	Abaixo deste valor, o GAFI permite um conjunto reduzido de dados (nomes e endereços, sem verificação).
Estados Unidos - BSA Travel Rule	3000 USD	O limiar histórico da FinCEN para transferências de fundos, aplicado a moedas virtuais convertíveis.
Reino Unido	Equivalente a 1000 EUR	Informação completa acima deste valor; conjunto reduzido de dados abaixo (MLRs Part 7A).
Singapura - MAS PSN02	1500 SGD	Requisitos reduzidos abaixo do limiar.
Suíça - FINMA	Sem mínimo	Informação obrigatória para todas as transferências; espera-se uma prova de propriedade para carteiras autocustodiadas.

Defina threshold_amount com o valor indicado pelo seu regulador; as transferências abaixo deste limiar resultam em NOT_APPLICABLE sem partilhar quaisquer dados de identidade. Os limiares evoluem - confirme o valor em vigor junto do seu consultor jurídico de conformidade em vez de tratar esta tabela como aconselhamento jurídico.

Modelo de dados IVMS 101

O padrão da indústria para os dados trocados ao abrigo da Travel Rule é o IVMS 101 (interVASP Messaging Standard). travel_rule_details.originator_data e travel_rule_details.beneficiary_data são payloads de pessoas no estilo IVMS 101: o Didit envolve-os no envelope nativo de cada rail - o rail TRP troca blocos IVMS101 (ivms101.2023, reportado no campo ivms_version da transferência), o rail Sygna a sua variante IVMS encriptada com ECIES, e os rails GTR, TRUST e VERIFYVASP os seus próprios envelopes encriptados - para que um único formato de payload chegue a cada contraparte no formato esperado pelo respetivo protocolo. O Didit lê estas chaves de cada payload de pessoa ao construir a mensagem IVMS 101: first_name e last_name (ou um único name ou full_name), date_of_birth, place_of_birth, residence_country (ou country), vendor_data (ou customer_identification) e wallet_address. Duas regras práticas:

Sistema de escrita latino. O IVMS 101 exige valores no sistema de escrita latino; translitere nomes que estejam originalmente escritos noutro sistema de escrita. A correspondência de nomes do Didit compara conjuntos de tokens normalizados, pelo que diferenças de ordenação e de maiúsculas/minúsculas não inviabilizam uma troca - mas sistemas de escrita diferentes entre ambas as partes irão inviabilizá-la.
Envie dados que verificou. Quando a pessoa por trás de vendor_data for um utilizador com uma verificação KYC aprovada no Didit, o Didit transmite a identidade verificada, e não os valores que introduziu: consulte Dados verificados e proveniência. Para qualquer outra pessoa, o Didit transmite exatamente o originator_data que enviar, pelo que deve construí-lo a partir da identidade que verificou no onboarding, e não a partir de um campo de formulário não verificado. É isso que a redação de “informações obrigatórias e exatas sobre o ordenante” do GAFI/FATF exige. No rail INTERNAL, a aplicação do beneficiário também recebe o subject que enviou (nome, vendor_data, data de nascimento, país e morada) como a contraparte da sua transação recebida.

Dados verificados e proveniência

Quando a parte de uma transferência for um dos seus utilizadores, uma pessoa singular com uma verificação KYC aprovada, o Didit constrói esse lado da troca a partir dos dados verificados:

o ordenante de uma transferência enviada que criar com POST /v3/transactions/;
o beneficiário de uma transferência recebida que reportar com POST /v3/transactions/, ou com POST /v3/travel-rule/inbound/ quando o holder_vendor_data da carteira correspondente indicar esse utilizador.

No POST /v3/transactions/, ambos aplicam-se a uma transação cujo transaction_category seja travel_rule enquanto a Travel Rule estiver ativada. Os nomes verificados, a data e o local de nascimento, o número e o tipo de documento, a morada e o país de residência (a partir dessa morada) têm precedência sobre os valores que enviou. Um campo que a verificação não contenha mantém o seu valor, assim como uma morada completa que tenha enviado quando a verificada não for suficientemente completa para transmissão. Os metadata da transferência, no objeto incorporado travel_rule da transação, registam a origem de cada campo e onde os seus valores divergiram:

{
  "metadata": {
    "originator_provenance": { "name": "verified", "date_of_birth": "verified", "customer_identification": "caller" },
    "originator_verified_differences": {
      "name": { "caller": "Jane Doe", "verified": "Jane Elizabeth Doe" }
    }
  }
}

*_provenance mapeia cada campo para verified ou caller, e *_verified_differences lista todos os campos onde enviou um valor diferente do verificado, ignorando maiúsculas/minúsculas, espaçamento e códigos de país de duas ou três letras. Enquanto os dados de uma transferência recebida estiverem mascarados, as diferenças são omitidas. O Didit calcula ambos, pelo que cópias destas chaves, ou de name_match, que enviar em travel_rule_details.metadata são descartadas.

Envio direto de IVMS 101

Além dos objetos planos originator_data e beneficiary_data, o campo travel_rule_details (em POST /v3/transactions/) e o endpoint POST /v3/travel-rule/inbound/ aceitam IVMS 101 autêntico:

um bloco originator e um bloco beneficiary, com originatorPersons ou beneficiaryPersons contendo uma naturalPerson ou uma legalPerson, e accountNumber;
os mesmos blocos dentro de um objeto ivms101 (ou IVMS101);
uma pessoa IVMS 101, ou um bloco completo, como originator_data ou beneficiary_data.

Cada lado aceita uma pessoa: uma naturalPerson, ou uma legalPerson, o que torna a parte uma empresa. Um originator_data ou beneficiary_data plano não vazio tem precedência sobre um bloco para o mesmo lado.

{
  "travel_rule_details": {
    "status": "AWAITING_COUNTERPARTY",
    "beneficiary": {
      "beneficiaryPersons": [
        {
          "naturalPerson": {
            "name": { "nameIdentifier": [{ "primaryIdentifier": "Ruiz", "secondaryIdentifier": "Carlos", "nameIdentifierType": "LEGL" }] }
          }
        }
      ],
      "accountNumber": ["0xBeneficiaryWallet01"]
    }
  }
}

Um bloco malformado devolve uma resposta 400 identificada pelo seu caminho, por exemplo {"travel_rule_details": {"originator.originatorPersons": ["must be a non-empty list of originator persons."]}}. No POST /v3/travel-rule/inbound/, as mesmas chaves situam-se no nível raiz, sob ivms101. quando utilizou o invólucro.

Dados obrigatórios por regime

Enquanto a Travel Rule estiver ativada, uma transferência enviada de valor igual ou superior ao seu limiar deve incluir o que o respetivo regime exige, caso contrário responderá com 400. Apenas os lados enviados são verificados, os dados verificados contam para o ordenante e os erros situam-se sob travel_rule_details.originator_data ou travel_rule_details.beneficiary_data, por exemplo "EU TFR requires the originator name." ou "FATF Recommendation 16 requires the beneficiary wallet address.":

Regime	Ordenante	Beneficiário
EU TFR (a sua `jurisdiction` é um Estado-Membro da UE, Islândia, Listenstaine, Noruega, `EU` ou `EEA`; `EU` é a predefinição)	O nome, mais a morada, o número do documento oficial e o número de identificação do cliente em conjunto, ou a data e o local de nascimento. Uma empresa não dispõe da alternativa de nascimento.	Nome e endereço
FATF Recommendation 16 (todas as outras jurisdições, incluindo uma em branco)	O nome, mais um entre a morada, o número do documento oficial ou o número de identificação do cliente, ou a data e o local de nascimento em conjunto. Uma empresa não dispõe da alternativa de nascimento.	Nome e endereço

Para o ordenante, a validação lê os campos que a sua aplicação partilha em data_sharing_fields, pois são apenas esses que um rail envia; o beneficiário é verificado tal como o enviou. Quando a transferência cumpre o regime apenas através de um campo que não partilha, o erro 400 indica o requisito do regime seguido dos campos que as suas definições partilham. O número do documento oficial é national_id (ou document_number), o número de identificação do cliente é customer_identification (ou vendor_data), e a data de nascimento é date_of_birth. Um beneficiary_data.wallet_address vazio é preenchido a partir de counterparty.payment_method.account_id antes da validação, e um levantamento UTXO cujo output do beneficiário o Didit inferiu a partir de travel_rule_details.utxo conta como incluindo esse dado. Uma transferência Lightning à qual a Travel Rule não se aplica não é verificada.

Travel addresses

Um Travel Address é uma cadeia compacta e codificada que aponta para o endpoint de consulta TRP de entrada de um VASP - nunca expõe um URL em bruto nem qualquer endereço de carteira. Assim que a Travel Rule estiver ativada, a Didit deriva o seu próprio travel_address (devolvido em modo só de leitura nas definições) para que o possa partilhar com outros VASP que o contactem através do carril TRP. Cada uma das suas próprias carteiras do livro de endereços também recebe um receiving_travel_address por carteira: uma consulta enviada para o mesmo identifica essa carteira, pelo que a Didit não precisa de a procurar pelo número de conta ou nome do titular. O host TRP público da Didit ainda não responde a outros VASP, pelo que a receção através do TRP não está disponível até que o faça: consulte Redes da Travel Rule. Quando souber o Travel Address de uma contraparte, guarde-o na entrada do livro de endereços de carteiras de destino para que a Didit encaminhe diretamente através de TRP as transferências desse beneficiário em vez de recorrer ao e-mail. A Didit valida os Travel Addresses que guarda numa entrada do livro de endereços de carteiras ou que envia em originating_vasp: cada um deve começar por ta e descodificar-se num URL de consulta com t=i, pelo que um marcador de posição como ta... devolve 400. O campo beneficiary_data.travel_address numa transação não é validado: se não puder ser descodificado, o carril TRP é ignorado. A codificação é Base58Check com um prefixo ta: o host e caminho do endpoint (que inclui sempre o par de consulta t=i) mais uma soma de verificação double-SHA-256 de quatro bytes, codificada em base58. Um endereço real tem, portanto, o seguinte aspeto e tem cerca de 100 carateres:

ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx

Nos casos em que a Didit valida um Travel Address, um valor que não seja um endereço bem formatado e com soma de verificação válida devolve 400 com "Invalid travel address.". Obtenha um endereço real a partir da resposta às suas próprias definições ou diretamente da contraparte.

Testar sem credenciais de rede

Não precisa de uma adesão à GTR, TRUST, VerifyVASP ou Sygna para testar os caminhos sem adesão. Continua a necessitar de uma chave de API da Didit para a aplicação em teste.

Saída em sandbox: envie uma transação travelRule a partir de uma aplicação de sandbox. Após as verificações de limiar e de carteira autocustodiada, o Didit Test VASP responde dentro da Didit com o cenário que escolher com base na carteira ou no nome do beneficiário: aceitar, recusar, divergência de nome, inacessível, tempo limite excedido ou autocustodiada. Nenhuma rede, e-mail ou outro cliente da Didit recebe o que quer que seja.
Entrada em sandbox: faça com que o VASP de teste lhe envie uma transferência com Trigger Test VASP Inbound Transfer, ou registe uma por conta própria com Register Inbound Travel Rule Transfer. Teste uma carteira desconhecida, uma carteira não verificada, uma divergência no nome do beneficiário e uma carteira correspondente verificada. Isto permite testar decisões de entrada reais sem contactar uma rede.
Duas aplicações de produção controladas: utilize o carril INTERNAL entre duas das suas próprias aplicações de produção (a recetora é detetável e comprova o controlo da carteira de destino com uma mensagem assinada ou um depósito de teste), ou uma contraparte TRP controlada, para testar uma troca entre duas partes sem credenciais de redes comerciais. As aplicações de produção podem incorrer em cobranças e notificações normais; utilize identidades de teste e contrapartes que controle.

Consulte Testar a Travel Rule em sandbox para conhecer todos os cenários e o respetivo resultado exato. Os testes bem-sucedidos em sandbox ou de protocolo local não validam as credenciais, a adesão ou a interoperabilidade em produção de uma rede comercial. Estes requerem uma sandbox de rede autorizada ou uma troca controlada em produção com credenciais de adesão válidas.

Enviar uma transferência

Inclua a transferência em POST /v3/transactions/ definindo transaction_category como travelRule (ou travel_rule) e anexando um objeto travel_rule_details (alias: travelRule). O bloco travel_rule_details em si é opcional, mas depois de o anexar, travel_rule_details.status é obrigatório: um bloco sem este campo devolve 400. Quando a Travel Rule está ativada para a sua aplicação, a Didit ignora o valor de status que enviar e gere a troca por si própria:

Se o montante for inferior ao seu threshold_amount configurado, a transferência resolve-se imediatamente para NOT_APPLICABLE e nada é negociado.
Se o método de pagamento da contraparte declarar o destino como uma carteira autocustodiada (payment_method.method_type: "unhosted_wallet"), nenhum canal é tentado - a transferência avança diretamente para UNCONFIRMED_OWNERSHIP e o widget de propriedade da carteira é gerado automaticamente (consulte Carteiras autocustodiadas declaradas).
Caso contrário, os canais são executados por ordem de prioridade, e o primeiro que conseguir alcançar a contraparte processa a troca:
- INTERNAL - exatamente um outro cliente da Didit possui uma prova por mensagem assinada ou depósito de teste para beneficiary_data.wallet_address, realizada após a carteira ter mudado de titular pela última vez. A sua própria aplicação nunca conta e, quando o seu utilizador final tiver selecionado um membro da rede Didit no widget de propriedade da carteira, apenas a prova desse membro é considerada. A aplicação desse cliente está em produção (não sandbox), tem a Travel Rule ativada e is_discoverable definido, e é o VASP que indicou ao enviar counterparty_vasp_lei ou counterparty_vasp_name. Uma carteira que seja apenas autodeclarada, comprovada por captura de ecrã, não verificada ou apenas listada num livro de endereços nunca recebe nada através de INTERNAL.
- TRP - o ativo da transferência tem um mapeamento de identificador de token digital para a rede da transferência (consulte Identificadores de ativos TRP), e o payload contém beneficiary_data.travel_address, a própria entrada de livro de endereços do destino armazena um, ou a contraparte é resolvida no diretório (por counterparty_vasp_lei ou counterparty_vasp_name) com um endpoint TRP.
- GTR, TRUST, VERIFYVASP, SYGNA - ligou a sua própria adesão a essa rede no Marketplace, e a contraparte resolve-se para um ID de rede (campo explícito ou entrada no diretório - consulte Campos de resolução da contraparte). A Didit ainda não possui adesão de plataforma nestas redes (está em onboarding como fornecedor), pelo que disabled_networks não altera este passo atualmente.
- EMAIL - beneficiary_data.counterparty_vasp_email foi fornecido, ou counterparty_vasp_name é resolvido para uma entrada no diretório com um e-mail de conformidade.
Se nenhum canal conseguir resolver uma contraparte, a Didit executa a cadeia de descoberta de contrapartes. Com vasp_attribution_enabled ativado, isso inclui a atribuição por análise de blockchain: a carteira de destino é resolvida para o respetivo VASP proprietário, o nome atribuído é gravado em beneficiary_data.counterparty_vasp_name (quando vazio) e no diretório, e os canais são executados novamente uma vez - assim, uma carteira atribuída a um VASP cuja entrada no diretório contenha um endpoint TRP, ID de rede ou e-mail de conformidade é encaminhada nesta segunda passagem.
Se a contraparte continuar por resolver, a transferência passa para COUNTERPARTY_VASP_NOT_FOUND. Em transferências de saída, a Didit gera automaticamente o widget de propriedade da carteira (quando auto_wallet_verification estiver ativado) para que a transferência ainda possa ser concluída como uma transferência para carteira autocustodiada, e pode voltar a executar o encaminhamento mais tarde com action: "resend" assim que tiver melhores dados da contraparte.

Os passos 1 e 2 ocorrem dentro do pedido. Os passos 3 a 5 são executados logo após a resposta: a transferência regressa com AWAITING_COUNTERPARTY e protocol: null, e cada resultado chega como um webhook travel_rule.status.updated.

Identificadores de ativos TRP

O TRP identifica o ativo transferido pelo seu Identificador de token digital (DTI) ISO 24165. Um DTI identifica um token numa blockchain, pelo que um token multicadeia possui um DTI por rede. A Didit envia transferências através de TRP para estes ativos:

Ativo	Rede	DTI
`BTC`	Bitcoin	`4H95J0R2X`
`ETH`	Ethereum	`X9J9K872S`
`USDC`	Ethereum	`CK9PW1MFH`
`USDC`	Celo	`2ZTG3NNVB`
`USDC`	Base	`CP6817N4B`
`USDC`	Optimism	`898NNTPZJ`
`USDC`	Arbitrum One	`4ZSZS1F4F`
`USDC`	Polygon PoS	`LS71LQK3L`
`USDC`	Avalanche C-Chain	`45J6XJX7H`
`USDC`	Solana	`5R3XFPZSM`
`USDC`	Plume	`N064ZKXDM`

Os identificadores do USDC são os que o emissor do token publica no seu livro branco do MiCA. Para um token multicadeia, a transferência tem de indicar a sua rede em transaction_details.crypto_params.crypto_chain (por exemplo CELO, BASE, OP, ARB ou POL). Sem uma rede, ou numa rede sem mapeamento, a transferência não é enviada através de TRP e a Didit tenta os canais restantes: primeiro as redes de interoperabilidade e, em seguida, o e-mail. O USDT ainda não está mapeado. Um token sem mapeamento de DTI, tal como a stablecoin de uma própria empresa, requer que o seu emissor registe um DTI junto da autoridade de registo ISO 24165, um por token por blockchain. Assim que os DTI existirem, contacte o suporte da Didit com cada DTI, a respetiva blockchain e as casas decimais do token, e a Didit adicionará o mapeamento. Os pedidos de informação de TRP recebidos que incluam um DTI mapeado por cadeia são registados com a moeda do token, o montante nas casas decimais do token e a rede.

Descoberta de contrapartes

Uma transferência que contenha apenas um endereço de carteira continua a alcançar a sua contraparte sempre que alguém conseguir identificar esse endereço. Antes de uma transferência de saída ser declarada não encaminhável, a Didit consulta, por esta ordem, e interrompe no primeiro passo que indique um VASP com uma rota:

Passo	O que faz
`internal_address_book`	Outro cliente da Didit comprovou o controlo da carteira (uma assinatura ou um depósito de teste), pelo que o canal `INTERNAL` entrega a transferência a esse cliente. Uma entrada no livro de endereços não comprovada nunca é contabilizada.
`wallet_attribution`	A atribuição por análise de blockchain da carteira, associada a um VASP do diretório com uma rota. Um resultado armazenado é reutilizado e a cobrança é feita apenas uma vez. Requer `vasp_attribution_enabled`.
`network_lookup`	Uma rede de Travel Rule que responde a “a quem pertence este endereço”, quando a sua aplicação tem acesso a ela. Apenas a GTR oferece isto hoje, e é executada quando a via GTR efetua o envio. Caso contrário, o passo é registado como `skipped` com o respetivo motivo.
`customer_hint`	O nome da VASP, LEI ou jurisdição que indicou em `beneficiary_data`, associado a uma VASP do diretório com uma rota. Um `travel_address` ou e-mail de conformidade é contactado através da sua própria via.
`end_user`	Ninguém indicou a contraparte, pelo que é perguntado ao utilizador final. Consulte abaixo.

O campo discovery da transferência lista cada passo executado com o respetivo outcome (match, miss ou skipped), um reason legível por máquina, a vasp e a rail encontradas, e um carimbo de data/hora. Uma VASP selecionada por si ou pelo utilizador final tem prioridade sobre qualquer passo automático: a descoberta nunca a substitui pela sua própria estimativa. Quando nenhum passo identifica uma contraparte, a transferência passa para COUNTERPARTY_VASP_NOT_FOUND, ou COUNTERPARTY_VASP_NOT_REACHABLE quando uma VASP foi identificada mas nenhuma das suas rotas está disponível para a sua aplicação. A transferência inclui então um reason (awaiting_end_user, no_directory_match, directory_match_no_route, ou picked_member_without_proven_wallet quando o membro selecionado pelo utilizador final não comprovou a carteira) e uma lista de next_actions:

`action`	Significado
`select_counterparty_vasp`	O utilizador final seleciona a VASP de destino no widget de carteira, ou você mesmo indica-a com `{"action": "beneficiary_vasp", "beneficiary_vasp": "<directory VASP id>"}` no endpoint de transferência. A transferência é encaminhada para essa VASP e enviada novamente.
`declare_self_hosted`	O utilizador final declara a carteira como autocustodiada no mesmo widget.
`add_vasp_hint`	Envie o nome de uma VASP, LEI ou `travel_address` em `beneficiary_data`, e depois reenvie.
`update_compliance_email`	Indique novamente o e-mail de conformidade da contraparte quando o primeiro foi recusado; consulte Porque é que uma transferência está bloqueada.
`resend`	Execute a descoberta novamente com as alterações efetuadas.

A ligação do widget é o url nas ações que o utilizador final executa. Quando uma ação de propriedade da carteira está pendente, o bloco action_required da transação (do tipo wallet_ownership) contém o mesmo reason e next_actions, para que um cliente que já processe action_required mostre o seletor sem trabalho adicional.

Campos de resolução da contraparte

Tudo o que a Didit sabe sobre a contraparte provém de travel_rule_details.beneficiary_data. Estes campos determinam a resolução da via; todos são opcionais:

Campo	Determina
`wallet_address`	Correspondência no livro de endereços `INTERNAL`, pesquisa no livro de endereços `TRP` e os fluxos de propriedade da carteira. Quando omitido, a Didit utiliza `counterparty.payment_method.account_id`.
`chain`	Delimita ambas as pesquisas no livro de endereços: uma entrada corresponde apenas quando o seu `chain` for igual a este valor (insensível a maiúsculas/minúsculas) ou a entrada não tiver `chain`. Quando omitido, a Didit preenche-o a partir de `transaction_details.crypto_params.crypto_chain`, `custom_properties.crypto_chain` ou da moeda da transferência, em maiúsculas, mas apenas quando esse valor for uma blockchain reconhecida pela Didit (por exemplo `ETH`, `BTC`, `SOL`, `TRX`); caso contrário, a transferência não tem blockchain associada e corresponde a entradas em qualquer blockchain. Para uma transferência de `USDT` ou `USDC` sem blockchain explícita, a Didit infere-a a partir do hash da transação em `transaction_details.payment_reference_id` (um hash `0x` resulta em `ETH`).
`memo`	A tag de destino ou memo de `wallet_address` numa rede com memo. Faz parte da carteira sempre que `wallet_address` seja correspondido (consulte Redes de memo e tag). Alias: `destinationTag`.
`travel_address`	Encaminha diretamente através de `TRP` - o sinal mais forte que pode passar.
`counterparty_vasp_lei`	Pesquisa no diretório por LEI para `TRP`, `GTR`, `TRUST`, `VERIFYVASP` e `SYGNA`. Também verificado contra a identidade reportada pelo endpoint TRP - uma divergência, ou uma identidade sem LEI, aborta a troca como `COUNTERPARTY_VASP_NOT_REACHABLE`.
`counterparty_vasp_name`	Pesquisa no diretório para `TRP`, `GTR`, `TRUST`, `VERIFYVASP`, `SYGNA` e `EMAIL`: o nome exato, o mesmo nome escrito de outra forma (`B.V.` em vez de `BV`, um acento), e depois um alias de uma entrada. Comparação aproximada com a identidade TRP quando ambas estiverem presentes.
`counterparty_vasp_jurisdiction`	Código de país ISO 3166 da entidade recetora quando a VASP indicada for uma marca com várias entidades reguladas, ou quando várias entradas do diretório partilharem o nome - consulte Marcas e as respetivas entidades.
`counterparty_gtr_vasp_code`	ID de rede `GTR` explícito - ignora o diretório.
`counterparty_trust_membership_id`	ID de rede `TRUST` explícito - ignora o diretório.
`counterparty_verifyvasp_id`	ID de rede `VerifyVASP` explícito - ignora o diretório.
`counterparty_sygna_vasp_code`	Código de VASP `Sygna Bridge` explícito - ignora o diretório.
`counterparty_vasp_email`	Contacto de conformidade explícito para a via `EMAIL` - ignora o diretório.

Estruturas de blockchain

Numa blockchain baseada em contas (blockchains EVM, Solana, Tron), uma transferência move fundos de um endereço para outro, e a Didit lê ambas as carteiras diretamente da transação. Três outras estruturas exigem mais detalhes, e o que a Didit determinou para elas está na transferência como chain_details (vazio, {}, numa blockchain baseada em contas). chain_details.originator e chain_details.beneficiary contêm, cada um, o address, o respetivo memo e a source de onde veio, e a correspondência e o encaminhamento leem as carteiras a partir daí em primeiro lugar.

Transferências UTXO

Uma transação de Bitcoin, Litecoin, Bitcoin Cash ou Dogecoin gasta inputs de qualquer número de endereços e paga qualquer número de outputs, sendo alguns deles o troco devolvido ao remetente. Envie os inputs e outputs como travel_rule_details.utxo (valores na própria unidade da moeda, como cadeias de caracteres decimais), e a Didit deduz o que não declarar:

Ordenante: originator_data.wallet_address quando o envia, caso contrário o endereço de input que mais contribuiu (source: largest_input).
Beneficiário: a carteira declarada, caso contrário o único output que não devolve troco a um endereço de input (only_non_change_output), caso contrário o output que paga o valor da transferência (amount_match).

curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "btc-withdrawal-0042",
    "transaction_category": "travelRule",
    "transaction_details": {
      "direction": "outbound",
      "amount": "0.25",
      "currency": "BTC",
      "currency_kind": "crypto"
    },
    "subject": { "vendor_data": "user-042", "full_name": "Ana Diaz" },
    "counterparty": { "full_name": "Luis Perez" },
    "travel_rule_details": {
      "status": "AWAITING_COUNTERPARTY",
      "beneficiary_data": { "name": "Luis Perez", "counterparty_vasp_name": "Destination Exchange" },
      "utxo": {
        "inputs": [
          { "address": "bc1qsenderhotwallet01", "amount": "0.30" },
          { "address": "bc1qsendercoldwallet02", "amount": "0.05" }
        ],
        "outputs": [
          { "address": "bc1qbeneficiarydeposit01", "amount": "0.25" },
          { "address": "bc1qsenderhotwallet01", "amount": "0.0999" }
        ]
      }
    }
  }'

A transferência passa então a incluir:

{
  "chain_details": {
    "chain": "BTC",
    "shape": "utxo",
    "originator": { "address": "bc1qsenderhotwallet01", "memo": "", "source": "largest_input" },
    "beneficiary": { "address": "bc1qbeneficiarydeposit01", "memo": "", "source": "only_non_change_output" },
    "utxo": {
      "inputs": [
        { "address": "bc1qsenderhotwallet01", "amount": "0.300000000000000000" },
        { "address": "bc1qsendercoldwallet02", "amount": "0.050000000000000000" }
      ],
      "outputs": [
        { "address": "bc1qbeneficiarydeposit01", "amount": "0.250000000000000000" },
        { "address": "bc1qsenderhotwallet01", "amount": "0.099900000000000000" }
      ],
      "change_output_indexes": [1],
      "beneficiary_output_index": 0
    }
  }
}

chain_details.warnings sinaliza o que não coincide: declared_originator_not_an_input, declared_beneficiary_not_an_output, beneficiary_output_ambiguous (não foi possível distinguir uma saída única) e beneficiary_output_amount_differs. utxo em qualquer outra blockchain devolve um 400, e cada lista contém no máximo 1,000 entradas. Um depósito comunicado aceita o mesmo objeto utxo (consulte Registo sunrise após depósito).

Redes com memo e tag

No XRP, Stellar (XLM), EOS, Cosmos (ATOM) e Hedera (HBAR), uma exchange recebe todos os clientes num único endereço partilhado e distingue-os através da tag de destino ou memo. O memo faz, por isso, parte da carteira: envie-o como payment_method.memo no participante, ou como memo em originator_data / beneficiary_data (alias destinationTag), e a Didit compara o endereço e o memo em conjunto.

Uma entrada do livro de endereços com um memo corresponde apenas a transferências que indiquem esse memo. Uma entrada sem memo corresponde a todo o endereço. Uma transferência que não indique qualquer memo nunca chega a uma entrada que tenha um: num endereço partilhado, um depósito sem a sua tag não pertence a ninguém.
Um X-address do XRP inclui a sua tag no próprio endereço: a Didit divide-o no endereço clássico e na tag (source: x_address), pelo que uma carteira registada em qualquer um dos formatos corresponde a uma transferência no outro.
Cada memo num endereço partilhado é o seu próprio método de pagamento na transação.
O que cada rede aceita: uma tag de destino do XRP é um número inteiro de 0 a 4294967295 (um número em formato JSON é aceite); um memo da Stellar tem até 28 bytes de texto, um id de 64 bits ou um hash de 32 bytes em hexadecimal; a EOS aceita até 256 bytes, a Cosmos até 256 carateres e a Hedera até 100 bytes. Um memo numa blockchain que não os suporte (Bitcoin, blockchains EVM, Solana, Tron, Litecoin, Bitcoin Cash, Dogecoin, Lightning) devolve um 400.

Lightning

Um pagamento Lightning não possui um endereço de beneficiário on-chain: o pagador detém um pedido de pagamento. Numa transferência cripto de bitcoin ou Lightning, payment_method.account_id pode ser esse pedido, e a Didit identifica o beneficiário a partir dele sem contactar nenhuma rede:

O que envia	Beneficiário
Fatura BOLT11 (`lnbc...`)	O nó do destinatário, indicado na fatura ou recuperado a partir da sua assinatura.
Oferta ou fatura BOLT12 (`lno1...`, `lni1...`)	O nó emissor, exceto se estiver oculto por caminhos cegos.
Endereço Lightning (`name@domain`)	O próprio endereço.
ID do nó	O próprio nó.
LNURL (`lnurl1...`, `lnurlp://`)	Nenhum: indica um serviço, não um destinatário.

O destinatário é armazenado como a conta e como chain_details.beneficiary (source: invoice_payee), na blockchain LIGHTNING, e o que o pedido indica é colocado em chain_details.lightning. Quando o pedido não indica nenhum destinatário, uma transferência de saída fica como NOT_APPLICABLE com o motivo indicado em chain_details.not_applicable_reason e na sua timeline: LIGHTNING_NO_PAYEE_IDENTIFIER, LIGHTNING_BOLT12_BLINDED_PAYEE ou LIGHTNING_LNURL_NAMES_NO_PAYEE. Um valor só é interpretado como Lightning em bitcoin, em LIGHTNING ou quando nenhuma blockchain é indicada (um endereço Lightning apenas em bitcoin ou LIGHTNING): em qualquer outra blockchain, é interpretado como o próprio endereço dessa blockchain.

O canal INTERNAL só alcança outro cliente da Didit através de uma carteira que esse cliente tenha provado que controla com uma mensagem assinada ou um depósito de teste, e essas provas existem atualmente para Bitcoin, blockchains EVM, Solana e Tron. Em redes com memo, Lightning, Litecoin, Bitcoin Cash e Dogecoin, uma transferência, por conseguinte, nunca alcança outro cliente da Didit através de INTERNAL. A correspondência de memo, tag e Lightning continua a aplicar-se ao seu próprio livro de endereços: transferências recebidas, depósitos comunicados e consultas TRP às suas carteiras.

Atualizar a carteira do ordenante

Um levantamento é frequentemente declarado a partir da carteira principal do seu cliente e transmitido a partir dos endereços que continham as moedas. Registe a carteira de onde os fundos efetivamente saíram com PATCH /v3/transactions/{transaction_id}/travel-rule/:

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 '{ "action": "update_originator_wallet", "wallet_address": "bc1qsendercoldwallet02" }'

Apenas transferências de saída, e nunca transferências CANCELLED ou EXPIRED (409).
Quando as entradas UTXO da transferência são conhecidas, a carteira tem de ser uma delas (caso contrário, 400). Numa rede com memo, envie também memo.
Altera apenas o registo: nada é reenviado para a contraparte e o estado mantém-se. chain_details.originator passa a ser a nova carteira com source: updated, a timeline regista a carteira anterior e a nova carteira, e a contraparte INTERNAL da transferência é atualizada da mesma forma.

Atribuição por análise de blockchain

Quando fornece apenas um endereço de carteira, a Didit consegue, ainda assim, descobrir quem está do outro lado. Se nenhum canal conseguir encaminhar a transferência, a Didit resolve a carteira de destino consultando os dados de atribuição de análise de blockchain - a mesma análise que suporta a triagem de transações de cripto sabe quais carteiras pertencem a que exchanges e custodiantes. A atribuição é executada apenas em transferências de saída que incluam tanto uma carteira de destino como uma chain (consulte Campos de resolução da contraparte); sem uma blockchain indicada, a atribuição é ignorada. Quando a carteira é atribuída a uma entidade conhecida, a Didit:

Regista a atribuição na transferência: beneficiary_data.counterparty_vasp_name é preenchido (caso não tenha fornecido um), e os metadados da transferência passam a incluir um bloco vasp_attribution com o nome da entidade, o tipo de entidade, o país e source: "blockchain_analytics".
Adiciona a entidade ao diretório de VASPs (ou faz a correspondência com a entrada existente), para que a atribuição seja estável entre transferências.
Executa novamente os canais com o nome atribuído - uma entrada no diretório que já contenha um endpoint TRP faz com que a transferência seja imediatamente encaminhada em vez de terminar em COUNTERPARTY_VASP_NOT_FOUND.

A chamada de atribuição funciona também como uma triagem completa de cripto: a transação recebe o resultado completo da triagem - pontuação de risco, categoria de risco da carteira, instantâneo da rede - exatamente como se a monitorização de cripto tivesse sido executada, e custom_values.aml_screening_trigger da transação é definido como travel_rule_attribution para que possa verificar que a triagem foi executada porque o encaminhamento da Travel Rule a exigiu. Quando a monitorização de cripto já tiver analisado a mesma carteira nesta transação, o resultado armazenado é reutilizado - sem uma segunda chamada à análise e sem uma segunda cobrança. A atribuição nunca bloqueia a criação da transação: se a consulta analítica falhar ou o seu saldo não a puder cobrir, a transferência simplesmente avança para COUNTERPARTY_VASP_NOT_FOUND e nada é cobrado pela tentativa. Em action: "resend", uma atribuição registada anteriormente é reutilizada em vez de ser consultada de novo. Desative todo o passo com vasp_attribution_enabled: false nas definições. Consulte Preços para saber como a chamada de atribuição é faturada. Quando a Travel Rule está desativada, o objeto travel_rule_details (incluindo um status fornecido pelo autor da chamada, legado ou atual) continua a ser registado na transação, mas passivamente - nenhuma via (rail) é acionada. Utilize isto para preencher retroativamente dados de conformidade que já monitorizou através do seu próprio processo. Uma transferência passiva de saída não inicia qualquer troca, pelo que é faturada como Triagem de Transações, e não na linha da Travel Rule. Com a Travel Rule ativada, este pedido é encaminhado através da via EMAIL, porque indica o e-mail de conformidade da contraparte e nenhuma via anterior consegue alcançar o beneficiário:

curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "trv-2026-07-05-001",
    "transaction_category": "travelRule",
    "transaction_details": {
      "direction": "outbound",
      "action_type": "transfer",
      "amount": "0.25",
      "currency": "ETH",
      "currency_kind": "crypto"
    },
    "subject": {
      "entity_type": "individual",
      "vendor_data": "user-042",
      "full_name": "Jane Doe"
    },
    "travel_rule_details": {
      "status": "AWAITING_COUNTERPARTY",
      "originator_data": {
        "first_name": "Jane",
        "last_name": "Doe",
        "date_of_birth": "1990-04-12",
        "residence_country": "ES",
        "customer_identification": "user-042",
        "wallet_address": "0x135908330861442a814796ae99feac507925782a"
      },
      "beneficiary_data": {
        "wallet_address": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb",
        "name": "Ana Diaz",
        "counterparty_vasp_email": "compliance@bene-casp.example"
      }
    }
  }'

A resposta, abreviada para os campos relevantes aqui:

{
  "uuid": "22222222-3333-4444-5555-666666666666",
  "txn_id": "trv-2026-07-05-001",
  "transaction_type": "travelRule",
  "direction": "OUTBOUND",
  "status": "APPROVED",
  "amount": "0.25",
  "currency": "ETH",
  "currency_type": "crypto",
  "travel_rule": {
    "uuid": "33333333-4444-5555-6666-777777777777",
    "status": "AWAITING_COUNTERPARTY",
    "protocol": null,
    "required": true,
    "obligations_count": 0,
    "originator_data": {
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1990-04-12",
      "residence_country": "ES",
      "customer_identification": "user-042",
      "wallet_address": "0x135908330861442a814796ae99feac507925782a"
    },
    "beneficiary_data": {
      "wallet_address": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb",
      "name": "Ana Diaz",
      "counterparty_vasp_email": "compliance@bene-casp.example",
      "chain": "ETH"
    },
    "metadata": {
      "compliance_email_source": "caller_supplied"
    }
  },
  "action_required": null
}

originator_data corresponde ao que enviou, porque o utilizador do exemplo não tem uma verificação KYC aprovada; para um utilizador verificado, o Didit constrói-o a partir dos dados verificados (consulte Dados verificados e proveniência). A via EMAIL mostra ao destinatário apenas os campos do ordenante que partilhar em data_sharing_fields.
beneficiary_data.chain é ETH porque o pedido não especificou nenhuma cadeia, pelo que o Didit a deduziu a partir da moeda.
status é APPROVED porque nenhuma regra atuou sobre a transação; as suas próprias regras podem definir outro estado.
O contacto de conformidade recebe a ligação de recolha, e a transferência fica concluída, falha na correspondência do nome ou é recusada quando respondem, ou expira se não o fizerem (consulte Recolha por e-mail).

O campo protocol ainda é null porque a via é escolhida após a resposta (por exemplo, EMAIL quando indicou counterparty_vasp_email): Obter transação mostra-o assim que for escolhido, e cada webhook travel_rule.status.updated posterior transporta-o em rail. Se a carteira do beneficiário pertencer a outro cliente Didit que tenha comprovado o controlo da mesma, a via INTERNAL liquida toda a troca logo após a resposta, e esse webhook já reporta COMPLETED (ou COUNTERPARTY_MISMATCHED_DATA). Quando o nome não coincide, a sua transferência fica como COUNTERPARTY_MISMATCHED_DATA e o outro cliente não recebe nada. Sem counterparty_vasp_email, e quando nem as vias nem a atribuição conseguem alcançar o beneficiário, a transferência termina mais tarde em COUNTERPARTY_VASP_NOT_FOUND com uma ação wallet_ownership na transação.

O objeto travel_rule embutido na transação transporta os campos próprios da transferência (uuid, status, protocol, required, obligations_count, originator_data, beneficiary_data, metadata), o que o Didit determinou e comparou (chain_details, name_match, data_match, mismatched_fields, e os campos de mascaramento data_masked e data_unmasked), bem como os campos que indicam a sua situação atual: direction, rail, counterparty_vasp, delivery, discovery, reason e next_actions (consulte Por que motivo uma transferência está bloqueada). Cada linha de GET /v3/transactions/ transporta o mesmo bloco, ou null no caso de uma transação sem transferência. Os endpoints dedicados de transferência abaixo também devolvem esses campos, além de ivms_version, ownership_confirmed, deadline_at, timeline e created_at, mas sem obligations_count ou metadata.

Para encerrar uma transferência de saída COMPLETED após a ter transmitido on-chain:

curl -X PATCH https://verification.didit.me/v3/transactions/22222222-3333-4444-5555-666666666666/travel-rule/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payment_txn_id": "0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060"}'

Isto exige que a transferência seja uma transferência de saída no estado COMPLETED - caso contrário, a API devolve 409. Em caso de sucesso, tanto a transferência de saída como a sua contraparte da via INTERNAL transitam para FINISHED, e o campo payment_txn_id da transação é definido com o hash que forneceu. Na via TRP, o Didit também envia o hash para o callback de confirmação da contraparte. Para cancelar uma transferência que ainda não atingiu um estado terminal, envie, em vez disso, {"action": "cancel"} para o mesmo endpoint. A contraparte da via INTERNAL também é cancelada e, na via TRP, assim que a contraparte tiver aprovado o pedido de informação, o Didit envia o cancelamento para o respetivo callback de confirmação. Uma transferência que já esteja em FINISHED, CANCELLED ou EXPIRED devolve 409. Um pedido sem payment_txn_id nem uma action suportada devolve 400. Numa transferência efetuada através de GTR, VERIFYVASP ou SYGNA, o Didit comunica o hash on-chain (ou o cancelamento) à rede após a resposta, com as mesmas tentativas de repetição; o campo delivery da resposta mostra essa mensagem. Para tentar novamente uma transferência de saída que não conseguiu alcançar a respetiva contraparte - uma que esteja atualmente em COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE ou NOT_ENOUGH_COUNTERPARTY_DATA - melhore primeiro os dados da contraparte, por exemplo, adicionando um travel_address ao registo da carteira de destino, um contacto ao registo da contraparte no diretório, ou catalogando o VASP no diretório. Em seguida, envie {"action": "resend"} para o mesmo endpoint. O Didit reinicia o prazo limite de confirmação e coloca novamente a sequência de encaminhamento na fila desde o início, utilizando os dados armazenados na transferência: a resposta mostra a transferência novamente em AWAITING_COUNTERPARTY (com resend queued na sua timeline), e o resultado chega através de um webhook travel_rule.status.updated. Um reenvio submetido enquanto uma tentativa anterior ainda está em execução é enviado assim que essa tentativa for concluída. Qualquer outro estado, ou uma transferência de entrada, devolve 409.

curl -X PATCH https://verification.didit.me/v3/transactions/22222222-3333-4444-5555-666666666666/travel-rule/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "resend"}'

Para indicar a contraparte manualmente quando a descoberta não o conseguiu fazer, envie {"action": "beneficiary_vasp", "beneficiary_vasp": "<directory VASP id>"} (o id obtido a partir de GET /v3/travel-rule/vasps/). A transferência é encaminhada para esse VASP e enviada novamente. Apenas uma transferência de saída em COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE ou NOT_ENOUGH_COUNTERPARTY_DATA a aceita; qualquer outro estado devolve 409, e um id desconhecido devolve 404.

Por que motivo uma transferência está bloqueada

Uma transferência em COUNTERPARTY_VASP_NOT_FOUND ou COUNTERPARTY_VASP_NOT_REACHABLE indica por que motivo está bloqueada e o que permite desbloqueá-la, em cada consulta da respetiva transação. O bloco travel_rule de GET /v3/transactions/{transaction_id}/, da resposta 201 de POST /v3/transactions/, e de cada linha de GET /v3/transactions/ inclui essa informação, assim como o objeto de transferência devolvido pelo endpoint de transferência:

reason é a causa legível por máquina, "" para qualquer outro estado.
next_actions lista o que faz a transferência avançar, [] para qualquer outro estado.
delivery é a mensagem mais recente que a transferência deve ao outro lado: kind, status (QUEUED, SENDING, RETRYING, DELIVERED ou FAILED), rail, attempts, last_error, next_attempt_at e delivered_at, ou null quando não tiver nenhuma mensagem pendente.
discovery indica onde a Didit procurou a contraparte, uma entrada por passo executado: step, outcome (match, miss ou skipped), reason, vasp, rail e at.

email_undeliverable e delivery_failed resultam de uma falha de entrega e aparecem apenas em COUNTERPARTY_VASP_NOT_REACHABLE. Uma falha de entrega define reason primeiro, pelo que uma contraparte que a Didit tenha encontrado nunca é reportada como uma que não conseguiu encontrar. Os outros quatro resultam do rastreio de descoberta, em qualquer um dos estados.

`reason`	O que aconteceu	`next_actions`
`email_undeliverable`	O fornecedor de e-mail recusou o e-mail de conformidade e já não restam endereços por tentar: quando foi enviado, num lembrete ou como devolução permanente reportada posteriormente.	`update_compliance_email`, depois `resend`
`delivery_failed`	O rail que estava a entregar falhou em definitivo: um rail de rede recusou a mensagem ou esgotou as tentativas, um anfitrião de identidade `TRP` não respondeu ou o anfitrião `TRP` da contraparte não aceitou a consulta.	`resend`
`awaiting_end_user`	Nenhum passo de descoberta identificou uma contraparte que a Didit consiga contactar, pelo que é pedido ao utilizador final que a indique.	`select_counterparty_vasp`, `declare_self_hosted`, `add_vasp_hint`, `resend`
`directory_match_no_route`	Um passo identificou uma entrada do diretório, mas essa entrada não tem nenhuma rota que a Didit possa utilizar em seu nome.	Igual a `awaiting_end_user`
`picked_member_without_proven_wallet`	O utilizador final selecionou outro cliente da Didit como contraparte, mas esse cliente não comprovou o controlo da carteira.	Igual a `awaiting_end_user`
`no_directory_match`	O rastreio de descoberta não fornece nenhum outro motivo.	Igual a `awaiting_end_user`

Ação seguinte	O que fazer
`update_compliance_email`	Forneça novamente o e-mail de conformidade da contraparte, com `{"action": "update_compliance_email", "compliance_email": "..."}` no endpoint de transferência.
`resend`	Execute novamente o encaminhamento com `{"action": "resend"}` assim que algo tiver mudado.
`select_counterparty_vasp`	O utilizador final escolhe o VASP de destino no widget de propriedade da carteira. `url` é a ligação do widget enquanto a transferência tiver uma sessão de widget aberta.
`declare_self_hosted`	O utilizador final declara a carteira como autocustodiada no widget, no mesmo `url`.
`add_vasp_hint`	Indique à Didit quem é a contraparte, com um nome de VASP, LEI ou Travel Address (por exemplo, um `travel_address` na entrada do livro de endereços da carteira de destino) e, em seguida, reenvie.

Um reenvio faz a transferência avançar, pelo que o respetivo reason deixa de estar definido. A entrada na cronologia de uma transição causada por uma falha de entrega apresenta o mesmo valor em reason. Se o fornecedor de e-mail recusar o e-mail de conformidade da transferência de exemplo acima, o bloco travel_rule da respetiva transação apresentará, de forma abreviada:

{
  "uuid": "33333333-4444-5555-6666-777777777777",
  "status": "COUNTERPARTY_VASP_NOT_REACHABLE",
  "protocol": "EMAIL",
  "direction": "OUTBOUND",
  "rail": "EMAIL",
  "counterparty_vasp": null,
  "delivery": {
    "kind": "SEND",
    "status": "FAILED",
    "rail": "EMAIL",
    "attempts": 1,
    "last_error": "email undeliverable",
    "next_attempt_at": null,
    "delivered_at": null
  },
  "reason": "email_undeliverable",
  "next_actions": [
    { "action": "update_compliance_email" },
    { "action": "resend" }
  ]
}

Aqui delivery coincide com reason, porque o próprio envio foi recusado. Uma recusa num lembrete, ou uma devolução reportada posteriormente, mantém delivery.status como DELIVERED: o primeiro e-mail chegou a sair. Consulte reason, e não delivery, para saber por que razão uma transferência está bloqueada. Para corrigir, forneça novamente o e-mail de conformidade da contraparte e, em seguida, reenvie:

curl -X PATCH https://verification.didit.me/v3/transactions/22222222-3333-4444-5555-666666666666/travel-rule/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "update_compliance_email", "compliance_email": "desk@bene-casp.example"}'

curl -X PATCH https://verification.didit.me/v3/transactions/22222222-3333-4444-5555-666666666666/travel-rule/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "resend"}'

O update_compliance_email mantém o endereço como o 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 contactos. O estado não é alterado, a cronologia ganha compliance email updated e a transferência mantém reason: email_undeliverable até que o reenvio envie o pedido para o novo endereço. Apenas uma transferência de saída em COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE ou NOT_ENOUGH_COUNTERPARTY_DATA o aceita; qualquer outra transferência responde com 409, e um compliance_email em falta ou mal formatado responde com 400.

Carteiras autocustodiadas declaradas

Quando o seu cliente lhe informar que o destino é a sua própria carteira autocustodiada (não alojada), declare-o na transação em vez de permitir que o encaminhamento descubra que não existe nenhum VASP por trás dela: defina o tipo do método de pagamento da contraparte como unhosted_wallet.

curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "trv-2026-07-07-002",
    "transaction_category": "travelRule",
    "transaction_details": {
      "direction": "outbound",
      "action_type": "transfer",
      "amount": "0.25",
      "currency": "ETH",
      "currency_kind": "crypto"
    },
    "subject": {
      "entity_type": "individual",
      "vendor_data": "user-042",
      "full_name": "Jane Doe"
    },
    "counterparty": {
      "entity_type": "external",
      "full_name": "Jane Doe",
      "payment_method": {
        "method_type": "unhosted_wallet",
        "account_id": "0xd3b62acb76fb27a7f8961ec40fa11746b113aca9"
      }
    },
    "travel_rule_details": {
      "status": "AWAITING_COUNTERPARTY",
      "beneficiary_data": {
        "wallet_address": "0xd3b62acb76fb27a7f8961ec40fa11746b113aca9",
        "name": "Jane Doe"
      }
    }
  }'

A declaração contorna totalmente o encaminhamento:

Nenhum rail é tentado - não existe um VASP de contraparte com quem trocar dados - e a transferência é criada diretamente em UNCONFIRMED_OWNERSHIP.
Quando auto_wallet_verification está ativado (o valor predefinido), a Didit cria automaticamente uma sessão do widget de propriedade da carteira vinculada à transação e devolve-a no bloco action_required da transação; os SDKs iniciam-na automaticamente no envio do lado do cliente.
Assim que o cliente comprovar o controlo da carteira, a transferência executa a correspondência de nome do beneficiário e avança para COMPLETED (ou COUNTERPARTY_MISMATCHED_DATA se a correspondência falhar).

Esta é a obrigação da TFR da UE relativa a carteiras autocustodiadas em formato de API: verificar a propriedade da carteira não alojada em vez de trocar dados com um VASP de contraparte. A declaração é lida a partir do método de pagamento no lado de destino de uma transferência de saída e no lado de origem de uma de entrada - em ambos os casos, o participante da contraparte. Uma transferência declarada como não alojada já se encontra no seu caminho final sem rails, pelo que UNCONFIRMED_OWNERSHIP não é um estado passível de reenvio - conclua a comprovação de propriedade (ou cancele) em vez de chamar action: "resend".

Receber

Confirmar a propriedade da carteira

Uma transferência aguarda em UNCONFIRMED_OWNERSHIP em dois casos:

Uma transferência recebida corresponde a uma entrada do livro de endereços cuja propriedade ainda não foi verificada.
A carteira da contraparte foi declarada como autocustodiada (counterparty.payment_method.method_type: "unhosted_wallet"), num levantamento de saída ou num depósito recebido. Consulte Carteiras autocustodiadas declaradas.

A sua aplicação confirma ou rejeita a transferência:

curl -X POST https://verification.didit.me/v3/transactions/{transaction_uuid}/travel-rule/ownership/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirmed": true}'

O corpo aceita confirmed (obrigatório, booleano) e um wallet_address opcional. O endpoint aceita uma transferência em qualquer um destes estados e devolve 409 com {"detail": "Transfer is not awaiting ownership confirmation."} para qualquer outro:

UNCONFIRMED_OWNERSHIP, em qualquer uma das direções.
ON_HOLD numa transferência recebida.
UNCONFIRMED_OWNERSHIP, ON_HOLD ou COUNTERPARTY_MISMATCHED_DATA numa transferência TRP recebida, para que um responsável pela conformidade possa resolver uma consulta da contraparte manualmente.

Numa transferência que a própria Didit criou (via INTERNAL, registo sunrise ou uma carteira autocustodiada declarada):

confirmed: true marca a entrada correspondente no livro de endereços como tendo a propriedade verificada e, em seguida, faz a correspondência do nome com o holder_name dessa entrada - COMPLETED se passar, COUNTERPARTY_MISMATCHED_DATA se não passar. A contraparte da via INTERNAL, quando existir, obtém o mesmo resultado. Para uma carteira autocustodiada declarada, confirmed: true regista que o seu cliente verificou quem controla a carteira da contraparte e conclui a transferência (COMPLETED), enviada ou recebida. Uma transferência recebida cujo depósito já tenha sido liquidado avança então diretamente para FINISHED.
confirmed: false move ambos os lados da transferência para COUNTERPARTY_VASP_GENERAL_DECLINE.
A entrada correspondente é pesquisada no seu próprio livro de endereços apenas pelo endereço, sem a blockchain. Resolver um ON_HOLD recebido sem nenhuma entrada correspondente cria a entrada a partir do beneficiary_data.wallet_address da transferência e marca-a como verificada. Uma carteira autocustodiada declarada é a exceção: a carteira é registada no seu livro de endereços com a propriedade verificada, conforme descrito abaixo. Em todos os outros casos, uma entrada em falta devolve 409 com {"detail": "wallet address entry no longer available"}, que é também o que uma entrada eliminada devolve.

Numa transferência TRP recebida, a mesma chamada responde à consulta da contraparte:

confirmed: true necessita de um endereço de pagamento para devolver, obtido primeiro a partir de wallet_address do pedido, depois da entrada correspondente e, por fim, de beneficiary_data.wallet_address. Se nenhum dos três estiver presente, o pedido devolve 400 com {"wallet_address": ["wallet_address is required to approve."]}. A Didit cria ou verifica a entrada, envia o callback de resolução da consulta para a contraparte, define ownership_confirmed e move a transferência para COMPLETED.
confirmed: false envia uma resolução recusada e move a transferência para COUNTERPARTY_VASP_GENERAL_DECLINE.
Se o endpoint de callback da contraparte não puder ser alcançado, o pedido devolve 502 e a transferência mantém o seu estado atual. Numa aprovação, a entrada no livro de endereços continua a ser criada ou marcada como verificada.

Para uma carteira autocustodiada declarada, a carteira que você verifica é a da contraparte: o destino de um levantamento enviado ou a origem (a carteira do ordenante) de um depósito recebido. A Didit adiciona-a ao livro de endereços com a propriedade verificada sob o nome da contraparte, para que a carteira seja comparada com o nome da contraparte (o ordenante, no caso de um depósito). Se o livro de endereços já contiver essa carteira com um nome de titular diferente, a transferência move-se para COUNTERPARTY_MISMATCHED_DATA. Se a transferência não indicar nenhuma carteira da contraparte, transmita wallet_address no corpo do pedido. Quando nem a transferência nem o pedido fornecerem um endereço, o pedido é rejeitado com 400.

{"confirmed": true, "wallet_address": "0xCounterpartyWallet01"}

Uma transferência de rede já respondida através da respetiva rede (uma transferência VerifyVASP, ou uma transferência GTR ou Sygna Bridge já decidida) devolve 409 (consulte Transferências a partir de uma rede).

A resposta é o objeto de transferência mais completo descrito acima. Uma nova transferência INTERNAL nunca aguarda aqui: só chega a um cliente que já tenha comprovado a carteira. Uma transferência INTERNAL mais antiga que ainda esteja a aguardar desde antes dessa regra mantém os dados do remetente ocultos até que comprove o controlo da carteira (uma mensagem assinada ou um depósito de teste), e confirmá-la responde com 409 até que o faça. Recusá-la continua a funcionar. Quando a contraparte responder que a carteira é autocustodiada (atualmente, o Didit Test VASP dá essa resposta na sandbox), a confirmação adiciona a carteira ao seu livro de endereços sob o nome do beneficiário e executa a correspondência de nomes: uma correspondência conclui a transferência e marca a carteira como verificada.

Transferências a partir de uma rede

A Didit também pode receber transferências Travel Rule que uma contraparte envie através de GTR, VERIFYVASP ou SYGNA. A receção é ativada pela Didit para cada rede separadamente, e nenhuma está ativada hoje: também necessita do registo dos endpoints da Didit em cada rede, e a Didit ainda não é membro dessas redes. As transferências TRUST não podem ser recebidas. Assim que uma rede for ativada, uma mensagem entregue por ela é processada da seguinte forma:

Encaminhamento. A mensagem chega à sua aplicação quando identifica o código de participante da sua própria adesão ligada a essa rede. Uma mensagem endereçada à adesão da própria Didit só chega até si quando for o único cliente Didit em produção que comprovou o controlo da carteira do beneficiário. Qualquer outra mensagem é recusada, para que nenhum cliente receba a transferência de outro cliente.
Decisão. A Didit cria a transferência recebida na sua aplicação e decide-a como uma consulta TRP: correspondência da carteira, propriedade, correspondência de nomes e inbound_auto_accept.
Uma única vez. As redes reenviam uma mensagem até que seja respondida. Uma repetição obtém a resposta que a primeira cópia obteve, e nada é criado ou decidido duas vezes.
A sua revisão, através de GTR e SYGNA. Uma transferência que aguarde por si (UNCONFIRMED_OWNERSHIP, ON_HOLD ou COUNTERPARTY_MISMATCHED_DATA) é decidida com POST .../travel-rule/ownership/: confirmed: true aprova-a (transmita wallet_address quando a transferência não indicar nenhum) e confirmed: false recusa-a. A Didit responde à rede após a resposta, com as mesmas tentativas. Uma transferência que já tenha sido respondida devolve 409.
Sem resposta posterior através de VERIFYVASP. A VerifyVASP obtém a sua resposta no momento em que efetua o pedido, pelo que uma transferência que necessite da sua revisão é recusada de imediato e não pode ser decidida posteriormente (409).

Dados da contraparte mascarados

Até que a propriedade da carteira seja confirmada, os dados pessoais da contraparte numa transferência de entrada são devolvidos mascarados em vez de serem omitidos. A primeira letra de cada palavra é mantida, e o encaminhamento da carteira, da blockchain e do VASP permanece legível. data_masked é true, e a contraparte nos detalhes da transação, na lista e na exportação CSV é mascarada da mesma forma. Assim que a propriedade é confirmada, os valores reais aparecem e data_unmasked regista a entrada de auditoria:

{
  "data_masked": false,
  "data_unmasked": { "at": "2026-10-17T10:00:00Z", "reason": "wallet_proof", "actor": "" }
}

reason é ownership_confirmed, wallet_proof, address_book_match, own_verified_wallet, inquiry_approved (aprovou uma consulta TRP ou uma mensagem GTR ou Sygna), known_payment_method (a carteira do utilizador final nos seus próprios registos respondeu) ou travel_address (o Travel Address de cada carteira identificou a carteira). Uma transferência de entrada INTERNAL inclui data_unmasked com reason: wallet_proof desde o momento em que é criada, porque apenas um destinatário que comprovou a carteira recebe uma. actor é o e-mail do utilizador da consola ou a etiqueta da chave de API, ficando em branco para uma decisão automática. O relatório do Registo de transferências da Travel Rule (CSV e PDF) mascara os nomes de uma transferência de entrada da mesma forma até que a propriedade seja confirmada. Os relatórios que submete a um regulador, como o XML goAML e o PDF do relatório regulamentar, contêm os dados reais da contraparte.

Feedback de divergências

Uma transferência com COUNTERPARTY_MISMATCHED_DATA indica agora os campos que diferem. data_match contém a comparação e mismatched_fields lista os campos. Ambos contêm apenas os nomes dos campos e os resultados, nunca os valores, pelo que permanecem legíveis enquanto os dados estiverem mascarados:

{
  "status": "COUNTERPARTY_MISMATCHED_DATA",
  "mismatched_fields": ["date_of_birth"],
  "data_match": {
    "matched": false,
    "mismatched_fields": ["date_of_birth"],
    "fields": {
      "name": { "result": "matched", "strictness": "DEFAULT" },
      "date_of_birth": { "result": "mismatched", "strictness": "STRICT" },
      "address": { "result": "not_compared", "strictness": "NONE" },
      "account": { "result": "matched", "strictness": "STRICT" }
    }
  }
}

A entrada na cronologia indica os campos, por exemplo “a data de nascimento do beneficiário não corresponde ao titular da carteira”. Uma rejeição TRP após uma divergência informa o VASP de origem sobre quais os campos que diferem, por exemplo “Os dados do beneficiário não correspondem ao titular da carteira: nome”. O que o outro VASP fica a saber é deliberadamente limitado: enquanto o nome estiver incorreto, o nome é o único campo comunicado (mismatched_fields: ["name"], todos os outros campos not_compared), e assim que o nome coincidir, todos os campos que diferem são indicados. Isto aplica-se ao lado do remetente de um intercâmbio INTERNAL e a uma rejeição TRP. Um nome em falta em ambos os lados é apresentado como not_compared e não constitui uma divergência, e um país coincide com base no código que o identifica, pelo que ES e ESP coincidem.

Pontuação de correspondência do nome

Cada transferência cujo nome foi comparado contém name_match, e a entrada na cronologia que a decidiu contém o mesmo objeto junto ao seu detail:

{
  "name_match": {
    "score": 90,
    "matched": false,
    "method": "sequence_ratio",
    "strictness": "FUZZY",
    "compared_with": "wallet_holder",
    "transfer_name": "Ana Diaz",
    "compared_name": "Ana Diaz Garcia",
    "matched_names": ["Ana", "Diaz"],
    "mismatched_names": ["Garcia"]
  }
}

score é a semelhança dos dois nomes completos, de 0 a 100, e 0 quando qualquer um estiver em branco. matched é o resultado ao nível de rigor (strictness), pelo que os dois podem divergir: FUZZY decide com base no seu próprio rácio de semelhança de 0.85.
matched_names são as palavras do nome da transferência encontradas no outro nome; mismatched_names são as palavras que um dos lados tem e o outro não.
method é none, exact_token, token_subset, token_containment ou sequence_ratio, para NONE, STRICT, DEFAULT, CONTAINS e FUZZY.
compared_with é wallet_holder (o titular registado para a carteira) ou counterparty_vasp (o nome que a contraparte indicou na resposta através da página de resposta por e-mail, ou a resposta do Didit Test VASP).
O resultado da transferência depende de data_match, que compara todos os campos, pelo que uma transferência pode ter COUNTERPARTY_MISMATCHED_DATA enquanto name_match.matched é true.
name_match encontra-se no objeto de transferência devolvido pelos endpoints da Travel Rule e no travel_rule incorporado da transação, e é null até que um nome tenha sido comparado. A lista de transferências e os webhooks não o incluem.
Os nomes ficam ocultos enquanto as partes estiverem mascaradas, e na cópia do outro cliente de um intercâmbio INTERNAL.

Mensagens e pedidos de documentos

Dois VASPs podem resolver uma transferência contestada na Didit em vez de o fazerem por e-mail. GET e POST /v3/transactions/{transaction_id}/travel-rule/messages/ listam e enviam mensagens numa transferência:

curl -X POST https://verification.didit.me/v3/transactions/{transaction_uuid}/travel-rule/messages/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "DOCUMENT_REQUEST", "body": "Please confirm the beneficiary date of birth.", "requested_documents": ["Proof of address"]}'

kind é MESSAGE (predefinição) ou DOCUMENT_REQUEST. Um pedido de documentos necessita de pelo menos uma entrada em requested_documents (até 10); uma mensagem necessita de um body (até 5000 carateres) ou de um ficheiro.
reply_to faz referência a uma mensagem anterior da mesma transferência. Uma resposta do outro lado que inclua um documento cumpre o pedido de documentos a que responde, sendo definido fulfilled_at na mesma. A sua própria resposta nunca cumpre o seu próprio pedido.
Envie em formato multipart com files para anexar até 5 ficheiros de 10 MB cada, em PDF, PNG, JPEG ou WebP. A Didit verifica o conteúdo de cada ficheiro, não apenas o tipo declarado, e qualquer outro ficheiro faz com que o pedido responda com 400 no campo files (“Anexe apenas ficheiros PDF, PNG, JPEG ou WebP.”).
Uma transferência suporta até 100 mensagens, das quais até 20 podem conter anexos (cada uma com até 5 ficheiros), contabilizando ambos os lados; ultrapassar qualquer um dos limites faz com que o pedido responda com 400. Os anexos das mensagens não contam para os documentos da própria transação.
As mensagens funcionam através dos canais INTERNAL e EMAIL. Em INTERNAL, o outro cliente Didit vê a mensagem no seu lado do par. Em EMAIL, a contraparte recebe um e-mail e responde no portal de recolha. Se esse e-mail de notificação não puder ser enviado, a mensagem é guardada na mesma e o pedido responde com 201.
O pedido responde com 409 com um motivo em detail para uma transferência através de TRP, GTR, TRUST, VerifyVASP ou Sygna (esses protocolos não transmitem mensagens), uma transferência ainda sem contraparte, uma transferência INTERNAL cujos dados não coincidiram com o titular da carteira (nada chegou ao destinatário), uma transferência INTERNAL cujo destinatário ainda não comprovou o controlo da carteira (em ambos os lados, até que o faça), uma transferência EMAIL cuja contraparte já não possui um endereço de e-mail de conformidade e uma transferência EMAIL cuja ligação de recolha expirou ou cuja transferência se encontra encerrada.
Nenhum webhook é acionado quando a contraparte responde por escrito. Consulte o endpoint de mensagens.
O e-mail que informa a contraparte sobre uma nova mensagem é enviado em inglês.

Livro de endereços de carteiras

Registe as carteiras que controla para que as transferências de entrada (canal INTERNAL, consultas TRP de entrada e registos após depósito) possam ser associadas a essas carteiras, com POST/GET /v3/travel-rule/wallet-addresses/ e PATCH/DELETE /v3/travel-rule/wallet-addresses/{entry_uuid}/.

curl -X POST https://verification.didit.me/v3/travel-rule/wallet-addresses/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb",
    "chain": "ETH",
    "holder_name": "Ana Diaz",
    "holder_vendor_data": "user-042",
    "self_declared": true
  }'

Campo	Tipo	Descrição
`address`	string	O endereço da carteira. Único por aplicação, `chain` e `memo` (o endereço é comparado sem distinção entre maiúsculas e minúsculas) - um duplicado devolve `400`. Um endereço X de XRP é armazenado como o seu endereço clássico e a sua tag. Vazio numa entrada importada pelo seu hash.
`address_hash`	string	Apenas de leitura. SHA-256 do endereço em minúsculas, em hexadecimal em minúsculas.
`memo`	string	Opcional. A tag de destino ou memo que faz parte da carteira numa rede com memo; vazio para o endereço completo. Alias: `destinationTag`.
`chain`	string	Identificador opcional da chain, até 32 carateres. Utilize o mesmo token que as suas transferências contêm (por exemplo `ETH` ou `BTC`), ou deixe em branco para fazer corresponder transferências em qualquer chain - consulte a nota abaixo. Um destinatário Lightning (ID do nó ou Lightning Address) registado em bitcoin é armazenado em minúsculas em `LIGHTNING`, onde as transferências Lightning são correspondidas.
`holder_name`	string	Nome do titular da carteira, utilizado para a correspondência do nome do beneficiário.
`holder_vendor_data`	string	O seu identificador interno para o titular.
`entity_type`	string	Texto livre até 16 carateres, por omissão `"individual"`.
`travel_address`	string	Opcional. O Travel Address do VASP da contraparte para esta carteira, se o souber. Permite à Didit encaminhar transferências para este beneficiário através da via `TRP` em vez de e-mail.
`receiving_travel_address`	string	Apenas de leitura. O seu próprio Travel Address específico desta carteira. Forneça-o a um VASP que envie para esta carteira: a sua consulta TRP nomeia então a carteira diretamente. Vazio para uma carteira registada como pertencendo a outro VASP, enquanto a Travel Rule estiver desativada e antes de o seu perfil de VASP ser guardado. Deixa de responder assim que a carteira for eliminada.
`is_ownership_verified`	boolean	Apenas de leitura. Se a propriedade deste endereço foi comprovada (através do widget de propriedade de carteira ou autodeclaração).
`self_declared`	boolean	Apenas de escrita, apenas `POST`. Quando `true`, a entrada é criada já verificada através de uma prova `SELF_DECLARATION` - as transferências recebidas para este endereço ignoram `UNCONFIRMED_OWNERSHIP` por completo e avançam diretamente para a correspondência de nomes. Devolve `400` quando `allow_self_declaration` estiver desativado nas suas definições.

PATCH aceita holder_name, holder_vendor_data, entity_type e travel_address, e devolve apenas esses quatro campos. DELETE elimina a entrada (204) - o seu endereço fica disponível para novo registo e deixa imediatamente de corresponder a novas transferências.

A correspondência é insensível a maiúsculas e minúsculas no endereço, inclui o seu memo numa rede com memo e é limitada por chain. Quando uma transferência tem uma chain associada, uma entrada só corresponde se a sua chain tiver o mesmo valor (sem sensibilidade a maiúsculas e minúsculas) ou estiver vazia. Os nomes das chains são comparados como texto, não são traduzidos, pelo que uma entrada guardada como ethereum não corresponde a uma transferência cuja chain seja ETH. As transferências de saída obtêm a sua chain a partir de beneficiary_data.chain, depois de transaction_details.crypto_params.crypto_chain, depois de custom_properties.crypto_chain e, em seguida, da moeda (por exemplo ETH, ou para USDT e USDC a chain inferida de payment_reference_id), definida apenas quando for uma chain que a Didit reconhece, e os registos pós-depósito a partir do respetivo campo chain, em minúsculas. As consultas TRP de entrada ignoram a chain: correspondem por endereço ou, quando a consulta não indica nenhuma carteira, comparando o nome do beneficiário com as suas entradas verificadas. POST .../travel-rule/ownership/ também faz a correspondência apenas pelo endereço. Quando várias entradas correspondem, a via INTERNAL e os registos pós-depósito dão preferência a uma entrada cuja propriedade foi verificada e, de seguida, à mais antiga; e a pesquisa TRP de saída escolhe a entrada mais antiga que armazena um Travel Address. As consultas TRP de entrada e o endpoint de propriedade aceitam qualquer uma das entradas correspondentes, pelo que deve manter uma entrada por endereço sempre que possível. A via INTERNAL não faz corresponder nenhuma entrada se existirem entradas verificadas para o endereço em mais do que uma outra aplicação.

Importar carteiras em lote

Importe até 10,000 carteiras numa única chamada com POST /v3/travel-rule/wallet-addresses/import/, como JSON ({"entries": [...]} ou um array simples) ou como um ficheiro CSV em UTF-8 com um máximo de 5 MB com uma linha de cabeçalho. Uma linha identifica uma carteira pelo seu address, por address_hash (o SHA-256 do endereço em minúsculas, 64 carateres hexadecimais ou 44 carateres base64), ou ambos, além de qualquer um dos campos de entrada acima. Envie apenas o hash para registar uma carteira sem divulgar o seu endereço: corresponde a transferências para esse endereço como qualquer outra entrada e pode ser comprovada com o widget de propriedade de carteira.

curl -X POST https://verification.didit.me/v3/travel-rule/wallet-addresses/import/ \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@wallets.csv;type=text/csv"

address,address_hash,chain,memo,holder_name,holder_vendor_data
0xBeneficiaryWallet01,,ethereum,,Ana Diaz,user-042
,4f7d2e1c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e,bitcoin,,,user-043
rExchangeSharedAddress01,,XRP,104729,Ana Diaz,user-042

A importação é idempotente e reporta cada linha na ordem enviada: created, existing (a mesma carteira, chain e memo já estão registados e não foram alterados), duplicate (repete uma linha anterior, indicada em duplicate_of_row) ou failed com os seus errors. Uma linha inválida nunca faz falhar as restantes: a resposta é 200 quando nenhuma linha falhou e 207 quando alguma falhou, com as contagens em total, created, existing, duplicate e failed. Uma célula vazia no CSV conta como não enviada e as colunas que a importação não lê são ignoradas, pelo que uma exportação de outra ferramenta é importada tal como está. Em GET /v3/travel-rule/transfers/, cada linha inclui originator_memo e beneficiary_memo junto às duas carteiras.

Recolha por e-mail para contrapartes inacessíveis

Quando nenhuma via de protocolo consegue alcançar a contraparte, a Didit recorre a EMAIL: envia uma ligação de recolha de utilização única para beneficiary_data.counterparty_vasp_email (ou um e-mail resolvido a partir de beneficiary_data.counterparty_vasp_name face ao registo do diretório de VASPs). O destinatário não necessita de uma conta Didit nem de uma chave de API - o token da ligação é a autenticação. Como o pedido é enviado:

Para os endereços certos. Um counterparty_vasp_email que forneça é o único destinatário. Caso contrário, a Didit envia mensagens para até três endereços: os contactos da contraparte que não tenham sofrido bounce (primeiro os seus, depois os contactos da plataforma, dando prioridade aos que responderam anteriormente) e, se restar uma vaga, o e-mail de conformidade da entrada do diretório. Cada endereço recebe o seu próprio e-mail.
Em seu nome. O e-mail provém do endereço da Didit como “a sua denominação social via Didit”, no idioma da jurisdição da contraparte (inglês quando não for conhecida nenhuma), e a ligação abre a página de resposta nesse idioma. Não recebe nenhuma cópia: acompanhe a linha temporal da transferência.
Com lembretes. Até a contraparte responder, a Didit envia-lhe lembretes 72, 24 e 6 horas antes do prazo limite, pelo menos 12 horas após o pedido ou o último lembrete, e nunca após o prazo limite.
Com gestão de bounces. Um bounce ou uma denúncia de spam marca o contacto alcançado como inválido com o respetivo motivo, sendo registado na linha temporal da transferência. Um contacto da plataforma fica então inválido para todos os clientes da Didit; o contacto da sua própria aplicação apenas para a sua aplicação. Quando a entrega de e-mail da Didit deixa de enviar para um endereço (após um bounce permanente, uma denúncia de spam ou um cancelamento de subscrição), todos os contactos nesse endereço são marcados como inválidos (suppressed), voltando a ser válidos assim que o envio para o endereço for retomado. Quando já não resta nenhum endereço para o qual escrever, a transferência passa para COUNTERPARTY_VASP_NOT_REACHABLE com o motivo do servidor de correio recetor na respetiva linha temporal. Um bounce permanente ou uma denúncia de spam no counterparty_vasp_email que forneceu provoca isso de imediato, por ser o único destinatário; um bounce temporário (soft_bounce) no mesmo, ou no e-mail de conformidade da própria entrada do diretório, mantém o pedido aberto para os lembretes.

A ligação abre uma página alojada que mostra a troca pendente e chama estes dois endpoints públicos para o destinatário. Para a transferência de exemplo acima, os detalhes de recolha são:

curl https://verification.didit.me/v3/travel-rule/pickup/{token}/

{
  "reference": "33333333-4444-5555-6666-777777777777",
  "requested_at": "2026-07-05T10:00:00Z",
  "originator_vasp_name": "Origin CASP SL",
  "originator_vasp_lei": "529900EXAMPLEORIG001",
  "recipient_vasp_name": "Example Counterparty VASP",
  "language": "es",
  "amount": "0.250000000000000000",
  "currency": "ETH",
  "fiat_amount": "",
  "fiat_currency": "",
  "chain": "ETH",
  "beneficiary_wallet": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb",
  "status": "AWAITING_COUNTERPARTY",
  "ivms_version": "ivms101.2023",
  "deadline_at": "2026-07-07T10:00:00Z",
  "reminders_sent": 0,
  "contact": "",
  "decline_reasons": ["data_mismatch", "not_our_customer", "wallet_not_hosted", "sanctions", "risk_appetite", "jurisdiction", "insufficient_data", "other"],
  "join_invitation": { "eligible": false, "url": "" },
  "originator_data": { "name": "Jane Doe", "wallet_address": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7" },
  "beneficiary_data": { "name": "Ana Diaz", "wallet_address": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb" },
  "ivms_request": {
    "originator": {
      "originatorPersons": [{ "naturalPerson": { "name": { "nameIdentifier": [{ "primaryIdentifier": "Doe", "secondaryIdentifier": "Jane", "nameIdentifierType": "LEGL" }] } } }],
      "accountNumber": ["0x77ccff0cc624a53cd8b8d8703ced826710211ec7"]
    },
    "beneficiary": {
      "beneficiaryPersons": [{ "naturalPerson": { "name": { "nameIdentifier": [{ "primaryIdentifier": "Diaz", "secondaryIdentifier": "Ana", "nameIdentifierType": "LEGL" }] } } }],
      "accountNumber": ["0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb"]
    }
  },
  "data_masked": false
}

reference é o uuid da transferência. originator_data e o ivms_request IVMS 101 construído a partir dele contêm apenas os campos do ordenante que partilhar em data_sharing_fields; o nome e a carteira estão sempre incluídos. fiat_amount e fiat_currency ficam vazios quando não enviou qualquer valor convertido, contact reflete o valor ?contact= da ligação e decline_reasons lista os valores que decline_reason aceita. join_invitation.eligible é true enquanto a contraparte tiver um convite ativo para aderir à Didit; a própria ligação de convite viaja apenas no e-mail. Este endpoint devolve o montante armazenado na íntegra, pelo que contém as 18 casas decimais completas em vez do formato truncado utilizado pelo objeto de detalhes da transação.

curl -X POST https://verification.didit.me/v3/travel-rule/pickup/{token}/respond/ \
  -H "Content-Type: application/json" \
  -d '{"decision": "accept", "beneficiary_name": "Ana Diaz"}'

decision é accept ou decline. Em accept, o beneficiary_name fornecido é comparado com o beneficiary_data.name da transferência ao abrigo da sua regra de nomes - COMPLETED em caso de correspondência, COUNTERPARTY_MISMATCHED_DATA caso contrário. A contraparte pode, em alternativa, enviar uma resposta IVMS 101 completa como ivms_response; o seu nome de beneficiário prevalece então sobre beneficiary_name. Em decline, a transferência passa para COUNTERPARTY_VASP_GENERAL_DECLINE. A contraparte pode indicar um decline_reason a partir de decline_reasons, com um decline_detail (até 512 carateres, obrigatório para other), e a linha temporal da sua transferência regista-o, por exemplo, counterparty declined: The beneficiary is not our customer. A resposta é o {"status": "..."} resultante, mais decline_reason após uma recusa. Assim que a contraparte responder, ambos os endpoints devolvem 410. Ambos os endpoints devolvem 404 para um token desconhecido e 410 assim que a janela fecha - quer porque a transferência saiu de AWAITING_COUNTERPARTY, quer porque o respetivo prazo de confirmação (confirmation_timeout_hours após a criação ou o último reenvio) expirou. A contraparte consulta e responde através da ligação de recolha com GET e POST /v3/travel-rule/pickup/{token}/messages/. Não necessita de chave de API, aceita apenas anexos em PDF, PNG, JPEG ou WebP, e responde com 410 assim que a ligação expira ou a transferência é encerrada. Uma mensagem enviada por si apresenta o nome do seu VASP como author e como uploaded_by do anexo, nunca a pessoa ou a chave de API por trás da mesma.

Depósitos sem correspondência

Um depósito de entrada pode chegar antes dos dados de Travel Rule do VASP de origem. Esse depósito permanece em AWAITING_COUNTERPARTY ou NOT_ENOUGH_COUNTERPARTY_DATA até que os dados cheguem. Liste os depósitos que ainda estão a aguardar com uma chave de API que tenha o privilégio de transações:

curl "https://verification.didit.me/v3/travel-rule/unmatched/" \
  -H "x-api-key: YOUR_API_KEY"

A resposta utiliza as mesmas linhas que GET /v3/travel-rule/transfers/, limitada a depósitos de entrada que aguardam os dados do VASP de origem. Quando os dados tiverem chegado como uma mensagem recebida separada, emparelhe os dois manualmente:

curl -X POST "https://verification.didit.me/v3/travel-rule/unmatched/{transaction_uuid}/match/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_id": "<uuid of the received message transaction>"}'

{transaction_uuid} é o depósito. transaction_id é a transação da mensagem de Travel Rule recebida. A chamada devolve { "deposit": ..., "message": ... }. Responde com 404 quando qualquer uma das transações já não existir, e com 409 com travel_rule_match_conflict (“This deposit can no longer be matched.”) quando qualquer um dos lados já tiver avançado.

Registo sunrise posterior ao depósito

Quando um depósito de cripto é liquidado on-chain antes de qualquer troca de Travel Rule ter ocorrido - o VASP remetente estava inalcançável ou está a registar retroativamente depósitos históricos - registe-o posteriormente com POST /v3/travel-rule/inbound/.

curl -X POST https://verification.didit.me/v3/travel-rule/inbound/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "eth",
    "txid": "0xf103cfc37f6d390b61827987b9dc631b5e1d2bfeb008a780c1e38047ae5d557b",
    "wallet_address": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb",
    "amount": "500.00",
    "currency": "USDC",
    "originator_data": { "name": "Carlos Ruiz", "wallet_address": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7" },
    "beneficiary_data": { "name": "Ana Diaz" },
    "originating_vasp": {
      "name": "Northwind Digital Assets Ltd",
      "lei": "5493001KJTIIGC8Y1R12",
      "travel_address": "tareGfwAzkySLkFzcqr7AKno3K4VsT3jayMwPvj3ovbFZHzpayHLmgCrAMoLqjfCYRPpvLqr9dSr2VVTFAncwChcMjL4AheNuHCJM8NRcUg"
    }
  }'

originating_vasp.travel_address tem de ser um Travel Address real e com soma de verificação válida: um marcador de posição devolve 400 com "Invalid travel address.". originating_vasp.lei tem de estar vazio ou conter 20 carateres no formato LEI (18 letras ou dígitos, seguidos de 2 dígitos); qualquer outra coisa devolve 400 com "Invalid LEI: expected 20 alphanumeric characters (ISO 17442).". A Didit valida apenas este formato, e não os dígitos de controlo da ISO 17442.

Campo	Tipo	Descrição
`chain`	string	blockchain onde o depósito foi liquidado, até 32 carateres. A Didit converte-a para minúsculas e utiliza-a para fazer a correspondência com as entradas do seu livro de endereços; por isso, utilize o mesmo token das suas entradas (`eth` corresponde a uma entrada armazenada como `ETH`). Também determina se o depósito pode ser analisado: `bitcoin`/`btc`, `ethereum`/`eth`, `solana`/`sol`, `tron`/`trx`, `polygon`/`matic`, `bsc`/`bnb`, `litecoin`/`ltc`, `ripple`/`xrp`, `bitcoin-cash`/`bch` e `dogecoin`/`doge`.
`txid`	string	O hash da transação on-chain. Utilizado para desduplicação - a combinação do mesmo `txid` + `wallet_address` devolve a transferência existente em vez de criar um duplicado.
`wallet_address`	string	A carteira de destino onde recebeu o depósito. Um X-address de XRP é dividido no respetivo endereço clássico e na tag.
`memo`	string	Opcional. A tag de destino ou o memo do depósito numa rede com memo: num endereço de depósito partilhado, identifica o cliente ao qual o depósito pertence.
`amount`	string (decimal)	Montante do depósito.
`currency`	string	Ativo do depósito.
`originator_data`	object	Detalhes do ordenante do VASP remetente, se conhecidos, como um objeto simples: a Didit lê `name` (ou `full_name`), `first_name`, `last_name` e `vendor_data`.
`beneficiary_data`	object	Detalhes do beneficiário (o seu cliente), como um objeto simples: a Didit compara o respetivo `name` com o `holder_name` da entrada correspondente no livro de endereços e adiciona-lhe `wallet_address` e `chain`.
`utxo`	object	Opcional, apenas para blockchains UTXO. Os `inputs` e `outputs` da transação de depósito: a carteira do remetente é `originator_data.wallet_address` quando a declara, caso contrário é a entrada de maior valor.
`originating_vasp`	object	`{ name, lei, travel_address }` opcional que descreve o remetente. `lei` tem de corresponder ao formato LEI acima e `travel_address` tem de ser um Travel Address válido, sob pena de o pedido devolver `400`. Mantido nesta transferência como `metadata.originating_vasp`; nunca cria nem altera uma entrada partilhada no diretório.

A Didit cria uma transação de entrada travelRule (ou reutiliza um depósito de entrada que já tenha submetido com o mesmo hash e carteira, se este ainda não tiver uma transferência da Travel Rule) e resolve a transferência em relação ao seu livro de endereços de carteiras, pelo endereço e respetivo memo:

Nenhuma entrada correspondente -> ON_HOLD. Resolva com POST .../travel-rule/ownership/: confirmed: true adiciona a carteira ao seu livro de endereços como verificada e executa a correspondência de nomes; havendo correspondência, a transferência avança para COMPLETED e depois para FINISHED.
A entrada existe, mas a propriedade não está comprovada -> UNCONFIRMED_OWNERSHIP.
O nome do beneficiário não corresponde ao holder_name da entrada -> COUNTERPARTY_MISMATCHED_DATA.
Entrada verificada e o nome corresponde -> COMPLETED e logo de seguida FINISHED (o depósito já foi liquidado).

Com a entrada verificada do livro de endereços registada no exemplo acima, a resposta é:

{
  "transaction_id": "44444444-5555-6666-7777-888888888888",
  "txn_id": "tr-in-0xf103cfc37f6d390b61827987b9dc631b5e1d2bfeb008a780c1e38047ae5d557b-6151d81b366e",
  "created": true,
  "travel_rule": {
    "uuid": "55555555-6666-7777-8888-999999999999",
    "status": "FINISHED",
    "direction": "INBOUND",
    "rail": null,
    "protocol": null,
    "ivms_version": "ivms101.2023",
    "required": true,
    "ownership_confirmed": true,
    "deadline_at": null,
    "timeline": [
      { "status": "COMPLETED", "at": "2026-07-06T10:15:02.114208+00:00", "detail": "matched verified wallet address book entry" },
      { "status": "FINISHED", "at": "2026-07-06T10:15:02.131544+00:00", "detail": "on-chain deposit already settled" }
    ],
    "counterparty_vasp": null,
    "originator_data": { "name": "Carlos Ruiz", "wallet_address": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7" },
    "beneficiary_data": { "name": "Ana Diaz", "wallet_address": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb", "chain": "eth" },
    "created_at": "2026-07-06T10:15:02.087412Z"
  }
}

O txn_id da nova transação é tr-in-, os primeiros 80 carateres do txid e um hash de 12 carateres do txid e da carteira. created é true (HTTP 201) quando esta chamada registou o depósito, e false (HTTP 200) quando os mesmos txid e wallet_address já estavam registados, caso em que a transferência existente é devolvida sem alterações. No caminho de entrada verificada, ambas as transições ocorrem antes de o endpoint responder, pelo que a resposta síncrona já apresenta o estado terminal FINISHED - o passo intermédio COMPLETED continua registado na timeline da transferência. Cada transição aciona um webhook travel_rule.status.updated (COMPLETED e FINISHED acionam, cada um, um webhook). Quando a Didit cria uma nova transação, envia primeiro transaction.created e estes eventos a seguir. O registo não tem qualquer taxa de Travel Rule ou de monitorização. Quando a monitorização de criptoativos está ativada e a chain é uma das que a Didit consegue analisar, o depósito recém-criado também é analisado e faturado uma vez à tarifa de Verificação e Triagem de Carteiras. Para retirar uma transferência de UNCONFIRMED_OWNERSHIP - ou para pré-verificar uma carteira antes da chegada de qualquer transferência -, crie um widget alojado de propriedade da carteira com POST /v3/travel-rule/widget-session/ e encaminhe o seu cliente para o url retornado. O widget comprova o controlo da carteira através de assinatura de mensagens (incluindo contas de contratos inteligentes EVM, através de ERC-1271 e ERC-6492), um teste de Satoshi, uma captura de ecrã ou autodeclaração, e de seguida marca a entrada correspondente no livro de endereços como verificada para que a plataforma de câmbio possa prosseguir. A captura de ecrã é a exceção: nunca verifica a carteira por si só, pelo que a sua equipa de conformidade a revê e confirma uma transferência em UNCONFIRMED_OWNERSHIP com POST .../travel-rule/ownership/. Consulte Widget de propriedade da carteira para conhecer o fluxo completo, os métodos de comprovação e a nota importante de que o widget tem de ser aberto num navegador real - nunca dentro de uma webview de SDK móvel.

Diretório

GET /v3/travel-rule/vasps/ pesquisa o diretório de VASPs: as entradas partilhadas do diretório mais os membros da rede Didit. Cada linha indica como a sua aplicação pode contactar esse VASP hoje.

curl "https://verification.didit.me/v3/travel-rule/vasps/?search=counterparty" \
  -H "x-api-key: YOUR_API_KEY"

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91",
      "kind": "directory",
      "name": "Example Counterparty VASP",
      "lei": "529900EXAMPLECPTY001",
      "jurisdiction": "DE",
      "domains": ["counterparty.example"],
      "reachable": true,
      "aliases": [{ "name": "Example Counterparty", "kind": "trading_name" }],
      "networks": [
        {
          "network": "GTR",
          "code": "EXAMPLE01",
          "listed_name": "Example Counterparty VASP",
          "country": "DE",
          "verified_at": "2026-10-12T09:30:00Z",
          "last_seen_at": "2026-10-12T09:30:00Z",
          "source": "staff"
        }
      ],
      "routes": [
        { "rail": "GTR", "status": "unavailable", "reason": "no_membership", "via": "" },
        { "rail": "EMAIL", "status": "available", "reason": "", "via": "contact" }
      ],
      "umbrella": null,
      "entities": [],
      "contacts": [
        {
          "id": "6c1f9b8e-2d4a-4f7e-8b3c-5a9d0e1f2a3b",
          "email": "travelrule@counterparty.example",
          "name": "Travel Rule desk",
          "source": "staff",
          "scope": "platform",
          "verified_at": null
        }
      ],
      "dd_status": "NOT_STARTED",
      "dd_score": 62,
      "dd_score_breakdown": {
        "jurisdiction": { "points": 25.0, "max": 25, "reason": "jurisdiction_not_high_risk", "detail": "DEU is not on the high-risk jurisdiction list" },
        "verification": { "points": 3.8, "max": 15, "reason": "dd_status_not_started", "detail": "due diligence status NOT_STARTED" },
        "protocol": { "points": 6.0, "max": 15, "reason": "email_only", "detail": "reachable over the email fallback only" },
        "lei": { "points": 10.0, "max": 10, "reason": "lei_valid", "detail": "valid LEI on record" },
        "history": { "points": 5.0, "max": 10, "reason": "no_history", "detail": "no exchange history" },
        "essentials": { "points": 7.5, "max": 15, "reason": "no_essential_checks", "detail": "no decided essential check yet" },
        "responsiveness": { "points": 5.0, "max": 10, "reason": "responsiveness_unknown", "detail": "0 decided recent requests, too few to judge" }
      },
      "dd_assessed_at": "2026-10-12T09:30:00Z",
      "dd_score_semantic": "higher_is_safer",
      "risk_level": "MEDIUM",
      "responsiveness": { "status": "UNKNOWN", "answered": 0, "total": 0, "computed_at": "2026-10-12T09:30:00Z" },
      "essential_checks": {},
      "reachable_rails": ["GTR", "EMAIL"],
      "is_didit_customer": false,
      "decision": {
        "decision": "APPROVED",
        "reason": "Licensed in DE",
        "decided_by": "",
        "updated_at": "2026-10-14T10:05:00Z",
        "inherited_from": null
      },
      "entity_screening": {
        "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
        "status": "Approved",
        "total_hits": 0,
        "score": null,
        "screened_at": "2026-10-14T09:58:00Z",
        "fresh": true,
        "flagged": false
      },
      "questionnaires": []
    }
  ]
}

search faz corresponder um fragmento de nome ou alias, um LEI exato ou um domínio (counterparty.example ou um URL nesse domínio). Filtre os resultados com:

Parâmetro	Efeito
`network`	`GTR`, `TRUST`, `VERIFYVASP`, `SYGNA` ou `TRISA`: apenas entradas que o diretório de membros dessa rede lista atualmente.
`jurisdiction`	Código de país ISO 3166 alpha-2 ou alpha-3.
`reachable`	`true`: apenas VASPs para os quais a sua aplicação tem uma rota disponível. `false`: apenas entradas que não consegue alcançar hoje.
`kind`	`directory` para entradas partilhadas, `didit` para membros da rede Didit.
`risk`	`LOW`, `MEDIUM` ou `HIGH`: apenas entradas do diretório cujo `risk_level` esteja nessa faixa. Consulte Pontuação e nível de risco.
`responsiveness`	`RESPONSIVE`, `UNRESPONSIVE` ou `UNKNOWN`: apenas entradas do diretório com esse `responsiveness.status`. Consulte Capacidade de resposta.

Os membros da rede Didit não são pontuados, pelo que risk e responsiveness devolvem apenas entradas do diretório. Os resultados são ordenados por nome e paginados com limit (predefinição 50) e offset. Uma rede, código de país, faixa de risco ou estado de capacidade de resposta desconhecido responde com 400 indicando o campo. GET /v3/travel-rule/vasps/{vasp_id}/ devolve uma linha pelo respetivo id. O perfil do seu próprio VASP nunca aparece nos seus próprios resultados. dd_status, dd_score, dd_score_breakdown, dd_assessed_at, dd_score_semantic, risk_level, responsiveness e essential_checks contêm a avaliação partilhada de due diligence de uma entrada do diretório. decision, entity_screening e questionnaires são registos da própria aplicação sobre o VASP, e nenhum outro cliente os vê. Consulte Due diligence da contraparte para saber o que cada um significa, e aplique restrições com os campos de regras da contraparte em vez de criar ramificações em linha. Os membros da rede Didit não são pontuados: dd_status é COMPLETED, dd_score é null, risk_level está vazio e o detalhamento está vazio.

Rotas

routes lista as formas como a sua aplicação pode entregar ao VASP, pela ordem em que são tentadas pela hierarquia de encaminhamento, e reachable é true quando pelo menos uma está available:

TRP quando a entrada inclui um endpoint TRP verificado pelo diretório.
GTR, TRUST, VERIFYVASP, SYGNA quando uma rede lista o VASP sob um código. A rota está available apenas quando a sua aplicação pode enviar através dessa rede hoje (via: own_membership para a sua própria adesão ligada, via: didit_membership para a da Didit). Caso contrário, está unavailable com reason: no_membership ou reason: network_switched_off, nunca sendo apresentada como uma forma de alcançar o VASP. As adesões a redes da própria Didit ainda não estão ativas, pelo que hoje uma rota de rede está disponível apenas através de uma adesão que a sua aplicação associou no Marketplace.
EMAIL quando existe um contacto de conformidade para a entrada.
INTERNAL para um membro da rede Didit.

Uma listagem TRISA aparece em networks e indica quem é o VASP na TRISA, mas a Didit não tem um canal TRISA, pelo que nunca é uma rota. Uma aplicação de sandbox envia apenas para o Didit Test VASP, pelo que nenhuma rota do diretório está disponível para ela: todas as rotas estão unavailable com reason: sandbox_application, todas as linhas têm reachable: false, e reachable=true não devolve linhas.

Marcas e as respetivas entidades

Uma marca que opera através de várias entidades reguladas constitui uma linha cujas entities são as entidades legais que recebem as suas transferências; uma linha de entidade aponta de volta para a sua marca em umbrella. Uma transferência que indique a marca vai para uma das suas entidades, escolhida de entre todas elas: aquela na jurisdição indicada em beneficiary_data.counterparty_vasp_jurisdiction, caso contrário a entidade que a atribuição de análise de blockchain associou à carteira de destino, caso contrário a única entidade da marca quando nenhuma jurisdição for indicada. Só então essa entidade deve estar alcançável; se não estiver, a transferência nunca vai para outra entidade nem para a marca em substituição. Quando nenhuma entidade se adequa (duas adequam-se igualmente, ou uma jurisdição indicada na qual nenhuma delas se encontra), é utilizada a rota da própria marca e, sem ela, a transferência fica como COUNTERPARTY_VASP_NOT_FOUND. A escolha da entidade legal que recebe os dados do ordenante nunca é feita por suposição, e nunca é decidida com base em que entidade tem por acaso um contacto. Várias entradas com o mesmo nome, como empresas do grupo que partilham um nome comercial, são diferenciadas pela mesma regra: a que estiver na jurisdição indicada, caso contrário a que a atribuição de análise de blockchain tiver associado. Quando nenhuma das opções seleciona uma, nenhuma é utilizada, e os detalhes contam como não indicando qualquer entrada do diretório.

Contactos

contacts são os endereços para os quais o canal EMAIL escreve. Os contactos com scope: platform servem todos os clientes Didit: a Didit faz a sua curadoria (source: staff), ou um endereço num dos domínios do próprio VASP respondeu a um pedido através da sua ligação de resposta (source: learned). Os contactos com scope: application são privados para a sua aplicação: os que adiciona (source: application), e um endereço fora dos domínios do próprio VASP que respondeu a um dos seus pedidos (source: learned). Uma transferência envia um e-mail primeiro para o contacto da sua própria aplicação, depois para um contacto da plataforma que já tenha respondido anteriormente (verified_at definido) e, em seguida, para os restantes. Faça a gestão dos contactos da sua própria aplicação com a API de contactos de contrapartes:

curl -X POST https://verification.didit.me/v3/travel-rule/counterparty-contacts/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"counterparty": "0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91", "email": "compliance@counterparty.example", "name": "Compliance desk"}'

GET /v3/travel-rule/counterparty-contacts/ lista todos os contactos para os quais a sua aplicação pode enviar, incluindo contactos da plataforma e contactos com mensagens devolvidas, os mais recentes primeiro, paginados com limit e offset. Filtre com ?counterparty= e um id de entrada do diretório; um valor que não seja um UUID responde com 400.
POST adiciona um contacto privado (counterparty, email, opcional name) e responde com 201. Adicionar um endereço que a entrada já tenha entre os seus próprios contactos devolve esse contacto. Uma entrada desconhecida responde com 400 ("No directory entry with this id.").
DELETE /v3/travel-rule/counterparty-contacts/{contact_uuid}/ elimina um dos seus próprios contactos (204). Os contactos da plataforma não podem ser eliminados e respondem com 404.

Um contacto cuja mensagem foi devolvida ou que apresentou uma reclamação tem is_invalid: true, com invalid_reason (hard_bounce, soft_bounce, spam_complaint ou suppressed), invalid_detail e invalid_at, e o canal EMAIL ignora-o. created_by está vazio em contactos da plataforma e em contactos adicionados por uma chave de API.

Como as entradas entram no diretório

O registo provisório MiCA da ESMA de prestadores de serviços de criptoativos, consultado semanalmente: o nome de cada prestador, LEI e Estado-Membro de origem.
O diretório público da TRISA, consultado semanalmente: a identidade de cada membro, o seu país e a sua listagem TRISA. Uma listagem que o diretório deixe de apresentar durante três semanas é removida.
O registo global de LEI preenche o LEI, outras denominações sociais e o país de uma entrada, e localiza o LEI de uma entrada pela sua denominação social exata no respetivo país.
A atribuição por análise de blockchain adiciona ou faz corresponder o VASP detentor de uma carteira de destino, mantendo o nome atribuído como um alias.
A equipa da Didit faz a curadoria das entradas: identificadores de encaminhamento e listagens de rede verificados por esta, contactos de conformidade, aliases, marcas e as respetivas entidades, duplicados fundidos e entradas ocultadas.

Os dados comunicados por um cliente sobre uma contraparte, tais como um originating_vasp recebido ou um Travel Address, permanecem na transferência desse cliente e nunca alteram uma entrada partilhada. As entradas são correspondidas primeiro pelo LEI, depois pelo nome exato ou alias, e são enriquecidas em vez de duplicadas.

A rede Didit

O perfil do seu VASP faz parte da rede Didit, pelo que outros clientes da Didit conseguem encontrá-lo no diretório e no seletor de VASP do utilizador final, apenas se todas as seguintes condições se verificarem:

a sua aplicação está em produção (não na sandbox) e a Travel Rule está ativa;
is_discoverable está a true e legal_name está definido;
compliance_email está definido e confirmado: envie a confirmação com POST /v3/travel-rule/settings/compliance-email/confirmation/ e abra a ligação enviada por e-mail. Alterar o endereço exige uma nova confirmação;
a Didit não marcou a aplicação como teste, demonstração ou aplicação interna.

O canal INTERNAL em si realiza a entrega numa carteira cuja posse comprovou, conforme descrito em Enviar uma transferência: apenas necessita que a sua aplicação esteja em produção, com a Travel Rule ativa e is_discoverable, dispensando o resto da lista. GET /v3/travel-rule/settings/ devolve didit_network: listed, compliance_email_confirmed, e em missing cada condição ainda não cumprida (travel_rule_off, sandbox_application, not_discoverable, legal_name_missing, compliance_email_missing, compliance_email_unconfirmed, excluded_by_staff, internal_organization).

Identificadores de encaminhamento

O encaminhamento de saída consulta uma entrada do diretório sempre que a sua transferência identifica a contraparte por counterparty_vasp_lei ou counterparty_vasp_name (um alias também funciona). Uma entrada inclui um identificador por rede na qual pode ser contactada, um endpoint TRP verificado e os seus contactos de conformidade, e routes mostra quais deles a sua aplicação pode utilizar. Pode sempre ignorar o diretório numa única transferência transmitindo os campos explícitos em Campos de resolução da contraparte.

Diligência devida da contraparte

Antes de os fundos dos seus clientes chegarem a outro VASP, precisa de saber quem é esse VASP e se o aceita. A diligência devida sobre uma contraparte tem duas camadas:

A avaliação partilhada. Cada entrada do diretório inclui uma pontuação de diligência devida, o respetivo nível de risco, um estado de capacidade de resposta e um relatório de verificações essenciais. A Didit calcula-os a partir dos dados da própria plataforma, para que todos os clientes vejam os mesmos valores.
Os seus próprios registos. A sua decisão sobre o VASP, a sua triagem de sanções e de notícias adversas do mesmo, e os questionários de diligência devida que trocou com ele pertencem unicamente à sua aplicação. Outro cliente nunca os vê e nunca alteram a entrada partilhada.

Os seus próprios registos funcionam de igual forma para uma entrada do diretório e para um membro da rede Didit: identifique ambos através do id que o diretório apresenta.

Endpoint	O que faz
`GET` / `PUT` / `DELETE /v3/travel-rule/vasps/{vasp_id}/decision/`	Consultar, definir ou limpar a sua decisão sobre a contraparte.
`GET` / `POST /v3/travel-rule/vasps/{vasp_id}/screening/`	Consultar a sua triagem da contraparte mais recente ou executar uma.
`GET` / `POST /v3/travel-rule/vasps/{vasp_id}/questionnaires/`	Listar os seus questionários de diligência devida com a contraparte ou enviar um.
`GET /v3/travel-rule/transfers/?counterparty={vasp_id}`	As suas transferências com essa contraparte.

Pontuação e nível de risco

O dd_score varia de 0 a 100 e quanto mais elevado, mais seguro. Todos os resultados indicam-no em dd_score_semantic, que é sempre higher_is_safer. O risk_level é o intervalo em que a pontuação se enquadra:

`risk_level`	`dd_score`
`LOW`	70 ou mais
`MEDIUM`	40 a 69
`HIGH`	Inferior a 40

A pontuação é a soma de sete componentes. O dd_score_breakdown apresenta cada um como {points, max, reason, detail}: max é o peso do componente, reason um código legível por máquina que pode traduzir e detail uma explicação de uma linha em inglês.

Componente	Peso	Como pontua	Códigos de `reason`
`jurisdiction`	25	Total quando o país da entrada não consta da lista predefinida de jurisdições de alto risco (`IRN`, `PRK`, `SYR`, `AFG`, `RUS`, `MMR`), zero quando consta, metade quando o país é desconhecido.	`jurisdiction_not_high_risk`, `jurisdiction_high_risk`, `jurisdiction_unknown`
`verification`	15	Estado de verificação da Didit para a entrada (`dd_status`): total para `COMPLETED`, metade para `IN_PROGRESS`, um quarto para `NOT_STARTED`, zero para `REJECTED`.	`dd_status_completed`, `dd_status_in_progress`, `dd_status_not_started`, `dd_status_rejected`
`protocol`	15	Total quando uma via de protocolo nativa alcança a entrada (um endpoint TRP ou a via `INTERNAL`), 40 por cento quando apenas o recurso alternativo por e-mail o faz, zero sem uma via alcançável.	`native_rail`, `email_only`, `no_rail`
`lei`	10	Total com um LEI válido registado, zero sem ele.	`lei_valid`, `lei_missing`
`history`	10	A percentagem das trocas decididas da entrada que foram bem-sucedidas, metade caso não exista nenhuma.	`history`, `no_history`
`essentials`	15	A percentagem de verificações essenciais decididas que são aprovadas, metade enquanto nenhuma estiver decidida.	`essential_checks`, `no_essential_checks`
`responsiveness`	10	Total para `RESPONSIVE`, zero para `UNRESPONSIVE`, metade para `UNKNOWN`. Consulte Capacidade de resposta.	`responsive`, `unresponsive`, `responsiveness_unknown`

Os pontos são arredondados a uma casa decimal e o total a um número inteiro. O history avalia os mesmos pedidos que a capacidade de resposta, sem janela temporal: uma troca com o estado COMPLETED ou FINISHED é um sucesso, e uma troca com o estado EXPIRED, COUNTERPARTY_MISMATCHED_DATA ou COUNTERPARTY_VASP_GENERAL_DECLINE é uma falha. Um cancelamento é um ato do próprio remetente e nunca é contabilizado. A Didit recalcula a avaliação quando uma troca com a entrada é concluída, finalizada, expira, apresenta discrepâncias ou é recusada, quando atualiza ou faz a curadoria da entrada, e para cada entrada na atualização semanal do diretório. O dd_assessed_at indica quando foi executada pela última vez; uma entrada que ainda não tenha sido avaliada não tem dd_assessed_at, tem um dd_score de 0 e um risk_level vazio, pelo que deve ler o risk_level em vez da pontuação em bruto. Os membros da rede Didit não são pontuados: o respetivo dd_score é null, o respetivo risk_level está vazio e o respetivo dd_score_breakdown está vazio.

Verificações essenciais

O essential_checks é um breve relatório sobre quatro verificações que a Didit executa em cada entrada do diretório, apenas a partir de fontes verificadas da plataforma, nunca a partir de dados reportados por um cliente:

`id` da verificação	É aprovada quando
`registration`	Um registo oficial lista o VASP: o registo provisório do MiCA da UE de prestadores de serviços de criptoativos, o diretório público do TRISA ou o registo global de LEI com um LEI emitido.
`licence`	O registo do MiCA regista uma autorização para o VASP que não tenha terminado.
`domain`	O domínio da entrada corresponde ao respetivo endpoint TRP ou ao site indicado pelo seu registo.
`lei`	O registo LEI da entrada está ativo e emitido, e a respetiva denominação social e país correspondem à entrada.

Cada verificação em checks reporta o seu status (pass, fail, ou unknown quando nenhuma fonte registada o consegue decidir), um reason legível por máquina e um detail de uma linha em inglês. passed, failed, unknown e total contabilizam-nas, level é essential e checked_at indica quando o relatório foi gerado. O componente essentials pontua a percentagem de verificações decididas que são aprovadas, pelo que uma verificação com unknown não conta nem a favor nem contra a entrada. O relatório está vazio até que a atualização semanal do diretório verifique uma entrada pela primeira vez, e está sempre vazio para um membro da rede Didit.

Capacidade de resposta

O responsiveness indica se o VASP responde a pedidos de Travel Rule:

{ "status": "UNRESPONSIVE", "answered": 0, "total": 6, "computed_at": "2026-10-12T09:30:00Z" }

O total contabiliza os pedidos iniciados pelos clientes da Didit destinados ao VASP nos últimos 90 dias cujo resultado foi decidido, e o answered os pedidos aos quais este respondeu:

Contabilizados: pedidos enviados através de uma rede ou via de protocolo, e pedidos enviados por e-mail para um endereço partilhado, que seja o endereço de conformidade da entrada ou um contacto da plataforma.
Nunca contabilizados: um pedido enviado por e-mail para um endereço introduzido por um cliente ou para um contacto privado de um cliente. Essa troca permanece no histórico de transferências do próprio cliente e nunca rotula o VASP para todos os outros.
Respondidos: COMPLETED, FINISHED, COUNTERPARTY_VASP_GENERAL_DECLINE ou COUNTERPARTY_MISMATCHED_DATA. Uma recusa ou uma discrepância é uma resposta: o VASP interagiu.
Não respondidos: EXPIRED.
Nenhum dos dois: todos os restantes estados. Um pedido CANCELLED é um ato do próprio remetente, COUNTERPARTY_VASP_NOT_REACHABLE pode ser uma falha do lado do remetente e um pedido que ainda esteja em curso ainda não foi decidido.

`status`	Quando
`UNKNOWN`	Menos de 5 pedidos decididos na janela, pelo que um único pedido expirado nunca rotula um VASP.
`UNRESPONSIVE`	O VASP respondeu a menos de 10 por cento dos seus pedidos decididos.
`RESPONSIVE`	Caso contrário.

Os membros da rede Didit respondem dentro da Didit e mostram sempre UNKNOWN com contagens a zero. Atue sobre uma contraparte que não responde com a política de não resposta ou com a predefinição travel-rule-counterparty-unresponsive.

A sua decisão sobre uma contraparte

Registe o veredito da sua equipa de conformidade sobre uma contraparte com PUT /v3/travel-rule/vasps/{vasp_id}/decision/:

curl -X PUT https://verification.didit.me/v3/travel-rule/vasps/0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91/decision/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision": "BLOCKED", "reason": "Unlicensed in its home jurisdiction"}'

{
  "decision": {
    "decision": "BLOCKED",
    "reason": "Unlicensed in its home jurisdiction",
    "decided_by": "",
    "updated_at": "2026-10-14T10:05:00Z",
    "inherited_from": null
  }
}

`decision`	Significado	Predefinição que atua sobre ela
`APPROVED`	A sua equipa aprovou a contraparte.	Nenhuma
`RESTRICTED`	As transferências para a mesma podem avançar após revisão.	`travel-rule-counterparty-restricted` retém-nas para revisão.
`BLOCKED`	A sua equipa recusou a contraparte.	`travel-rule-counterparty-blocked` recusa-as.

A decisão é privada para a sua aplicação: outro cliente nunca a vê e nunca altera a entrada partilhada.
Uma decisão não altera nada por si só e nunca altera a forma como uma transferência é encaminhada. Chega às suas transações através do campo de regra counterparty_dd_status: instale as predefinições ou escreva a sua própria regra sobre o mesmo.
Uma decisão sobre uma marca abrange cada uma das suas entidades que não tenha uma decisão própria, e a entidade mostra a marca em inherited_from. Uma decisão sobre a entidade sobrepõe-se à da marca para essa entidade.
GET devolve a decisão aplicável ou {"decision": null}. DELETE limpa a sua própria decisão e devolve o que se aplica a seguir: a decisão da marca para uma entidade; caso contrário, null. Responde com 404 quando a sua aplicação não tem uma decisão própria sobre a contraparte.
reason é opcional, tem até 255 carateres e cada PUT substitui-o. decided_by é o utilizador da consola que tomou ou alterou pela última vez a decisão e fica vazio quando foi uma chave de API a fazê-lo.

Triagem de contrapartes

A triagem de contrapartes verifica o próprio VASP da contraparte, enquanto empresa, contra sanções e notícias adversas. É opcional e faturada: ative-a com counterparty_screening_enabled nas suas definições. Enquanto estiver desativada, nada é analisado ou faturado.

curl -X POST https://verification.didit.me/v3/travel-rule/vasps/0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91/screening/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"refresh": false}'

{
  "outcome": "screened",
  "screening": {
    "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "status": "In Review",
    "total_hits": 2,
    "score": 85.0,
    "screened_at": "2026-10-14T09:58:00Z",
    "fresh": true,
    "flagged": true
  }
}

Faturação. Cada nova triagem custa o preço de Triagem AML de empresas da sua organização. O GET /v3/travel-rule/vasps/{vasp_id}/screening/ devolve esse price, fresh_days e se a triagem está enabled, sem custos. Uma triagem com menos de 30 dias é recente: o POST devolve-a novamente com 200 e outcome: reused e não fatura nada, a menos que envie refresh: true. Uma nova triagem devolve 201 com outcome: screened. As aplicações em sandbox nunca são analisadas nem faturadas.
Triagem automática. Com a triagem ativada, a Didit também analisa a contraparte que uma exchange de saída contacta quando a exchange se inicia, antes de as suas regras avaliarem a transação, com a mesma reutilização e faturação. Uma recusa ou falha nesse ponto nunca faz falhar a transferência.
Resultado. O status é Approved quando nenhuma correspondência potencial necessita de atenção, e In Review ou Declined para uma possível correspondência em sanções ou notícias adversas. flagged é true enquanto uma triagem recente estiver em In Review ou Declined.
Efeito. Enquanto a sua triagem mais recente de uma contraparte estiver sinalizada e a triagem permanecer ativada, counterparty_risk_level é HIGH nas suas regras, pelo que a predefinição travel-rule-counterparty-high-risk, depois de instalada, retém as suas transferências. O risk_level partilhado no diretório não muda.
Privacidade. A triagem é privada para a sua aplicação: outro cliente nunca a vê e nunca altera a entrada partilhada. O diretório mostra a sua mais recente como entity_screening.
Recusas. 409 quando a triagem está desativada, para uma aplicação sandbox, ou enquanto uma triagem da mesma contraparte já estiver em execução. 403 com code: insufficient_credits quando o seu saldo não cobrir o preço. 502 quando a triagem não pôde ser concluída. Nenhuma delas fatura nada.

Questionário de diligência devida

Peça a uma contraparte as suas respostas de diligência devida com o questionário padrão da Didit. O POST /v3/travel-rule/vasps/{vasp_id}/questionnaires/ envia-o por e-mail para um endereço de conformidade registado para a contraparte, com uma ligação de utilização única para uma página de resposta:

curl -X POST https://verification.didit.me/v3/travel-rule/vasps/0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91/questionnaires/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sent_to": "travelrule@counterparty.example"}'

{
  "id": "3f9e8d7c-6b5a-4c3d-9e2f-1a0b9c8d7e6f",
  "status": "SENT",
  "form_version": "1",
  "sent_to": "travelrule@counterparty.example",
  "sent_at": "2026-10-14T10:00:00Z",
  "expires_at": "2026-11-13T10:00:00Z",
  "answered_at": null,
  "valid_until": null,
  "current": false,
  "answers": {}
}

Para onde vai. sent_to deve ser um endereço de conformidade registado: para uma entrada de diretório, o seu endereço de conformidade ou um contacto que a sua aplicação veja em contacts; para um membro da rede Didit, o seu e-mail de conformidade confirmado. Omita-o para utilizar o endereço para o qual vai um e-mail de Travel Rule para a contraparte: primeiro o seu próprio contacto, depois um contacto da plataforma e, a seguir, o endereço de conformidade da entrada. A Didit nunca envia o questionário para nenhum outro local e responde com 400 quando a contraparte não tiver um endereço de conformidade registado.
Responder. A ligação abre /v3/travel-rule/questionnaires/{token}/, uma página para uma pessoa da contraparte que não necessita de conta nem de chave de API. Responde a cada pergunta, com até 2000 carateres cada (N/A onde não se aplique), e submete uma vez. Uma contraparte também pode enviar um pedido POST com {"answers": {"<question id>": "<answer>"}} para a mesma ligação. Uma ligação que tenha sido utilizada, substituída ou cujo prazo tenha expirado mostra, em vez disso, uma página de expiração. O e-mail e a página são traduzidos; as perguntas em si estão sempre em inglês, para que o seu significado nunca mude entre idiomas.
Prazos. A contraparte tem 30 dias para responder (expires_at). As respostas permanecem válidas durante 365 dias (valid_until), e current é true até então. Um questionário sem resposta após o prazo, e respostas fora da sua validade, tornam-se EXPIRED.
Um questionário aberto por contraparte. Um novo envio substitui o seu questionário anterior sem resposta para a mesma contraparte: torna-se EXPIRED e a sua ligação deixa de funcionar. Pode ser enviado um e-mail por minuto para um endereço; um envio mais rápido responde com 429.
Ler as respostas. O GET /v3/travel-rule/vasps/{vasp_id}/questionnaires/ lista os seus questionários com a contraparte, dos mais recentes para os mais antigos, com answers organizadas por id de pergunta assim que respondidas. O diretório mostra-os como questionnaires. São privados para a sua aplicação.

A versão 1 do formulário faz estas doze perguntas:

ID da pergunta	Pergunta
`legal_name`	Nome da entidade jurídica e jurisdição de constituição.
`licensing`	Licenças ou registos detidos para serviços de ativos virtuais: regulador, número da licença e estado em cada jurisdição.
`jurisdictions`	Jurisdições onde opera e quaisquer jurisdições onde esteja excluído ou restringido.
`aml_program`	Resumo do seu programa AML/CFT: políticas, procedimentos e data da última auditoria ou revisão independente.
`compliance_officer`	Nome e função do seu responsável pela conformidade, e como pode ser contactado.
`sanctions_screening`	Como faz a triagem de clientes e contrapartes contra sanções e notícias adversas: fornecedor ou listas, frequência e escalamento.
`transaction_monitoring`	Como monitoriza transações para identificar atividades suspeitas: ferramentas, limiares e práticas de apresentação de relatórios.
`travel_rule`	Como cumpre a Travel Rule: protocolos e redes utilizados, e o seu tempo de resposta típico a um pedido.
`custody`	Disposições de custódia para ativos de clientes: custodiante qualificado, seguro e segregação.
`ownership`	Beneficiários efetivos com 25 por cento ou mais, e qualquer entidade-mãe ou agregadora.
`record_keeping`	Práticas de manutenção de registos e período de conservação para dados da Travel Rule e de transações.
`data_protection`	Como protege os dados pessoais partilhados para conformidade e onde são armazenados.

Transferências com uma contraparte

O endpoint GET /v3/travel-rule/transfers/?counterparty={vasp_id} lista as transferências da Travel Rule da sua aplicação com uma contraparte, da mais recente para a mais antiga, pelo id que o diretório apresenta: as suas transferências cuja contraparte é essa entrada do diretório, ou os seus intercâmbios INTERNAL com esse membro da rede Didit. Um valor que não seja um ID válido devolve 400. Cada linha inclui reason logo após status: o próprio reason da transferência, para que a lista distinga um e-mail de conformidade devolvido de uma contraparte sem rota sem abrir cada transferência.

Políticas de sunrise e de não resposta

Quando uma transferência expira (confirmation_timeout_hours decorreu enquanto estava em AWAITING_COUNTERPARTY), o timeout_outcome decide o que acontece à sua transação. Duas definições permitem-lhe tratar duas causas comuns para um tempo limite excedido de forma diferente:

Definição	Aplica-se quando a contraparte é uma entrada de diretório que
`sunrise_policy`	Está numa jurisdição listada em `sunrise_jurisdictions`: um país que ainda não aplica a Travel Rule, pelo que o VASP não é obrigado a responder.
`non_responsive_policy`	Tem `responsiveness.status` como `UNRESPONSIVE`.

Ambas aceitam HOLD, REJECT ou PROCEED, com o mesmo significado que para timeout_outcome, ou uma string vazia para seguir o timeout_outcome. Ambas estão vazias por predefinição, pelo que nada se altera até definir uma:

curl -X PUT https://verification.didit.me/v3/travel-rule/settings/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sunrise_policy": "PROCEED", "non_responsive_policy": "HOLD"}'

A primeira destas que se aplicar decide o resultado:

sunrise_policy, quando estiver definida e a jurisdição da contraparte constar de sunrise_jurisdictions.
non_responsive_policy, quando estiver definida e a contraparte for UNRESPONSIVE.
timeout_outcome em todos os outros casos, incluindo uma transferência para um membro da rede Didit ou para uma contraparte sem entrada no diretório.

sunrise_jurisdictions é apenas de leitura e atualmente contém ["CO", "KH", "VN"]. Apenas estes países contam como estando num período de sunrise: qualquer outra jurisdição, bem como uma vazia ou desconhecida, segue o timeout_outcome, para que uma contraparte nunca receba a sua política de sunrise por acidente. A cronologia da transferência expirada indica o resultado aplicado, por exemplo sunrise_policy=PROCEED (counterparty jurisdiction CO does not enforce the Travel Rule yet). As suas regras continuam a ser executadas após a expiração, pelo que uma regra como a do TFR da UE tr_eu_expired_review ainda pode mover a transação para análise sob PROCEED.

Campos e predefinições de regras

Quatro campos de regra contêm o que a sua aplicação sabe sobre a contraparte que o intercâmbio de Travel Rule de uma transação alcançou: a sua entrada de diretório ou, no caso de um intercâmbio INTERNAL, o cliente da Didit que a recebeu. Cada campo fica vazio quando o intercâmbio não alcançou nenhuma contraparte conhecida.

Campo	Valor
`counterparty_dd_status`	A sua decisão: `APPROVED`, `RESTRICTED` ou `BLOCKED`, ou o de uma entidade que segue o da sua marca. Vazio quando não tomou nenhuma. Nunca a decisão de outro cliente.
`counterparty_risk_level`	O `risk_level` da entrada (`LOW`, `MEDIUM` ou `HIGH`), ou `HIGH` enquanto a sua própria triagem da contraparte estiver sinalizada. Vazio para uma entrada ainda não avaliada e para um membro da rede Didit, a menos que a sua triagem do mesmo esteja sinalizada.
`counterparty_jurisdiction`	O país da contraparte, a partir da entrada de diretório ou do perfil do membro da rede Didit. Os códigos ISO-2 e ISO-3 são ambos comparados, tal como os outros campos de país.
`counterparty_responsiveness`	O `responsiveness.status` da entrada: `RESPONSIVE`, `UNRESPONSIVE` ou `UNKNOWN`. Vazio para um membro da rede Didit.

Cinco predefinições no pacote travel_rule atuam sobre eles. Instale-as a partir de Transactions → Rules → Library na Business Console ou com a API da biblioteca de regras:

`library_key`	Acionador	Ação predefinida
`travel-rule-counterparty-blocked`	`counterparty_dd_status` é `BLOCKED`	+90 à pontuação, `DECLINED`
`travel-rule-counterparty-restricted`	`counterparty_dd_status` é `RESTRICTED`	+50 à pontuação, `IN_REVIEW`
`travel-rule-counterparty-high-risk`	`counterparty_risk_level` é `HIGH`	+40 à pontuação, `IN_REVIEW`
`travel-rule-counterparty-high-risk-jurisdiction`	`counterparty_jurisdiction` está na lista predefinida de alto risco (`IRN`, `PRK`, `SYR`, `AFG`, `RUS`, `MMR`)	+60 à pontuação, `IN_REVIEW`
`travel-rule-counterparty-unresponsive`	`counterparty_responsiveness` é `UNRESPONSIVE`	+30 à pontuação, `IN_REVIEW`

Todas as cinco aplicam-se apenas a transações da Travel Rule.

Webhooks

Subscreva um destino a travel_rule.status.updated para receber notificações em cada transição de estado de todas as transferências na sua aplicação, de saída e de entrada, incluindo os segmentos do rail INTERNAL. O encaminhamento é executado após o retorno da criação da transação, pelo que resultados como COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE, ou uma troca INTERNAL liquidada de imediato chegam até si através deste evento em vez de serem incluídos na resposta de criação.

{
  "event_id": "9c0c8b8a-1111-4222-9333-666666666666",
  "webhook_type": "travel_rule.status.updated",
  "timestamp": 1774970000,
  "created_at": 1774970000,
  "application_id": "11111111-2222-3333-4444-555555555555",
  "environment": "live",
  "transaction_id": "22222222-3333-4444-5555-666666666666",
  "txn_id": "trv-2026-07-05-001",
  "travel_rule_status": "COMPLETED",
  "rail": "INTERNAL",
  "direction": "OUTBOUND"
}

O campo rail fica vazio até que um rail seja selecionado. Para uma transação, o Didit envia travel_rule.status.updated após transaction.created: quando o Didit cria a transação (o seu POST /v3/transactions/, um registo sunrise, um pedido TRP de entrada ou o segmento de entrada do rail INTERNAL), envia primeiro transaction.created. Cada evento é entregue e é feita uma nova tentativa de forma independente, pelo que um transaction.created que tenha necessitado de nova tentativa pode ainda chegar após um evento de estado: utilize transaction_id como chave no seu processador e leia a transação quando um evento de estado referenciar uma que ainda não tenha visto. Uma transferência enviada através da TRUST não recebe nenhum evento COMPLETED: a TRUST não devolve nada que o Didit possa ler, pelo que, a menos que o envio falhe ou que o cancele, o seu último evento é EXPIRED. Na GTR, VERIFYVASP e SYGNA, o evento segue a resposta que o Didit lê da rede. As aplicações sandbox também enviam este evento, com "environment": "sandbox"; uma transferência respondida pelo Didit Test VASP inclui rail: "TEST_VASP", test_vasp: true e test_vasp_scenario. Consulte o guia de webhooks para ver o catálogo completo de eventos, a verificação da assinatura e a política de novas tentativas.

Preços

A taxa da Travel Rule é de $0.02 por troca de saída iniciada, cobrada uma vez aquando da criação da transação, independentemente de quantas transições de estado a troca atravesse posteriormente. Um resend nunca a cobra novamente.

Aplica-se a uma transação travelRule de saída numa aplicação com a Travel Rule ativada, cujo montante seja igual ou superior ao seu threshold_amount, para que o Didit inicie uma troca gerida para essa transação. Uma transferência para uma carteira autocustodiada, ou para a própria carteira verificada do seu utilizador, também conta: a prova de propriedade é a respetiva troca.
Todas as outras transações de saída que transportem dados da Travel Rule são faturadas como Triagem de transações padrão, que o seu plano inclui até ao respetivo limite mensal de transações e tem o preço de $0.001 para além desse limite: uma transferência abaixo do seu limiar, um pagamento Lightning ao qual a Travel Rule não se aplica e uma transferência registada passivamente enquanto a Travel Rule está desativada. Uma transação é faturada numa das duas linhas, nunca em ambas.
As transações travelRule de entrada não têm taxa da Travel Rule ou de monitorização: o segmento de entrada que o Didit cria na aplicação do beneficiário através do rail INTERNAL, pedidos TRP de entrada e registos após depósito.
Uma aplicação que tenha aderido gratuitamente à Travel Rule não paga nenhuma das taxas em transações travelRule de saída até ativar a faturação de saída com POST /v3/travel-rule/workspace/billing/; a receção permanece gratuita.
As aplicações sandbox nunca são cobradas.
A taxa da Travel Rule é de $0.02 e a Triagem de transações é de $0.001 para além do seu limite incluído. Cada transação é cobrada pelo preço da linha em que é faturada.
Se a triagem AML de cripto/carteiras também for executada na mesma transação (por exemplo, um depósito de entrada com currency_kind: "crypto" e monitorização ativada), isso é faturado separadamente à taxa padrão de Verificação e Triagem de Carteiras - não está incluído na taxa da Travel Rule.
A triagem de contrapartes é opcional e faturada separadamente, ao preço de Triagem AML de empresas por triagem; uma triagem com menos de 30 dias é reutilizada sem custos. Decisões, questionários e a avaliação de diligência devida do diretório não têm custos.

Preços de atribuição

A atribuição por análise de blockchain necessita de uma consulta de carteira junto do fornecedor de análise, e você obtém sempre o valor total dessa consulta:

A monitorização de cripto já fez a triagem da carteira nesta transação - o resultado armazenado é reutilizado. Uma chamada de análise, uma cobrança de Verificação e Triagem de Carteiras (aquela que a monitorização de cripto já efetuou). A atribuição não acrescenta custos.
A monitorização de cripto não foi executada - o Didit faz a chamada de análise necessária uma única vez e transmite o seu valor total: a transação é cobrada à taxa padrão de Verificação e Triagem de Carteiras ($0.15 com análise gerida pelo Didit) e recebe em troca o resultado completo da triagem de cripto - pontuação de risco, categoria de risco da carteira, instantâneo da rede - e não apenas o nome do VASP. O item de utilização é marcado com o acionador travel_rule_attribution para que a cobrança seja explicável.
Chave de análise própria - a mesma taxa de plataforma que se aplica à monitorização de cripto com a sua própria chave aplica-se aqui ($0.02 por chamada). O seu fornecedor fatura-lhe diretamente a consulta subjacente.
As consultas falhadas nunca são cobradas, os reenvios reutilizam a atribuição registada sem uma nova chamada ou cobrança, e as aplicações sandbox nunca são cobradas.

Portanto, uma transferência de saída que necessitou de atribuição custa $0.02 (Travel Rule) + uma cobrança de Verificação e Triagem de Carteiras - e quando ambos os produtos estão ativados, a chamada de análise e a respetiva cobrança ocorrem apenas uma vez.

Pacote de regras TFR da UE

Quatro regras pré-definidas são fornecidas no pacote travel_rule_eu_tfr, concebidas especificamente para as obrigações do TFR da UE. Tal como qualquer outro pacote pré-definido, ative-o a partir da Business Console em Transactions → Rules → Library.

Regra (`library_key`)	Acionador	Ação
`tr_eu_mismatch_hold`	O estado da transferência é `COUNTERPARTY_MISMATCHED_DATA`	Adicionar `+50` à pontuação, transação colocada em `IN_REVIEW`
`tr_eu_unverified_selfhosted_review`	O estado da transferência é `UNCONFIRMED_OWNERSHIP` e o montante na moeda predefinida é de pelo menos `1000`	Transação colocada em `IN_REVIEW`
`tr_eu_vasp_not_found_score`	O estado da transferência é `COUNTERPARTY_VASP_NOT_FOUND`	Adicionar `+25` à pontuação, etiquetada com `travel-rule-sunrise`
`tr_eu_expired_review`	O estado da transferência é `EXPIRED`	Transação colocada em `IN_REVIEW`

Estas regras são acionadas em todas as transições relevantes - na criação da transferência, na confirmação de propriedade, na resposta à recolha por e-mail e através do processo de limpeza de transferências expiradas - para que uma transferência que nunca seja concluída continue a surgir para revisão de conformidade em vez de ser liquidada silenciosamente.

Por que motivo funciona melhor numa única plataforma

A conformidade com a Travel Rule é um problema de identidade disfarçado de pagamentos - e a Didit já detém a identidade:

Dados verificados disponíveis. A pessoa associada a cada transferência está associada através de vendor_data ao perfil de KYC que a Didit verificou no onboarding (OCR de documentos, prova de vida, correspondência facial), para que possa construir originator_data a partir de campos verificados na mesma plataforma. Para um utilizador com uma verificação de KYC aprovada, a Didit transmite a identidade verificada em vez dos valores que introduziu (consulte Dados verificados e proveniência).
Biometria adicional para transferências de risco. Uma regra pode reter qualquer transferência de valor elevado até que o utilizador passe por uma nova verificação biométrica contra o rosto capturado no onboarding - a resposta mais forte possível à tomada de controlo de conta no momento do levantamento. Consulte o exemplo prático.
Um único grafo de dispositivos. As transferências submetidas através do SDK contêm os mesmos dados de inteligência sobre o dispositivo que as sessões de KYC, pelo que “novo dispositivo + montante elevado + beneficiário pela primeira vez” é uma única regra, e não uma junção no armazém de dados.
Triagem, regras, casos e a troca num único local. A triagem de carteiras que atribui o VASP da contraparte é a mesma triagem que as suas regras e analistas veem - uma cobrança, uma consola, um registo de auditoria.
Preços públicos. $0.02 por troca de saída, sem níveis de volume, sem chamadas de vendas.

FAQ

Como funciona a troca

A Didit executa a troca VASP a VASP diretamente ou apenas regista os dados da Travel Rule após outra rede concluir o handshake?

A Didit executa a troca diretamente. Quando submete uma transferência travelRule, a Didit realiza a descoberta de contrapartes em tempo real, envia os dados do ordenante e do beneficiário para o VASP recetor nos canais que os transportam e marca a transferência como COMPLETED apenas quando a contraparte a confirmar - trata-se de um handshake gerido, não de um registo pós-liquidação. A resposta de uma contraparte é processada em todos os canais, exceto no TRUST, que apenas envia, pelo que uma transferência através dele expira em vez de ser concluída. No GTR, VERIFYVASP e SYGNA, a Didit lê a resposta a partir da resposta da rede ou consultando-a a cada 5 minutos, e nenhuma troca através destes foi ainda concluída contra uma rede em produção; no TRP, uma resposta que a contraparte não forneça de imediato requer o anfitrião público TRP da Didit, que ainda não está ativo (consulte Redes da Travel Rule). A Didit também mantém o registo completo e o estado de conformidade de cada troca (um ciclo de vida de 13 estados, webhooks e um registo de auditoria). Se preferir executar a Travel Rule através do seu próprio processo, a Didit pode, em alternativa, registar os dados passivamente como o seu sistema único de registo (consulte a pergunta sobre registo passivo abaixo). Ambos os modos estão disponíveis: a troca ativa é executada assim que definir is_enabled: true nas definições (está como false por predefinição) e, até lá, a Didit regista os dados de forma passiva.

A troca é nativa da Didit ou depende de um fornecedor externo de interoperabilidade (Notabene, Sygna, VerifyVASP, TRP)?

É nativa. A Didit executa a sua própria implementação do Travel Rule Protocol (TRP), disponibilizada em trp.didit.me assim que esse anfitrião público estiver ativo (ainda não responde, pelo que as contrapartes não conseguem contactá-lo por TRP hoje), e implementa diretamente os protocolos de rede da indústria - GTR (Global Travel Rule), TRUST, VerifyVASP e Sygna Bridge (falado nativamente, incluindo o IVMS 101 encriptado com ECIES da Sygna e pedidos de permissão assinados). A Didit não é um revendedor de uma única camada de interoperabilidade de terceiros. Contactar uma contraparte que pertença a uma rede de adesão específica ocorre necessariamente através dessa rede - não existe um canal universal único na Travel Rule - mas a descoberta, o handshake, a verificação e a conservação de registos são todos executados pela Didit. Atualmente, cada canal de rede requer a sua própria adesão, e o TRUST apenas envia: consulte Visão geral.

Que redes e protocolos da Travel Rule são suportados pela Didit?

Implementados nativamente, tentados por ordem estrita de prioridade: INTERNAL (ambos os VASP na Didit), TRP (OpenVASP Travel Rule Protocol), GTR, TRUST, VerifyVASP, Sygna Bridge e um recurso de contingência por EMAIL para contrapartes sem ferramentas. Os canais de rede requerem a sua própria adesão atualmente, o TRUST apenas envia e a receção através de uma rede ainda não está ativada: consulte Redes da Travel Rule. CODE, TRISA, Notabene e Veriscope surgem no Marketplace da Didit como mosaicos para solicitar acesso, ainda sem integração. Consulte Como a Didit encaminha uma troca para a tabela de encaminhamento completa e Redes da Travel Rule para saber o alcance atual de cada uma.

Que rede devo utilizar e preciso das minhas próprias adesões?

O TRP é a base que recomendamos: não requer qualquer adesão partilhada - partilhar o seu Travel Address permite que qualquer VASP compatível com TRP o contacte - e quando uma contraparte é conhecida apenas pelo endereço da carteira, a atribuição por análise de blockchain encaminha-a através de TRP apenas se a entrada correspondente no diretório já tiver um endpoint TRP. No envio, a Didit envia os ativos listados em Identificadores de ativos TRP através dele, e uma contraparte que não responda de imediato requer o anfitrião público TRP da Didit, que ainda não está ativo. Para redes de adesão, escolha em função do local onde as suas contrapartes operam: a GTR oferece uma cobertura global alargada, a TRUST está orientada para VASP dos EUA e a VerifyVASP (que agora também opera a Sygna Bridge) tem uma forte cobertura na Ásia. Sim, atualmente necessita da sua própria adesão: a Didit ainda não detém uma adesão de plataforma nestas redes e está em processo de integração como fornecedor. Ligue a sua adesão no Marketplace; não está limitado a uma única rede. Lembre-se de que o TRUST apenas envia, pelo que uma transferência através dele não fica concluída, e que nenhuma troca através de uma rede foi ainda concluída contra uma rede em produção.

Como é que a Didit encontra o VASP da contraparte quando tenho apenas o endereço de uma carteira?

Através de uma cadeia de resolução: outro cliente Didit que tenha comprovado o controlo da carteira (o canal INTERNAL), o seu próprio livro de endereços de carteiras para um Travel Address guardado, depois os canais de protocolo e de rede e, por fim, a atribuição por análise de blockchain. Se a transferência incluir apenas uma carteira de destino, a Didit resolve-a através de dados de análise de blockchain para atribuir a exchange ou serviço de custódia da contraparte e cataloga-a no diretório de VASP. A transferência é depois encaminhada automaticamente apenas se essa entrada do diretório já tiver uma rota, como um endpoint TRP; caso contrário, termina em COUNTERPARTY_VASP_NOT_FOUND com o nome da contraparte registado, e pode reenviar assim que existir uma rota, por exemplo após guardar o travel_address da contraparte na entrada do seu livro de endereços para essa carteira (para os ativos listados em Identificadores de ativos TRP).

Preços e licenciamento

Quanto custa a Travel Rule e está incluída no meu plano de KYC ou verificação?

A Travel Rule é um produto separado, baseado na utilização. Não está incluída na verificação de identidade. Custa **$0.02 por troca de saída iniciada** ([tabela de preços publicada](#preços), sem escalões de volume, sem chamadas comerciais). Quando o encaminhamento necessita de uma consulta de análise de blockchain para identificar o VASP da contraparte, essa consulta é cobrada uma vez à [taxa de atribuição](#preços-de-atribuição): a partir de $0.15 com gestão, ou $0.02 com uma chave de fornecedor existente. Não é faturada novamente se a monitorização de cripto já tiver analisado a mesma carteira. Uma transferência abaixo do seu limiar, ou uma registada enquanto a Travel Rule está desativada, é faturada como triagem de transações; as transferências recebidas, como os fluxos que a Didit cria no lado do beneficiário, não pagam a taxa da Travel Rule.

Serei cobrado duas vezes quando a Travel Rule e a monitorização de cripto forem executadas em simultâneo?

Não. Uma transação travelRule é faturada numa única linha: a taxa da Travel Rule ($0.02) quando inicia uma troca enviada; caso contrário, como triagem de transações padrão. A consulta de análise de blockchain é cobrada uma vez: se a monitorização de cripto já tiver analisado a carteira de destino na transação, a atribuição reutiliza esse resultado guardado sem custos adicionais. Os fluxos recebidos que a Didit cria no lado do beneficiário nunca são faturados com a taxa da Travel Rule.

A Didit pode fornecer documentação ou uma declaração de capacidades para o meu processo de licenciamento de VASP ou para o meu processo junto do regulador?

Sim. O KYT e a monitorização de transações, triagem AML e de sanções, risco de carteira por análise de blockchain e as capacidades da Travel Rule da Didit estão todos documentados publicamente em docs.didit.me, e pode citar livremente estas páginas num processo regulatório. Para uma declaração formal de capacidades do produto adaptada a uma submissão específica - por exemplo, um pedido de licença VASP no âmbito da AIFC/AFSA, MiCA ou outro -, contacte a equipa responsável pela sua conta Didit com o formato exigido pelo seu regulador.

Operações e dados

O que acontece às transferências abaixo do meu limiar?

Resolvem-se imediatamente para NOT_APPLICABLE: nenhum canal é utilizado e nenhum dado de identidade sai da Didit. A transação é faturada como Triagem de transações padrão, e não com a tarifa da Travel Rule. A Didit compara o limiar com o montante convertido para a moeda predefinida da sua aplicação. Se a Didit não conseguir converter o montante, o limiar não é aplicado e a transferência é trocada. O TFR da UE não tem valor mínimo, pelo que os CASP da UE devem manter threshold_amount em 0.00.

E se a contraparte nunca responder?

A transferência permanece em AWAITING_COUNTERPARTY até que confirmation_timeout_hours decorra, momento em que um processo de limpeza move-a para EXPIRED e aplica o seu timeout_outcome à transação subjacente - HOLD para revisão, REJECT para recusar ou PROCEED para a deixar inalterada. A regra predefinida tr_eu_expired_review apresenta adicionalmente cada expiração aos seus analistas. Uma contraparte que nunca chega a receber a mensagem é um caso diferente: a Didit tenta novamente e, após a sexta tentativa falhada, a transferência passa para COUNTERPARTY_VASP_NOT_REACHABLE (consulte Entrega e tentativas).

A minha contraparte não tem quaisquer ferramentas de Travel Rule. Ainda assim posso cumprir?

Sim - esse é o canal EMAIL. O respetivo contacto de conformidade recebe uma ligação de recolha de utilização única e pode confirmar ou recusar a troca a partir de uma página alojada sem conta Didit, sem chave de API e sem integração. Para depósitos que já tenham sido liquidados antes de qualquer troca ser possível, utilize o registo sunrise pós-depósito.

Como funcionam os levantamentos para a própria carteira do utilizador?

Declare o destino como autocustodiado (payment_method.method_type: "unhosted_wallet"). A Didit ignora o encaminhamento do VASP e, em alternativa, recolhe a prova de que o seu cliente controla a carteira - assinatura de mensagens, teste Satoshi, captura de ecrã ou autodeclaração - através do widget de propriedade da carteira. Essa é a obrigação de carteira autocustodiada do TFR da UE em formato de API.

Os dados pessoais da contraparte estão protegidos durante a troca?

Sim. Até que a propriedade da carteira seja confirmada do seu lado, os dados pessoais da contraparte numa transferência de entrada são mascarados, tanto no objeto da transferência como na parte da contraparte da transação (consulte Dados mascarados da contraparte). As páginas de recolha por e-mail mostram apenas o resumo da transferência (nome do VASP ordenante, montante, carteira de destino), nunca os payloads relativos às pessoas. As trocas através de canais são realizadas através de HTTPS, e os canais de rede (GTR, TRUST, VERIFYVASP, SYGNA) encriptam adicionalmente o payload IVMS com a chave pública do VASP destinatário.

Já monitorizo a conformidade com a Travel Rule através do meu próprio processo. Posso apenas registá-la?

Sim. Com a Travel Rule desativada, quaisquer travel_rule_details que submeta (incluindo um status fornecido pelo chamador, atual ou legado) são registados passivamente na transação - nenhum canal é acionado, nada é negociado. Utilize isto para preenchimento retroativo ou para executar o seu próprio processo mantendo um único sistema de registo.

Como testo isto antes de avançar para produção?

Utilize uma aplicação sandbox com a Travel Rule ativada. O ambiente sandbox ignora regras, faturação e os webhooks transaction.created e transaction.status.updated, e cada troca de saída segue para o Didit Test VASP no canal TEST_VASP, que responde no interior da Didit com o cenário que selecionar: aceitar, recusar, divergência de nomes, não acessível, tempo limite excedido ou autocustodiada. Recebe webhooks travel_rule.status.updated marcados com environment: sandbox, e nenhuma mensagem chega a uma contraparte real. Para entrada, peça ao VASP de teste que lhe envie uma transferência com Acionar transferência de entrada do Test VASP, ou registe uma com POST /v3/travel-rule/inbound/; ambas são avaliadas com base no seu livro de endereços de carteiras - ON_HOLD, UNCONFIRMED_OWNERSHIP, COUNTERPARTY_MISMATCHED_DATA, ou COMPLETED e depois FINISHED. Para uma troca entre duas partes com outra aplicação real, utilize duas das suas próprias aplicações de produção no canal INTERNAL: a que recebe tem de estar disponível para descoberta e provar o controlo da carteira de destino com uma mensagem assinada ou um depósito de teste.

Passos seguintes

Widget de propriedade da carteira

Comprove que um cliente controla uma carteira através de assinatura, teste Satoshi, captura de ecrã ou autodeclaração.

Interoperabilidade

Os endpoints destinados às contrapartes, que outros VASP utilizam para comunicar consigo: TRP, callbacks, recolha por e-mail, sunrise.

Redes

O alcance atual de cada canal e rede e o que ainda aguarda adesão.

Testar em sandbox

Teste todos os resultados com o Didit Test VASP antes de avançar para produção.

Submeter transações

Como incluir dados da Travel Rule no payload do Create Transaction.

Biblioteca de regras

O catálogo completo de regras predefinidas, incluindo o pacote da Travel Rule.

Webhooks

Subscreva travel_rule.status.updated e todas as outras famílias de eventos.

Guia da consola

Visualizar o estado da Travel Rule na vista de detalhe da transação.

Última modificação em 7 de novembro de 2026

​Visão geral

​O que é executado ao submeter uma transferência

​Como cada passo corresponde às suas obrigações

​Ciclo de vida

​Entrega e tentativas

​Valores de estado legados

​Configuração

​Rigor da correspondência de nomes

​Modos de validação de propriedade

​Partilha de dados

​Correspondência por campo

​Limiares por jurisdição

​Modelo de dados IVMS 101

​Dados verificados e proveniência

​Envio direto de IVMS 101

​Dados obrigatórios por regime

​Travel addresses

​Testar sem credenciais de rede

​Enviar uma transferência

​Identificadores de ativos TRP

​Descoberta de contrapartes

​Campos de resolução da contraparte

​Estruturas de blockchain

​Transferências UTXO

​Redes com memo e tag

​Lightning

​Atualizar a carteira do ordenante

​Atribuição por análise de blockchain

​Por que motivo uma transferência está bloqueada

​Carteiras autocustodiadas declaradas

​Receber

​Confirmar a propriedade da carteira

​Transferências a partir de uma rede

​Dados da contraparte mascarados

​Feedback de divergências

​Pontuação de correspondência do nome

​Mensagens e pedidos de documentos

​Livro de endereços de carteiras

​Importar carteiras em lote

​Recolha por e-mail para contrapartes inacessíveis

​Depósitos sem correspondência

​Registo sunrise posterior ao depósito

​Widget de propriedade da carteira

​Diretório

​Rotas

​Marcas e as respetivas entidades

​Contactos

​Como as entradas entram no diretório

​A rede Didit

​Identificadores de encaminhamento

​Diligência devida da contraparte

​Pontuação e nível de risco

​Verificações essenciais

​Capacidade de resposta

​A sua decisão sobre uma contraparte

​Triagem de contrapartes

​Questionário de diligência devida

​Transferências com uma contraparte

​Políticas de sunrise e de não resposta

​Campos e predefinições de regras

​Webhooks

​Preços

​Preços de atribuição

​Pacote de regras TFR da UE

​Por que motivo funciona melhor numa única plataforma

​FAQ

​Como funciona a troca

​Preços e licenciamento

​Operações e dados

​Passos seguintes

Widget de propriedade da carteira

Interoperabilidade

Redes

Testar em sandbox

Submeter transações

Biblioteca de regras

Webhooks

Guia da consola

Visão geral

O que é executado ao submeter uma transferência

Como cada passo corresponde às suas obrigações

Ciclo de vida

Entrega e tentativas

Valores de estado legados

Configuração

Rigor da correspondência de nomes

Modos de validação de propriedade

Partilha de dados

Correspondência por campo

Limiares por jurisdição

Modelo de dados IVMS 101

Dados verificados e proveniência

Envio direto de IVMS 101

Dados obrigatórios por regime

Travel addresses

Testar sem credenciais de rede

Enviar uma transferência

Identificadores de ativos TRP

Descoberta de contrapartes

Campos de resolução da contraparte

Estruturas de blockchain

Transferências UTXO

Redes com memo e tag

Lightning

Atualizar a carteira do ordenante

Atribuição por análise de blockchain

Por que motivo uma transferência está bloqueada

Carteiras autocustodiadas declaradas

Receber

Confirmar a propriedade da carteira

Transferências a partir de uma rede

Dados da contraparte mascarados

Feedback de divergências

Pontuação de correspondência do nome

Mensagens e pedidos de documentos

Livro de endereços de carteiras

Importar carteiras em lote

Recolha por e-mail para contrapartes inacessíveis

Depósitos sem correspondência

Registo sunrise posterior ao depósito

Widget de propriedade da carteira

Diretório

Rotas

Marcas e as respetivas entidades

Contactos

Como as entradas entram no diretório

A rede Didit

Identificadores de encaminhamento

Diligência devida da contraparte

Pontuação e nível de risco

Verificações essenciais

Capacidade de resposta

A sua decisão sobre uma contraparte

Triagem de contrapartes

Questionário de diligência devida

Transferências com uma contraparte

Políticas de sunrise e de não resposta

Campos e predefinições de regras

Webhooks

Preços

Preços de atribuição

Pacote de regras TFR da UE

Por que motivo funciona melhor numa única plataforma

FAQ

Como funciona a troca

Preços e licenciamento

Operações e dados

Passos seguintes