Saltar para o conteúdo principal
Esta página destina-se ao outro lado de uma troca Didit Travel Rule: o VASP da contraparte (ou a respetiva equipa de engenharia) que precisa de enviar dados da Travel Rule para um VASP que utiliza a Didit, ou de os receber dele. Tudo o que está documentado aqui é infraestrutura pública operada pela Didit. Não precisa de uma conta na Didit, de uma chave de API nem de qualquer relação comercial com a Didit para interoperar - a integração mais profunda exige apenas HTTPS e JSON.

​
Como a Didit encaminha uma transferência

Quando um cliente da Didit envia uma transferência, a Didit tenta estes canais por ordem estrita de prioridade e usa o primeiro que consegue chegar até si:
A Didit não consegue receber uma resposta TRUST, e ainda não aceita transferências que lhe sejam enviadas por uma rede. Através de TRUST, a transferência de um cliente da Didit chega até si, mas a sua resposta não pode ser recebida, e a transferência expira no prazo de confirmação do remetente em vez de ser concluída. Através de GTR, VERIFYVASP e SYGNA, a Didit lê a sua resposta a partir da própria rede, pela resposta ou consultando periodicamente o estado da transferência.
A tabela acima abrange as transferências que um cliente da Didit envia. Quando você envia uma transferência a um cliente da Didit, a Didit só a pode receber como uma consulta de transferência TRP, quando o host TRP público da Didit estiver ativo (ainda não responde, veja endpoints TRP), ou, após a liquidação, como um registo sunrise: atualmente, nenhum canal de rede nem nenhum canal de e-mail entrega uma transferência recebida a um cliente da Didit. Os canais de rede (GTR, TRUST, VERIFYVASP, SYGNA) funcionam através de uma adesão do lado do remetente. Atualmente, essa adesão tem de ser a adesão própria e ligada do cliente da Didit: a Didit ainda não tem uma adesão de plataforma em nenhuma destas redes e está a fazer o onboarding como fornecedor. O GTR não está incluído por defeito, e o mesmo requisito de adesão se aplica às quatro redes. O remetente deve verificar o objeto networks em Obter definições da Travel Rule: didit significa que a adesão da Didit tem essa aplicação como participante próprio na rede, own significa uma adesão ligada de cliente, off significa que o encaminhamento pela plataforma está desativado, e unavailable significa que, por enquanto, nada pode enviar nessa rede para a aplicação. Enquanto a Didit não tiver uma adesão de plataforma, nenhuma rede apresenta didit. Ativar a Travel Rule não ativa uma adesão a uma rede. Veja redes da Travel Rule para o que cada rede alcança atualmente. Se estiver numa dessas redes e o cliente da Didit tiver a sua própria adesão nela, partilhe com ele o seu identificador de rede, e a transferência chega até si pela rede que já opera. Através de SYGNA, a sua resposta de autorização conclui ou recusa a transferência: a Didit consulta periodicamente o estado da transferência a cada 5 minutos e também regista https://trp.didit.me/sygna/callbacks/permission/{token}/ como callback de cada pedido de autorização, com um token criado para essa transferência. Esse callback está no host TRP público da Didit, que ainda não responde a pedidos. Um permission_status de ACCEPTED passa a transferência do remetente para COMPLETED, e REJECTED passa-a para COUNTERPARTY_VASP_GENERAL_DECLINE, ou para COUNTERPARTY_MISMATCHED_DATA quando o reject_code é BVRC007 (o nome do beneficiário não corresponde). O callback exige a sua assinatura: responde com 401 e {"status": "INVALID_SIGNATURE"} sem uma assinatura válida, com 404 para um token desconhecido, e com 200 novamente para uma decisão que já foi aplicada. Sem nenhuma adesão partilhada, o TRP é o caminho a planear: partilhe o seu Travel Address com o cliente da Didit, e as transferências dele chegam ao seu endpoint TRP. Uma resposta que dê na resposta à sua consulta conclui ou recusa a transferência de imediato; uma resposta que publique mais tarde no callback da Didit precisa do host TRP público da Didit, que ainda não está ativo. Quando nenhum dos canais o consegue identificar, a Didit executa mais um passo de resolução: atribuição por análise de blockchain. O endereço de destino é resolvido com dados de análise de blockchain e, quando é atribuído ao seu serviço de câmbio ou de custódia, a Didit regista o seu nome no diretório de VASP e volta a tentar os canais com esse nome. Isto significa que pode ser identificado mesmo quando o remetente forneceu apenas um endereço. As transferências atribuídas só são encaminhadas para si automaticamente quando a sua entrada no diretório tem uma rota: um endpoint TRP verificado, uma listagem numa rede ou um contacto de conformidade (veja Como entrar no diretório de VASP da Didit). A cadeia completa de resolução é, portanto: um cliente da Didit que comprovou o controlo da carteira (INTERNAL) e o Travel Address que o remetente guardou para ela, depois os canais de protocolo e de rede, e por fim a análise de blockchain.

