Die Überprüfung der realen Identität eines Benutzers ist eine jener Aufgaben, die auf einem Whiteboard einfach aussieht und sich in ein monatelanges Projekt verwandelt, sobald man mit dem Aufbau beginnt. Sie benötigen Dokumentenerfassung, OCR, Gesichtsabgleich, Liveness-Erkennung, Betrugssignale und Abdeckung für Dutzende von ID-Typen in verschiedenen Ländern. Die Stripe Identity API bündelt all das in einer einzigen Integration, sodass Sie einen produktionsbereiten ID-Verifizierungsfluss an einem Nachmittag statt in einem Quartal einrichten können.
Dieser Leitfaden führt Sie durch jeden Schritt, den ein Entwickler benötigt, um Stripe Identity zu implementieren: Aktivierung im Dashboard, Erstellung einer VerificationSession, Wahl zwischen dem gehosteten Redirect und der eingebetteten Stripe.js-Komponente, Bearbeitung von Webhooks und Lesen der verifizierten Ausgaben. Sie werden cURL- und Node-Beispiele, Muster zur Fehlerbehandlung und erfahren, wie Sie den gesamten Fluss lokal mit Apidog testen können. Falls Sie zuerst Alternativen evaluieren möchten, lesen Sie unsere Übersicht der besten KYC APIs, bevor Sie sich festlegen.
Stripe Identity passt natürlich gut zu Teams, die Stripe bereits für Zahlungen nutzen, funktioniert aber auch als eigenständiges Produkt. Die offiziellen Stripe Identity-Dokumente decken die Produktoberfläche ab, und dieser Beitrag füllt die Lücken in der Entwicklererfahrung: Was passiert im Hintergrund, welche Felder sind wichtig und wo lauern die häufigsten Fallstricke.
TL;DR
- Stripe Identity verifiziert Benutzer mit einem amtlichen Ausweis und einem Selfie-Liveness-Check; die Preise beginnen bei 1,50 $ pro Verifizierung in den USA.
- Das Kern-Primitiv ist das Objekt
VerificationSession; Sie erstellen eines serverseitig und leiten den Benutzer dann weiter oder mounten die Stripe.js-Komponente. - Fordern Sie die benötigten Felder über
options.document.require_matching_selfie,require_id_numberundallowed_typesan. - Hören Sie auf
identity.verification_session.verifiedundidentity.verification_session.requires_inputWebhooks, um den Status Ihrer App zu steuern. - Verifizierte Ausgaben (Name, Geburtsdatum, Adresse, ID-Nummer) werden nur angezeigt, wenn Sie
verified_outputsbei der Sitzungserstellung festlegen. - Stripe Identity deckt über 35 Länder mit lokalisierter Dokumentenunterstützung ab.
Was ist die Stripe Identity API?
Stripe Identity ist ein ID-Verifizierungsprodukt, das auf der Kern-API-Oberfläche von Stripe aufbaut. Es bietet Ihnen eine einzige Endpunktfamilie (/v1/identity/verification_sessions), die Dokumentenerfassung, Datenextraktion, Gesichtsabgleich und Betrugserkennung orchestriert. Die Ausgabe ist ein signierter, strukturierter Datensatz, dem Sie vertrauen können: ein verifizierter vollständiger Name, Geburtsdatum, Adresse und optional eine ID-Nummer, gepaart mit den Original-Dokumentbildern, die in Stripes Tresor gespeichert sind.
Unter der Haube verwendet Stripe das gleiche Session-plus-Webhook-Muster, das Sie bereits von Checkout und Payment Intents kennen. Sie erstellen eine Session serverseitig, Stripe übernimmt die benutzerseitige Erfassungs-UI, und Sie werden benachrichtigt, wenn das Ergebnis bereit ist. Wenn Sie bereits einen Checkout-Flow erstellt haben, wird sich Identity innerhalb weniger Minuten vertraut anfühlen.
Authentifizierung und Einrichtung
Bevor Sie die API aufrufen, aktivieren Sie Stripe Identity im Dashboard. Gehen Sie zu Dashboard > Einstellungen > Identity, akzeptieren Sie die Bedingungen und füllen Sie die Geschäftsdetails aus, die Stripe für die KYC-Konformität benötigt. Die Umschaltung aktiviert Identity sowohl für den Testmodus als auch für den Live-Modus in Ihrem Konto.
Die Authentifizierung verwendet Ihren standardmäßigen Stripe Secret Key. Test-Keys beginnen mit sk_test_, und Live-Keys beginnen mit sk_live_. Stripe Identity benötigt keine separate Anmeldeinformation, was die Integrationsfläche klein hält.
Installieren Sie das Node SDK:
npm install stripe
Initialisieren Sie dann einen Client. Legen Sie die API-Version fest, damit Stripe Sie nie mit einer Schemaänderung überrascht:
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
apiVersion: "2024-06-20",
});
Sie können jetzt jeden Endpunkt unter stripe.identity.verificationSessions aufrufen.
Kernendpunkte
Erstellen einer VerificationSession
Die VerificationSession ist das einzelne Objekt, das Sie pro Verifizierungsversuch eines Benutzers erstellen. Sie steuert, welche Dokumenttypen akzeptiert werden, ob ein Selfie erforderlich ist und welche Felder an Ihr Backend zurückgegeben werden.
Mit cURL:
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"
Mit dem Node SDK:
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" },
});
// Send one of these to the client:
// session.url -> hosted redirect
// session.client_secret -> Stripe.js embedded component
Einige Felder verdienen besondere Aufmerksamkeit. type: "document" weist Stripe an, eine Dokumentenprüfung durchzuführen; die Alternative, id_number, führt eine nur in den USA verfügbare SSN-ähnliche Suche ohne Erfassung eines Ausweises durch. allowed_types beschränkt, welche Dokumentenkategorien der Benutzer hochladen kann, was für Compliance-Programme wichtig ist, die nur amtliche Lichtbildausweise akzeptieren. verified_outputs ist die Positivliste der Felder, die Sie zurückgegeben haben möchten; Stripe legt keine Daten offen, die Sie nicht angefordert haben, was Ihre Datenminimierung sauber hält.
Gehosteter Verifizierungs-Redirect vs. eingebettetes Stripe.js
Stripe bietet Ihnen zwei Integrationsformen. Der gehostete Redirect ist der schnellste Weg: Senden Sie den Benutzer an session.url, Stripe übernimmt die gesamte Erfassungserfahrung auf einer stripe.com-Domain, und der Benutzer wird zu Ihrer return_url zurückgeleitet. Sie schreiben ungefähr zehn Zeilen Code.
Der eingebettete Flow verwendet Stripe.js und das Paket @stripe/stripe-js, um ein Verifizierungsmodal in Ihrer eigenen App einzubinden. Sie übergeben session.client_secret an das Frontend und rufen stripe.verifyIdentity(clientSecret) auf. Dies hält die Benutzer in Ihrem Produkt und gibt Ihnen Designkontrolle über die umgebende Seite. Wählen Sie es, wenn die Verifizierung mitten im Flow in einem Anmelde- oder KYC-Schritt stattfindet; wählen Sie den Redirect, wenn die Verifizierung eine diskrete Aufgabe ist.
Webhooks
Verlassen Sie sich niemals auf den Client-Redirect, um zu erfahren, dass eine Verifizierung erfolgreich war; bestätigen Sie dies immer auf dem Backend über Webhooks. Registrieren Sie einen Endpunkt unter Dashboard > Entwickler > Webhooks und abonnieren Sie:
identity.verification_session.verifiedwird ausgelöst, wenn alle Prüfungen bestanden sind und verifizierte Daten bereitstehen.identity.verification_session.requires_inputwird ausgelöst, wenn der Benutzer eine Prüfung nicht besteht oder ein unlesbares Dokument hochlädt. Sie können ihn zur Wiederholung zurückleiten.identity.verification_session.processingwird ausgelöst, während Stripe asynchrone Prüfungen durchführt; nützlich zum Anzeigen von Ladezuständen.identity.verification_session.canceledwird ausgelöst, wenn Sie die Sitzung programmatisch abbrechen.
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 });
});
Abrufen verifizierter Ausgaben
Die Webhook-Payload teilt Ihnen mit, dass die Sitzung verifiziert wurde, enthält aber nicht die sensiblen Felder. Um verifizierte Ausgaben zu lesen, rufen Sie verificationSessions.retrieve mit expand: ["verified_outputs"] auf:
const session = await stripe.identity.verificationSessions.retrieve(
"vs_1N...",
{ expand: ["verified_outputs"] }
);
const { first_name, last_name, dob, address, id_number } = session.verified_outputs;
Stripe gibt die id_number nur einmal zurück; speichern Sie sie sofort verschlüsselt auf Ihrer Seite. Die Dokumentbilder selbst verbleiben in Stripes Tresor und sind zur Überprüfung über das Dashboard zugänglich.
Häufige Fehler und Ratenbegrenzungen
Der häufigste Fehler ist verification_session.requires_input mit einem Code wie document_unverified_other oder selfie_face_mismatch. Behandeln Sie diese, indem Sie eine freundliche Wiederholungs-UI anzeigen; dieselbe Sitzung kann wiederverwendet werden, indem Sie verificationSessions.cancel aufrufen und eine neue erstellen, oder indem Sie zum selben session.url umleiten, während es noch geöffnet ist.
Stripe wendet Standard-API-Ratenbegrenzungen von 100 Anfragen pro Sekunde im Live-Modus und 25 pro Sekunde im Testmodus an. Die /identity/verification_sessions-Endpunkte fallen in dieselbe Kategorie wie der Rest der API. Wenn Sie Limits erreichen, erhalten Sie HTTP 429 mit einem Retry-After-Header; verwenden Sie exponentielles Backoff und respektieren Sie den Header.
Weitere Fehler, auf die Sie achten sollten: unsupported_document_type, wenn der Benutzer einen Ausweis hochlädt, der nicht in Ihrer allowed_types-Liste enthalten ist, und country_not_supported, wenn jemand ein Dokument aus einem der Länder versucht, die Stripe Identity noch nicht abdeckt.
Stripe Identity Preise
Stripe Identity kostet 1,50 $ pro Verifizierung in den Vereinigten Staaten. Die internationalen Preise variieren; die meisten europäischen Länder liegen bei etwa 1,50 $ bis 2,00 $, und Stripe veröffentlicht die vollständige länderspezifische Aufschlüsselung auf seiner Preisseite. Ein Verifizierungsversuch, der mit requires_input endet, zählt nicht als kostenpflichtiges Ereignis; nur abgeschlossene verified-Sitzungen werden abgerechnet.
Für Großkunden bietet Stripe individuelle Preise an, die die Gebühr pro Prüfung erheblich senken können. Wenn Sie mehr als 10.000 Verifizierungen pro Monat verarbeiten, wenden Sie sich an den Vertrieb.
Stripe Identity mit Apidog testen
API-Spielplätze schlagen das manuelle Schreiben von cURL-Befehlen jedes Mal, besonders wenn Sie Webhook-Payloads iterieren. Apidog importiert die OpenAPI-Spezifikation von Stripe direkt, sodass jedes Feld auf dem VerificationSession-Objekt mit Inline-Dokumentation angezeigt wird. Sie können echte Anfragen an Stripes Testumgebung senden, die Antwort inspizieren und so oft wiederholen, wie Sie möchten.
Die Webhook-Testseite ist der Bereich, in dem Apidog die meiste Zeit spart. Sie können identity.verification_session.verified-Ereignisse lokal mocken, sie an Ihren Entwicklungsserver senden und Ihren Handler Schritt für Schritt durchgehen, ohne dass eine echte Verifizierung abgeschlossen werden muss. Wenn Sie Workflows vergleichen, bietet unser Leitfaden zum API-Testen ohne Postman im Jahr 2026 eine tiefere Anleitung. Laden Sie Apidog herunter, um den Desktop-Client zu erhalten.
FAQ
Was ist der Unterschied zwischen Stripe Identity und Stripes regulärem KYC? Stripes integriertes KYC verifiziert Geschäftsinhaber für Connect- und Zahlungskonten. Stripe Identity ist eine eigenständige API zur Verifizierung Ihrer Endbenutzer; die beiden Systeme teilen keine Verifizierungsergebnisse.
Kann ich eine verifizierte Identität über mehrere Sitzungen hinweg wiederverwenden? Ja. Sobald eine Sitzung verifiziert ist, sind die verified_outputs auf diesem Sitzungsobjekt permanent. Wenn Sie für ein neues Ereignis erneut verifizieren müssen, erstellen Sie eine neue Sitzung und verknüpfen Sie sie auf Ihrer Seite mit dem Benutzerdatensatz.
Funktioniert Stripe Identity auch außerhalb von Zahlungen? Absolut. Viele Kunden nutzen es rein als KYC-Schicht und berühren nie die Zahlungsfläche von Stripe. Wenn Sie zusätzlich zur ID-Verifizierung eine breitere Sanktionsprüfung benötigen, koppeln Sie es mit einer speziellen AML-Screening-API.
Wie vergleicht sich Stripe Identity mit Plaid Identity Verification? Stripe konzentriert sich auf Dokument plus Selfie; Plaid setzt auf bankverifizierte Identitätsdaten. Sehen Sie sich unseren Plaid API-Leitfaden für den anderen Ansatz an.
Ist Selfie-Liveness obligatorisch? Nein. Setzen Sie options.document.require_matching_selfie auf false, wenn Sie nur eine Dokumentenprüfung benötigen. Die meisten Betrugsabteilungen behalten es bei, da passive Liveness viele Angriffe mit geringem Aufwand abfängt.
Welche Länder deckt Stripe Identity ab? Über 35 Länder in Nordamerika, Europa und Teilen des asiatisch-pazifischen Raums, mit lokalisierten Dokumentenparsern für jedes Land. Stripe veröffentlicht die aktuelle Länderliste in seinen Dokumenten und fügt regelmäßig neue Märkte hinzu.