KYC por redirecionamento: página de verificação hospedada

O método de redirecionamento envia os usuários para uma página hospedada pela Didit para a verificação e depois os redireciona de volta para a sua aplicação por meio de uma URL de retorno.

Recurso	Descrição
Tempo de configuração	5 minutos
Backend necessário	✅ Sim (para criar sessões)
Permanece no seu domínio	❌ Não (redireciona para verify.didit.me ou para o seu domínio personalizado com sua marca)
Suporte entre dispositivos	✅ Sim
Compatibilidade com navegadores	✅ Todos os navegadores

Quando usar o redirecionamento

Verificação entre dispositivos: comece no desktop e conclua no celular
Compatibilidade máxima: funciona em todos os navegadores, inclusive nos mais antigos
Integração simples: não exige configuração de iframe
Problemas com a câmera: quando o acesso à câmera dentro do iframe é problemático

Implementação

Etapa 1: criar uma sessão (backend)

A resposta da criação de sessão usa um campo chamado url. Repasse esse valor para o navegador.

// Node.js / Express
app.post('/api/create-verification', async (req, res) => {
  const { userId } = req.body;

  const response = await fetch('https://verification.didit.me/v3/session/', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.DIDIT_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      workflow_id: process.env.DIDIT_WORKFLOW_ID,
      vendor_data: userId,
      callback: 'https://yourapp.com/verification-complete',
      callback_method: 'both', // most reliable across desktop ↔ mobile handoffs
    }),
  });

  if (!response.ok) {
    return res.status(response.status).send(await response.text());
  }

  const session = await response.json();
  // 201 per OpenAPI: { session_id, session_number, session_token, url, vendor_data,
  //                    metadata, status, workflow_id, workflow_version, callback }
  res.json({ sessionId: session.session_id, verificationUrl: session.url });
});

Etapa 2: redirecionar o usuário (frontend)

HTML:

<button onclick="startVerification()">Verify Identity</button>

<script>
  async function startVerification() {
    const response = await fetch('/api/create-verification', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ userId: 'user-123' })
    });
    
    const { verificationUrl } = await response.json();
    window.location.href = verificationUrl;
  }
</script>

React:

function VerifyButton() {
  const [loading, setLoading] = useState(false);

  const startVerification = async () => {
    setLoading(true);
    
    const response = await fetch('/api/create-verification', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ userId: 'user-123' })
    });
    
    const { verificationUrl } = await response.json();
    window.location.assign(verificationUrl);
  };

  return (
    <button onClick={startVerification} disabled={loading}>
      {loading ? 'Loading...' : 'Verify Identity'}
    </button>
  );
}

Vue:

<template>
  <button @click="startVerification" :disabled="loading">
    {{ loading ? 'Loading...' : 'Verify Identity' }}
  </button>
</template>

<script setup>
import { ref } from 'vue';

const loading = ref(false);

async function startVerification() {
  loading.value = true;
  
  const response = await fetch('/api/create-verification', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ userId: 'user-123' })
  });
  
  const { verificationUrl } = await response.json();
  window.location.href = verificationUrl;
}
</script>

Como lidar com o retorno

Quando a verificação é concluída, a Didit redireciona para a sua URL de retorno com parâmetros de consulta:

https://yourapp.com/verification-complete?verificationSessionId=abc123&status=Approved

Parâmetro	Descrição
`verificationSessionId`	Identificador único da sessão
`status`	O status atual da sessão, por exemplo `Approved`, `Declined`, `In Review` ou `Expired`. Consulte os status de verificação

Exemplo com Next.js

// pages/verification-complete.tsx
import { useRouter } from 'next/router';
import { useEffect, useState } from 'react';

export default function VerificationComplete() {
  const router = useRouter();
  const { verificationSessionId, status } = router.query;
  const [message, setMessage] = useState('Processing...');

  useEffect(() => {
    if (!router.isReady) return;

    async function handleResult() {
      // Optionally verify the result with your backend
      await fetch('/api/verify-session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ 
          sessionId: verificationSessionId, 
          status 
        })
      });

      // Redirect based on status
      switch (status) {
        case 'Approved':
          setMessage('Verification successful! Redirecting...');
          setTimeout(() => router.push('/dashboard'), 2000);
          break;
        case 'Declined':
          setMessage('Verification was not successful.');
          setTimeout(() => router.push('/verification-failed'), 2000);
          break;
        case 'In Review':
          setMessage('Your verification is under review.');
          setTimeout(() => router.push('/verification-pending'), 2000);
          break;
        default:
          setMessage('Unknown status. Please contact support.');
      }
    }

    handleResult();
  }, [router.isReady, verificationSessionId, status]);

  return (
    <div className="flex flex-col items-center justify-center min-h-screen">
      <div className="animate-spin w-8 h-8 border-4 border-blue-500 border-t-transparent rounded-full mb-4" />
      <p className="text-lg">{message}</p>
    </div>
  );
}

Exemplo com Express.js

// routes/verification.js
app.get('/verification-complete', async (req, res) => {
  const { verificationSessionId, status } = req.query;
  
  // Optionally verify with Didit API
  // const session = await diditApi.getSession(verificationSessionId);
  
  // Update your database
  await db.users.update({
    where: { verificationSessionId },
    data: { verificationStatus: status }
  });
  
  // Redirect based on status
  switch (status) {
    case 'Approved':
      res.redirect('/dashboard?verified=true');
      break;
    case 'Declined':
      res.redirect('/verification-failed');
      break;
    case 'In Review':
      res.redirect('/verification-pending');
      break;
    default:
      res.redirect('/error');
  }
});