​
Travel addresses

Cada VASP da Didit com a Travel Rule ativada tem uma Travel Address, uma cadeia compacta que começa por ta e codifica o URL do seu endpoint pessoal de pedidos de informação de transferência TRP. Os clientes da Didit consultam a sua nas definições de Travel Rule e partilham-na com as contrapartes; quando um cliente da Didit lhe fornece a sua, tem tudo o que precisa para o contactar através do TRP. A codificação segue a convenção de Travel Address do TRP:
  • Remova o prefixo ta.
  • Descodifique o restante em Base58Check (alfabeto Bitcoin, checksum double-SHA256).
  • Os bytes descodificados são o URL de pedido de informação sem o esquema; acrescente https://.
  • O URL inclui sempre o par de consulta t=i (tipo: pedido de informação).
Uma Travel Address da Didit descodificada tem uma de duas formas:
{profile_uuid} identifica o perfil de VASP alojado - envie através de POST os seus pedidos de informação de transferência para esse URL e consulte primeiro o endpoint de identidade correspondente para verificar com quem está a comunicar. A segunda forma é uma Travel Address por carteira: identifica uma carteira do cliente da Didit (receiving_travel_address no respetivo livro de endereços), pelo que o seu pedido de informação chega a essa carteira sem que o cliente tenha de a associar através do número de conta ou do nome do titular. Responde com 404 depois de a carteira ser eliminada ou quando fica registada como pertencente a outro VASP.

​
Endpoints TRP

A Didit usa a versão 3.2.1 da API TRP no URL base https://trp.didit.me. Todos os endpoints trocam JSON sobre HTTPS.
O host TRP público da Didit ainda não serve estes endpoints. Até o fazer, um pedido de informação TRP ou um pedido de identidade dirigido a um cliente da Didit não pode ser entregue; esta secção é o contrato que o host seguirá quando estiver ativo.
Dois cabeçalhos TRP são importantes:
  • api-version - a versão do protocolo TRP que utiliza, por exemplo 3.2.1. Obrigatório nos pedidos de informação e em ambos os callbacks.
  • request-identifier - o seu identificador único do pedido, devolvido nos cabeçalhos da resposta. Obrigatório nos pedidos de informação e em ambos os callbacks.
Um pedido aos endpoints de informação ou de callback sem ambos os cabeçalhos devolve 400. Cada resposta da Didit inclui api-version: 3.2.1 e devolve o seu request-identifier.

​
GET /identity

Devolve a identidade do operador da plataforma. Não são necessários cabeçalhos.

​
GET /trp/identity//

Devolve a identidade do VASP específico com o qual vai trocar informação - use-a para verificar o nome e o LEI antes de enviar dados pessoais. A Didit faz a mesma verificação no sentido inverso quando inicia a troca: se a identidade que o seu endpoint indica não corresponder ao LEI ou ao nome esperados, a troca é cancelada.
Devolve 404 quando o perfil não existe ou quando a sua configuração da Travel Rule está desativada.

​
POST /trp/inquiries//

