Weiter zum Inhalt
Konto erstellen oder anmelden
Das Logo der Stripe-Dokumentation
/
Konto erstellenAnmelden
ÜbersichtZahlung annehmenAktualisieren Sie Ihre Integration
Online-Zahlungen
ÜbersichtIhren Use case findenVerwenden Sie Managed PaymentsWiederkehrende Zahlungen
Präsenzzahlungen
Zahlungsmethoden
Zahlungsvorgänge
Salden und AbwicklungsdauerZahlungsbelegeRückerstattungen und Stornierungen
Erweiterte Integrationen
Mehr als Zahlungen

Hinweis

Bis jetzt ist diese Seite noch nicht in dieser Sprache verfügbar. Wir arbeiten aber verstärkt daran, unsere Dokumentation in weiteren Sprachen bereitzustellen, und werden die Übersetzung sofort anzeigen, sobald diese verfügbar ist.

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. 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.
  2. Wie erfolgreiche und fehlgeschlagene Verifizierungsprüfungen gehandhabt werden.
  3. Wie Sie Ihren Ereignis-Handler in der Produktionsumgebung aktivieren.

Verifizierungsprüfungen 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 immer dann, wenn sich ein Sitzungsstatus ändert. In diesem Leitfaden implementieren wir Webhooks, 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:

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Einen Webhook erstellen und VerificationSession-Ereignisse verarbeiten
Serverseitig

Ein webhook 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 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.

server.js
Node.js
Ruby
Python
PHP
Java
Go
.NET
No results
// 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')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

// 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 enthalten das Objekt VerificationSession, 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.

Stripe übermittelt die folgenden Ereignisse, wenn sich der Status einer Sitzung ändert:

EreignisnameBeschreibungNächste Schritte
identity.verification_session.verifiedDie Verarbeitung aller Verifizierungsprüfungen ist abgeschlossen, und alle waren erfolgreich.Lösen Sie relevante Aktionen in Ihrer Anwendung aus.
identity.verification_session.requires_inputDie 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.

Ihr Webhook-Code muss die Ereignisse identity.verification_session.verified und identity.verification_session.requires_input verarbeiten. Sie können weitere Sitzungsereignisse 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:

server.js
Node.js
Ruby
Python
PHP
Java
Go
.NET
No results
// 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')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

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

  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 der verifizierten Ausgaben 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 der Verifizierungssitzung untersuchen, um mit bestimmten Fehlerursachen umzugehen:

  • Das Feld last_error.code kann zum programmgesteuerten Umgang mit Verifizierungsfehlern verwendet werden.
  • Das Feld last_error.reason enthält eine Beschreibung der Fehlerursache und kann Ihren Nutzer/innen angezeigt werden.

Fehlercodes für Ereignisse

FehlercodeBeschreibung
consent_declinedDer/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_ageStripe verifiziert keine Nutzer/innen, die minderjährig sind.
country_not_supportedStripe verifiziert keine Nutzer/innen aus dem angegebenen Land.

Fügen Sie Ihrem Ereignis-Handler Code hinzu, um Fehler bei der Verifizierungsprüfung zu bearbeiten:

server.js
Node.js
Ruby
Python
PHP
Java
Go
.NET
No results
// 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')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

// 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 durchzugehen, um einen reibungslosen Übergang zu gewährleisten, wenn Sie Ihre Integration live schalten.

Webhook-Endpoints werden Workbench oder programmgesteuert über die API konfiguriert.

Endpoint im Dashboard hinzufügen

  1. Klicken Sie in Workbench auf der Registerkarte Webhooks auf Ziel hinzufügen, um einen neuen Webhook-Endpoint hinzuzufügen.
  2. Geben Sie die Stripe-API-Version ein.
  3. Zu überwachende Ereignisse auswählen. Die vollständige Liste der Verifizierungssitzungsereignisse finden Sie hier.
  4. Klicken Sie auf Fortfahren und wählen Sie Webhook-Endpoint aus der Liste der verfügbaren Zieltypen.
  5. Klicken Sie auf Weiter und geben Sie die URL Ihres Endpoints, einen optionalen Namen und eine optionale Beschreibung ein.
  6. Klicken Sie auf Ziel erstellen.

Endpoint mit der API hinzufügen

Sie können Webhook-Endpoints 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.

Command Line
curl https://api.stripe.com/v1/webhook_endpoints \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "url"="https://{{DOMAIN}}/my/webhook/endpoint" \
  -d "enabled_events[]"="identity.verification_session.verified" \
  -d "enabled_events[]"="identity.verification_session.requires_input"

Siehe auch