Verificação KYC por redirecionamento web: página alojada

O método de redirecionamento envia os utilizadores para uma página de verificação alojada pela Didit e, depois, devolve-os à sua aplicação através de um URL de retorno.

Funcionalidade	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 de marca branca)
Suporte entre dispositivos	✅ Sim
Compatibilidade com navegadores	✅ Todos os navegadores

Quando usar o redirecionamento

Verificação entre dispositivos: iniciar no computador e concluir no telemóvel
Máxima compatibilidade: funciona em todos os navegadores, incluindo os mais antigos
Integração simples: não é necessária nenhuma configuração de iframe
Problemas com a câmara: quando o acesso à câmara num iframe é problemático

Implementação

Passo 1: Criar uma sessão (servidor)

A resposta da criação de sessão usa um campo chamado url: passe esse valor ao 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 });
});

Passo 2: Redirecionar o utilizador (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>

Tratar o retorno

Quando a verificação é concluída, a Didit redireciona para o seu 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 estado atual da sessão, por exemplo `Approved`, `Declined`, `In Review` ou `Expired`. Consulte os estados 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 num novo separador

Se preferir manter a sua aplicação aberta enquanto o utilizador verifica:

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

// Poll for completion or use webhooks

Ao usar novos separadores, combine com webhooks para saber quando a verificação é concluída.

Boas práticas de segurança

Verifique o retorno no servidor

Trate os parâmetros de consulta verificationSessionId e status como indicações de interface não fiáveis. Confirme sempre a decisão final no seu servidor, seja tratando o webhook (preferível), seja voltando a obter a decisão através da 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');
});

Utilizar webhooks

Para a integração mais fiável, use webhooks para receber os resultados da verificação diretamente no seu servidor, independentemente do comportamento do navegador do utilizador.

Fluxo entre dispositivos

O método de redirecionamento suporta naturalmente a verificação entre dispositivos:

O utilizador clica em “Verificar” no computador
O utilizador é redirecionado para a página de verificação
Se necessário, o utilizador pode ler o código QR para continuar no telemóvel
Após a conclusão, o utilizador é redirecionado para o seu URL de retorno. O dispositivo que redireciona é controlado por callback_method (initiator, completer ou both)

Resolução de problemas

Retorno não recebido

Verifique se o URL de retorno está corretamente definido ao criar a sessão
Certifique-se de que o seu URL de retorno está acessível a partir da internet
Verifique se o URL não tem erros de digitação ou problemas de codificação

Estado sempre “Declined”

Verifique as definições do seu fluxo na Didit Console
Verifique se os documentos de teste que está a usar são válidos
Reveja os detalhes da sessão através da API para ver os motivos específicos da recusa

Ciclo de redirecionamento

Certifique-se de que o seu gestor de retorno não volta a redirecionar para a verificação
Verifique se existem problemas de cache na sua página de retorno
Limpe a cache do navegador e tente novamente

Repositório de exemplos

Repositório no GitHub

Consulte o código-fonte e os exemplos no GitHub

Guias

Autenticação

Model Context Protocol (MCP)

SDKs web

SDKs nativos

SDKs de servidor

Integrações

Verificação KYC por redirecionamento web: página alojada

Quando usar o redirecionamento

Implementação

Passo 1: Criar uma sessão (servidor)

Passo 2: Redirecionar o utilizador (frontend)

Tratar o retorno

Exemplo com Next.js

Exemplo com Express.js

Exemplo com Vue Router

Abrir num novo separador

Boas práticas de segurança

Verifique o retorno no servidor

Utilizar webhooks

Fluxo entre dispositivos

Resolução de problemas

Retorno não recebido

Estado sempre “Declined”

Ciclo de redirecionamento

Repositório de exemplos

Repositório no GitHub

​Quando usar o redirecionamento

​Implementação

​Passo 1: Criar uma sessão (servidor)

​Passo 2: Redirecionar o utilizador (frontend)

​Tratar o retorno

​Exemplo com Next.js

​Exemplo com Express.js

​Exemplo com Vue Router

​Abrir num novo separador

​Boas práticas de segurança

​Verifique o retorno no servidor

​Utilizar webhooks

​Fluxo entre dispositivos

​Resolução de problemas

​Retorno não recebido

​Estado sempre “Declined”

​Ciclo de redirecionamento

​Repositório de exemplos

Repositório no GitHub

Quando usar o redirecionamento

Implementação

Passo 1: Criar uma sessão (servidor)

Passo 2: Redirecionar o utilizador (frontend)

Tratar o retorno

Exemplo com Next.js

Exemplo com Express.js

Exemplo com Vue Router

Abrir num novo separador

Boas práticas de segurança

Verifique o retorno no servidor

Utilizar webhooks

Fluxo entre dispositivos

Resolução de problemas

Retorno não recebido

Estado sempre “Declined”

Ciclo de redirecionamento

Repositório de exemplos