Stripe Identity API nutzen: Entwickler-Anleitung zur ID-Verifizierung

Die Überprüfung der realen Identität eines Benutzers ist komplex: Sie benötigen Dokumentenerfassung, OCR, Gesichtsabgleich, Liveness-Erkennung, Betrugssignale und Unterstützung für viele ID-Typen und Länder. Die Stripe Identity API fasst all das in einer einzigen Integration zusammen. So können Sie einen produktionsbereiten ID-Verifizierungsprozess in wenigen Stunden statt Monaten einbauen.

Teste Apidog heute

In diesem Leitfaden findest du alle notwendigen Schritte zur Implementierung von Stripe Identity: Aktivierung im Dashboard, Anlegen einer VerificationSession, Auswahl zwischen gehostetem Redirect und eingebettetem Stripe.js, Webhook-Handling und Auslesen der verifizierten Daten. Beispiele mit cURL und Node, Fehlerbehandlung und Hinweise zum lokalen Testen mit Apidog sind enthalten. Alternativen findest du in der Übersicht der besten KYC APIs.

Stripe Identity eignet sich für Teams, die Stripe für Payments nutzen, läuft aber auch als Standalone-Lösung. Die offiziellen Stripe-Dokumente erklären die Oberfläche; dieser Beitrag liefert Best Practices für den Entwickleralltag: Was passiert technisch, welche Felder sind kritisch, wo lauern typische Stolperfallen.

TL;DR

Stripe Identity verifiziert Nutzer mit amtlichem Ausweis und Selfie-Liveness; Preise ab 1,50 $ pro Verifizierung (USA).
Das zentrale Objekt ist die VerificationSession. Erstelle sie serverseitig, leite den Nutzer weiter oder verwende Stripe.js.
Fordere benötigte Felder über options.document.require_matching_selfie, require_id_number und allowed_types an.
Höre auf die Webhooks identity.verification_session.verified und identity.verification_session.requires_input.
Verifizierte Daten wie Name, Geburtsdatum, Adresse und ID-Nummer bekommst du nur, wenn du verified_outputs beim Anlegen der Session angibst.
Stripe Identity unterstützt über 35 Länder mit länderspezifischer Dokumentenerkennung.

Was ist die Stripe Identity API?

Stripe Identity ist eine API zur ID-Verifizierung mit dem Endpunkt /v1/identity/verification_sessions. Sie übernimmt Dokumentenerfassung, Datenauswertung, Gesichtsabgleich und Fraud-Detection für dich. Das Resultat: Ein signierter Datensatz mit Name, Geburtsdatum, Adresse und optional ID-Nummer, plus die Originalbilder im Stripe-Tresor.

Hinter den Kulissen arbeitet Stripe wie bei Checkout/Payment Intents: Du erstellst eine Session im Backend, Stripe übernimmt die Benutzeroberfläche, du bekommst das Ergebnis per Webhook. Für Entwickler, die Checkout kennen, ist der Flow sofort verständlich.

Authentifizierung und Einrichtung

Stripe Identity im Dashboard aktivieren:

Navigiere zu Dashboard → Einstellungen → Identity, akzeptiere die Bedingungen, fülle die Firmendaten für KYC aus. Identity ist dann für Test- und Live-Modus aktiv.
Authentifiziere dich mit deinem Stripe Secret Key (sk_test_... für Test, sk_live_... für Live). Keine separaten Credentials nötig.
Node SDK installieren:

npm install stripe

Stripe-Client initialisieren und API-Version festlegen:

import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: "2024-06-20",
});

Jetzt kannst du alle Methoden unter stripe.identity.verificationSessions nutzen.

Kernendpunkte

VerificationSession erstellen

Erstelle eine VerificationSession für jeden Verifizierungsversuch. Lege fest, welche Dokumente akzeptiert werden, ob ein Selfie nötig ist, und welche Felder du zurückbekommen willst.

cURL-Beispiel:

curl https://api.stripe.com/v1/identity/verification_sessions \
  -u "$STRIPE_SECRET_KEY:" \
  -d "type=document" \
  -d "options[document][require_matching_selfie]=true" \
  -d "options[document][require_id_number]=true" \
  -d "options[document][allowed_types][]=driving_license" \
  -d "options[document][allowed_types][]=passport" \
  -d "verified_outputs[]=first_name" \
  -d "verified_outputs[]=last_name" \
  -d "verified_outputs[]=dob" \
  -d "verified_outputs[]=address" \
  -d "verified_outputs[]=id_number" \
  -d "metadata[user_id]=usr_7f3k2"

Node SDK Beispiel:

const session = await stripe.identity.verificationSessions.create({
  type: "document",
  options: {
    document: {
      require_matching_selfie: true,
      require_id_number: true,
      allowed_types: ["driving_license", "passport", "id_card"],
    },
  },
  verified_outputs: [
    "first_name",
    "last_name",
    "dob",
    "address",
    "id_number",
  ],
  metadata: { user_id: "usr_7f3k2" },
});

// Für den Client weitergeben:
// session.url              -> hosted redirect
// session.client_secret    -> Stripe.js Embedded Component

Hinweise:

type: "document" startet die Dokumentenprüfung.
Über allowed_types beschränkst du, welche Dokumente akzeptiert werden.
verified_outputs gibt an, welche Felder du zurückbekommst (Datenminimierung).
metadata ist ideal zur Verknüpfung mit deinem User-Objekt.

