> ## 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.
# NFC-Verifizierungs-API: e-Reisepass & eID-Chip
> e-Reisepässe & eIDs per NFC mit Didit verifizieren: kryptografisch validiert, fälschungssicher, höchste ID-Sicherheit. $0.15 pro Aufruf.
Die NFC-basierte Authentifizierung ermöglicht es Ihnen, Ausweisdokumente zu verifizieren, indem der in modernen Reisepässen und Ausweisen eingebettete sichere Chip über die NFC-Funktionen eines Mobiltelefons ausgelesen wird. Dies bietet das **höchste verfügbare Sicherheitsniveau** für die Ausweisverifizierung.
Prompt zur Integration der NFC-Verifizierung
Prompt in die Zwischenablage kopieren
\
\````# Goal
Integrate Didit NFC Verification — cryptographic ePassport / eID chip read — into your app.
\# Delivery mode
NFC is **session-only**. There is no standalone /v3/nfc/ endpoint. The chip is read by the Didit Web/Mobile SDK during a hosted session, which uses the device's NFC radio.
\# Steps
1\. Create a workflow that includes the NFC feature (Business Console or POST /v3/workflows/). NFC normally runs alongside ID Verification: the user first photographs the document so the SDK derives BAC/PACE keys from the MRZ, then taps the chip.
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open the returned session.url on a mobile device with NFC (iOS 13+/Android with NFC enabled), or mount the native SDK in your app.
4\. After completion fetch the decision — GET /v3/session/{sessionId}/decision/ (or subscribe to session.status.updated).
curl (create session):
\```bash
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-123",
"callback": "https://yourapp.com/post-kyc"
}'
\```
\# Decision shape
The NFC result is returned under the plural array `nfc_verifications[]` on the decision payload.
\> Heads-up: the V3 schema deliberately keeps the **plural-array** name `nfc_verifications[]` even though early integrators occasionally hit a singular `nfc_verification` key. Always read from the plural array — it is the canonical, multi-instance shape and matches every other feature.
\# Status enum (per nfc_verifications[].status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"
\# Warnings (LogWarningChoices.NFC)
The warnings[] array on each nfc_verification includes risk codes such as:
NFC_NOT_READ, NFC_DATA_INVALID, NFC_DATA_DOES_NOT_MATCH_OCR, NFC_BAC_FAILED, NFC_PASSIVE_AUTHENTICATION_FAILED, NFC_ACTIVE_AUTHENTICATION_FAILED, NFC_CHIP_CLONED, NFC_DOCUMENT_REVOKED.
Full catalogue: /core-technology/nfc-verification/warnings-nfc-verification.
\# Failure modes to handle
\- Device has no NFC chip or NFC is disabled — the SDK falls back to OCR + face match; nfc_verifications[] will be empty.
\- The user fails to hold the chip long enough — status="Declined" with NFC_NOT_READ or NFC_BAC_FAILED. Allow a retry.
\- nfc_verifications[].status="Declined" with NFC_DATA_DOES_NOT_MATCH_OCR — the chip and the printed data disagree (likely tampered document). Do not approve.
\- Passive Authentication failed — the chip's signing certificate did not chain back to a trusted CSCA. Stop the flow.
\# Japan My Number Card (JPKI)
\- The My Number Card is read through JPKI, not ICAO 9303: native SDKs only, and the person enters the card PIN. Its item has chip_protocol "jpki", its evidence under jpki (chain_valid, signature_valid, revocation_status good | revoked | unchecked, attributes, attributes_match_ocr), and null ICAO fields (chip_data, authenticity, certificate_summary).
\- iOS host apps add D392F000260100000001 to com.apple.developer.nfc.readersession.iso7816.select-identifiers.
\- Not enabled in production yet: until it is, a My Number Card in a native SDK on an NFC phone skips NFC with nfc_skip_reason JPKI_UNAVAILABLE.
\# See also
\- Canonical schema: /reference/data-models#nfc-verification
\- Per-feature report: /core-technology/nfc-verification/report-nfc-verification
\- Risk catalogue: /core-technology/nfc-verification/warnings-nfc-verification
\- Supported documents: /core-technology/nfc-verification/supported-documents-nfc-verification
\- Full integration playbook: /integration/integration-prompt````
\
Einfügen in
***## Wichtigste Vorteile| Vorteil | Beschreibung |
| - | - |
| **Höchste Sicherheit** | Verifiziert kryptografische Signaturen direkt von staatlichen Ausstellern |
| **Einfach zu bedienen** | Funktioniert automatisch mit jedem NFC-fähigen Smartphone |
| **Manipulationssicher** | Erkennt Dokumentenmanipulationen, die für das menschliche Auge unsichtbar sind |
| **Umfassende Daten** | Extrahiert zusätzliche Daten, die allein über OCR nicht verfügbar sind |
| **Flexibler Fallback** | Fällt nahtlos auf die Standardverifizierung zurück, wenn NFC nicht verfügbar ist |***## So aktivieren Sie die NFC-Verifizierung### Native SDK-Integration (empfohlen)Die NFC-Verifizierung ist über unsere **nativen SDKs** verfügbar, die vollen Zugriff auf die NFC-Funktionen des Geräts bieten:| Plattform | NFC-Unterstützung | Dokumentation |
| - | - | - |
| **iOS** | ✅ Volle Unterstützung | [iOS-SDK-Dokumentation](https://docs.didit.me/de/integration/native-sdks/ios-sdk.md) |
| **Android** | ✅ Volle Unterstützung | [Android-SDK-Dokumentation](https://docs.didit.me/de/integration/native-sdks/android-sdk.md) |Das iOS-SDK übernimmt die gesamte NFC-Konfiguration automatisch, einschließlich:- ISO7816-Anwendungs-Identifier für ePässe
- Einrichtung von Entitlements und Capabilities
- Auslesen des Chips in Echtzeit mit visuellem Feedback### Web-Integration> ⚠️ **Browser-Einschränkungen**
>
> Die NFC-Verifizierung ist aufgrund von Plattformbeschränkungen **in Webbrowsern nicht verfügbar**:
>
> | Browser | NFC-Unterstützung |
> | - | - |
> | **Chrome (Android)** | Experimentelle Web NFC API – instabil, erfordert explizite Berechtigungen |
> | **Safari (iOS)** | Keine Unterstützung der Web NFC API |
> | **Andere Browser** | Keine Unterstützung |
>
> Bei Web-Integrationen wird die NFC-Verifizierung automatisch übersprungen und Benutzer fahren mit der standardmäßigen Verifizierung mit Dokument + Selfie fort.***## Funktionsweise**1. Sitzungsinitiierung**Der Benutzer startet den Verifizierungsprozess über Ihre App oder Plattform:- **Natives SDK**: Starten Sie den Verifizierungs-Workflow direkt in Ihrer App
- **Web/Mobiles Web**: Der Benutzer wird angeleitet, die Didit-App für die NFC-fähige Verifizierung zu verwenden, oder setzt den Vorgang mit der Standardverifizierung fort**2. Aufnahme von Dokumentenfotos**Der Benutzer fotografiert sein Ausweisdokument und erfasst dabei:- **MRZ** (Machine Readable Zone) — dient zur Ableitung der Zugriffsschlüssel für den Chip
- **Vorder- und Rückseitenbilder des Dokuments** — visuelle Daten und Sicherheitsmerkmale
- **Visuelle Sicherheitsmerkmale** — Hologramme, Wasserzeichen, Mikroschrift**3. Erkennung der NFC-Unterstützung**Das System prüft automatisch die Geräte- und Dokumentkompatibilität:| Prüfung | Beschreibung |
| - | - |
| **Dokumenttyp** | Handelt es sich um einen ePass bzw. eine eID mit NFC-Chip? |
| **Gerätekompatibilität** | Unterstützt das Smartphone das Auslesen von NFC? |
| **Berechtigungen** | Wurden die erforderlichen NFC-Berechtigungen erteilt? |> [!NOTE]
>
> Falls NFC nicht verfügbar ist, wird die Verifizierung nahtlos mit der Standard-Dokumenten- und biometrischen Verifizierung fortgesetzt.**4. Auslesen des NFC-Chips**Bei kompatiblen Geräten und Dokumenten:1) Der Benutzer wird angeleitet, sein Dokument an das NFC-Lesegerät des Smartphones zu halten
2) Visuelles Feedback zeigt den Lesefortschritt in Echtzeit an
3) Eine sichere Kommunikation mit dem Chip wird über PACE/BAC-Protokolle aufgebaut**5. Datenextraktion**Das System extrahiert umfassende Daten aus dem Chip gemäß den **ICAO 9303**-Standards:| Datengruppe | Inhalt | Beschreibung |
| - | - | - |
| **SOD** | Document Security Object | Digitale Signaturen für alle Datengruppen |
| **DG1** | Personenbezogene Daten | Name, Ausweisnummer, Geburtsdatum, Ablaufdatum |
| **DG2** | Gesichtsbild | Hochauflösendes digitales Foto des Inhabers |
| **DG7** | Signatur | Digitale Darstellung der Unterschrift des Inhabers |
| **DG11-14** | Zusätzliche Daten | Kann Fingerabdrücke, Iris-Scans enthalten (sofern gespeichert) |**6. Kryptografische Verifizierung**Die extrahierten Daten durchlaufen eine strenge kryptografische Verifizierung:> [accordion] Prüfung der digitalen Signatur
>
> Der Hash jeder Datengruppe wird anhand der im SOD gespeicherten Signaturen überprüft, um die Datenintegrität sicherzustellen.> [accordion] Validierung der Zertifikatskette
>
> Die Vertrauenskette wird validiert: **Dokumentenzertifikat → Country Signing CA → ICAO PKD Root**, unter Abgleich mit CSCA-Masterlisten und dem ICAO Public Key Directory.> [accordion] Zertifikatssperrprüfung
>
> Zertifikate werden anhand von Zertifikatssperrlisten (CRLs) überprüft, um sicherzustellen, dass sie nicht widerrufen wurden und das Dokument nicht als gestohlen oder kompromittiert gemeldet ist.> [accordion] Kreuzvalidierung
>
> Per NFC extrahierte Daten werden mit den OCR-Daten aus den Dokumentenfotos, dem biometrischen Gesichtsabgleich und der MRZ-Prüfsummenvalidierung abgeglichen.**7. Ergebnis & Konfidenzwert**Das endgültige Verifizierungsergebnis umfasst:| Ausgabe | Beschreibung |
| - | - |
| **Status der NFC-Verifizierung** | Erfolgreich, fehlgeschlagen oder übersprungen |
| **Datenkonsistenzwert** | Wie gut die NFC-Daten mit den visuellen Daten übereinstimmen |
| **Zertifikatsvalidierung** | Status der vollständigen Zertifikatskettenprüfung |
| **Konfidenzsteigerung** | NFC erhöht die Konfidenz der Gesamtverifizierung erheblich |***## Unterstützte DokumenteDie NFC-Verifizierung funktioniert mit **ePässen** und **elektronischen Ausweisen**, die einen NFC-Chip enthalten, was typischerweise durch dieses Symbol auf dem Dokument gekennzeichnet ist:Die meisten nach 2006 ausgestellten Reisepässe enthalten NFC-Chips. Bei nationalen Personalausweisen variiert die Verfügbarkeit je nach Land. Prüfen Sie alle [unterstützten Dokumente](https://docs.didit.me/de/core-technology/nfc-verification/supported-documents-nfc-verification.md).Die Japan My Number Card besitzt eine andere Art von Chip, der über JPKI anstelle von ICAO 9303 ausgelesen wird. Siehe [Japan My Number Card (JPKI)](#japan-my-number-card-jpki).***## Japan My Number Card (JPKI)Die japanische My Number Card (マイナンバーカード) besitzt einen Chip, jedoch keinen Chip nach ICAO 9303. Sie enthält Zertifikate, die unter JPKI (Japans Public-Key-Infrastruktur) ausgestellt wurden, sowie private Schlüssel, die erst signieren, nachdem der Inhaber die PIN der Karte eingegeben hat. Didit liest sie im selben NFC-Schritt über JPKI statt ICAO 9303 aus, und jedes NFC-Ergebnis gibt in `chip_protocol` an, welches Protokoll verwendet wurde (`icao` oder `jpki`).> [!WARNING]
>
> **Noch nicht verfügbar.** Das Auslesen der My Number Card über JPKI ist in der Produktion noch nicht aktiviert. Bis dahin überspringt eine in einem nativen SDK erfasste My Number Card den NFC-Schritt mit dem Abbruchgrund `JPKI_UNAVAILABLE`, und die Karte wird wie bisher per Dokumentenerfassung und Gesichtsabgleich verifiziert.### Anforderungen| Anforderung | Detail |
| - | - |
| **Dokument** | Nur die japanische My Number Card. Bei japanischen Reisepässen bleibt das Auslesen des ICAO-9303-Chips bestehen. |
| **Integration** | Ein natives SDK-Release, das My Number Cards auslesen kann (iOS, Android oder die darauf aufbauenden React Native- und Flutter-SDKs). Das SDK teilt Didit mit, dass es JPKI lesen kann; ein älteres Release überspringt den Schritt mit `JPKI_UNAVAILABLE`. Web- und WebView-Integrationen überspringen ihn mit `INTEGRATION_WITHOUT_NFC_ACCESS`. |
| **Gerät** | Ein Smartphone mit einem NFC-Lesegerät. Ohne ein solches wird der Schritt mit `DEVICE_WITHOUT_NFC` übersprungen. |
| **iOS-Host-App** | `D392F000260100000001` in den ISO7816-Select-Identifiers der App. Siehe [iOS-NFC-Konfiguration](https://docs.didit.me/de/integration/native-sdks/ios-sdk.md#nfc-konfiguration). |
| **Person** | Kennt die 4-stellige PIN der Karte sowie das Signaturpasswort, wenn Ihr Workflow die Inhaberdaten anfordert. |### Was die Person tut**1. Karte fotografieren**Die Person erfasst die My Number Card im Ausweisverifizierungsschritt wie jedes andere Dokument. Didit erkennt die Karte und startet einen JPKI-NFC-Schritt anstelle des Auslesens eines Reisepass-Chips.**2. Karten-PIN eingeben**Das SDK fordert zur Eingabe der 4-stelligen PIN der Karte auf (利用者証明用電子証明書の暗証番号). Wenn die Einstellung `jpki_request_attributes` des NFC-Knotens aktiviert ist (Standardeinstellung), fordert es zusätzlich das Signaturpasswort an, auch Signatur-PIN genannt (署名用電子証明書の暗証番号, 6 bis 16 Großbuchstaben und Zahlen).**3. Karte an das Smartphone halten**Das SDK liest die Zertifikate der Karte aus, und die Karte signiert eine Einmal-Challenge von Didit mit ihrem eigenen Schlüssel. Das SDK lädt die Zertifikate und Signaturen hoch. Die PINs werden ausschließlich an die Karte übermittelt, niemals an Didit.> [!NOTE]
>
> Die Karte zählt Fehleingaben: Sie sperrt die 4-stellige PIN nach 3 Fehlversuchen in Folge und das Signaturpasswort nach 5. Ein gesperrter Wert – die 4-stellige PIN oder das Signaturpasswort – muss beim zuständigen Gemeindeamt des Inhabers zurückgesetzt werden. Nach einer Fehleingabe zeigt das SDK an, wie viele Versuche verbleiben. Es führt den letzten Versuch niemals aus: Ist nur noch ein Versuch übrig, stoppt es und informiert die Person darüber, wo das Zurücksetzen möglich ist. Bitten Sie die Personen, ihre PIN und ihr Signaturpasswort bereitzuhalten, bevor sie beginnen.### Was Didit prüft| Prüfung | Was Didit verifiziert | Warnung bei Fehlschlag (Standardaktion) |
| - | - | - |
| **Zertifikatskette** | Jedes Zertifikat lässt sich auf die JPKI-Zertifizierungsstelle seines Typs zurückführen, befindet sich innerhalb seiner Gültigkeitsdauer und ist ein My-Number-Card-Zertifikat (`jpki.chain_valid`). | `JPKI_CERTIFICATE_INVALID` (Ablehnen) |
| **Karte und PIN** | Die Signatur der Karte über die Einmal-Challenge lässt sich anhand ihres Zertifikats verifizieren (`jpki.signature_valid`). Die Karte signiert erst nach Eingabe ihrer PIN; dies beweist somit, dass die Person die Karte besitzt und die PIN kennt. | `JPKI_SIGNATURE_INVALID` (Ablehnen) |
| **Widerruf** | Kein Zertifikat wurde widerrufen (`jpki.revocation_status`). | `JPKI_CERTIFICATE_REVOKED` bei `revoked` (Ablehnen), `JPKI_REVOCATION_UNCHECKED` bei `unchecked` (Überprüfung) |
| **Inhaberdaten** | Name, Geburtsdatum, Geschlecht und Adresse im Signaturzertifikat stimmen mit den aus dem Foto derselben Karte ausgelesenen Daten überein (`jpki.attributes_match_ocr`, `jpki.mismatched_attributes`). | `JPKI_AND_OCR_DATA_NOT_SAME` (Überprüfung) |Jede Aktion ist eine Einstellung am NFC-Knoten, sodass Sie sie auf **Keine Aktion**, **Überprüfung** oder **Ablehnen** ändern können. Siehe [NFC-Warnungen](https://docs.didit.me/de/core-technology/nfc-verification/warnings-nfc-verification.md#japan-my-number-card-jpki) und die [NFC-Funktionskonfiguration](https://docs.didit.me/de/management-api/workflows/feature-configs.md#nfc-/-epassport).### Was ein ungeprüfter Widerrufsstatus bedeutet`revocation_status: "unchecked"` bedeutet, dass Didit die Zertifikatskette und die Signatur der Karte verifiziert hat, jedoch keine Rückmeldung darüber erhalten hat, ob ein Zertifikat widerrufen wurde. Ein Zertifikat wird beispielsweise widerrufen, wenn die Karte als verloren gemeldet wird. Da eine widerrufene Karte nicht ausgeschlossen werden kann, wird `unchecked` niemals als `good` behandelt. Es löst `JPKI_REVOCATION_UNCHECKED` aus, wodurch der NFC-Schritt standardmäßig in die manuelle Prüfung gesendet wird. Wählen Sie mit `jpki_revocation_unchecked_action` ein anderes Ergebnis.Wenn die Zertifikatskette oder die Signatur ungültig ist, fragt Didit den Widerrufsstatus gar nicht erst ab: Der Status bleibt `unchecked` und es wird nur die Warnung zur Kette oder Signatur ausgelöst.### Inhaberdaten und Datenschutz- Bei aktiviertem `jpki_request_attributes` enthält die Entscheidung Name, Geburtsdatum, Geschlecht und Adresse des Inhabers aus dem Signaturzertifikat unter `jpki.attributes`. Bei deaktivierter Option gibt die Person nur die 4-stellige PIN ein: Das Auslesen beweist weiterhin, dass die Person die Karte besitzt und die PIN kennt, enthält jedoch keine Inhaberdaten und wird nicht mit dem Foto der Karte verglichen.
- Der NFC-Schritt liest niemals die 12-stellige Individual Number (My Number) der Karte aus dem Chip aus.
- Die Entscheidung gibt an, was die Karte bewiesen hat, niemals die Zertifikate selbst, deren Seriennummern oder die Signaturen.Das vollständige Ergebnis wird im [NFC-Verifizierungsbericht](https://docs.didit.me/de/core-technology/nfc-verification/report-nfc-verification.md#japan-my-number-card-jpki) beschrieben.***## Integrationsbeispiele### iOS-SDK (Jetzt verfügbar)```swift theme={null}
import DiditSdk
// NFC is automatically enabled when the document supports it
let config = DiditSdk.Configuration(
// NFC configuration is handled automatically
// Just ensure your app has the required entitlements
)
let result = try await DiditSdk.shared.startVerification(
with: sessionId,
configuration: config
)
```**[Vollständige iOS-SDK-Dokumentation →](https://docs.didit.me/de/integration/native-sdks/ios-sdk.md)**### Android-SDK (Jetzt verfügbar)```kotlin theme={null}
import me.didit.sdk.DiditSdk
// NFC is automatically enabled when the document supports it
DiditSdk.startVerification(
token = "your-session-token"
) { result ->
handleResult(result)
}
```**[Android-SDK-Dokumentation →](https://docs.didit.me/de/integration/native-sdks/android-sdk.md)*****## Sicherheitsarchitektur```
┌─────────────────────────────────────────────────────────────┐
│ NFC Verification Flow │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
│ │ Document │───▶│ Phone │───▶│ Didit Backend │ │
│ │ NFC Chip │ │ NFC Read │ │ │ │
│ └──────────┘ └──────────┘ │ ┌────────────────┐ │ │
│ │ │ ICAO PKD │ │ │
│ │ │ Validation │ │ │
│ │ └────────────────┘ │ │
│ │ ┌────────────────┐ │ │
│ │ │ CSCA Master │ │ │
│ │ │ List Check │ │ │
│ │ └────────────────┘ │ │
│ │ ┌────────────────┐ │ │
│ │ │ CRL Revocation │ │ │
│ │ │ Check │ │ │
│ │ └────────────────┘ │ │
│ └──────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ Verification Result │ │
│ │ + Confidence Score │ │
│ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```***## FAQ
**Was passiert, wenn das Smartphone des Benutzers kein NFC unterstützt?**
Der Verifizierungsablauf erkennt automatisch die NFC-Fähigkeit. Falls sie nicht verfügbar ist, fahren Benutzer mit der standardmäßigen Dokumenten- und Selfie-Verifizierung fort. Die Verifizierung bleibt weiterhin sicher – lediglich ohne den zusätzlichen Vertrauensgewinn durch NFC.
**Was passiert, wenn das Dokument keinen NFC-Chip hat?**
Viele Dokumente (insbesondere ältere Reisepässe und einige Personalausweise) besitzen keine NFC-Chips. Das System erkennt dies und setzt die Verifizierung nahtlos mit dem Standardverfahren fort.
**Wie stark verbessert die NFC-Verifizierung die Genauigkeit?**
Die NFC-Verifizierung liefert einen kryptografischen Nachweis der Dokumentenauthentizität direkt von der ausstellenden Regierung. Dies erhöht das Vertrauen in das Verifizierungsergebnis erheblich und erkennt raffinierte Fälschungen, die eine visuelle Prüfung möglicherweise bestehen würden.
**Ist die NFC-Verifizierung erforderlich?**
Nein. NFC ist eine Erweiterung, keine Voraussetzung. Ihr Verifizierungs-Workflow kann so konfiguriert werden, dass NFC erforderlich ist, bei Verfügbarkeit bevorzugt wird oder basierend auf Ihrer Risikotoleranz vollständig übersprungen wird.
***
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.