Identitätsnachweise Ihrer Nutzer/innen verifizieren

Erstellen Sie Sitzungen und erfassen Sie Identitätsnachweise.

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 einrichten
Serverseitig

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ügen
Clientseitig

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:

verification.html
<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:

verification.html
<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:

verification.html
<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('pk_test_TYooMQauvdEDq54NiTphI7jx'
);
    </script>
  </body>
</html>

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.

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:

Command Line
curl -X POST -is "http://localhost:4242/create-verification-session" -d ""

Die Antwort in Ihrem Terminal sieht folgendermaßen aus:

Command Line
HTTP/1.1 200 OK
Content-Type: application/json

{ id: "vs_QdfQQ6xfGNJR7ogV6", client_secret: "vs_QdfQQ6xfGNJR7ogV6_secret_live_..."  }

Ereignis-Handler zur Schaltfläche „Verifizieren“ hinzufügen

Now that you have a button and an endpoint to create a VerificationSession, modify the button to show the document upload modal when clicked. Add a call to verifyIdentity using the client secret:

verification.html
<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('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

      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>

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.

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 anzeigen
Clientseitig

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:

submitted.html
<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:

verification.html
<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('pk_test_TYooMQauvdEDq54NiTphI7jx'
)

      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>

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

Document checks are typically completed as soon as the user redirects back to your site and you can retrieve the result from the API immediately. In some rare cases, the document verification isn’t ready yet and must continue asynchronously. In these cases, you’re notified through webhooks when the verification result is ready. After the processing completes, the VerificationSession status changes from processing to 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 waren erfolgreich.	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.

Testverifizierungen im Dashboard anzeigen