# Umgang mit Verifizierungsergebnissen Erfassen Sie die Ergebnisse der Identitätsprüfung, damit Ihre Integration automatisch Reaktionen auslösen kann. Sie haben Code erstellt, um [ein Modal zur Erfassung von Identitätsdokumenten anzuzeigen](https://docs.stripe.com/identity/verify-identity-documents.md). Wenn Ihre Nutzer/innen ein Dokument übermitteln, können Sie jetzt Verifizierungsergebnisse überwachen, um Reaktionen in Ihrer Anwendung auszulösen. In diesem Leitfaden lernen Sie Folgendes: 1. Wie Sie eine Ereignisbenachrichtigung erhalten, wenn die Verifizierung abgeschlossen ist. 1. Wie erfolgreiche und fehlgeschlagene Verifizierungsprüfungen gehandhabt werden. 1. Wie Sie Ihren Ereignis-Handler in der Produktionsumgebung aktivieren. [Verifizierungsprüfungen](https://docs.stripe.com/identity/verification-checks.md) sind asynchron, d. h. die Verifizierungsergebnisse sind nicht sofort verfügbar. Wenn die Verarbeitung abgeschlossen ist, wird der Status der VerificationSession aktualisiert, und die verifizierten Informationen sind verfügbar. Stripe generiert [Ereignisse](https://docs.stripe.com/api/events.md) immer dann, wenn sich ein Sitzungsstatus ändert. In diesem Leitfaden implementieren wir [Webhooks](https://docs.stripe.com/webhooks.md), um Ihre App zu benachrichtigen, wenn Verifizierungsergebnisse verfügbar sind. ## Stripe einrichten [Serverseitig] Installieren Sie unsere offiziellen Bibliotheken für den Zugriff auf die Stripe-API aus Ihrer Anwendung heraus: #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` ## Einen Webhook erstellen und VerificationSession-Ereignisse verarbeiten [Serverseitig] Im Leitfaden [Webhook-Endpoint erstellen](https://docs.stripe.com/webhooks/quickstart.md) finden Sie eine schrittweise Erläuterung des Verfahrens zum Erstellen eines Webhook-Endpoints. Ein [webhook](https://docs.stripe.com/webhooks.md) ist ein Endppoint auf Ihrem Server, der Anfragen von Stripe empfängt und Sie über Ereignisse auf Ihrem Konto benachrichtigt. In diesem Schritt erstellen wir einen Endpoint, der Ereignisse zu VerificationSession [Statusänderungen](https://docs.stripe.com/identity/verification-sessions.md) empfängt. Webhook-Endpoints müssen öffentlich zugänglich sein, damit Stripe nicht authentifizierte Anfragen senden kann. Sie müssen jedoch anhand der Stripe-Bibliothek und des Anfrage-Headers überprüfen, ob Stripe das Ereignis gesendet hat. #### Node.js ```javascript // Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. // Find your keys at https://dashboard.stripe.com/apikeys. const stripe = require('stripe')('<>'); // You can find your endpoint's secret in your webhook settings const endpointSecret = 'whsec_...'; // This example uses Express to receive webhooks const express = require('express'); // Use body-parser to retrieve the raw body as a buffer const bodyParser = require('body-parser'); const app = express(); // Use JSON parser for all non-webhook routes app.use((req, res, next) => { if (req.originalUrl === '/webhook') { next(); } else { bodyParser.json()(req, res, next); } }); app.post('/webhook', bodyParser.raw({type: 'application/json'}), (req, res) => { let event; // Verify the event came from Stripe try { const sig = req.headers['stripe-signature']; event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret); } catch (err) { // On error, log and return the error message console.log(`❌ Error message: ${err.message}`); return res.status(400).send(`Webhook Error: ${err.message}`); } // Successfully constructed event res.json({received: true}); }); app.listen(4242, () => { console.log('Running on port 4242'); }); ``` Nachdem Sie nun über die grundlegende Struktur und Sicherheit verfügen, um Benachrichtigungen von Stripe zu überwachen, aktualisieren Sie Ihren Webhook-Endpoint, um Verifizierungssitzungsereignisse zu verarbeiten. Alle [Sitzungsereignisse](https://docs.stripe.com/identity/verification-sessions.md#events) enthalten das Objekt [VerificationSession](https://docs.stripe.com/api/identity/verification_sessions.md), das Details zu den durchgeführten Verifizierungsprüfungen enthält. Weitere Informationen zum Abrufen verifizierter Informationen, die nicht in Sitzungsereignissen enthalten sind, finden Sie unter [Auf Verifizierungsergebnisse zugreifen](https://docs.stripe.com/identity/access-verification-results.md). Stripe übermittelt die folgenden Ereignisse, wenn sich der Status einer Sitzung ändert: | Ereignisname | Beschreibung | Nächste Schritte | | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | [identity.verification_session.verified](https://docs.stripe.com/api/events/types.md#event_types-identity.verification_session.verified) | Die Verarbeitung aller [Verifizierungsprüfungen](https://docs.stripe.com/identity/verification-checks.md) ist abgeschlossen, und alle waren erfolgreich. | Lösen Sie relevante Aktionen in Ihrer Anwendung aus. | | [identity.verification_session.requires_input](https://docs.stripe.com/api/events/types.md#event_types-identity.verification_session.requires_input) | Die Verarbeitung aller [Verifizierungsprüfungen](https://docs.stripe.com/identity/verification-checks.md) 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. | Ihr Webhook-Code muss die Ereignisse `identity.verification_session.verified` und `identity.verification_session.requires_input` verarbeiten. Sie können weitere [Sitzungsereignisse](https://docs.stripe.com/identity/verification-sessions.md#events) abonnieren, um zusätzliche Reaktionen in Ihrer App auszulösen. ### Änderung am Status der VerificationSession verarbeiten Das Ereignis `identity.verification_session.verified` wird gesendet, wenn die Verifizierungsprüfungen abgeschlossen wurden, und alle erfolgreich waren. Fügen Sie Ihrem Ereignis-Handler Code hinzu, um alle Verifizierungsprüfungen zu verarbeiten: #### Node.js ```javascript // Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. // Find your keys at https://dashboard.stripe.com/apikeys. const stripe = require('stripe')('<>'); // You can find your endpoint's secret in your webhook settings const endpointSecret = 'whsec_...'; // This example uses Express to receive webhooks const express = require('express'); // Use body-parser to retrieve the raw body as a buffer const bodyParser = require('body-parser'); const app = express(); // Use JSON parser for all non-webhook routes app.use((req, res, next) => { if (req.originalUrl === '/webhook') { next(); } else { bodyParser.json()(req, res, next); } }); app.post('/webhook', bodyParser.raw({type: 'application/json'}), (req, res) => { let event; // Verify the event came from Stripe try { const sig = req.headers['stripe-signature']; event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret); } catch (err) { // On error, log and return the error message console.log(`❌ Error message: ${err.message}`); return res.status(400).send(`Webhook Error: ${err.message}`); } // Successfully constructed eventswitch (event.type) { case 'identity.verification_session.verified': { // All the verification checks passed const verificationSession = event.data.object; break; } } res.json({received: true}); }); app.listen(4242, () => { console.log('Running on port 4242'); }); ``` Beim Umgang mit diesem Ereignis können Sie auch Folgendes berücksichtigen: - Speichern des Verifizierungsstatus in Ihrer eigenen Datenbank - Senden einer E-Mail an Ihre Nutzer/innen, um sie darüber zu informieren, dass sie verifiziert wurden - [Erweitern](https://docs.stripe.com/api/expanding_objects.md) der [verifizierten Ausgaben](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-verified_outputs) der VerificationSession und Vergleich mit einem erwarteten Wert ### Änderungen am Status „requires_input“ der VerificationSession verarbeiten Das Ereignis `identity.verification_session.requires_input` wird gesendet, wenn mindestens eine der Prüfungen fehlgeschlagen ist. Sie können den Hash [last_error](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-last_error) der Verifizierungssitzung untersuchen, um mit bestimmten Fehlerursachen umzugehen: - Das Feld [last_error.code](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-last_error-code) kann zum programmgesteuerten Umgang mit Verifizierungsfehlern verwendet werden. - Das Feld [last_error.reason](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-last_error-reason) enthält eine Beschreibung der Fehlerursache und kann Ihren Nutzer/innen angezeigt werden. #### Fehlercodes für Ereignisse #### Sitzung | Fehlercode | Beschreibung | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `consent_declined` | Der/die Nutzer/in lehnte es ab, von Stripe verifiziert zu werden. Erkundigen Sie sich bei Ihrer Rechtsberatung, ob Sie verpflichtet sind, alternative, nicht-biometrische Verifizierungsmethoden anzubieten, z. B. durch eine manuelle Überprüfung. | | `under_supported_age` | Stripe verifiziert keine Nutzer/innen, die minderjährig sind. | | `country_not_supported` | Stripe verifiziert keine Nutzer/innen aus dem angegebenen Land. | #### Dokument | Fehlercode | Beschreibung | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `document_expired` | Das eingereichte Identitätsdokument ist abgelaufen. | | `document_unverified_other` | Stripe konnte das eingereichte Identitätsdokument nicht verifizieren. [Prüfen Sie die Liste unterstützter Dokumententypen](https://docs.stripe.com/identity/verification-checks.md?type=document). | | `document_type_not_supported` | Das eingereichte Identitätsdokument gehört nicht zu den [erlaubten Dokumententypen](https://docs.stripe.com/api/identity/verification_sessions/create.md#create_identity_verification_session-options-document-allow_document_types) der Sitzung. | #### Selfie | Fehlercode | Beschreibung | | ------------------------------- | ------------------------------------------------------------------------------- | | `selfie_document_missing_photo` | Das eingereichte Identitätsdokument enthält keine Aufnahme eines Gesichts. | | `selfie_face_mismatch` | Das aufgenommene Gesichtsbild stimmt nicht mit dem Gesicht im Dokument überein. | | `selfie_unverified_other` | Stripe konnte das eingereichte Selfie nicht verifizieren. | | `selfie_manipulated` | Die Gesichtsaufnahme wurde verfälscht oder in betrügerischer Weise verändert. | #### Ausweisnummer | Fehlercode | Beschreibung | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id_number_unverified_other` | Stripe konnte die angegebene ID-Nummer nicht verifizieren. [Siehe die Liste der unterstützten ID-Nummern](https://docs.stripe.com/identity/verification-checks.md?type=id-number). | | `id_number_insufficient_document_data` | Das bereitgestellte Dokument enthält nicht genügend Daten für den Abgleich mit der ID-Nummer. | | `id_number_mismatch` | Die bereitgestellten Informationen konnten nicht mit globalen Datenbanken abgeglichen werden. | #### Adresse (nur auf Einladung) | Fehlercode | Beschreibung | | ------------------ | --------------------------------------------------------------------------------------------- | | `address_mismatch` | Die bereitgestellten Informationen konnten nicht mit globalen Datenbanken abgeglichen werden. | Fügen Sie Ihrem Ereignis-Handler Code hinzu, um Fehler bei der Verifizierungsprüfung zu bearbeiten: #### Node.js ```javascript // Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. // Find your keys at https://dashboard.stripe.com/apikeys. const stripe = require('stripe')('<>'); // You can find your endpoint's secret in your webhook settings const endpointSecret = 'whsec_...'; // This example uses Express to receive webhooks const express = require('express'); // Use body-parser to retrieve the raw body as a buffer const bodyParser = require('body-parser'); const app = express(); // Use JSON parser for all non-webhook routes app.use((req, res, next) => { if (req.originalUrl === '/webhook') { next(); } else { bodyParser.json()(req, res, next); } }); app.post('/webhook', bodyParser.raw({type: 'application/json'}), (req, res) => { let event; // Verify the event came from Stripe try { const sig = req.headers['stripe-signature']; event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret); } catch (err) { // On error, log and return the error message console.log(`❌ Error message: ${err.message}`); return res.status(400).send(`Webhook Error: ${err.message}`); } // Successfully constructed event switch (event.type) { case 'identity.verification_session.verified': { // All the verification checks passed const verificationSession = event.data.object; break; }case 'identity.verification_session.requires_input': { // At least one of the verification checks failed const verificationSession = event.data.object; console.log('Verification check failed: ' + verificationSession.last_error.reason); // Handle specific failure reasons switch (verificationSession.last_error.code) { case 'document_unverified_other': { // The document was invalid break; } case 'document_expired': { // The document was expired break; } case 'document_type_not_supported': { // document type not supported break; } default: { // ... } } } } res.json({received: true}); }); app.listen(4242, () => { console.log('Running on port 4242'); }); ``` Je nach Anwendungsszenario sollten Sie Ihren Nutzer/innen die Möglichkeit geben, die Überprüfung zu wiederholen, wenn sie fehlschlägt. Wir empfehlen Ihnen, die Anzahl der Übermittlungsversuche zu beschränken. Beim Umgang mit diesem Ereignis können Sie auch Folgendes berücksichtigen: - Manuelle Überprüfung der erfassten Informationen - Versand einer E-Mail an Ihre Nutzer/innen, um sie darüber zu informieren, dass ihre Verifizierung fehlgeschlagen ist - Bereitstellung einer alternativen Verifizierungsmethode für Ihre Nutzer/innen ## Live in Produktion gehen Nachdem Sie Ihren Ereignis-Handler-Endpoint in der Produktionsumgebung bereitgestellt haben, richten Sie den Endpoint so ein, dass Stripe weiß, wohin Live-Modus-Ereignisse gesendet werden sollen. Es ist auch hilfreich, die [Checkliste für die Entwicklung](https://docs.stripe.com/get-started/checklist/go-live.md) durchzugehen, um einen reibungslosen Übergang zu gewährleisten, wenn Sie Ihre Integration live schalten. Webhook-Endpoints werden [Workbench](https://docs.stripe.com/workbench.md) oder programmgesteuert über die API konfiguriert. ### Endpoint im Dashboard hinzufügen 1. Klicken Sie in Workbench auf der Registerkarte [Webhooks](https://dashboard.stripe.com/workbench/webhooks) auf **Ziel hinzufügen**, um einen neuen Webhook-Endpoint hinzuzufügen. 1. Geben Sie die Stripe-API-Version ein. 1. Zu überwachende Ereignisse auswählen. Die vollständige Liste der [Verifizierungssitzungsereignisse](https://docs.stripe.com/identity/verification-sessions.md#events) finden Sie hier. 1. Klicken Sie auf **Fortfahren** und wählen Sie **Webhook-Endpoint** aus der Liste der verfügbaren Zieltypen. 1. Klicken Sie auf **Weiter** und geben Sie die URL Ihres Endpoints, einen optionalen Namen und eine optionale Beschreibung ein. 1. Klicken Sie auf **Ziel erstellen**. ### Endpoint mit der API hinzufügen Sie können [Webhook-Endpoints](https://docs.stripe.com/api/webhook_endpoints/create.md) auch programmgesteuert erstellen. Wie im Formular in Workbench können Sie eine beliebige URL als Ziel für Ereignisse eingeben und festlegen, welche Ereignistypen abonniert werden sollen. ```bash curl https://api.stripe.com/v1/webhook_endpoints \ -u <>: \ -d "url"="https://{{DOMAIN}}/my/webhook/endpoint" \ -d "enabled_events[]"="identity.verification_session.verified" \ -d "enabled_events[]"="identity.verification_session.requires_input" ``` ## See also - [Webhook-Endpoint testen](https://docs.stripe.com/webhooks.md#test-webhook) - [Best Practices für die Verwendung von Webhooks](https://docs.stripe.com/webhooks.md#best-practices) - [Checkliste für die Webhook-Entwicklung](https://docs.stripe.com/get-started/checklist/go-live.md)