Gehosteter Redirect vs. eingebettetes Stripe.js

Gehosteter Redirect:

Leite den Nutzer zu session.url, Stripe übernimmt die UX auf stripe.com und leitet zu deiner return_url zurück. Schnell implementiert, für abgeschlossene Flows.

Eingebettetes Stripe.js:

Mit <@stripe/stripe-js> kannst du das Verifizierungsmodul direkt in deine App einbinden. Übergib session.client_secret ans Frontend und rufe stripe.verifyIdentity(clientSecret) auf. Gut für Onboarding-Flows im eigenen UI.

Webhooks

Verlasse dich nicht auf Redirects, sondern validiere Verifizierungen immer backendseitig über Webhooks.

Endpoint im Dashboard registrieren:

Dashboard → Entwickler → Webhooks
Abonniere folgende Events:
- identity.verification_session.verified: Prüfung bestanden, Daten bereit.
- identity.verification_session.requires_input: Prüfung fehlgeschlagen oder unlesbares Dokument.
- identity.verification_session.processing: Async-Checks laufen.
- identity.verification_session.canceled: Sitzung wurde abgebrochen.

Node Webhook-Beispiel:

app.post("/webhooks/stripe", express.raw({ type: "application/json" }), async (req, res) => {
  const event = stripe.webhooks.constructEvent(
    req.body,
    req.headers["stripe-signature"],
    process.env.STRIPE_WEBHOOK_SECRET
  );

  if (event.type === "identity.verification_session.verified") {
    const session = event.data.object;
    await markUserVerified(session.metadata.user_id, session.id);
  }

  if (event.type === "identity.verification_session.requires_input") {
    await notifyUserToRetry(event.data.object.metadata.user_id);
  }

  res.json({ received: true });
});

Verifizierte Ausgaben abrufen

Die Webhook-Nachricht meldet dir nur den Status. Die eigentlichen Daten liest du so aus:

const session = await stripe.identity.verificationSessions.retrieve(
  "vs_1N...",
  { expand: ["verified_outputs"] }
);

const { first_name, last_name, dob, address, id_number } = session.verified_outputs;

Wichtig:

id_number wird nur einmal ausgeliefert – speichere sie sofort verschlüsselt. Dokumentbilder verbleiben ausschließlich im Stripe-Tresor.

Häufige Fehler und Ratenbegrenzungen

Typischer Fehler: verification_session.requires_input mit Codes wie document_unverified_other oder selfie_face_mismatch.
- Zeige dem User eine Retry-Option.
- Entweder neue Session anlegen oder auf die alte session.url zurückleiten, solange offen.
Ratenlimits:
- Live: 100 Requests/sec
- Test: 25 Requests/sec
- Bei 429-Fehlern Retry-After-Header beachten und mit Backoff erneut versuchen.
Weitere Fehler:
- unsupported_document_type – Dokument nicht erlaubt.
- country_not_supported – Land nicht abgedeckt.

Stripe Identity Preise

USA: 1,50 $ pro Verifizierung.
Europa: 1,50–2,00 $ (siehe Preisseite).
Nur erfolgreich abgeschlossene Sessions (Event: verified) werden berechnet.
Bei >10.000 Verifizierungen/Monat gibt es individuelle Preise über den Vertrieb.

Stripe Identity mit Apidog testen

API-Testtools wie Apidog erleichtern das Testen enorm. Apidog importiert Stripes OpenAPI-Spezifikation, zeigt alle Felder mit Doku an und erlaubt wiederholbare Requests gegen Stripes Testumgebung.

Besonders hilfreich:

Webhook-Events wie identity.verification_session.verified lassen sich lokal mocken und gezielt gegen dein Dev-Backend senden.
So kannst du Handler Schritt für Schritt testen, ohne echte Verifizierungen auszuführen.
Mehr dazu im API-Testen ohne Postman 2026 Guide.

Lade Apidog herunter, um den Desktop-Client zu nutzen.

FAQ

Was ist der Unterschied zwischen Stripe Identity und Stripes regulärem KYC?

Stripes Standard-KYC verifiziert Geschäftsinhaber für Connect- und Zahlungskonten. Stripe Identity ist eine API zur Verifizierung deiner Endnutzer – die Ergebnisse sind getrennt.

Kann ich eine verifizierte Identität über mehrere Sessions wiederverwenden?

Ja. Sobald eine Session verifiziert ist, sind die verified_outputs permanent verfügbar. Für neue Events erstellst du einfach eine neue Session und verknüpfst sie mit deinem User-Objekt.

Funktioniert Stripe Identity unabhängig von Zahlungen?

Ja. Viele nutzen es als reine KYC-Schicht. Für zusätzliche Sanktionsprüfungen kannst du eine AML-Screening-API anbinden.

Wie vergleicht sich Stripe Identity mit Plaid Identity Verification?

Stripe: Dokument + Selfie.

Plaid: Bankverifizierte Identitätsdaten. Siehe unseren Plaid API Leitfaden.

Ist Selfie-Liveness Pflicht?

Nein. Setze options.document.require_matching_selfie auf false, wenn du nur Dokumentenprüfung willst. Meistens ist Liveness sinnvoll als zusätzlicher Schutz.

Welche Länder werden unterstützt?

Über 35 Länder in Nordamerika, Europa und APAC. Die aktuelle Liste steht in den Stripe-Dokumenten; neue Länder werden laufend ergänzt.