Integração de monitoramento de transações: API KYT

Este guia cobre todos os aspectos da integração do Monitoramento de transações. O guia de início rápido permite que você comece a usar; esta página prepara você para produção.

Arquitetura

Autenticação

Cabeçalho padrão x-api-key. São as mesmas chaves usadas para sessões e entidades. Consulte autenticação da API.

Envio de uma transação

Um único endpoint: POST /v3/transactions/. Consulte envio de transações para ver o esquema completo. Payload mínimo:

{
  "transaction_id": "tx-0001",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "500.00",
    "currency": "EUR"
  },
  "subject": { "entity_type": "person", "vendor_data": "user-42", "full_name": "John Doe" },
  "counterparty": { "entity_type": "company", "full_name": "Acme Corp" }
}

Payload mais completo, com métodos de pagamento, contexto de dispositivo e propriedades personalizadas:

{
  "transaction_id": "tx-0002",
  "transaction_at": "2026-04-16T10:00:00Z",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "12500.00",
    "currency": "USD",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "person",
    "vendor_data": "user-42",
    "full_name": "John Doe",
    "country_code": "US",
    "device_context": {
      "fingerprint": "fp-9f2c...",
      "user_agent": "Mozilla/5.0 ...",
      "browser_family": "Chrome",
      "platform": "web",
      "network_context": { "ip_address": "203.0.113.5" }
    },
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US12345678901234567890",
      "issuing_country": "US"
    }
  },
  "counterparty": {
    "entity_type": "company",
    "vendor_data": "biz-acme",
    "full_name": "Acme Corp",
    "country_code": "US",
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US09876543210987654321",
      "issuing_country": "US"
    }
  },
  "custom_properties": {
    "invoice_id": "INV-2026-00042",
    "category": "b2b_goods"
  }
}

Aliases em camelCase são aceitos para todos os campos de nível superior (txnId, txnDate, type, info, applicant, props, travelRule, includeCryptoScreening): o formato de transmissão do SDK e o formato snake_case são processados da mesma forma.

Modelagem das partes

Toda transação tem um subject obrigatório (seu cliente, a parte que você monitora) e uma counterparty opcional (o outro lado). Cada uma tem seu próprio payment_method e um contexto de device opcional. Na resposta, elas voltam no array parties com as funções APPLICANT e COUNTERPARTY. Uma parte sem vendor_data é armazenada como um snapshot externo (kind: EXTERNAL), sem entidade vinculada. Consulte payload de transações para ver os campos das partes.

Idempotência

txn_id (o transaction_id que você envia) é único por aplicação. Reenviar um transaction_id que já existe retorna 400 com A transaction with this transaction_id already exists. no campo transaction_id. Quando duas requisições idênticas concorrem entre si, a segunda recebe 409. Nenhuma das duas respostas retorna a transação existente. Diante de um 400 ou 409 por transaction_id duplicado, consulte a transação existente em vez de reenviá-la: leia-a com GET /v3/transactions/{uuid}/ usando o uuid da primeira resposta, ou use o transaction_id (o uuid da Didit) que o webhook transaction.created traz junto com o seu txn_id. Sempre gere o txn_id do seu lado antes de enviar; não dependa de um ID gerado pela Didit para a idempotência. Use o ID do seu próprio banco de dados, um UUID ou um hash dos campos da transação.

Tempo real vs. lote

Tempo real: recomendado para a maioria dos casos de uso. Envie a transação no momento em que ela acontece no seu sistema. As regras são avaliadas de forma síncrona e retornam a decisão.
Lote / carga retroativa: para ingestão de histórico, informe um txn_date no passado. As regras continuam sendo executadas e podem disparar webhooks. Para evitar que as regras sejam acionadas na carga retroativa, use a importação de CSV do console com a opção “dry ingest”.

Ingestão de histórico

Quando você estiver migrando de outro sistema de monitoramento de transações:

Exporte suas transações históricas para um CSV.
Use Transactions → Import history na console (ou envie pela API em um loop) com txn_date no passado.
Ative as regras somente depois que a ingestão terminar, ou use o dry ingest para pular a avaliação de regras.

Pense bem antes de avaliar regras sobre o histórico. Passar 6 meses de histórico por uma regra de “20 transferências em 30 dias” vai gerar milhares de alertas de uma só vez.

Webhooks

Inscreva-se em:

transaction.created: toda transação enviada.
transaction.status.updated: mudanças de status (por exemplo, um analista muda de IN_REVIEW para APPROVED, ou uma verificação AML assíncrona atualiza a pontuação).

Detalhes completos: webhooks de TM.

app.post('/webhooks/didit-tm', (req, res) => {
  if (!verifySignature(req)) return res.status(401).end();

  const { webhook_type, status, txn_id } = req.body;
  if (webhook_type === 'transaction.status.updated' && status === 'DECLINED') {
    suspendTransaction(txn_id);
  }
  res.status(200).end();
});

Tratamento dos status

Status	O que fazer
`APPROVED`	Processe a transação normalmente.
`IN_REVIEW`	Retenha a transação até que a revisão do analista ou uma nova verificação automática seja concluída.
`DECLINED`	Rejeite a transação. Mostre um erro genérico ao usuário.
`AWAITING_USER`	O usuário precisa agir antes que a transação possa ser liquidada: leia o bloco `action_required` e forneça a `url` ao usuário (os SDKs podem cuidar disso automaticamente).

