Identitätsnachweise Ihrer Nutzer/innen verifizieren
In diesem Leitfaden wird erläutert, wie Sie mit Stripe Identity Identitätsnachweise sicher erfassen und verifizieren können.
Bevor Sie loslegen
- Aktivieren Sie Ihr Konto.
- Füllen Sie Ihren Antrag für Stripe Identity aus.
- (Optional) Passen Sie Ihre Markeneinstellungen auf der Seite Branding-Einstellungen an.
Zeigen Sie ein Modal zum Hochladen von Dokumenten auf Ihrer Website an. Sie gehen wie folgt vor:
- Fügen Sie Ihrer Webseite eine Schaltfläche zur Verifizierung hinzu, die ein Modal zum Hochladen von Dokumenten anzeigt.
- Zeigen Sie eine Bestätigungsseite für die Übermittlung von Identitätsnachweisen an.
- Umgang mit den Verifizierungsergebnissen.
Stripe einrichtenServerseitig
Registrieren Sie sich zunächst für ein Stripe-Konto.
Installieren Sie dann die Bibliotheken für den Zugriff auf die Stripe-API über Ihre Anwendung:
Schaltfläche auf Ihrer Website hinzufügenClientseitig
Erstellen Sie auf Ihrer Website eine Schaltfläche, um die Verifizierung zu starten.
Schaltfläche hinzufügen
Fügen Sie Ihrer Seite zunächst eine Schaltfläche zur Verifizierung hinzu:
<html> <head> <title>Verify your identity</title> </head> <body> <button id="verify-button">Verify</button> </body> </html>
Stripe.js-Bibliothek zu Ihrer Seite hinzufügen
Fügen Sie Stripe.js zu Ihrer Seite hinzu, indem Sie in Ihr HTML-Dokument einen Script-Tag einbinden:
<html> <head> <title>Verify your identity</title> <script src="https://js.stripe.com/v3/"></script> </head> <body> <button id="verify-button">Verify</button> </body> </html>
Notiz
Laden Sie Stripe.js immer direkt von https://js.stripe.com
. Sie können die Bibliothek nicht in ein Paket einfügen oder selbst hosten.
Stripe.js initialisieren
Initialisieren Sie Stripe.js mit Ihrem veröffentlichbaren API-Schlüssel, indem Sie das folgende JavaScript an Ihre Seite übergeben:
<html> <head> <title>Verify your identity</title> <script src="https://js.stripe.com/v3/"></script> </head> <body> <button id="verify-button">Verify</button> <script type="text/javascript"> // Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys var stripe = Stripe(
); </script> </body> </html>'pk_test_TYooMQauvdEDq54NiTphI7jx'
Modal zum Hochladen von Dokumenten anzeigenClientseitigServerseitig
Richten Sie die neue Schaltfläche zur Anzeige eines Modals zum Hochladen von Dokumenten ein. Nach dem Anklicken der Schaltfläche können Ihre Nutzer/innen ein Bild ihres Reisepasses, Führerscheins oder Personalausweises erfassen und hochladen.
Das Modal reduziert die Entwicklungszeit und den Wartungsaufwand und ermöglicht die Erfassung von Identitätsnachweisen im Rahmen Ihrer bestehenden Abläufe. So wird auch die Menge der auf Ihrer Website verarbeiteten privaten Informationen reduziert. Außerdem können Sie Nutzer/innen auf verschiedenen Plattformen und in verschiedenen Sprachen unterstützen und das Design individuell an Ihr Branding anzupassen.
VerificationSession erstellen
Eine VerificationSession ist die programmgesteuerte Darstellung der Verifizierung. Sie enthält Details zur Art der Verifizierung (z. B. welche Prüfung durchgeführt werden soll). Sie können das Feld verifizierte Ergebnisse erweitern, um Details zu den verifizierten Daten anzuzeigen.
Nachdem Sie eine VerificationSession
erfolgreich erstellt haben, senden Sie das Client-Geheimnis an das Frontend, um das Modal zum Hochladen von Dokumenten anzuzeigen.
Sie benötigen einen serverseitigen Endpoint zum Erstellen der VerificationSession. Die serverseitige Erstellung der VerificationSession
verhindert, dass böswillige Nutzer/innen die Verifizierungsoptionen außer Kraft setzen und Abwicklungskosten für Ihr Konto verursachen. Fügen Sie dem Endpoint eine Authentifizierung hinzu, indem Sie einen Verweis auf die Nutzer/innen in die Metadaten der Sitzung einschließen oder die Sitzungs-ID in Ihrer Datenbank speichern.
// Set your secret key. Remember to switch to your live secret key in production. // See your keys here: https://dashboard.stripe.com/apikeys const stripe = require('stripe')(
); // In the route handler for /create-verification-session: // Authenticate your user. // Create the session. const verificationSession = await stripe.identity.verificationSessions.create({ type: 'document', metadata: { user_id: '{{USER_ID}}', }, }); // Return only the client secret to the frontend. const clientSecret = verificationSession.client_secret;'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
Vorsicht
Mit dem Client-Geheimnis kann Ihr Frontend sensible Verifizierungsinformationen erfassen. Es ist einmalig verwendbar und läuft nach 24 Stunden ab. Es darf nicht gespeichert, protokolliert, in URLs eingebettet oder Personen außer der Kundin/dem Kunden selbst zugänglich gemacht werden. Achten Sie darauf, dass auf jeder Seite, die das Client-Geheimnis enthält, TLS aktiviert ist. Senden Sie nur das Client-Geheimnis an Ihr Frontend, damit die Konfiguration oder die Ergebnisse der Verifizierung nicht weitergegeben werden.
Testen Sie Ihren Endpoint, indem Sie Ihren Webserver starten (z. B. localhost:4242
) und mit curl eine POST-Anfrage zur Erstellung einer VerificationSession senden:
curl -X POST -is "http://localhost:4242/create-verification-session" -d ""
Die Antwort in Ihrem Terminal sieht folgendermaßen aus:
HTTP/1.1 200 OK Content-Type: application/json { client_secret: "vs_QdfQQ6xfGNJR7ogV6..." }
Ereignis-Handler zur Schaltfläche „Verifizieren“ hinzufügen
Nachdem Sie jetzt eine Schaltfläche und einen Endpoint zum Erstellen einer VerificationSession haben, können Sie die Schaltfläche so anpassen, dass das Modal zum Hochladen von Dokumenten nach dem Anklicken angezeigt wird. Fügen Sie den Aufruf zu verifyIdentity
mithilfe des Client-Geheimnisses hinzu:
<html> <head> <title>Verify your identity</title> <script src="https://js.stripe.com/v3/"></script> </head> <body> <button id="verify-button">Verify</button> <script type="text/javascript"> // Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys var stripe = Stripe(
); var verifyButton = document.getElementById('verify-button'); verifyButton.addEventListener('click', function() { // Get the VerificationSession client secret using the server-side // endpoint you created in step 3. fetch('/create-verification-session', { method: 'POST', }) .then(function(response) { return response.json(); }) .then(function(session) { // Show the verification modal. return stripe.verifyIdentity(session.client_secret); }) .then(function(result) { // If `verifyIdentity` fails, you should display the localized // error message to your user using `error.message`. if (result.error) { alert(result.error.message); } }) .catch(function(error) { console.error('Error:', error); }); }); </script> </body> </html>'pk_test_TYooMQauvdEDq54NiTphI7jx'
Ereignisfehlercodes
Fehlercode | Beschreibung |
---|---|
consent_declined | Der/die Nutzer/in hat die Verifizierung durch Stripe abgelehnt. Erkundigen Sie sich bei Ihrer Rechtsberatung, ob Sie verpflichtet sind, alternative, nicht-biometrische Verifizierungsmethoden anzubieten, z. B. durch eine manuelle Überprüfung. |
device_unsupported | Für die Verifizierung ist eine Kamera erforderlich, und der/die Nutzer/in verwendet ein Gerät ohne Kamera. |
under_supported_age | Stripe verifiziert keine Nutzer/innen, die noch nicht volljährig sind. |
phone_otp_declined | Der/die Nutzer/in kann die angegebene Telefonnummer nicht verifizieren. |
email_verification_declined | Der/die Nutzer/in kann die angegebene E-Mail-Adresse nicht verifizieren. |
Modal zum Hochladen testen
Testen Sie, ob die Schaltfläche „Verifizieren“ ein Modal zum Hochladen von Dokumenten anzeigt:
- Klicken Sie auf die Schaltfläche „Verifizieren“, woraufhin sich das Stripe-Modal zum Hochladen von Dokumenten öffnet.
- Stellen Sie sicher, dass keine Fehlermeldungen angezeigt werden.
Wenn Ihre Integration nicht funktioniert:
- Öffnen Sie in den Entwickler-Tools Ihres Browsers die Registerkarte „Netzwerk“.
- Klicken Sie auf die Schaltfläche zur Verifizierung und prüfen Sie, ob eine XHR-Anfrage an Ihren serverseitigen Endpoint erfolgt (
POST /create-checkout-session
). - Prüfen Sie, ob die Anfrage den Status 200 zurückgibt.
- Verwenden Sie in Ihrem Button-Click-Listener
console.log(session)
, um zu prüfen, ob die richtigen Daten zurückgegeben werden.
Bestätigungsseite anzeigenClientseitig
Um den Prozess nutzerfreundlich zu gestalten, sollten Sie nach erfolgreicher Übermittlung des Identitätsnachweises eine Bestätigungsseite anzeigen. Hosten Sie die Seite auf Ihrer Website, damit die Nutzer/innen über den Bearbeitungsstatus der Prüfung informiert werden.
So erstellen Sie eine einfache Bestätigungsseite:
<html> <head><title>Your document was submitted</title></head> <body> <h1>Thanks for submitting your identity document.</h1> <p> We are processing your verification. </p> </body> </html>
Aktualisieren Sie als Nächstes den Schaltflächen-Handler, um zu dieser Seite weiterzuleiten:
<html> <head> <title>Verify your identity</title> <script src="https://js.stripe.com/v3/"></script> </head> <body> <button id="verify-button">Verify</button> <script type="text/javascript"> // Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys var stripe = Stripe(
) var verifyButton = document.getElementById('verify-button'); verifyButton.addEventListener('click', function() { // Get the VerificationSession client secret using the server-side // endpoint you created in step 3. fetch('/create-verification-session', { method: 'POST', }) .then(function(response) { return response.json(); }) .then(function(session) { // Show the verification modal. return stripe.verifyIdentity(session.client_secret); }) .then(function(result) { // If `verifyIdentity` fails, you should display the error message // using `error.message`. if (result.error) { alert(result.error.message); } else { window.location.href = 'submitted.html'; } }) .catch(function(error) { console.error('Error:', error); }); }); </script> </body> </html>'pk_test_TYooMQauvdEDq54NiTphI7jx'
Bestätigungsseite testen
Testen Sie, ob Ihre Bestätigungsseite funktioniert:
- Klicken Sie auf Ihre Schaltfläche zur Verifizierung.
- Übermitteln Sie die Sitzung, indem Sie einen vordefinierten Testfall auswählen.
- Prüfen Sie, ob die neue Bestätigungsseite angezeigt wird.
- Testen Sie den gesamten Ablauf auf mögliche Fehler (z. B. fehlende Zustimmung oder Nichtgewährung des Kamerazugriffs) und stellen Sie sicher, dass Ihre App diese ohne Einschränkungen verarbeitet.
Suchen Sie anschließend die Verifizierung im Stripe-Dashboard. Verifizierungssitzungen werden im Dashboard in der Liste der VerificationSessions angezeigt. Klicken Sie auf eine Sitzung, um zur Seite mit den Sitzungsdetails weitergeleitet zu werden. Der Abschnitt „Übersicht“ enthält Verifizierungsergebnisse, die Sie in Ihrer App verwenden können.
Verifizierungsereignisse verarbeiten
Dokumentprüfungen erfolgen asynchron, d. h., die Ergebnisse der Prüfung sind nicht sofort verfügbar. Die Prüfung eines Identitätsnachweises dauert in der Regel 1 bis 3 Minuten. Sobald die Verarbeitung abgeschlossen ist, ändert sich der Status der VerificationSession von processing
in verified
.
Stripe übermittelt die folgenden Ereignisse, wenn sich der Status einer Sitzung ändert:
Ereignisname | Beschreibung | Nächste Schritte |
---|---|---|
identity.verification_session.verified | Die Verarbeitung aller Verifizierungsprüfungen ist abgeschlossen und alle wurden erfolgreich verifiziert. | Lösen Sie relevante Aktionen in Ihrer Anwendung aus. |
identity.verification_session.requires_input | Die Verarbeitung aller Verifizierungsprüfungen ist abgeschlossen und mindestens eine dieser Prüfungen ist fehlgeschlagen. | Lösen Sie relevante Aktionen in Ihrer Anwendung aus und ermöglichen Sie Ihren Nutzer/innen, die Verifizierung zu wiederholen. |
Verwenden Sie einen Webhook-Handler, um diese Ereignisse zu empfangen und Aktionen wie das Senden einer E-Mail zur Bestätigung, das Aktualisieren der Verifizierungsergebnisse in Ihrer Datenbank oder das Abschließen eines Onboarding-Schritts zu automatisieren. Sie können die Verifizierungsereignisse auch im Dashboard anzeigen.
Ereignisse empfangen und Geschäftsaktionen ausführen
Mit Code
Erstellen Sie einen Webhook-Handler, um Ereignisse zu überwachen und benutzerdefinierte asynchrone Verifizierungsabläufe zu erstellen. Mit der Stripe-CLI können Sie Ihre Webhook-Integration lokal testen und Fehler beheben.
Nutzerdefinierten Webhook erstellen
Ohne Code
Verwenden Sie das Dashboard, um alle Ihre Verifizierungen anzuzeigen, die erfassten Daten zu prüfen und fehlgeschlagene Verifizierungen nachvollziehen zu können.