Submeta um pedido de informação de transferência - atua como VASP ordenante e o cliente da Didit é o VASP beneficiário.
Neste canal os ativos são identificados por DTI, e um DTI identifica um token numa única blockchain. Atualmente, a Didit mapeia BTC (4H95J0R2X), ETH (X9J9K872S) e USDC em nove redes, e outros ativos serão acrescentados ao longo do tempo. Consulte identificadores de ativos TRP para a lista completa. Um pedido de informação cujo DTI a Didit não reconhece é aceite e apresentado ao VASP beneficiário com o DTI como código do ativo. Uma resposta 200 significa que o pedido de informação foi aceite para processamento; 400 significa cabeçalhos TRP em falta ou um corpo inválido; 404 significa que o perfil (ou a carteira de um Travel Address por carteira) é desconhecido ou está desativado; e 422 significa que o pedido usa uma extensão TRP: a Didit não suporta nenhuma, pelo que um cabeçalho api-extensions ou uma chave extensions no corpo são recusados. Reenviar o mesmo request-identifier é idempotente - o pedido de informação original é reutilizado em vez de ser duplicado. A Didit cria então a transferência de entrada na aplicação do cliente e resolve-a face à lista de endereços de carteira e à política do cliente. O beneficiário é associado pela carteira indicada num Travel Address por carteira; caso contrário, pelo primeiro endereço de carteira em IVMS101.beneficiary.accountNumber; ou, na ausência de um endereço de carteira, pelo nome em beneficiaryPersons[0].naturalPerson face às carteiras verificadas do cliente. A resposta 200 contém a decisão quando a Didit a pode dar de imediato:
  • {"approved": {"address": "...", "callback": "..."}} quando o pedido de informação foi aprovado automaticamente. A Didit não envia essa aprovação também para o seu callback.
  • {"rejected": "NOT_ENOUGH_COUNTERPARTY_DATA: inquiry carries no beneficiary identification"} quando o pedido de informação não indica nem o beneficiário nem um endereço de carteira, por isso inclua sempre os dois.
  • {"version": "3.2.1"} quando a decisão aguarda o cliente da Didit. A resolução chega depois, como um POST para o seu URL de callback, com um dos dois corpos abaixo.
A aprovação pode ser automática - quando o VASP beneficiário ativa a aceitação automática e o beneficiário corresponde a uma carteira verificada na cadeia do ativo - ou pode seguir uma revisão manual ou uma prova de propriedade da carteira do lado do beneficiário, por isso conte com um atraso entre o pedido de informação e a resolução. Um pedido de informação nunca corresponde a uma carteira que o cliente da Didit registou como pertencente a outro VASP, e o nome do seu VASP em originatingVASP é o que o cliente da Didit vê como VASP ordenante da transferência. A Didit não define um prazo para um pedido de informação que envia, e um cliente da Didit que o cancele não lhe envia qualquer rejeição, por isso aplique o seu próprio tempo limite. Depois de receber uma aprovação e de transmitir a transferência na blockchain, conclua a troca enviando um POST para o URL approved.callback que lhe foi dado:
Se abortar a transferência, envie em vez disso { "canceled": "reason" } para o mesmo URL. txid passa a transferência do lado do beneficiário para FINISHED; canceled passa-a para CANCELLED. Ambos os callbacks respondem 204 depois de processados, 404 para um token desconhecido ou para uma transferência que já não aguarda esse callback, e 400 para um corpo que não contém nenhum dos dois campos do callback.

​
Resolver os pedidos que a Didit lhe envia

