API für Verification Sessions

Erfahren Sie, wie Sie die Verification Sessions API für Stripe Identity verwenden.

Verwenden Sie die Verification Session API, um Daten auf sichere Weise zu erfassen und Verifizierungsprüfungen durchzuführen. Diese API verfolgt eine Verifizierung von ihrer Erstellung über den gesamten Verifizierungsprozess hinweg nach und zeigt nach Abschluss die Verifizierungsergebnisse an.

Eine detaillierte Anleitung zur Überprüfung der Identitätsnachweise Ihrer Nutzer/innen mithilfe der Verification Session API finden Sie im zugehörigen Leitfaden: Identitätsnachweise Ihrer Nutzer/innen verifizieren.

VerificationSession erstellen

Wenn Sie die VerificationSession erstellen, legen Sie fest, welche Verifizierungsprüfung ausgeführt werden soll, indem Sie den type der Sitzung angeben:

document – Verifizieren Sie die Echtheit und die Inhaberschaft von behördlich ausgestellten Ausweisdokumenten. Dies kann auch eine Selfie-Prüfung umfassen.
id_number – Verifizieren Sie den Namen, das Geburtsdatum und die Nummer des nationalen Ausweisdokuments einer Nutzerin/eines Nutzers.

Best Practices

Wenn der Verifizierungsvorgang unterbrochen und später wieder aufgenommen wird, sollten Sie versuchen, dieselbe VerificationSession wiederzuverwenden, statt eine neue zu erstellen. Jede VerificationSession verfügt über eine einzigartige ID, mit deren Hilfe Sie sie abrufen können. Im Datenmodell Ihrer Anwendung können Sie die ID der VerificationSession speichern, um das Abrufen zu ermöglichen.

Der Vorteil einer Wiederverwendung der VerificationSession besteht darin, dass das Objekt dabei hilft, alle fehlgeschlagenen Verifizierungsversuche nachzuverfolgen. Sollten eine oder mehrere dieser Prüfungen fehlschlagen, nimmt die VerificationSession den Status requires_input an.

Wir empfehlen, beim Erstellen der VerificationSession außerdem einen Idempotenz-Schlüssel anzugeben, um zu vermeiden, dass fälschlicherweise doppelte VerificationSessions für dieselbe Person erstellt werden. Dieser Schlüssel basiert üblicherweise auf der ID, die Sie in Ihrer Anwendung mit der Verifizierung verknüpfen, zum Beispiel eine Nutzerreferenz.

Das Client-Geheimnis an das Frontend übergeben

Die VerificationSession enthält ein Client-Geheimnis, einen Schlüssel, der für jede einzelne VerificationSession einmalig ist. Das Frontend verwendet das Client-Geheimnis, um die Verifizierung abzuschließen.

Um das Client-Geheimnis zu verwenden, müssen Sie es von der VerificationSession auf Ihrem Server beziehen und an das Frontend übergeben. Sie können das Client-Geheimnis mit der fetch-Funktion des Browsers auf dem Client von einem Endpoint auf Ihrem Server abrufen. Diese Vorgehensweise bietet sich an, wenn Sie auf dem Client über eine einseitige Anwendung verfügen, die mit einem modernen Front-End-Framework wie React erstellt wurde.

Dieses Beispiel zeigt, wie Sie einen Server-Endpoint erstellen, der das Client-Geheimnis bereitstellt.

Dieses Beispiel zeigt, wie Sie das Client-Geheimnis mit JavaScript auf der Client-Seite abrufen:

(async () => {
  const response = await fetch('/create-verification-session');
  const {client_secret: clientSecret} = await response.json();
  // Call stripe.verifyIdentity() with the client secret.
})();

Notiz

Das Client-Geheimnis ist ein sensibler Token, den Sie für die Verifizierung verwenden können. Er darf nicht protokolliert, in URLs eingebettet oder Personen außer den zu verifizierenden Personen selbst zugänglich gemacht werden. Achten Sie darauf, dass auf jeder Seite, die das Client-Geheimnis enthält, TLS aktiviert ist.

Auf Verifizierungsergebnisse zugreifen

