# API für Verification Sessions Erfahren Sie, wie Sie die Verification Sessions API für Stripe Identity verwenden. Verwenden Sie die [Verification Session API](https://docs.stripe.com/api/identity/verification_sessions.md), um Daten auf sichere Weise zu erfassen und [Verifizierungsprüfungen](https://docs.stripe.com/identity/verification-checks.md) 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](https://docs.stripe.com/identity/verify-identity-documents.md). ## VerificationSession erstellen Wenn Sie die [VerificationSession erstellen](https://docs.stripe.com/api/identity/verification_sessions/create.md), legen Sie fest, welche [Verifizierungsprüfung](https://docs.stripe.com/identity/verification-checks.md) ausgeführt werden soll, indem Sie den [type](https://docs.stripe.com/api/identity/verification_sessions/create.md#create_identity_verification_session-type) der Sitzung angeben: - [document](https://docs.stripe.com/identity/verification-checks.md?type=document) – Verifizieren Sie die Echtheit und die Inhaberschaft von behördlich ausgestellten Ausweisdokumenten. Dies kann auch eine Selfie-Prüfung umfassen. - [id_number](https://docs.stripe.com/identity/verification-checks.md?type=id-number) – Verifizieren Sie den Namen, das Geburtsdatum und die Nummer des nationalen Ausweisdokuments einer Nutzerin/eines Nutzers. ```curl curl https://api.stripe.com/v1/identity/verification_sessions \ -u "<>:" \ -d type=document ``` ### 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](https://docs.stripe.com/api/identity/verification_sessions/retrieve.md) 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](https://docs.stripe.com/api/idempotent_requests.md) 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. ## Passing the client secret to the front end Die VerificationSession enthält ein [Client-Geheimnis](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-client_secret), einen Schlüssel, der für jede einzelne VerificationSession einmalig ist. Das Frontend verwendet das Client-Geheimnis, um die Verifizierung abzuschließen. To use the client secret, you must obtain it from the VerificationSession on your server and pass it to the front end. You can retrieve the client secret from an endpoint on your server using the browser’s `fetch` function on the client. This approach is generally most suitable when the client is a single-page application, especially one built with a modern front-end framework such as React. Dieses Beispiel zeigt, wie Sie einen Server-Endpoint erstellen, der das Client-Geheimnis bereitstellt. #### 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')('<>'); // In the route handler for /create-verification-session: // Authenticate your user. // Create the session. const verificationSession = await stripe.identity.verificationSessions.create({ type: 'document', provided_details: { email: 'user@example.com', }, metadata: { user_id: '{{USER_ID}}', }, }); // Return only the client secret to the frontend. const clientSecret = verificationSession.client_secret; ``` Dieses Beispiel zeigt, wie Sie das Client-Geheimnis mit JavaScript auf der Client-Seite abrufen: ```javascript (async () => { const response = await fetch('/create-verification-session'); const {client_secret: clientSecret} = await response.json(); // Call stripe.verifyIdentity() with the client secret. })(); ``` > 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* (TLS refers to the process of securely transmitting data between the client—the app or browser that your customer is using—and your server. This was originally performed using the SSL (Secure Sockets Layer) protocol) aktiviert ist. ## Auf Verifizierungsergebnisse zugreifen Durch Einreichen und Abwickeln einer VerificationSession wird der `status` der Sitzung aktualisiert und ein [VerificationReport](https://docs.stripe.com/api/identity/verification_reports/object.md) erstellt. Dies erfolgt in der Regel innerhalb weniger Minuten. After all of the verification checks have passed, the status changes to `verified`. You can [expand](https://docs.stripe.com/api/expanding_objects.md) the [verified_outputs](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-verified_outputs) field to see the verified data. ```json { "id": "vs_orWziM4j7CiRL8J4vQmXgW2w", "object": "identity.verification_session", "created": 1610744321, "last_error": null, "last_verification_report": "vr_orWziM4j7CiRL8J4vQmXgW2w", "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 } } ``` Wenn eine der Verifizierungsprüfungen fehlschlägt, hat die Sitzung den Status `requires_input`. Details zu Verifizierungsfehlern sind im Hash [last_error](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-last_error) der Sitzung verfügbar. Der Wert [last_error.code](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-last_error-code) kann zur programmgesteuerten Behandlung häufiger Verifizierungsfehler verwendet werden. Der [last_error.reason](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-last_error-code) enthält eine Zeichenfolge, die den Fehlergrund erklärt und Ihren Nutzer/innen angezeigt werden kann. ```json { "id": "vs_orWziM4j7CiRL8J4vQmXgW2w", "object": "identity.verification_session", "created": 1610744321, "last_error": { "code": "document_expired", "reason": "The document is expired." }, "last_verification_report": "vr_orWziM4j7CiRL8J4vQmXgW2w", "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](https://docs.stripe.com/api/identity/verification_sessions/retrieve.md), 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](https://docs.stripe.com/identity/access-verification-results.md) 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. ```curl curl -X POST https://api.stripe.com/v1/identity/verification_sessions/{{IDENTITYVERIFICATIONSESSION_ID}}/cancel \ -u "<>:" ``` ## VerificationSession entfernen Ein Grund, warum Sie eine Verifizierungssitzung eventuell schwärzen möchten, kann sein, dass Sie eine Anfrage zur Datenlöschung von Ihrem/Ihrer Nutzer/in erhalten. Sie können eine Sitzung schwärzen, um sicherzustellen, dass Stripe personenbezogene Daten löscht. Nachdem wir die personenbezogenen Daten gelöscht haben, werden sie nicht mehr von der Stripe API zurückgegeben und sind im Dashboard nicht mehr sichtbar. Sie können geschwärzte Sitzungen weiterhin [mit der API abrufen](https://docs.stripe.com/api/identity/verification_sessions/retrieve.md), aber Sie können sie nicht aktualisieren. Sie können Sitzungen im Dashboard oder mit der API schwärzen: ```curl curl -X POST https://api.stripe.com/v1/identity/verification_sessions/{{IDENTITYVERIFICATIONSESSION_ID}}/redact \ -u "<>:" ``` Geschwärzte Sitzungen haben Platzhalterwerte in allen Feldern, die zuvor personenbezogene Daten (PII) enthielten. Die Sitzung enthält ein Feld [redaction.status](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-redaction-status), das den Status des Prozesses der Schwärzung angibt. Wir senden den Webhook [identity.verification_session.redacted](https://docs.stripe.com/api/events/types.md#event_types-identity.verification_session.redacted), wenn die Sitzung geschwärzt ist. Die Schwärzung kann bis zu 4 Tage dauern. Wenn eine geschwärzte 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 geschwärzten VerificationSession erweitert hat. ```json { "id": "vs_orWziM4j7CiRL8J4vQmXgW2w", "object": "identity.verification_session", "created": 1610744321, "last_error": null, "last_verification_report": "vr_orWziM4j7CiRL8J4vQmXgW2w", "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 } ``` Wir schwärzen alle mit der `VerificationSession` verknüpften [VerificationReports](https://docs.stripe.com/api/identity/verification_reports.md), [Ereignisse](https://docs.stripe.com/api/events.md) und [Anfrage-Logs](https://dashboard.stripe.com/logs). Nachdem wir den Inhalt der [Datei](https://docs.stripe.com/api/files.md) gelöscht haben, können Sie ihn nicht mehr herunterladen. 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](https://docs.stripe.com/api.md#metadata) 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. ```curl curl https://api.stripe.com/v1/identity/verification_sessions \ -u "<>:" \ -d type=document \ -d "metadata[user_id]={{USER_ID}}" \ -d "metadata[reference]={{IDENTIFIER}}" ``` 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](https://docs.stripe.com/api/events.md) erstellt. Hier ist eine vollständige Liste der [Ereignistypen](https://docs.stripe.com/api.md#event_types) in einer VerificationSession: | Ereignistyp | Beschreibung | | --- | --- | | `identity.verification_session.created` | Die Sitzung wurde [erstellt](https://docs.stripe.com/identity/verification-sessions.md#create). | | `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](https://docs.stripe.com/identity/verification-checks.md) ist abgeschlossen und alle waren erfolgreich. | | `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. | | `identity.verification_session.canceled` | Die Sitzung wurde abgebrochen und zukünftige Übermittlungsversuche wurden deaktiviert. Dieses Ereignis wird gesendet, wenn eine Sitzung [abgebrochen](https://docs.stripe.com/identity/verification-sessions.md#cancel) oder [entfernt](https://docs.stripe.com/identity/verification-sessions.md#redact) wird. | | `identity.verification_session.redacted` | Die Sitzung wurde [geschwärzt](https://docs.stripe.com/identity/verification-sessions.md#redact). Sie müssen einen [Webhook-Endpoint](https://docs.stripe.com/api/webhook_endpoints.md) erstellen, der diesen Ereignistyp explizit abonniert, um darauf zuzugreifen. 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](https://docs.stripe.com/identity/handle-verification-outcomes.md) entsprechende Ereignisse überwachen. ## See also - [Identitätsnachweise Ihrer Nutzer/innen verifizieren](https://docs.stripe.com/identity/verify-identity-documents.md)