Fluxo de Biometria

Guie o cliente pela verificação de identidade, acompanhe o progresso e saiba como reagir a cada resultado.

Após cadastrar o cliente, dois processos acontecem em paralelo:

1. Análise de crédito — a Dinie começa automaticamente a avaliar o perfil de crédito da empresa.
2. Verificação KYC — o cliente precisa enviar documentos e completar a biometria no seu próprio ritmo.

Você não precisa esperar a análise de crédito terminar para iniciar a verificação. Assim que o cliente atingir o status pending_kyc, apresente a opção de iniciar a biometria.

Quando o webhook customer.created chegar (ou quando o status mudar para pending_kyc), apresente ao cliente a opção de iniciar a verificação. Você pode mostrar um botão explícito ou iniciar automaticamente.

O importante é comunicar ao cliente que ele precisa completar a verificação de identidade para receber ofertas de crédito.

Quando o cliente confirmar que quer iniciar, crie uma sessão de biometria:

const session = await client.customers.createBiometricsSession(customer.id);

// Abra esta URL em um webview ou redirecione o cliente
console.log(session.session_url);
console.log(session.expires_at); // Expira em 30 minutos

Abra a session_url em um webview (mobile) ou redirecione o navegador (web). A sessão expira em 30 minutos — se expirar, gere uma nova.

Tip: Se o parceiro já possui documentos do cliente, pode enviá-los via API antes de gerar a sessão. Documentos enviados antecipadamente já aparecerão como completos na sessão, acelerando o processo para o cliente. Veja Envio Antecipado via API.

Na sessão de biometria, o cliente verá a lista de documentos necessários. Documentos já enviados via API aparecem como completos. O cliente precisa completar os itens pendentes.

O fluxo na sessão inclui:

• Envio de documentos — fotos de identidade (CNH ou RG), comprovante de endereço, documentos da empresa
• Selfie — captura pelo próprio cliente via câmera do dispositivo
• Revisão — visualizar tudo que foi enviado antes de confirmar

Ao final, o cliente terá duas opções:

• Salvar para depois — o progresso é mantido, mas a análise não é disparada
• Enviar para análise — dispara a verificação de todos os documentos

Se o cliente escolher "Salvar para depois", ele retornará ao seu ambiente. Nenhuma análise é disparada nesse momento — o cliente pode voltar a qualquer momento para continuar.

Você pode acompanhar o progresso de duas formas:

Via webhook: receba o customer.kyc_updated sempre que um documento for enviado. O payload inclui o array kyc atualizado.

Via API: consulte o cliente e verifique o campo kyc:

const customer = await client.customers.get(customerId);

for (const req of customer.kyc) {
  const status = req.submitted ? "Enviado" : "Pendente";
  console.log(`${req.label}: ${status}`);
}

Mostre ao cliente o progresso da verificação — quais documentos já foram enviados e quais ainda faltam. Para retomar, basta gerar uma nova sessão de biometria. O progresso anterior é preservado.

Quando o cliente clicar "Enviar para análise" na sessão de biometria, a Dinie inicia a verificação de todos os documentos. Você receberá o webhook customer.under_review, e o status do cliente mudará para under_review.

app.post("/webhooks/dinie", express.raw({ type: "application/json" }), (req, res) => {
  const event = client.webhooks.unwrap(req.body.toString(), req.headers);

  if (event.type === "customer.under_review") {
    updateCustomerScreen(event.data.external_id, "Em análise");
  }

  res.sendStatus(200);
});

A partir daqui, a Dinie pode aprovar, negar ou solicitar correções em documentos específicos.

Se todos os documentos forem aprovados, o cliente recebe o status active e você recebe o webhook customer.active.

Isso não significa que já existem ofertas de crédito. A análise de crédito acontece em paralelo e pode levar mais tempo. A partir do momento que o cliente é active, a Dinie continua processando a análise de crédito.

Quando uma oferta estiver disponível, você receberá o webhook credit_offer.available:

app.post("/webhooks/dinie", express.raw({ type: "application/json" }), (req, res) => {
  const event = client.webhooks.unwrap(req.body.toString(), req.headers);

  if (event.type === "customer.active") {
    updateCustomerScreen(event.data.external_id, "Verificado");
  }

  if (event.type === "credit_offer.available") {
    const offers = await client.creditOffers.list(event.data.customer_id);
    notifyCustomer(event.data.external_id, offers);
  }

  res.sendStatus(200);
});

Info: Entre o customer.active e o credit_offer.available, mostre ao cliente uma mensagem como "Verificação concluída, estamos buscando as melhores ofertas para você". Isso transmite que o processo está avançando.

Se a Dinie identificar problemas em algum documento, você receberá o webhook customer.kyc_updated com os detalhes. Consulte o campo kyc para verificar quais documentos foram rejeitados:

const customer = await client.customers.get(customerId);

for (const req of customer.kyc) {
  if (req.submitted?.review_status === "rejected") {
    console.log(`${req.label}: Rejeitado — ${req.submitted.review_reason}`);
  }
}

Mostre ao cliente quais documentos precisam de correção e o motivo da rejeição. Você não precisa fazer nada diretamente na API — apenas apresente um botão para o cliente abrir a sessão de biometria novamente:

// Gere uma nova sessão para o cliente corrigir os documentos
const session = await client.customers.createBiometricsSession(customer.id);
redirectCustomer(session.session_url);

Na sessão, os documentos rejeitados aparecerão destacados com o motivo da rejeição. O cliente corrige, reenvia, e o ciclo se repete até que todos sejam aprovados.

Se o cliente for negado permanentemente, você receberá o webhook customer.denied. Isso indica que a Dinie não conseguiu aprovar o cliente na análise de KYC (por exemplo, fraude detectada ou empresa encerrada).

Neste caso, informe ao cliente que não é possível oferecer crédito neste momento. Diferente do cenário de aprovação sem ofertas (onde o cliente pode receber ofertas no futuro), o status denied é definitivo.

Warning: Não comunique ao cliente o motivo específico da negação. Informe apenas que não foi possível prosseguir com a análise neste momento.

• Cadastro e Ofertas para o fluxo completo de criação do cliente
• Requisitos de KYC para detalhes sobre tipos de documentos
• Simulação e Contratação para o passo seguinte após receber ofertas
• Webhooks para configurar os endpoints de notificação