Zum Hauptinhalt springen
Verwenden Sie einen dedizierten Wallet-Endpoint, um eine Person aus Ihrer eigenen Anwendung zu verifizieren. Sie müssen keinen Workflow erstellen oder veröffentlichen und keine workflow_id angeben. Ihr Backend startet die Verifizierung und ruft ihr Ergebnis ab. Ihre Oberfläche führt die Person durch die vom Wallet geforderte Authentifizierung.
Bei einer API-Integration muss sich die Person weiterhin authentifizieren und die Weitergabe ihrer Identität genehmigen. Ohne diese Interaktion können Sie niemanden verifizieren, indem Sie dessen persönliche Kennung übermitteln.

Wie die Verifizierung funktioniert

  1. Ihr Backend prüft den Wallet-Katalog und ruft dann mit Ihrem API-Schlüssel den Start-Endpoint eines verfügbaren Wallets auf.
  2. Didit gibt eine Verifizierungsreferenz und die Aktion zurück, die die Person ausführen muss.
  3. Ihre Anwendung öffnet die Authentifizierungsseite oder zeigt die Freigabeanweisungen des Wallets an.
  4. Die Person authentifiziert sich mit ihrem Wallet.
  5. Ihr Backend ruft das verifizierte Ergebnis ab und verarbeitet die Abschlussbenachrichtigungen.
Die Wallet-Authentifizierung ist asynchron. Eine erfolgreiche Startanfrage bedeutet, dass die Authentifizierung begonnen hat. Sie bedeutet nicht, dass die Identität verifiziert wurde. Prüfen Sie immer das endgültige Ergebnis, bevor Sie die Person als verifiziert behandeln.

Backend-Integration

Verwenden Sie Digitale ID-Wallets auflisten, um die aktuellen Endpoints, Pflichtfelder und die Verfügbarkeit für Ihre Anwendung abzurufen. Bewahren Sie Ihren x-api-key auf Ihrem Backend auf. Platzieren Sie ihn nicht in einem Browser-Bundle oder in einer mobilen Anwendung. Verwenden Sie für jeden neuen Verifizierungsversuch einen eigenen Idempotency-Key, und verwenden Sie diesen Schlüssel erneut, wenn Sie dieselbe Startanfrage wiederholen. Eine Änderung der Anfrage bei Wiederverwendung ihres Schlüssels ist ein Konflikt und kein neuer Verifizierungsversuch. Jedes Wallet hat eine eigene Start-URL, etwa /v3/id-verification/wallets/ftn/ für Finnish Trust Network. Die request_id identifiziert die eigenständige Verifizierung für nachfolgende Vorgänge. Verwenden Sie vendor_data für Ihre eigene Referenz, bis zu 2.000 UTF-8-Bytes, und metadata für ein optionales JSON-Objekt. Beide werden zusammen mit dem Ergebnis und dem Abschluss-Webhook zurückgegeben. Diese Vorgänge verwenden den API-Schlüssel der Anwendung, die die Verifizierung gestartet hat. Abfragen und die Verfügbarkeit der Authentifizierung hängen vom gewählten Wallet ab. Ein Abbruch lehnt eine ausstehende Verifizierung ab, ohne dafür Gebühren zu berechnen, und gibt eine abgeschlossene Verifizierung unverändert zurück. Bei Smart-ID und Mobile-ID wartet eine Stornierung, die eintrifft, während eine Abfrage die Freigabe prüft, einige Sekunden auf diese Abfrage. Danach lehnt sie die Verifizierung ab oder gibt sie als verified zurück, falls die Person bereits zugestimmt hatte. Eine Verifizierung, die die Person in diesem Moment abschließt, kann nicht storniert werden. Die Antwort ist 409 mit error: "verification_in_progress" und einem Retry-After-Header. Wiederholen Sie den Aufruf nach so vielen Sekunden, um das abgeschlossene Ergebnis abzurufen.

Ihr Rückgabeziel registrieren