Durch Einreichen und Abwickeln einer VerificationSession wird der status der Sitzung aktualisiert und ein VerificationReport erstellt. Dies erfolgt in der Regel innerhalb weniger Minuten.

Sobald alle Verifizierungsprüfungen erfolgreich abgeschlossen sind, wechselt der Status auf verified. Sie können dann das Feld verified_outputs erweitern, um die verifizierten Daten anzuzeigen.

{
  "id": "vs_yjIXWw4v6dIIoATbp9hMeAMv",
  "object": "identity.verification_session",
  "created": 1610744321,
  "last_error": null,
  "last_verification_report": "vr_2A0eTnZuCazI5g8LkiWFbmZe",
  "livemode": true,
  "metadata": {},
  "options": {
    "document": {},
  },
  "status": "verified",
  "type": "document",
  "redaction": null,
  "url": null,
  "verified_outputs": {
    "first_name": "Jenny",
    "last_name": "Rosen",
    "address": {
      "line1": "1234 Main St.",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94111",
      "country": "US"
    },
    "id_number_type": null
  }
}

If any of the verification checks fail, the session will have a requires_input status. Verification failure details are available in the session last_error hash. The last_error.code value can be used to programmatically handle common verification failures. The last_error.reason will contain a string that explains the failure reason and can be shown to your user.

{
  "id": "vs_2Aej2aW2KK4bdZac7kkNLXtX",
  "object": "identity.verification_session",
  "created": 1610744321,
  "last_error": {
    "code": "document_expired",
    "reason": "The document is expired.",
  },
  "last_verification_report": "vr_CR5m6nPqzGiTzM6Vnrx1k3MW",
  "livemode": true,
  "metadata": {},
  "options": {},
  "status": "requires_input",
  "type": "document",
  "redaction": null,
  "url": null,
}

Wenn Sie möchten, dass Ihre/e Nutzer/in einen erneuten Verifizierungsversuch durchführt, müssen Sie die VerificationSession abrufen, um eine neue URL bzw. ein neues Client-Geheimnis zu erhalten, das Sie an Ihren Client übergeben können.

So greifen Sie auf sensible Verifizierungsergebnisse zu

VerificationSession abbrechen

Sie können eine VerificationSession jederzeit stornieren, bevor sie den Status processing oder verified annimmt. Dadurch wird die VerificationSession für zukünftige Übermittlungsversuche ungültig und dies kann nicht rückgängig gemacht werden. Die Sitzung nimmt dann den Status canceled an.

VerificationSession entfernen

Einer der Gründe, eine Verifizierungssitzung zu schwärzen, ist, wenn Sie von Ihrem/Ihrer Nutzer/in einen Antrag auf Datenlöschung erhalten. Sie können eine Sitzung entfernen, um sicherzustellen, dass erfasste Informationen nicht länger von der Stripe-API zurückgegeben werden oder im Dashboard sichtbar sind. Sie können entfernte Sitzungen weiterhin mithilfe der API abrufen, können sie jedoch nicht aktualisieren. Sitzungen können über das Dashboard oder die API entfernt werden:

Entfernte Sitzungen zeigen Platzhalterwerte für alle Felder an, die zuvor personenbezogene Daten enthielten. Die Sitzung beinhaltet das Feld redaction.status, das den Status des Entfernungsvorgangs angibt. Ein identity.verification_session.redacted-Webhook wird gesendet, wenn die Sitzung entfernt wurde. Das Entfernen kann bis zu 4 Tage dauern.

Wenn eine entfernte VerificationSession mit erweiterten PII-Feldern abgerufen wird, werden diese Felder weiterhin in der Antwort angezeigt, aber ihre Werte enthalten keine PII. Hier ist zum Beispiel eine Antwort, die die Felder verified_outputs und verified_outputs.dob in einer entfernten VerificationSession erweitert hat.

