Redirecció web KYC: pàgina de verificació allotjada

El mètode de redirecció envia els usuaris a una pàgina de verificació allotjada per Didit i, després, els torna a la teva aplicació mitjançant una URL de callback.

Funcionalitat	Descripció
Temps de configuració	5 minuts
Cal backend	✅ Sí (per crear sessions)
Es manté al teu domini	❌ No (redirigeix a verify.didit.me o al teu domini personalitzat de marca blanca)
Suport entre dispositius	✅ Sí
Compatibilitat amb navegadors	✅ Tots els navegadors

Quan utilitzar la redirecció

Verificació entre dispositius: comença a l’ordinador i completa-la al mòbil
Compatibilitat màxima: funciona en tots els navegadors, inclosos els més antics
Integració senzilla: no cal configurar cap iframe
Problemes amb la càmera: quan l’accés a la càmera des d’un iframe dóna problemes

Implementació

Pas 1: crear una sessió (backend)

La resposta de creació de la sessió conté un camp anomenat url. Envia aquest 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 });
});

Pas 2: redirigir l’usuari (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ó del callback

Quan acaba la verificació, Didit redirigeix a la teva URL de callback amb paràmetres de consulta:

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

Paràmetre	Descripció
`verificationSessionId`	Identificador únic de la sessió
`status`	L’estat actual de la sessió, per exemple `Approved`, `Declined`, `In Review` o `Expired`. Consulta estats de verificació

Exemple amb 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>
  );
}

Exemple amb 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');
  }
});

Exemple amb 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');
    }
  }
}

Obrir en una pestanya nova

Si prefereixes mantenir la teva aplicació oberta mentre l’usuari fa la verificació:

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

// Poll for completion or use webhooks

Quan utilitzis pestanyes noves, combina-ho amb webhooks per saber quan acaba la verificació.

Bones pràctiques de seguretat

Verifica el callback al servidor

Tracta els paràmetres de consulta verificationSessionId i status com a pistes d’interfície no fiables. Confirma sempre la decisió final al teu backend, ja sigui gestionant el webhook (opció preferida), ja sigui tornant a obtenir la decisió a través de l’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');
});

Utilitza webhooks

Per a la integració més fiable, utilitza webhooks per rebre els resultats de la verificació directament al teu backend, independentment del comportament del navegador de l’usuari.

Flux entre dispositius

El mètode de redirecció admet de manera natural la verificació entre dispositius:

L’usuari fa clic a «Verifica» a l’ordinador
L’usuari és redirigit a la pàgina de verificació
Si cal, l’usuari pot escanejar el codi QR per continuar al mòbil
Quan acaba, l’usuari és redirigit a la teva URL de callback; el dispositiu des del qual es fa la redirecció ve determinat per callback_method (initiator, completer o both)

Resolució de problemes

No es rep el callback

Verifica que la URL de callback s’hagi definit correctament en crear la sessió
Assegura’t que la teva URL de callback sigui accessible des d’internet
Comprova que la URL no tingui errors tipogràfics ni problemes de codificació

L’estat és sempre “Declined”

Revisa la configuració del flux de treball a la Didit Console
Verifica que els documents de prova que fas servir siguin vàlids
Revisa els detalls de la sessió a través de l’API per consultar els motius concrets de rebuig

Bucle de redirecció

Assegura’t que el gestor de callback no redirigeixi de nou cap a la verificació
Comprova si hi ha problemes de memòria cau a la pàgina de callback
Esborra la memòria cau del navegador i torna-ho a provar

Repositori d’exemples

Repositori de GitHub

Consulta el codi font i els exemples a GitHub

Guies

Autenticació

Model Context Protocol (MCP)

SDK web

SDK natius

SDK de servidor

Integracions

Redirecció web KYC: pàgina de verificació allotjada

Quan utilitzar la redirecció

Implementació

Pas 1: crear una sessió (backend)

Pas 2: redirigir l’usuari (frontend)

Gestió del callback

Exemple amb Next.js

Exemple amb Express.js

Exemple amb Vue Router

Obrir en una pestanya nova

Bones pràctiques de seguretat

Verifica el callback al servidor

Utilitza webhooks

Flux entre dispositius

Resolució de problemes

No es rep el callback

L’estat és sempre “Declined”

Bucle de redirecció

Repositori d’exemples

Repositori de GitHub

​Quan utilitzar la redirecció

​Implementació

​Pas 1: crear una sessió (backend)

​Pas 2: redirigir l’usuari (frontend)

​Gestió del callback

​Exemple amb Next.js

​Exemple amb Express.js

​Exemple amb Vue Router

​Obrir en una pestanya nova

​Bones pràctiques de seguretat

​Verifica el callback al servidor

​Utilitza webhooks

​Flux entre dispositius

​Resolució de problemes

​No es rep el callback

​L’estat és sempre “Declined”

​Bucle de redirecció

​Repositori d’exemples

Repositori de GitHub

Quan utilitzar la redirecció

Implementació

Pas 1: crear una sessió (backend)

Pas 2: redirigir l’usuari (frontend)

Gestió del callback

Exemple amb Next.js

Exemple amb Express.js

Exemple amb Vue Router

Obrir en una pestanya nova

Bones pràctiques de seguretat

Verifica el callback al servidor

Utilitza webhooks

Flux entre dispositius

Resolució de problemes

No es rep el callback

L’estat és sempre “Declined”

Bucle de redirecció

Repositori d’exemples