Wallets mit Weiterleitung senden die Person nach der Authentifizierung zurück zu Ihrer Anwendung. Registrieren Sie den exakten Hostnamen, bevor Sie eine Verifizierung starten:
Senden Sie dann in der Startanfrage eine HTTPS-return_url, etwa https://app.example.com/identity/complete. Verwenden Sie in allowed_return_hosts nur reine Hostnamen ohne Schema, Pfad oder Wildcard. Registrieren Sie jede Subdomain, die Sie verwenden, separat, bis zu 20 Hostnamen. Eine Aktualisierung von allowed_return_hosts ersetzt die registrierte Liste. Nehmen Sie deshalb jeden Hostnamen auf, den Sie behalten möchten. GET /v3/webhook/ gibt die aktuelle Liste zurück; siehe Webhook-Konfiguration. Sie benötigen weder einen Workflow noch eine White-Label-Domain, um ein Rückgabeziel zu registrieren. Das Ziel ist eine Rückgabeseite im Browser. Konfigurieren Sie Abschluss-Webhooks separat für Ihr Backend.

Beispiel: Finnish Trust Network

Nachdem Sie Ihren Rückgabe-Hostnamen registriert haben, starten Sie eine Verifizierung mit Finnish Trust Network:
Speichern Sie die zurückgegebene request_id und leiten Sie den Browser der Person zu wallet_verification.next_action.url weiter, wenn sein type redirect ist. Nachdem die Person zurückgekehrt ist, rufen Sie das Ergebnis von Ihrem Backend ab:
Prüfen Sie wallet_verification.outcome: Verwenden Sie die Identität nur, wenn das Ergebnis verified ist und simulated bei einer echten Identitätsprüfung false ist. Eine ausstehende Antwort kann eine nächste Aktion enthalten. Abschließende Antworten haben keine nächste Aktion.

Authentifizierungsabläufe

Redirect-Wallets geben eine Authentifizierungs-URL zurück. Öffnen Sie diese URL im Browser der Person, lassen Sie sie den Authentifizierungsprozess der Wallet abschließen und leiten Sie sie zu Ihrem registrierten Ziel zurück. Lesen Sie das Ergebnis über Ihr Backend aus, statt einem Rückgabe-URL-Parameter als Identitätsnachweis zu vertrauen. Smart-ID und Mobile-ID verwenden eine Genehmigungsaufforderung auf dem Telefon der Person. Ihre Oberfläche erfasst die erforderliche persönliche Kennung; Mobile-ID benötigt zusätzlich die zugehörige Telefonnummer. Zeigen Sie den Vergleichscode an und weisen Sie die Person an, nur dann zu genehmigen, wenn er mit dem Code auf ihrem Telefon übereinstimmt. Ihre PIN gehört in die Aufforderung der Wallet oder des Telefons, niemals in Ihr Formular oder in einen API-Aufruf. Fragen Sie über Ihr Backend im zurückgegebenen poll_interval_seconds-Intervall ab, um Rückmeldungen zur Aufforderung zu erhalten. Didit prüft ausstehende Telefon-Genehmigungen außerdem im Hintergrund, sodass der Abschluss Ihren Webhook erreichen kann, nachdem die Person Ihre Seite geschlossen hat. Google Wallet wird von Ihrer eigenen Seite oder App über die Digital Credentials API angefragt, ohne Weiterleitung; siehe Digital-Credentials-Wallets (Google Wallet). Welche Interaktion verfügbar ist, hängt von der gewählten Wallet ab. Gehen Sie nicht davon aus, dass jede Wallet ein eingebettetes Formular, einen QR-Code oder eine Authentifizierung ohne Browser unterstützt.

Digital-Credentials-Wallets (Google Wallet)

Google Wallet wird direkt von Ihrer Webseite oder Android-App angefragt, über die W3C Digital Credentials API. Es gibt keine Weiterleitung, keine von Didit gehostete Seite und keinen QR-Code von Didit. Die Wallet ist in der Produktion und in der Sandbox verfügbar. Anwendungen in der Sandbox benötigen keine Registrierung; jede Produktionsanwendung registriert sich einmal in der Konsole (Schritt zur Ausweisverifizierung, Zeile Google Wallet, Register with Google), bevor sie Google Wallet nutzen kann. Unter Digitale ID-Wallets auflisten sehen Sie, was Ihre Anwendung jetzt starten kann.
1

Mit Ihrem Origin starten