{
  "id": "vs_EMHuXNgDCgAQjdNTmSD3o2DR",
  "object": "identity.verification_session",
  "created": 1610744321,
  "last_error": null,
  "last_verification_report": "vr_0QZiDT1OQDHyxKxczG1Cd3fM",
  "livemode": true,
  "options": {},
  "status": "verified",
  "type": "document",
  "url": null,
  "client_secret": null,
  "redaction": {
    "status": "redacted"
  },
  "verified_outputs": {
    "first_name": "[redacted]",
    "last_name": "[redacted]",
    "dob": {
      "year": 1,
      "month": 1,
      "day": 1
    },
    "address": {
      "line1": "[redacted]",
      "city": "[redacted]",
      "state": "[redacted]",
      "postal_code": "[redacted]",
      "country": "US"
    },
    "id_number_type": null
  },
  "metadata": {} // Metadata will also be redacted
}

Alle mit der VerificationSession verknüpften VerificationReports, Ereignisse und Anfrageprotokolle werden ebenfalls entfernt und Dateiinhalte können nicht länger heruntergeladen werden.

Wenn sich die VerificationSession im Status processing befindet, müssen Sie warten, bis sie abgeschlossen ist, bevor sie entfernt werden kann. Durch Entfernen einer VerificationSession mit dem Status requires_action wird diese automatisch abgebrochen.

Informationen in Metadaten speichern

Stripe unterstützt das Hinzufügen von Metadaten zum VerificationSession-Objekt. Metadaten sind für Kundinnen/Kunden nicht sichtbar und fließen auch nicht in die Kriterien ein, ob eine Verifizierungsprüfung erfolgreich ist oder fehlschlägt.

Mithilfe von Metadaten können Sie andere Informationen, die für Ihre Abläufe wichtig sind, mit Stripe-Aktivitäten verknüpfen. Alle Metadaten, die Sie angeben, lassen sich im Dashboard (z. B. auf der Detailseite einer Sitzung) anzeigen und stehen auch in allgemeinen Berichten zur Verfügung. Zum Beispiel können Sie die Nutzer-ID Ihrer Anwendung an die VerificationSession anhängen, um diese/n Nutzer/in zu verifizieren, damit Sie oder Ihr Team die Verifizierungen in Stripe den jeweiligen Nutzer/innen in Ihrem System zuordnen können.

Wir empfehlen Ihnen, keine vertraulichen Informationen wie personenbezogene Daten, ID-Nummern usw. in Sitzungs-Metadaten zu speichern. Metadaten werden beim Schwärzen einer VerificationSession entfernt.

Sitzungsereignisse

Jedes Mal, wenn sich der Status einer Sitzung ändert, werden Ereignisse erstellt. Hier ist eine vollständige Liste der Ereignistypen in einer VerificationSession:

Ereignistyp	Beschreibung
`identity.verification_session.created`	Die Sitzung wurde erstellt.
`identity.verification_session.processing`	Die Nutzerin oder der Nutzer hat ihre bzw. seine Informationen erfolgreich übermittelt und die Verifizierungsprüfungen wurden gestartet.
`identity.verification_session.verified`	Die Verarbeitung aller Verifizierungsprüfungen ist abgeschlossen und alle waren erfolgreich.
`identity.verification_session.requires_input`	Die Verarbeitung aller Verifizierungsprüfungen ist abgeschlossen und mindestens eine dieser Prüfungen ist fehlgeschlagen.
`identity.verification_session.canceled`	Die Sitzung wurde abgebrochen und zukünftige Übermittlungsversuche wurden deaktiviert. Dieses Ereignis wird gesendet, wenn eine Sitzung abgebrochen oder entfernt wird.
`identity.verification_session.redacted`	Die Sitzung wurde entfernt. Um darauf zuzugreifen, müssen Sie einen Webhook-Endpoint erstellen, der diesen Ereignistyp ausdrücklich abonniert. Webhook-Endpoints, die alle Ereignisse abonnieren, enthalten diesen Ereignistyp nicht.

In Reaktion auf bestimmte Ereignisse möchten Sie gegebenenfalls bestimmte Aktionen ausführen, wie eine E-Mail an eine Nutzerin oder einen Nutzer senden, wenn eine Verifizierung erfolgreich ist oder fehlschlägt.

Stripe empfiehlt, dass Sie mit Webhooks entsprechende Ereignisse überwachen.

Siehe auch

Identitätsnachweise Ihrer Nutzer/innen verifizieren