KYC via redirect: pagina di verifica ospitata

Il metodo di reindirizzamento invia gli utenti a una pagina di verifica ospitata da Didit e poi li riporta alla tua app tramite un URL di callback.

Funzionalità	Descrizione
Tempo di configurazione	5 minuti
Backend richiesto	✅ Sì (per creare le sessioni)
Resta sul tuo dominio	❌ No (reindirizza a verify.didit.me o al tuo dominio personalizzato White label)
Supporto cross-device	✅ Sì
Compatibilità browser	✅ Tutti i browser

Quando usare il reindirizzamento

Verifica cross-device: inizia da desktop e completa da mobile
Massima compatibilità: funziona in tutti i browser, inclusi quelli meno recenti
Integrazione semplice: non serve alcuna configurazione di iframe
Problemi con la fotocamera: quando l’accesso alla fotocamera in iframe non funziona

Implementazione

Passaggio 1: crea una sessione (backend)

La risposta di creazione della sessione contiene un campo chiamato url: passa questo valore al browser.

// 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 });
});

Passaggio 2: reindirizza l’utente (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>

Gestione della callback

Quando la verifica è completata, Didit reindirizza all’URL di callback con i seguenti parametri di query:

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

Parametro	Descrizione
`verificationSessionId`	Identificatore univoco della sessione
`status`	Lo stato attuale della sessione, ad esempio `Approved`, `Declined`, `In Review` o `Expired`. Vedi stati della verifica

Esempio 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>
  );
}

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

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

Apri in una nuova scheda

Se preferisci tenere aperta la tua app mentre l’utente esegue la verifica:

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

// Poll for completion or use webhooks

Quando usi le nuove schede, combinale con i webhook per sapere quando la verifica è completata.

Buone pratiche di sicurezza

Verifica la callback lato server

Considera i parametri di query verificationSessionId e status come semplici indicazioni dell’interfaccia non attendibili. Conferma sempre la decisione finale sul tuo backend, gestendo il webhook (opzione preferita) oppure recuperando di nuovo la decisione tramite 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');
});

Usa i webhook

Per l’integrazione più affidabile, usa i webhook per ricevere i risultati della verifica direttamente sul tuo backend, indipendentemente dal comportamento del browser dell’utente.

Flusso cross-device

Il metodo di reindirizzamento supporta in modo naturale la verifica cross-device:

L’utente clicca su “Verifica” sul desktop
L’utente viene reindirizzato alla pagina di verifica
Se necessario, l’utente può scansionare il codice QR per continuare da mobile
Al termine, l’utente viene reindirizzato all’URL di callback: il dispositivo da cui viene effettuato il reindirizzamento è determinato da callback_method (initiator, completer o both)

Risoluzione dei problemi

Callback non ricevuta

Verifica che l’URL di callback sia impostato correttamente quando crei la sessione
Assicurati che il tuo URL di callback sia raggiungibile da internet
Controlla che l’URL non contenga errori di battitura o problemi di codifica

Lo stato è sempre “Declined”

Controlla le impostazioni del workflow nella Didit Console
Verifica che i documenti di test che usi siano validi
Consulta i dettagli della sessione tramite API per i motivi specifici del rifiuto

Guide

Autenticazione

Model Context Protocol (MCP)

SDK web

SDK nativi

SDK server

Integrazioni

KYC via redirect: pagina di verifica ospitata

Quando usare il reindirizzamento

Implementazione

Passaggio 1: crea una sessione (backend)

Passaggio 2: reindirizza l’utente (frontend)

Gestione della callback

Esempio Next.js

Esempio Express.js

Esempio Vue Router

Apri in una nuova scheda

Buone pratiche di sicurezza

Verifica la callback lato server

Usa i webhook

Flusso cross-device

Risoluzione dei problemi

Callback non ricevuta

Lo stato è sempre “Declined”

Loop di reindirizzamento

Repository di esempio

Repository GitHub

​Quando usare il reindirizzamento

​Implementazione

​Passaggio 1: crea una sessione (backend)

​Passaggio 2: reindirizza l’utente (frontend)

​Gestione della callback

​Esempio Next.js

​Esempio Express.js

​Esempio Vue Router

​Apri in una nuova scheda

​Buone pratiche di sicurezza

​Verifica la callback lato server

​Usa i webhook

​Flusso cross-device

​Risoluzione dei problemi

​Callback non ricevuta

​Lo stato è sempre “Declined”

​Loop di reindirizzamento

​Repository di esempio

Repository GitHub

Quando usare il reindirizzamento

Implementazione

Passaggio 1: crea una sessione (backend)

Passaggio 2: reindirizza l’utente (frontend)

Gestione della callback

Esempio Next.js

Esempio Express.js

Esempio Vue Router

Apri in una nuova scheda

Buone pratiche di sicurezza

Verifica la callback lato server

Usa i webhook

Flusso cross-device

Risoluzione dei problemi

Callback non ricevuta

Lo stato è sempre “Declined”

Loop di reindirizzamento

Repository di esempio