Ihr Backend ruft POST /v3/id-verification/wallets/google-wallet/ mit dem country der Person (USA, GBR, BRA, SGP oder TWN) und dem origin auf, der die Wallet anfragt. Der origin ist der HTTPS-Origin Ihrer Seite, etwa https://app.example.com, dessen Host einer Ihrer registrierten Rückgabe-Hostnamen oder Ihrer White-Label-Domain entsprechen muss. Für eine Android-App lautet er android:apk-key-hash:, gefolgt vom Base64-SHA-256 des Signaturzertifikats Ihrer App, ohne Padding. Die Wallet lehnt eine Anfrage ab, die von einem anderen Origin stammt. Es gibt kein return_url.
2

Die Wallet innerhalb einer Benutzergeste anfragen

Die Antwort enthält wallet_verification.interaction = "digital_credentials" und next_action.type = "request_digital_credential". Übergeben Sie next_action.digital_credentials.request an den Browser oder an den Android Credential Manager, und zwar durch Tippen oder Klicken auf dem origin, mit dem Sie begonnen haben. Auf dem Desktop zeigt der Browser einen eigenen QR-Code, wenn sich die Wallet auf einem anderen Gerät befindet.
3

Die Antwort der Wallet übermitteln

Senden Sie das zurückgegebene {protocol, data} an Ihr Backend und von dort an POST /v3/id-verification/wallets/verifications/{request_id}/response/ als {"response": {...}}. Die Anfrage kann nur einmal übermittelt werden; eine zweite Übermittlung gibt die bereits entschiedene Verifizierung zurück.
4

Das Ergebnis abrufen

Die Antwort auf die Übermittlung ist die entschiedene Verifizierung. Sie können sie auch mit GET /v3/id-verification/wallets/verifications/{request_id}/ abrufen oder im Abschluss-Webhook empfangen.
Im Browser fragen Sie die Wallet aus einem Klick-Handler an:
Bieten Sie die Methode nur dort an, wo der Browser sie unterstützt, zum Beispiel wenn "DigitalCredential" in window wahr ist. navigator.credentials.get muss innerhalb einer Benutzergeste ausgeführt werden, rufen Sie es also aus dem Klick-Handler auf und nicht nach einem asynchronen Schritt. Auf Android verwenden Sie Jetpack Credential Manager (androidx.credentials 1.5.0 oder neuer) mit derselben Anfrage:
Fehler, die Sie behandeln sollten: Ein Berechtigungsnachweis, der die Verifizierung nicht besteht, ist eine entschiedene Verifizierung mit dem Ergebnis failed, keine Fehlerantwort. Nur die Felder, die die Verifizierung angefordert hat, verlassen die Wallet, und das Ergebnis enthält die Identitätsattribute, die die Wallet zurückgegeben hat. Ein Google-Wallet-Ausweis oder ein mobiler Führerschein eines US-Bundesstaats liefert kein Porträt. In einer Sandbox-Anwendung wird der Ablauf mit denselben Schritten simuliert und liefert simulated: true. Jede übermittelte Antwort entscheidet die Verifizierung gemäß sandbox_scenario, sodass Sie den vollständigen Browser- oder App-Ablauf ohne einen echten Berechtigungsnachweis aufbauen können.

Abschluss-Webhooks

Richten Sie ein Anwendungs-Webhook-Ziel für status.updated ein, indem Sie der Anleitung zur Webhook-Integration folgen. Verwenden Sie webhook_version: "v3" für die hier beschriebene Entscheidungsstruktur. Prüfen Sie die Webhook-Signatur in Ihrem Backend, bevor Sie den Webhook verarbeiten. Die session_id des Webhooks entspricht der request_id, die die Wallet-API zurückgibt. Eine abgeschlossene Wallet-Identität erscheint im Array decision.id_verifications des Webhooks mit verification_method: "wallet". Mit dieser Kennung können Sie auch das dedizierte Ergebnis der Wallet-API abrufen. Verarbeiten Sie Benachrichtigungen über Genehmigungen und Ablehnungen von Verifizierungen, einschließlich abgebrochener und abgelaufener Verifizierungen. Machen Sie Ihren Webhook-Handler idempotent, weil fehlgeschlagene Zustellungen erneut versucht werden. Eine Rücksendung aus dem Browser ist kein Abschluss-Webhook, und ihre Query-Parameter sind kein Identitätsnachweis.

