Guia rápido de KYB: verificação de empresas em 10 minutos

Este guia leva você por uma verificação KYB completa em menos de 10 minutos. Você vai criar um fluxo (workflow), iniciar uma sessão, entregar o link de verificação hospedado ao contato da empresa, aguardar o webhook e obter a decisão final.

Pré-requisitos

Uma aplicação da Didit com o KYB ativado. Crie uma em business.didit.me, se necessário.
Uma chave de API em Developer Settings → Chaves de API.
Um endpoint de webhook acessível pela internet (para o webhook de decisão).

Passos

Crie um fluxo de KYB no console

Acesse Fluxos de trabalho → Criar fluxo de trabalho. Escolha Verificação de empresas como o tipo de fluxo.Ative os recursos de que você precisa:

Consulta ao registro da empresa (obrigatório)
AML da empresa (recomendado)
Pessoas-chave (obrigatório na maioria dos setores regulados)
Documentos (opcional - escolha os tipos de documento que você vai exigir)

Salve e copie o workflow_id - você vai usá-lo no próximo passo.

Crie uma sessão de Verificação de empresas (KYB) pela API

curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "YOUR_KYB_WORKFLOW_ID",
    "vendor_data": "biz-acme-001"
  }'

A resposta contém o session_id, o session_number e a url - o link de verificação hospedado que você entrega ao contato da empresa. O tipo do fluxo (KYB) marca automaticamente a sessão como uma sessão de empresa.

Envie o link ao contato da empresa

Entregue a url ao administrador da empresa pelo seu próprio e-mail ou chat. Ele a abre, preenche os dados do registro, adiciona as pessoas-chave e os UBOs e envia os documentos.Você pode personalizar a experiência hospedada com marca, logotipo e domínio - veja Marca própria.

Receba o webhook de status

Quando a empresa conclui o fluxo e o processamento do KYB chega a um status final, a Didit envia um evento status.updated por POST ao seu endpoint de webhook. Os eventos de sessões de empresa trazem session_kind: "business" dentro de data - filtre por esse campo para encaminhar o evento ao seu tratador de KYB.Verifique a assinatura HMAC X-Signature-V2 antes de confiar no evento (veja webhooks) e depois acione a sua lógica posterior. Guarde o secret_shared_key do destino (retornado quando você registra o webhook) como DIDIT_WEBHOOK_SECRET no seu .env.Exemplo de payload:

{
  "event": "status.updated",
  "application_id": "app_abc123",
  "timestamp": "2026-04-18T12:30:00Z",
  "data": {
    "session_id": "bs_01H...",
    "session_kind": "business",
    "vendor_data": "biz-acme-001",
    "status": "APPROVED",
    "previous_status": "IN_PROGRESS"
  }
}

Obtenha a decisão (opcional)

O payload do webhook status.updated já contém a decisão completa. Você só precisa chamar este endpoint se não assinou os webhooks ou se quer buscar a decisão sob demanda mais tarde.

curl https://verification.didit.me/v3/session/bs_01H.../decision/ \
  -H "x-api-key: YOUR_API_KEY"

A decisão inclui os dados do registro, as pessoas-chave (UBOs, acionistas, diretores e representantes), as ocorrências de AML, os documentos e os resultados por recurso. Veja o esquema de resposta para a referência completa do payload.

Aja de acordo com a decisão

Com base em status:

APPROVED - faça o onboarding da empresa.
DECLINED - rejeite e registre o código do motivo.
IN_REVIEW - aguarde a decisão do analista; você receberá outro webhook quando ela for resolvida.

Exemplo em Node.js

import fetch from 'node-fetch';

const API_KEY = process.env.DIDIT_API_KEY!;
const WORKFLOW_ID = process.env.DIDIT_KYB_WORKFLOW_ID!;
const BASE_URL = 'https://verification.didit.me';

async function startKybVerification(vendorData: string) {
  const res = await fetch(`${BASE_URL}/v3/session/`, {
    method: 'POST',
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ workflow_id: WORKFLOW_ID, vendor_data: vendorData }),
  });
  if (!res.ok) throw new Error(`Session create failed: ${res.status}`);
  return res.json();
}

async function getDecision(sessionId: string) {
  const res = await fetch(`${BASE_URL}/v3/session/${sessionId}/decision/`, {
    headers: { 'x-api-key': API_KEY },
  });
  return res.json();
}

// Kick off the flow
const { session_id, url } = await startKybVerification('biz-acme-001');
console.log('Deliver this URL to your contact:', url);

// ... later, after the webhook confirms completion:
const decision = await getDecision(session_id);
console.log('KYB status:', decision.status);

O que acontece automaticamente

Consulta ao registro da empresa em 190+ jurisdições.
Extração de UBOs e administradores a partir dos dados do registro.
Triagem de AML no nível da empresa (sanções, PEPs, mídia negativa).
AML no nível da pessoa para cada parte identificada.
OCR de documentos e verificação cruzada.
Criação e agregação de perfis de empresa com base em vendor_data.

Próximos passos

Guia de integração

Arquitetura de ponta a ponta, polling versus webhooks, lógica de novas tentativas.

Webhooks de KYB

Todos os eventos de KYB e o formato de cada payload.

Status

Referência de status de sessão, de recurso e de registro.

Esquema de resposta

O payload completo da decisão de KYB.

Entidades empresariais

Como os perfis são agregados entre sessões.

​Pré-requisitos

​Passos

​Exemplo em Node.js

​O que acontece automaticamente

​Próximos passos

Guia de integração

Webhooks de KYB

Status

Esquema de resposta

Entidades empresariais

Pré-requisitos

Passos

Exemplo em Node.js

O que acontece automaticamente

Próximos passos