> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Digitale ID-Wallet Verifizierungs-APIs

> Mit Didit über eine digitale ID-Wallet aus Ihrer eigenen Anwendung Identitäten verifizieren, ohne einen Verifizierungs-Workflow anzulegen.

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.

> [!NOTE]
>
> 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](https://docs.didit.me/de/standalone-apis/digital-id-wallet-catalog.md) 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](https://docs.didit.me/de/standalone-apis/digital-id-wallet-catalog.md), 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.

| Vorgang | Endpoint |
| - | - |
| Status und Ergebnis abrufen | `GET /v3/id-verification/wallets/verifications/{request_id}/` |
| Eine Telefonfreigabe abfragen | `POST /v3/id-verification/wallets/verifications/{request_id}/poll/` |
| Eine Antwort des Digital-Credentials-Wallets übermitteln | `POST /v3/id-verification/wallets/verifications/{request_id}/response/` |
| Eine ausstehende Verifizierung abbrechen | `POST /v3/id-verification/wallets/verifications/{request_id}/cancel/` |

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:

```bash theme={null}
curl --request PATCH \
  --url https://verification.didit.me/v3/webhook/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"allowed_return_hosts": ["app.example.com"]}'
```

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](https://docs.didit.me/de/sessions-api/management-api.md#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:

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/ftn/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "FIN",
    "return_url": "https://app.example.com/identity/complete",
    "vendor_data": "your-customer-reference"
  }'
```

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:

```bash theme={null}
curl --request GET \
  --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/ \
  --header 'x-api-key: YOUR_API_KEY'
```

Prüfen Sie `wallet_verification.outcome`:

| Ergebnis | Bedeutung |
| - | - |
| `pending` | Die Authentifizierung läuft noch. |
| `verified` | Die Authentifizierung ist abgeschlossen und die zurückgegebene Identität ist verifiziert. |
| `cancelled` | Die Person oder Ihre Anwendung hat den Versuch abgebrochen. |
| `timeout` | Das Zeitfenster für die Authentifizierung ist abgelaufen. |
| `failed` | Die Authentifizierung oder die Identitätsprüfung ist fehlgeschlagen. |

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)](#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](https://docs.didit.me/de/standalone-apis/digital-id-wallet-catalog.md) 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](#ihr-rückgabeziel-registrieren) 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`.

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/google-wallet/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "USA",
    "origin": "https://app.example.com",
    "vendor_data": "your-customer-reference"
  }'
```

**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:

```javascript theme={null}
// start = the JSON your backend returned from the start request
const request = start.wallet_verification.next_action.digital_credentials.request;

button.addEventListener("click", async () => {
  try {
    const credential = await navigator.credentials.get({ digital: request });
    // Send {protocol, data} to your backend, which calls POST .../response/ with your API key.
    await fetch("/api/wallet-response", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        request_id: start.request_id,
        response: { protocol: credential.protocol, data: credential.data },
      }),
    });
  } catch (error) {
    // NotAllowedError or AbortError: the person cancelled. NotSupportedError: this browser cannot ask the wallet.
    console.error(error.name);
  }
});
```

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:

```kotlin theme={null}
val option = GetDigitalCredentialOption(
    requestJson = JSONObject(request).toString(), // next_action.digital_credentials.request
)
val result = credentialManager.getCredential(activity, GetCredentialRequest(listOf(option)))
val credentialJson = (result.credential as DigitalCredential).credentialJson // {"protocol": ..., "data": {...}}
// Send credentialJson, parsed as JSON, to your backend as the "response" body.
```

Fehler, die Sie behandeln sollten:

| Fehler | Wo | Bedeutung |
| - | - | - |
| `origin_invalid` | Start, `400` | `origin` ist kein HTTPS-Origin und kein Android-App-Origin. |
| `origin_not_allowed` | Start, `400` | Der Host des Origins ist für Ihre Anwendung nicht registriert. Registrieren Sie ihn in `allowed_return_hosts`. |
| `not_a_digital_credentials_wallet` | Übermittlung, `409` | Diese Verifizierung nimmt keine Wallet-Antwort entgegen. |

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](https://docs.didit.me/de/integration/webhooks.md) 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](https://docs.didit.me/de/api-reference/digital-id-wallets/connectid.md).
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](https://docs.didit.me/de/getting-started/pricing.md#preise-für-digital-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](https://docs.didit.me/de/sessions-api/create-session.md), 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.