Zurückgegebene Identität

Verwenden Sie für Namen und Geburtsdaten die normalisierten Identitätsfelder, sofern diese zurückgegeben werden. Wallet-spezifische Attribute beschreiben die Identitätsinformationen, die vom ausgewählten Wallet übermittelt werden. Welche Attribute verfügbar sind, hängt von Wallet und Land ab. Eine erfolgreich authentifizierte Identität bedeutet nicht, dass ein Porträt, eine Adresse oder alle anderen angefragten Attribute verfügbar sind.

Test in der Sandbox

Eine Anwendung im Didit-Sandbox-Modus simuliert die Wallet-Verifizierung, ohne einen Wallet-Anbieter zu kontaktieren oder Credits zu berechnen. Die Antwort kennzeichnet diese Anfragen mit wallet_verification.simulated: true. Eine simulierte Genehmigung ist ein Beispieldatensatz und keine verifizierte reale Identität. Folgen Sie bei einem Redirect-Wallet der zurückgegebenen URL, um den Callback zu testen und zu Ihrer Anwendung zurückzukehren. Verwenden Sie bei Smart-ID oder Mobile-ID den Polling-Endpoint, um die simulierte Genehmigung abzuschließen; an ein Telefon wird keine Benachrichtigung gesendet. Um die Fehlerbehandlung zu testen, setzen Sie beim Starten einer Anfrage sandbox_scenario auf wallet_cancelled, wallet_timeout oder wallet_provider_error. Live-Anwendungen lehnen sandbox_scenario ab. Die Sandbox-Simulation von Didit ist von Tests in der eigenen Testumgebung eines Anbieters getrennt. Eine erfolgreiche Simulation begründet weder einen Live-Zugang zum Anbieter noch eine Verfügbarkeit in der Produktion.

ConnectID-Anbieter-Sandbox

Die Anbieter-Sandbox von ConnectID verwendet Test-Banken und ist von der Sandbox-Simulation von Didit getrennt. Wenn der Zugang zur Anbieter-Sandbox für Ihre Integration konfiguriert ist, übergeben Sie die authorisation_server_id der ausgewählten Bank an den ConnectID-Start-Endpoint. Verwenden Sie die ID, die von der ConnectID-Bankauswahl zurückgegeben wird; senden Sie weder eine Bank-URL noch einen beliebigen Aussteller. Wird das Feld weggelassen, wird die Standard-Test-Bank ausgewählt. Das Feld ist spezifisch für ConnectID und ändert die angefragten Identitätsattribute nicht. Das initiale Bundle fordert Vorname, Nachname und Geburtsdatum an. Folgen Sie dem zurückgegebenen next_action, um sich zu authentifizieren, und rufen Sie anschließend das Verifizierungsergebnis ab oder fragen Sie es über den Polling-Endpoint ab. Nur ein abgeschlossenes Ergebnis mit dem Status genehmigt bestätigt, dass die Verifizierung erfolgreich war; die Rückkehr zu Ihrer Anwendung genügt dafür nicht. ConnectID ist in der Produktion weiterhin Demnächst verfügbar, bis Onboarding und Zertifizierung abgeschlossen sind.

Verfügbarkeit und Preise

Die Endpoint-Abdeckung und die Aktivierung von Wallets in der Produktion sind voneinander getrennt. Für ein Wallet kann eine API-Referenzseite existieren, obwohl die Live-Authentifizierung noch nicht verfügbar ist. Prüfen Sie vor der Implementierung eines Live-Ablaufs die Länderabdeckung und den Produktionsstatus des Wallets. Veröffentlichte Tarife und Verfügbarkeit finden Sie unter Preise für digitale ID-Wallets. Die Wallet-Verifizierung wird separat von der Dokumentenerfassung abgerechnet.

Die passende Integration wählen

Verwenden Sie diese APIs, wenn Sie die umgebende Oberfläche und die Anwendungslogik selbst gestalten möchten. Verwenden Sie die Sessions API, wenn Sie den gehosteten Verifizierungsablauf von Didit, Workflow-Regeln und konfigurierte Ausweichschritte nutzen möchten. Beide Ansätze erfordern weiterhin den Authentifizierungs- und Einwilligungsprozess des Wallets.
Zuletzt geändert am 7. November 2026