Exemplo com Vue Router

// router/index.ts
{
  path: '/verification-complete',
  component: () => import('@/views/VerificationComplete.vue'),
  beforeEnter: async (to, from, next) => {
    const { verificationSessionId, status } = to.query;
    
    // Store result and redirect
    await store.dispatch('verification/handleResult', { 
      sessionId: verificationSessionId, 
      status 
    });
    
    if (status === 'Approved') {
      next('/dashboard');
    } else if (status === 'Declined') {
      next('/verification-failed');
    } else {
      next('/verification-pending');
    }
  }
}

Abrir em uma nova aba

Se você preferir manter sua aplicação aberta enquanto o usuário faz a verificação:

// Open in new tab
window.open(verificationUrl, '_blank');

// Poll for completion or use webhooks

Ao usar novas abas, use webhooks em conjunto para saber quando a verificação for concluída.

Boas práticas de segurança

Verifique o retorno no servidor

Trate os parâmetros de consulta verificationSessionId e status como indicadores não confiáveis da interface. Sempre confirme a decisão final no seu backend, seja tratando o webhook (preferível), seja consultando novamente a decisão pela API:

// Backend: re-fetch the canonical decision before granting access
app.get('/verification-complete', async (req, res) => {
  const { verificationSessionId } = req.query;

  const response = await fetch(
    `https://verification.didit.me/v3/session/${verificationSessionId}/decision/`,
    {
      headers: { 'x-api-key': process.env.DIDIT_API_KEY },
    }
  );

  if (!response.ok) {
    return res.status(response.status).send(await response.text());
  }

  const decision = await response.json();

  // decision.status uses the canonical enum:
  // Not Started | In Progress | Awaiting User | In Review | Approved |
  // Declined   | Resubmitted | Expired | Kyc Expired | Abandoned
  if (decision.status === 'Approved') {
    // Grant access. Per-feature reports are plural arrays:
    //   decision.id_verifications[], decision.face_matches[], decision.aml_screenings[], ...
  }

  res.redirect('/dashboard');
});

Use webhooks

Para a integração mais confiável, use webhooks para receber os resultados da verificação diretamente no seu backend, independentemente de como o navegador do usuário se comporta.

Fluxo entre dispositivos

O método de redirecionamento oferece suporte nativo à verificação entre dispositivos:

O usuário clica em “Verificar” no desktop
O usuário é redirecionado para a página de verificação
Se necessário, o usuário pode escanear um QR code para continuar no celular
Após a conclusão, o usuário é redirecionado para a sua URL de retorno. O dispositivo que faz o redirecionamento é determinado por callback_method (initiator, completer ou both)

Solução de problemas

Retorno não recebido

Verifique se a URL de retorno foi definida corretamente ao criar a sessão
Garanta que a sua URL de retorno esteja acessível pela internet
Confira se a URL não tem erros de digitação ou problemas de codificação

Status sempre “Declined”

Verifique as configurações do seu fluxo de verificação (workflow) no Didit Console
Confirme que os documentos de teste que você está usando são válidos
Analise os detalhes da sessão pela API para ver os motivos específicos da recusa

Loop de redirecionamento

Garanta que o seu handler de retorno não redirecione de volta para a verificação
Verifique se há problemas de cache na sua página de retorno
Limpe o cache do navegador e tente novamente

Repositório de exemplo

Repositório no GitHub

Veja o código-fonte e exemplos no GitHub

Guias

Autenticação

Model Context Protocol (MCP)

SDKs web

SDKs nativos

SDKs de servidor

Integrações

KYC por redirecionamento: página de verificação hospedada

Quando usar o redirecionamento

Implementação

Etapa 1: criar uma sessão (backend)

Etapa 2: redirecionar o usuário (frontend)

Como lidar com o retorno

Exemplo com Next.js

Exemplo com Express.js

Exemplo com Vue Router

Abrir em uma nova aba

Boas práticas de segurança

Verifique o retorno no servidor

Use webhooks

Fluxo entre dispositivos

Solução de problemas

Retorno não recebido

Status sempre “Declined”

Loop de redirecionamento

Repositório de exemplo

Repositório no GitHub

​Quando usar o redirecionamento

​Implementação

​Etapa 1: criar uma sessão (backend)

​Etapa 2: redirecionar o usuário (frontend)

​Como lidar com o retorno

​Exemplo com Next.js

​Exemplo com Express.js

​Exemplo com Vue Router

​Abrir em uma nova aba

​Boas práticas de segurança

​Verifique o retorno no servidor

​Use webhooks

​Fluxo entre dispositivos

​Solução de problemas

​Retorno não recebido

​Status sempre “Declined”

​Loop de redirecionamento

​Repositório de exemplo

Repositório no GitHub

Quando usar o redirecionamento

Implementação

Etapa 1: criar uma sessão (backend)

Etapa 2: redirecionar o usuário (frontend)

Como lidar com o retorno

Exemplo com Next.js

Exemplo com Express.js

Exemplo com Vue Router

Abrir em uma nova aba

Boas práticas de segurança

Verifique o retorno no servidor

Use webhooks

Fluxo entre dispositivos

Solução de problemas

Retorno não recebido

Status sempre “Declined”

Loop de redirecionamento

Repositório de exemplo