Web-Redirect-KYC: Gehostete Verifizierungsseite

Die Redirect-Methode leitet Benutzer für die Verifizierung auf eine von Didit gehostete Seite weiter und führt sie anschließend über eine Callback-URL zu Ihrer Anwendung zurück.

Funktion	Beschreibung
Einrichtungszeit	5 Minuten
Backend erforderlich	✅ Ja (zum Erstellen von Sitzungen)
Bleibt auf Ihrer Domain	❌ Nein (leitet zu verify.didit.me oder Ihrer benutzerdefinierten White-Label-Domain weiter)
Geräteübergreifende Unterstützung	✅ Ja
Browser-Kompatibilität	✅ Alle Browser

Wann Sie den Redirect nutzen sollten

Geräteübergreifende Verifizierung: Auf dem Desktop beginnen, auf dem Smartphone abschließen
Maximale Kompatibilität: Funktioniert in allen Browsern, auch in älteren Versionen
Einfache Integration: Keine iframe-Konfiguration erforderlich
Kameraprobleme: Wenn der Kamerazugriff im iframe problematisch ist

Implementierung

Schritt 1: Sitzung erstellen (Backend)

Die Antwort beim Erstellen der Sitzung enthält ein Feld namens url – übergeben Sie diesen Wert an den 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 });
});

Schritt 2: Benutzer weiterleiten (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>

Callback verarbeiten

Sobald die Verifizierung abgeschlossen ist, leitet Didit mit Query-Parametern zu Ihrer Callback-URL weiter:

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

Parameter	Beschreibung
`verificationSessionId`	Eindeutige Sitzungskennung
`status`	Der aktuelle Status der Sitzung, zum Beispiel `Approved`, `Declined`, `In Review` oder `Expired`. Siehe Verifizierungsstatus

Next.js-Beispiel

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

Express.js-Beispiel

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

Vue-Router-Beispiel

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

In neuem Tab öffnen

Wenn Sie Ihre Anwendung geöffnet lassen möchten, während sich der Benutzer verifiziert:

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

// Poll for completion or use webhooks

Wenn Sie neue Tabs verwenden, kombinieren Sie dies mit Webhooks, um zu erfahren, wann die Verifizierung abgeschlossen ist.

Best Practices für die Sicherheit

Callback serverseitig verifizieren

Behandeln Sie die Query-Parameter verificationSessionId und status als nicht vertrauenswürdige UI-Hinweise. Bestätigen Sie die endgültige Entscheidung stets auf Ihrem Backend – entweder durch die Verarbeitung des Webhooks (bevorzugt) oder durch erneutes Abrufen der Entscheidung über die 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');
});

Webhooks verwenden

Verwenden Sie für eine möglichst zuverlässige Integration Webhooks, um Verifizierungsergebnisse direkt an Ihr Backend zu übermitteln – unabhängig davon, wie sich der Browser des Benutzers verhält.

Geräteübergreifender Ablauf

Die Redirect-Methode unterstützt von Natur aus geräteübergreifende Verifizierungen:

Der Benutzer klickt auf dem Desktop auf „Verifizieren“
Der Benutzer wird zur Verifizierungsseite weitergeleitet
Bei Bedarf kann der Benutzer einen QR-Code scannen, um auf dem Smartphone fortzufahren
Nach Abschluss wird der Benutzer zu Ihrer Callback-URL weitergeleitet – welches Gerät die Weiterleitung ausführt, wird über callback_method gesteuert (initiator, completer oder both)

Fehlerbehebung

Callback nicht empfangen

Prüfen Sie, ob die Callback-URL beim Erstellen der Sitzung korrekt festgelegt wurde
Stellen Sie sicher, dass Ihre Callback-URL über das Internet erreichbar ist
Überprüfen Sie, dass die URL keine Tippfehler oder Probleme bei der Zeichenkodierung aufweist

Status immer „Declined“

Überprüfen Sie Ihre Workflow-Einstellungen in der Didit Console
Stellen Sie sicher, dass die von Ihnen verwendeten Testdokumente gültig sind
Prüfen Sie die Sitzungsdetails über die API auf spezifische Ablehnungsgründe

Weiterleitungsschleife

Stellen Sie sicher, dass Ihr Callback-Handler nicht wieder zur Verifizierung weiterleitet
Prüfen Sie, ob Caching-Probleme auf Ihrer Callback-Seite vorliegen
Leeren Sie den Browser-Cache und versuchen Sie es erneut

Beispiel-Repository

GitHub-Repository

Quellcode und Beispiele auf GitHub ansehen

Leitfäden

Authentifizierung

Model Context Protocol (MCP)

Web-SDKs

Native SDKs

Server-SDKs

Integrationen

Web-Redirect-KYC: Gehostete Verifizierungsseite

Wann Sie den Redirect nutzen sollten

Implementierung

Schritt 1: Sitzung erstellen (Backend)

Schritt 2: Benutzer weiterleiten (Frontend)

Callback verarbeiten

Next.js-Beispiel

Express.js-Beispiel

Vue-Router-Beispiel

In neuem Tab öffnen

Best Practices für die Sicherheit

Callback serverseitig verifizieren

Webhooks verwenden

Geräteübergreifender Ablauf

Fehlerbehebung

Callback nicht empfangen

Status immer „Declined“

Weiterleitungsschleife

Beispiel-Repository

GitHub-Repository

​Wann Sie den Redirect nutzen sollten

​Implementierung

​Schritt 1: Sitzung erstellen (Backend)

​Schritt 2: Benutzer weiterleiten (Frontend)

​Callback verarbeiten

​Next.js-Beispiel

​Express.js-Beispiel

​Vue-Router-Beispiel

​In neuem Tab öffnen

​Best Practices für die Sicherheit

​Callback serverseitig verifizieren

​Webhooks verwenden

​Geräteübergreifender Ablauf

​Fehlerbehebung

​Callback nicht empfangen

​Status immer „Declined“

​Weiterleitungsschleife

​Beispiel-Repository

GitHub-Repository

Wann Sie den Redirect nutzen sollten

Implementierung

Schritt 1: Sitzung erstellen (Backend)

Schritt 2: Benutzer weiterleiten (Frontend)

Callback verarbeiten

Next.js-Beispiel

Express.js-Beispiel

Vue-Router-Beispiel

In neuem Tab öffnen

Best Practices für die Sicherheit

Callback serverseitig verifizieren

Webhooks verwenden

Geräteübergreifender Ablauf

Fehlerbehebung

Callback nicht empfangen

Status immer „Declined“

Weiterleitungsschleife

Beispiel-Repository