Quando um cliente da Didit inicia uma transferência para si através do TRP, a Didit:
  1. Obtém /identity na raiz do host do seu URL de pedido (https://{your-host}/identity) e verifica o nome e o LEI indicados face ao que o cliente espera. Quando a rota veio do diretório da Didit, o seu /identity tem de indicar o LEI dessa entrada do diretório.
  2. Envia um POST de um pedido de transferência para o seu URL de pedido, com a mesma estrutura de corpo indicada acima - asset.dti, um amount em unidades base como número JSON, um callback e o payload IVMS101.
Só uma resposta 2xx é considerada entregue. Uma resposta 3xx é recusada, porque os redirecionamentos não são seguidos, e qualquer outra resposta fica registada no histórico de transferências do cliente com o seu código de estado, por exemplo refused by counterparty (HTTP 403): .... Ambos os pedidos incluem os dois cabeçalhos TRP, e a Didit não segue redirecionamentos HTTP nestes pedidos; por isso, sirva /identity e o URL de pedido diretamente. Se /identity estiver inacessível, não indicar nenhum LEI ou indicar um LEI diferente quando o cliente o tiver fornecido, ou indicar um nome que não corresponde, a Didit interrompe o envio antes de enviar o pedido e a transferência do cliente passa para COUNTERPARTY_VASP_NOT_REACHABLE. Se o POST do pedido falhar a seguir, ou se o seu endpoint responder com um estado 4xx ou 5xx, a transferência também passa para COUNTERPARTY_VASP_NOT_REACHABLE. O callback desse pedido aponta para o endpoint de resolução da Didit (/trp/callbacks/resolution/{token}/). Responda enviando por POST os mesmos corpos de pedido de resolução que a Didit utiliza: { "approved": { "address": "...", "callback": "..." } } para aprovar (o seu callback é o URL para onde a Didit enviará a confirmação on-chain), ou { "rejected": "reason" } para recusar. Envie com ele os dois cabeçalhos TRP. A Didit responde com 204 depois de tratar o pedido, com 404 quando a transferência já não está a aguardar resolução e com 400 para uma aprovação sem address ou cujo callback não seja um URL http(s) público que a Didit possa chamar. Com a aprovação, o lado da Didit passa para COMPLETED; quando o cliente indicar o hash on-chain, a Didit envia por POST { "txid": "..." } para a URL de retorno de confirmação que forneceu (ou { "canceled": "reason" }, se a transferência for cancelada antes).
Os tokens de callback são segredos de finalidade única, impossíveis de adivinhar, gerados por transferência: trate os URLs de retorno completos como confidenciais, e tenha em atenção que uma resolução só é aceite enquanto a transferência ainda estiver a aguardar uma resolução.

​
Recolha por e-mail

Se nenhum canal de protocolo lhe chegar e o cliente da Didit tiver fornecido o seu e-mail de conformidade, a Didit recorre ao e-mail: o seu contacto de conformidade recebe uma mensagem que identifica a VASP ordenante, com uma ligação segura de recolha de utilização única. Não é necessária qualquer conta, chave de API ou integração - o token da ligação é a autenticação. Ao abrir a ligação, é apresentada a troca pendente; a API subjacente (que a página alojada aciona em seu nome) é pública:
O amount é o decimal armazenado tal como está, pelo que inclui as 18 casas decimais completas.
O decision é accept ou decline; ao aceitar, indique o nome do beneficiário tal como consta dos seus registos, para que o lado ordenante possa executar a correspondência de nomes, ou envie a sua resposta IVMS 101 completa como ivms_response, caso em que o nome do beneficiário nela indicado prevalece. Ao recusar, pode indicar um decline_reason (data_mismatch, not_our_customer, wallet_not_hosted, sanctions, risk_appetite, jurisdiction, insufficient_data ou other) e um decline_detail com até 512 caracteres, obrigatório para other. Uma aceitação sem beneficiary_name fica registada como discrepância quando o remetente tiver fornecido um nome de beneficiário, a não ser que o remetente tenha a correspondência de nomes desativada. A resposta é o {"status": "..."} resultante: COMPLETED quando os nomes correspondem, COUNTERPARTY_MISMATCHED_DATA quando não correspondem, ou COUNTERPARTY_VASP_GENERAL_DECLINE após uma recusa. Pode responder uma única vez, enquanto a transferência estiver a aguardar a sua resposta: depois de responder, depois de a transferência ser cancelada ou depois do prazo de confirmação, ambos os endpoints devolvem 410, e um token desconhecido devolve 404. O pedido mostra os campos do ordenante que o remetente partilha e um ivms_request IVMS 101, no idioma da sua jurisdição, e são-lhe enviados lembretes 72, 24 e 6 horas antes do prazo, enquanto não tiver respondido.

​
Sunrise: transferências liquidadas antes do intercâmbio

Quando uma transferência chega à carteira de um cliente da Didit antes de ter ocorrido qualquer intercâmbio da Travel Rule - porque não existia nenhum canal partilhado na altura -, os dados podem ainda ser entregues depois da liquidação. Envie ao cliente da Didit (a sua contraparte beneficiária) o payload da Travel Rule através do seu canal habitual e peça-lhe que o registe; este chama POST /v3/travel-rule/inbound/ com a rede do depósito, o txid, o endereço da carteira, o montante, a moeda e os dados do seu ordenante. Inclua a identidade da sua VASP - nome, LEI e Travel Address - como originating_vasp nesse payload, para que o registo de transferências do cliente da Didit indique quem enviou o depósito. Esta informação fica nessa transferência e nunca cria nem altera a sua entrada do diretório. O LEI tem de ser um LEI válido de 20 caracteres e o Travel Address tem de ser válido, caso contrário o registo é rejeitado.

​
Entrar no diretório de VASPs da Didit

A Didit mantém um diretório de VASP que o encaminhamento de saída dos seus clientes consulta. As entradas provêm das seguintes fontes:
  • O registo provisório MiCA da ESMA dos prestadores de serviços de criptoativos, lido todas as semanas: o seu nome, LEI e Estado-Membro de origem, se estiver lá inscrito.
  • O diretório público da TRISA, lido todas as semanas: quem é, o seu país e a sua inscrição na TRISA.
  • O registo global de LEI, que preenche o seu LEI, outros nomes legais e país.
  • A atribuição por análise de blockchain, quando uma carteira de destino é associada ao seu serviço de câmbio ou de custódia: a Didit acrescenta ou associa a sua entrada e mantém o nome atribuído como alias.
  • A equipa da Didit, que faz a curadoria das entradas: identificadores de encaminhamento e registos em redes que verificou, contactos de conformidade, alias e marcas com as respetivas entidades.
O que um cliente da Didit comunica sobre si, como um originating_vasp num registo Sunrise ou uma Travel Address numa transferência, fica limitado a essa transferência do cliente e nunca altera a sua entrada. Os pedidos de transferência que envia a um cliente da Didit também não criam nem atualizam a sua entrada. A sua entrada encaminha uma transferência para si quando inclui um endpoint TRP verificado, um registo numa rede que o remetente pode usar, ou um contacto de conformidade para a alternativa por e-mail. Um endereço de conformidade num dos seus próprios domínios que responda a um pedido através da ligação de resposta torna-se um contacto que todos os clientes da Didit podem usar. Enquanto a sua entrada não tiver um encaminhamento, um cliente da Didit só o alcança com os campos que transmite em cada transferência: a sua Travel Address, o seu identificador de rede (counterparty_gtr_vasp_code, counterparty_trust_membership_id, counterparty_verifyvasp_id ou counterparty_sygna_vasp_code), ou o seu e-mail de conformidade (counterparty_vasp_email). Para ser alcançável hoje, partilhe a sua Travel Address, o seu identificador de rede ou o seu e-mail de conformidade com os clientes da Didit com quem trabalha.

​
Lista de verificação para VASPs contrapartes

  • Já usa o TRP: partilhe a sua Travel Address e o seu LEI com o cliente da Didit - as transferências BTC, ETH e USDC dele chegam como pedidos TRP padrão ao seu endpoint. Responda na sua resposta ao pedido: uma resposta posterior exige o host TRP público da Didit, que ainda não está disponível.
  • Está no GTR, no TRUST ou no VerifyVASP: partilhe o seu identificador de rede; as transferências chegam por essa rede quando o cliente da Didit tem a sua própria inscrição nela. A Didit lê a sua resposta GTR ou VerifyVASP a partir da rede, mas não uma resposta TRUST, por isso publique também um endpoint TRP quando uma troca por TRUST tiver de ser concluída. Redes Travel Rule explicam quando isso muda.
  • Está no Sygna Bridge: partilhe o seu código VASP da Sygna; quando o cliente da Didit tiver a sua própria inscrição na Sygna, a sua resposta de autorização conclui ou recusa a transferência assim que a Didit a ler por consulta periódica.
  • Ainda não tem um canal de protocolo: dê ao cliente da Didit um e-mail de conformidade monitorizado - receberá as ligações de recolha e poderá responder a partir da página alojada, sem qualquer integração.
  • Uma transferência já foi liquidada: entregue os dados através do registo Sunrise por intermédio do cliente da Didit.
  • Também quer enviar para VASPs da Didit: peça à sua contraparte o Travel Address que consta das definições de Travel Rule da Didit dessa contraparte e siga POST /trp/inquiries quando o host TRP público da Didit estiver disponível.

​
Próximos passos

Travel Rule

O produto para clientes: ciclo de vida, definições, redes e a API /v3/.

Widget de propriedade da carteira

Como são recolhidas as provas de propriedade do lado do beneficiário quando a carteira é autocustodiada.

Registo Sunrise

Registo de dados da Travel Rule para depósitos já liquidados on-chain.

Webhooks

Como os clientes da Didit acompanham cada transição da plataforma de câmbio do seu lado.
Última modificação em 7 de novembro de 2026