KYC por redirección web: página de verificación alojada

El método de redirección envía a los usuarios a una página alojada por Didit para la verificación y, después, los devuelve a tu aplicación mediante una URL de callback.

Función	Descripción
Tiempo de configuración	5 minutos
Requiere backend	✅ Sí (para crear sesiones)
Permanece en tu dominio	❌ No (redirige a verify.didit.me o a tu dominio personalizado de marca blanca)
Compatibilidad entre dispositivos	✅ Sí
Compatibilidad con navegadores	✅ Todos los navegadores

Cuándo usar la redirección

Verificación entre dispositivos: empieza en el escritorio y termina en el móvil
Máxima compatibilidad: funciona en todos los navegadores, incluidos los más antiguos
Integración sencilla: no requiere configurar un iframe
Problemas con la cámara: cuando el acceso a la cámara desde un iframe da problemas

Implementación

Paso 1: Crear una sesión (backend)

La respuesta de creación de la sesión incluye un campo llamado url: pasa ese valor al 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 });
});

Paso 2: Redirigir al usuario (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>

Gestión del callback

Cuando la verificación finaliza, Didit redirige a tu URL de callback con parámetros de consulta:

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

Parámetro	Descripción
`verificationSessionId`	Identificador único de la sesión
`status`	El estado actual de la sesión, por ejemplo `Approved`, `Declined`, `In Review` o `Expired`. Consulta los estados de verificación

Ejemplo con 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>
  );
}

Ejemplo con 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');
  }
});

Ejemplo con 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 en una pestaña nueva

Si prefieres mantener tu aplicación abierta mientras el usuario realiza la verificación:

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

// Poll for completion or use webhooks

Si usas pestañas nuevas, combínalas con webhooks para saber cuándo finaliza la verificación.

Buenas prácticas de seguridad

Verifica el callback del lado del servidor

Trata los parámetros de consulta verificationSessionId y status como indicaciones de interfaz no fiables. Confirma siempre la decisión final en tu backend, ya sea gestionando el webhook (opción preferida) o volviendo a obtener la decisión mediante la 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');
});

Usa webhooks

Para lograr la integración más fiable, usa webhooks para recibir los resultados de la verificación directamente en tu backend, independientemente de cómo se comporte el navegador del usuario.

Flujo entre dispositivos

El método de redirección admite de forma natural la verificación entre dispositivos:

El usuario hace clic en “Verificar” en una computadora de escritorio
El usuario es redirigido a la página de verificación
Si es necesario, el usuario puede escanear un código QR para continuar en el móvil
Al terminar, el usuario es redirigido a tu URL de callback; el dispositivo desde el que se realiza la redirección se controla mediante callback_method (initiator, completer o both)

Solución de problemas

No se recibe el callback

Verifica que la URL de callback esté configurada correctamente al crear la sesión
Asegúrate de que tu URL de callback sea accesible desde internet
Comprueba que la URL no tenga errores tipográficos ni problemas de codificación

El estado siempre es “Declined”

Revisa la configuración de tu flujo en la Didit Console
Verifica que los documentos de prueba que usas sean válidos
Revisa los detalles de la sesión mediante la API para conocer los motivos concretos del rechazo

Bucle de redirección

Asegúrate de que tu manejador de callback no redirija de nuevo a la verificación
Comprueba si hay problemas de caché en tu página de callback
Borra la caché del navegador y vuelve a intentarlo

Repositorio de ejemplo

Repositorio de GitHub

Consulta el código fuente y los ejemplos en GitHub

Guías

Autenticación

Model Context Protocol (MCP)

SDKs web

SDKs nativos

SDK de servidor

Integraciones

KYC por redirección web: página de verificación alojada

Cuándo usar la redirección

Implementación

Paso 1: Crear una sesión (backend)

Paso 2: Redirigir al usuario (frontend)

Gestión del callback

Ejemplo con Next.js

Ejemplo con Express.js

Ejemplo con Vue Router

Abrir en una pestaña nueva

Buenas prácticas de seguridad

Verifica el callback del lado del servidor

Usa webhooks

Flujo entre dispositivos

Solución de problemas

No se recibe el callback

El estado siempre es “Declined”

Bucle de redirección

Repositorio de ejemplo

Repositorio de GitHub

​Cuándo usar la redirección

​Implementación

​Paso 1: Crear una sesión (backend)

​Paso 2: Redirigir al usuario (frontend)

​Gestión del callback

​Ejemplo con Next.js

​Ejemplo con Express.js

​Ejemplo con Vue Router

​Abrir en una pestaña nueva

​Buenas prácticas de seguridad

​Verifica el callback del lado del servidor

​Usa webhooks

​Flujo entre dispositivos

​Solución de problemas

​No se recibe el callback

​El estado siempre es “Declined”

​Bucle de redirección

​Repositorio de ejemplo

Repositorio de GitHub

Cuándo usar la redirección

Implementación

Paso 1: Crear una sesión (backend)

Paso 2: Redirigir al usuario (frontend)

Gestión del callback

Ejemplo con Next.js

Ejemplo con Express.js

Ejemplo con Vue Router

Abrir en una pestaña nueva

Buenas prácticas de seguridad

Verifica el callback del lado del servidor

Usa webhooks

Flujo entre dispositivos

Solución de problemas

No se recibe el callback

El estado siempre es “Declined”

Bucle de redirección

Repositorio de ejemplo