Consulte status de TM.

Vinculação de transações a entidades

Informe vendor_data para cada parte. Benefícios:

Todas as transações são agregadas ao perfil do usuário ou da empresa.
As regras de velocidade e de comportamento têm acesso ao histórico completo para avaliação.
O bloqueio de uma entidade se propaga automaticamente para as transações futuras.

A ausência de vendor_data não é um erro bloqueante (a transação é armazenada como um snapshot externo), mas você perde a agregação no nível da entidade.

Sessões de remediação

Quando a ação de uma regra move uma transação para AWAITING_USER, a Didit cria automaticamente uma sessão de remediação: uma sessão de verificação hospedada padrão para o mesmo vendor_data. Regras personalizadas sempre indicam o fluxo de verificação (workflow) na própria ação. Para regras da biblioteca integrada, o fluxo usado é, primeiro, o fluxo de remediação nas configurações de transações, depois o fluxo de Autenticação biométrica da sua aplicação (quando o titular tem um rosto de referência armazenado) e, por fim, o fluxo padrão da sua aplicação. Transações de Travel Rule ficam fora dessa fallback automático, pois a ação pendente delas é a comprovação de propriedade da carteira. A transação (na resposta, em toda leitura posterior e em todo webhook) traz essa sessão no bloco canônico action_required:

{
  "status": "AWAITING_USER",
  "action_required": {
    "type": "verification_session",
    "url": "https://verify.didit.me/session/...",
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "status": "Not Started"
  },
  "remediation": {
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "url": "https://verify.didit.me/session/...",
    "status": "Not Started"
  }
}

remediation é mantido por compatibilidade com versões anteriores. action_required é o bloco canônico (ele também traz ações wallet_ownership para transferências de Travel Rule). Uma ação wallet_ownership não altera o status da transação por si só: a transação mantém o status que suas regras atribuírem, muitas vezes APPROVED. Por isso, verifique action_required em toda resposta, e não apenas em AWAITING_USER. O usuário conclui a verificação. Em um fluxo de Autenticação biométrica, isso é uma selfie com prova de vida comparada ao rosto capturado no onboarding de KYC original, a verificação adicional mais forte para transações de alto valor. Quando a sessão chega a uma decisão, a transação a segue automaticamente: APPROVED (decision_reason_code: user_action_approved), DECLINED (user_action_declined) ou IN_REVIEW (user_action_in_review), e um webhook transaction.status.updated é disparado.

É possível selecionar qualquer tipo de fluxo, exceto KYB. Fluxos de Autenticação biométrica (e fluxos em que a correspondência facial é executada antes da verificação de identidade) exigem que o titular já tenha um rosto de referência armazenado obtido em uma verificação aprovada. Usuários sem esse rosto são enviados para o fluxo padrão da sua aplicação, e uma nota na transação registra a substituição.

Boas práticas

Prática	Motivo
Sempre envie `vendor_data`	Permite a agregação.
Use seu próprio `txn_id`	Idempotência.
Assine `transaction.created` e `transaction.status.updated`	Captura mudanças de estado assíncronas (por exemplo, resultados da revisão de analistas).
Defina os limiares das regras de forma deliberada	Limiares baixos = mais alertas; altos = mais riscos não detectados. Veja pontuação de risco.
Acompanhe no console quantas vezes cada regra é executada	Identifica regras que nunca disparam (mal configuradas) ou que disparam em tudo (permissivas demais).
Teste as regras no modo TEST antes de ir para produção	Veja regras.

Limites de requisições

Veja limite de requisições. A criação de transações é um dos endpoints de maior vazão; os limites típicos ficam na casa das centenas de requisições por segundo. Envie rajadas de requisições com cautela.

Próximos passos

Transações

Referência completa do payload.

Regras

Como as regras são avaliadas.

Webhooks

Catálogo de eventos.

Solução de problemas

Problemas comuns de integração.

Primeiros passos

Recursos

Referência

Console

Integração de monitoramento de transações: API KYT

Arquitetura

Autenticação

Envio de uma transação

Modelagem das partes

Idempotência

Tempo real vs. lote

Ingestão de histórico

Webhooks

Tratamento dos status

Vinculação de transações a entidades

Sessões de remediação

Boas práticas

Limites de requisições

Próximos passos

Transações

Regras

Webhooks

Solução de problemas

​Arquitetura

​Autenticação

​Envio de uma transação

​Modelagem das partes

​Idempotência

​Tempo real vs. lote

​Ingestão de histórico

​Webhooks

​Tratamento dos status

​Vinculação de transações a entidades

​Sessões de remediação

​Boas práticas

​Limites de requisições

​Próximos passos

Transações

Regras

Webhooks

Solução de problemas

Arquitetura

Autenticação

Envio de uma transação

Modelagem das partes

Idempotência

Tempo real vs. lote

Ingestão de histórico

Webhooks

Tratamento dos status

Vinculação de transações a entidades

Sessões de remediação

Boas práticas

Limites de requisições

Próximos passos