> ## 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.
# API di verifica NFC: passaporti elettronici e chip eID
> Verifica passaporti elettronici ed eID con Didit leggendo i chip NFC. Convalida crittografica e massima sicurezza. Pay-per-call a $0.15.
L'autenticazione basata su NFC ti consente di verificare i documenti d'identità leggendo il chip sicuro integrato nei passaporti e nelle carte d'identità moderni utilizzando le funzionalità NFC di uno smartphone. Ciò offre il **massimo livello di sicurezza disponibile** per la Verifica dell'identità.
Prompt di integrazione della verifica NFC
Copia il prompt negli appunti
\
\````# 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````
\
Incolla in
***## Vantaggi principali| Vantaggio | Descrizione |
| - | - |
| **Massima sicurezza** | Verifica le firme crittografiche direttamente dagli enti emittenti governativi |
| **Semplice da usare** | Funziona automaticamente con qualsiasi smartphone dotato di NFC |
| **A prova di manomissione** | Rileva manipolazioni dei documenti invisibili all'occhio umano |
| **Dati completi** | Estrae dati aggiuntivi non disponibili tramite il solo OCR |
| **Fallback flessibile** | Passa automaticamente alla verifica standard se l'NFC non è disponibile |***## Come abilitare la verifica NFC### Integrazione tramite SDK nativi (consigliata)La verifica NFC è disponibile tramite i nostri **SDK nativi**, che forniscono pieno accesso alle funzionalità NFC del dispositivo:| Piattaforma | Supporto NFC | Documentazione |
| - | - | - |
| **iOS** | ✅ Supporto completo | [Documentazione iOS SDK](https://docs.didit.me/it/integration/native-sdks/ios-sdk.md) |
| **Android** | ✅ Supporto completo | [Documentazione Android SDK](https://docs.didit.me/it/integration/native-sdks/android-sdk.md) |L'SDK iOS gestisce automaticamente l'intera configurazione NFC, tra cui:- Identificatori di applicazione ISO7816 per passaporti elettronici
- Configurazione di entitlement e capability
- Lettura del chip in tempo reale con feedback visivo### Integrazione web> ⚠️ **Limitazioni del browser**
>
> La verifica NFC **non è disponibile nei browser web** a causa delle restrizioni della piattaforma:
>
> | Browser | Supporto NFC |
> | - | - |
> | **Chrome (Android)** | Web NFC API sperimentale: instabile, richiede autorizzazioni esplicite |
> | **Safari (iOS)** | Nessun supporto per Web NFC API |
> | **Altri browser** | Nessun supporto |
>
> Per le integrazioni web, la verifica NFC viene ignorata automaticamente e gli utenti procedono con la verifica standard del documento e del selfie.***## Come funziona**1. Avvio della sessione**L'utente avvia il processo di verifica tramite la tua app o piattaforma:- **SDK nativo**: avvia il flusso di verifica direttamente nella tua app
- **Web/Mobile web**: l'utente viene guidato a usare l'app Didit per la verifica abilitata per NFC, oppure prosegue con la verifica standard**2. Acquisizione della foto del documento**L'utente fotografa il proprio documento d'identità, acquisendo:- **MRZ** (zona a lettura ottica) — utilizzata per ricavare le chiavi di accesso al chip
- **Immagini fronte e retro del documento** — dati visivi ed elementi di sicurezza
- **Elementi di sicurezza visivi** — ologrammi, filigrane, microscritture**3. Rilevamento del supporto NFC**Il sistema controlla automaticamente la compatibilità del dispositivo e del documento:| Controllo | Descrizione |
| - | - |
| **Tipo di documento** | Si tratta di un passaporto elettronico/carta d'identità elettronica con chip NFC? |
| **Funzionalità del dispositivo** | Lo smartphone supporta la lettura NFC? |
| **Autorizzazioni** | Sono state concesse le autorizzazioni NFC necessarie? |> [!NOTE]
>
> Se l'NFC non è disponibile, la verifica prosegue senza interruzioni con la verifica standard del documento + verifica biometrica.**4. Lettura del chip NFC**Per i dispositivi e i documenti compatibili:1) L'utente viene guidato a posizionare il proprio documento vicino al lettore NFC dello smartphone
2) Un feedback visivo mostra l'avanzamento della lettura in tempo reale
3) Viene stabilita una comunicazione sicura con il chip utilizzando i protocolli PACE/BAC**5. Estrazione dei dati**Il sistema estrae dati completi dal chip seguendo gli standard **ICAO 9303**:| Gruppo di dati | Contenuto | Descrizione |
| - | - | - |
| **SOD** | Oggetto di sicurezza del documento | Firme digitali per tutti i gruppi di dati |
| **DG1** | Dati personali | Nome, numero del documento, data di nascita, data di scadenza |
| **DG2** | Immagine facciale | Foto digitale ad alta risoluzione del titolare |
| **DG7** | Firma | Rappresentazione digitale della firma del titolare |
| **DG11-14** | Dati aggiuntivi | Possono includere impronte digitali, scansioni dell'iride (se memorizzate) |**6. Verifica crittografica**I dati estratti sono sottoposti a una rigorosa verifica crittografica:> [accordion] Verifica della firma digitale
>
> L'hash di ciascun gruppo di dati viene verificato rispetto alle firme memorizzate nel SOD, garantendo l'integrità dei dati.> [accordion] Validazione della catena di certificati
>
> La catena di attendibilità viene convalidata: **Certificato del documento → Country Signing CA → ICAO PKD Root**, effettuando un controllo incrociato con le liste principali CSCA e la Public Key Directory ICAO.> [accordion] Controllo della revoca dei certificati
>
> I certificati vengono verificati rispetto alle liste di revoca dei certificati (CRL) per garantire che non siano stati revocati e che il documento non sia stato segnalato come rubato o compromesso.> [accordion] Convalida incrociata
>
> I dati estratti tramite NFC vengono convalidati mediante il confronto con i dati OCR ottenuti dalle foto del documento e con il confronto biometrico facciale, nonché mediante la verifica del checksum della MRZ.**7. Risultato e punteggio di affidabilità**Il risultato finale della verifica include:| Risultato | Descrizione |
| - | - |
| **Stato della verifica NFC** | Riuscito, non riuscito o saltato |
| **Punteggio di coerenza dei dati** | Quanto i dati NFC corrispondono ai dati visivi |
| **Validazione del certificato** | Stato di verifica dell'intera catena |
| **Incremento dell'affidabilità** | L'NFC aumenta notevolmente il livello di affidabilità della verifica complessiva |***## Documenti supportatiLa verifica NFC funziona con **passaporti elettronici** ed **eID** che contengono un chip NFC, solitamente indicato da questo simbolo sul documento:La maggior parte dei passaporti emessi dopo il 2006 contiene chip NFC. La copertura per le carte d'identità nazionali varia in base al paese. Consulta tutti i [documenti supportati](https://docs.didit.me/it/core-technology/nfc-verification/supported-documents-nfc-verification.md).La My Number Card giapponese dispone di un tipo di chip diverso, letto tramite JPKI anziché ICAO 9303. Consulta [Japan My Number Card (JPKI)](#japan-my-number-card-jpki).***## Japan My Number Card (JPKI)La Japan My Number Card (マイナンバーカード) possiede un chip, ma non di tipo ICAO 9303. Contiene certificati emessi nell'ambito di JPKI, l'infrastruttura a chiave pubblica del Giappone, e chiavi private che appongono la firma solo dopo che il titolare ha inserito il PIN della carta. Didit la legge nello stesso passaggio NFC, tramite JPKI anziché ICAO 9303, e ogni risultato NFC specifica quale protocollo è stato utilizzato in `chip_protocol` (`icao` o `jpki`).> [!WARNING]
>
> **Non ancora disponibile.** La lettura della My Number Card tramite JPKI non è abilitata in produzione. Fino a quando non lo sarà, una My Number Card acquisita in un SDK nativo salta il passaggio NFC con motivo di esclusione `JPKI_UNAVAILABLE`, e la carta viene verificata con l'acquisizione del documento e il confronto facciale come in precedenza.### Requisiti| Requisito | Dettaglio |
| - | - |
| **Documento** | Solo la Japan My Number Card. I passaporti giapponesi mantengono la lettura del chip ICAO 9303. |
| **Integrazione** | Una versione dell'SDK nativo in grado di leggere le My Number Card (iOS, Android o gli SDK React Native e Flutter basati su di essi). L'SDK comunica a Didit che è in grado di leggere JPKI; una versione precedente salta il passaggio con `JPKI_UNAVAILABLE`. Le integrazioni Web e WebView lo saltano con `INTEGRATION_WITHOUT_NFC_ACCESS`. |
| **Dispositivo** | Un telefono dotato di lettore NFC. Senza di esso, il passaggio viene saltato con `DEVICE_WITHOUT_NFC`. |
| **App host iOS** | `D392F000260100000001` negli identificatori di selezione ISO7816 dell'app. Consulta la [configurazione NFC per iOS](https://docs.didit.me/it/integration/native-sdks/ios-sdk.md#configurazione-nfc). |
| **Persona** | Conosce il PIN di 4 cifre della carta e anche la relativa password di firma quando il tuo workflow richiede i dati del titolare. |### Cosa fa la persona**1. Fotografare la carta**La persona acquisisce la My Number Card nel passaggio di verifica dell'identità, come per qualsiasi documento. Didit riconosce la carta e invia un passaggio NFC JPKI anziché la lettura del chip del passaporto.**2. Inserire il PIN della carta**L'SDK richiede il PIN di 4 cifre della carta (利用者証明用電子証明書の暗証番号). Quando l'impostazione `jpki_request_attributes` del nodo NFC è attiva (impostazione predefinita), richiede anche la password di firma, detta anche PIN di firma (署名用電子証明書の暗証番号, da 6 a 16 lettere maiuscole e numeri).**3. Avvicinare la carta al telefono**L'SDK legge i certificati della carta e la carta firma una challenge monouso di Didit con la propria chiave. L'SDK carica i certificati e le firme. I PIN vengono inviati solo alla carta, mai a Didit.> [!NOTE]
>
> La carta tiene il conto dei tentativi errati: blocca il PIN di 4 cifre dopo 3 tentativi consecutivi e la password di firma dopo 5; un codice bloccato deve essere reimpostato presso l'ufficio municipale del titolare. Dopo un inserimento errato, l'SDK mostra quanti tentativi rimangono. Non effettua mai l'ultimo tentativo: quando ne rimane solo uno, si ferma e indica alla persona dove reimpostarlo. Chiedi agli utenti di preparare il PIN e la password di firma prima di iniziare.### Cosa verifica Didit| Controllo | Cosa verifica Didit | Avviso in caso di errore (azione predefinita) |
| - | - | - |
| **Catena di certificati** | Ogni certificato forma una catena fino all'autorità di certificazione JPKI del rispettivo tipo, rientra nel periodo di validità ed è un certificato My Number Card (`jpki.chain_valid`). | `JPKI_CERTIFICATE_INVALID` (Rifiuta) |
| **Carta e PIN** | La firma della carta sulla challenge monouso è verificata rispetto al suo certificato (`jpki.signature_valid`). La carta firma solo dopo che è stato inserito il PIN, dimostrando così che la persona possiede la carta e conosce il PIN. | `JPKI_SIGNATURE_INVALID` (Rifiuta) |
| **Revoca** | Nessun certificato è stato revocato (`jpki.revocation_status`). | `JPKI_CERTIFICATE_REVOKED` quando è `revoked` (Rifiuta), `JPKI_REVOCATION_UNCHECKED` quando è `unchecked` (Revisione) |
| **Dati del titolare** | Il nome, la data di nascita, il sesso e l'indirizzo nel certificato di firma corrispondono ai dati letti dalla foto della stessa carta (`jpki.attributes_match_ocr`, `jpki.mismatched_attributes`). | `JPKI_AND_OCR_DATA_NOT_SAME` (Revisione) |Ogni azione è un'impostazione presente sul nodo NFC, quindi puoi modificarla in **Nessuna azione**, **Revisione** o **Rifiuta**. Consulta gli [avvisi NFC](https://docs.didit.me/it/core-technology/nfc-verification/warnings-nfc-verification.md#japan-my-number-card-jpki) e la [configurazione della funzionalità NFC](https://docs.didit.me/it/management-api/workflows/feature-configs.md#nfc-/-epassport).### Cosa significa uno stato di revoca non verificato`revocation_status: "unchecked"` indica che Didit ha verificato la catena di certificati e la firma della carta, ma non ha ottenuto risposta in merito all'eventuale revoca di un certificato. Un certificato viene revocato, ad esempio, in caso di denuncia di smarrimento della carta. Poiché non è possibile escludere una carta revocata, `unchecked` non viene mai trattato come `good`. Genera l'avviso `JPKI_REVOCATION_UNCHECKED`, che invia il passaggio NFC a revisione per impostazione predefinita. Puoi scegliere un esito differente con `jpki_revocation_unchecked_action`.Quando la catena di certificati o la firma non è valida, Didit non effettua richieste sulla revoca: lo stato rimane `unchecked` e viene generato solo l'avviso relativo alla catena o alla firma.### Dati del titolare e privacy- Con `jpki_request_attributes` attivo, la decisione include il nome del titolare, la data di nascita, il sesso e l'indirizzo ricavati dal certificato di firma nel campo `jpki.attributes`. Quando è disattivato, la persona inserisce solo il PIN di 4 cifre: la lettura continua a verificare la carta e il PIN, ma non trasmette i dati del titolare e non viene confrontata con la foto della carta.
- Il passaggio NFC non legge mai dal chip il numero individuale (My Number) di 12 cifre della carta.
- La decisione riporta quanto dimostrato dalla carta, mai i certificati stessi, i loro numeri di serie o le firme.Il risultato completo è descritto nel [report della verifica NFC](https://docs.didit.me/it/core-technology/nfc-verification/report-nfc-verification.md#japan-my-number-card-jpki).***## Esempi di integrazione### SDK iOS (Già disponibile)```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
)
```**[Documentazione completa dell'SDK iOS →](https://docs.didit.me/it/integration/native-sdks/ios-sdk.md)**### SDK Android (Già disponibile)```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)
}
```**[Documentazione dell'SDK Android →](https://docs.didit.me/it/integration/native-sdks/android-sdk.md)*****## Architettura di sicurezza```
┌─────────────────────────────────────────────────────────────┐
│ 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
**Cosa succede se il telefono dell'utente non supporta l'NFC?**
Il flusso di verifica rileva automaticamente la funzionalità NFC. Se non è disponibile, gli utenti proseguono con la verifica standard di documento + selfie. La verifica rimane comunque sicura, semplicemente senza l'affidabilità aggiuntiva offerta dall'NFC.
**Cosa succede se il documento non ha un chip NFC?**
Molti documenti (soprattutto i passaporti più vecchi e alcune carte d'identità nazionali) non hanno chip NFC. Il sistema lo rileva e prosegue senza interruzioni con la verifica standard.
**Quanto migliora l'accuratezza con la verifica NFC?**
La verifica NFC fornisce una prova crittografica dell'autenticità del documento direttamente dal governo emittente. Questo aumenta notevolmente l'affidabilità del risultato della verifica e individua falsificazioni sofisticate che potrebbero superare l'ispezione visiva.
**La verifica NFC è obbligatoria?**
No. L'NFC è un miglioramento, non un requisito. Il tuo workflow di verifica può essere configurato per richiedere l'NFC, preferirlo quando disponibile o ignorarlo del tutto in base alla tua tolleranza al rischio.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.