> ## 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.
# Verificació NFC: API per a passaports electrònics i eID
> Verifica passaports i eID amb Didit mitjançant lectura de xip NFC. Validació criptogràfica de màxima seguretat. Pagament per crida: $0.15.
L'autenticació basada en NFC et permet verificar documents d'identitat llegint el xip segur integrat en passaports i documents d'identitat moderns mitjançant les capacitats NFC d'un telèfon mòbil. Això proporciona el **nivell més alt de seguretat disponible** per a la Verificació d'identitat.
Prompt d'integració de la verificació NFC
Copia el prompt al porta-retalls
\
\````# 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````
\
Enganxa a
***## Beneficis clau| Benefici | Descripció |
| - | - |
| **Màxima seguretat** | Verifica signatures criptogràfiques directament dels emissors governamentals |
| **Fàcil d'utilitzar** | Funciona automàticament amb qualsevol telèfon amb NFC |
| **A prova de manipulacions** | Detecta manipulacions al document invisibles a l'ull humà |
| **Dades completes** | Extreu dades addicionals no disponibles només mitjançant OCR |
| **Alternativa flexible** | Passa de manera fluida a la verificació estàndard si l'NFC no està disponible |***## Com habilitar la verificació NFC### Integració amb SDK natiu (Recomanada)La verificació NFC està disponible a través dels nostres **SDK natius**, que ofereixen accés complet a les capacitats NFC del dispositiu:| Plataforma | Suport d'NFC | Documentació |
| - | - | - |
| **iOS** | ✅ Suport complet | [Documentació de l'SDK per a iOS](https://docs.didit.me/ca/integration/native-sdks/ios-sdk.md) |
| **Android** | ✅ Suport complet | [Documentació de l'SDK per a Android](https://docs.didit.me/ca/integration/native-sdks/android-sdk.md) |L'SDK per a iOS gestiona tota la configuració d'NFC automàticament, incloent-hi:- Identificadors d'aplicació ISO7816 per a passaports electrònics (ePassports)
- Configuració de drets i capacitats
- Lectura del xip en temps real amb indicacions visuals### Integració web> ⚠️ **Limitacions del navegador**
>
> La verificació NFC **no està disponible en navegadors web** a causa de restriccions de la plataforma:
>
> | Navegador | Suport d'NFC |
> | - | - |
> | **Chrome (Android)** | API Web NFC experimental: inestable, requereix permisos explícits |
> | **Safari (iOS)** | Sense suport per a l'API Web NFC |
> | **Altres navegadors** | Sense suport |
>
> En integracions web, la verificació NFC s'omet automàticament i els usuaris continuen amb la verificació estàndard de document + selfie.***## Com funciona**1. Inici de la sessió**L'usuari inicia el procés de verificació a través de la teva aplicació o plataforma:- **SDK natiu**: inicia el flux de verificació directament a la teva aplicació
- **Web / Web mòbil**: es guia l'usuari perquè utilitzi la Didit App per a la verificació NFC, o bé continua amb la verificació estàndard**2. Captura de fotos del document**L'usuari fotografia el seu document d'identitat, capturant:- **MRZ** (zona de lectura mecànica) — s'utilitza per derivar les claus d'accés al xip
- **Imatges de l'anvers i el revers del document** — dades visuals i característiques de seguretat
- **Característiques visuals de seguretat** — hologrames, filigranes, microimpressió**3. Detecció de compatibilitat amb NFC**El sistema comprova automàticament la compatibilitat del dispositiu i del document:| Comprovació | Descripció |
| - | - |
| **Tipus de document** | És un passaport electrònic o document d'identitat electrònic amb xip NFC? |
| **Capacitat del dispositiu** | El telèfon permet llegir NFC? |
| **Permisos** | S'han concedit els permisos NFC necessaris? |> [!NOTE]
>
> Si l'NFC no està disponible, la verificació continua sense problemes amb la verificació estàndard de document + biometria.**4. Lectura del xip NFC**Per a dispositius i documents compatibles:1) Es guia l'usuari perquè col·loqui el seu document a prop del lector NFC del telèfon
2) Els indicadors visuals mostren el progrés de la lectura en temps real
3) S'estableix una comunicació segura amb el xip mitjançant els protocols PACE/BAC**5. Extracció de dades**El sistema extreu dades completes del xip seguint els estàndards **ICAO 9303**:| Grup de dades | Contingut | Descripció |
| - | - | - |
| **SOD** | Objecte de seguretat del document | Signatures digitals de tots els grups de dades |
| **DG1** | Dades personals | Nom, número d'identificació, data de naixement, data de caducitat |
| **DG2** | Imatge facial | Foto digital d'alta resolució del titular |
| **DG7** | Signatura | Representació digital de la signatura del titular |
| **DG11-14** | Dades addicionals | Poden incloure empremtes dactilars, escanejos d'iris (si estan emmagatzemats) |**6. Verificació criptogràfica**Les dades extretes se sotmeten a una verificació criptogràfica rigorosa:> [accordion] Verificació de la signatura digital
>
> Es verifica el hash de cada grup de dades respecte a les signatures emmagatzemades al SOD, garantint la integritat de les dades.> [accordion] Validació de la cadena de certificats
>
> Es valida la cadena de confiança: **Certificat del document → CA de signatura del país → Arrel PKD de l'ICAO**, comprovant-la contra les llistes mestres CSCA i el Directori de Claus Públiques (PKD) de l'ICAO.> [accordion] Comprovació de revocació de certificats
>
> Els certificats es verifiquen contra llistes de revocació de certificats (CRL) per garantir que no han estat revocats i que el document no s'ha notificat com a robat o compromès.> [accordion] Validació creuada
>
> Les dades extretes per NFC es validen de manera creuada amb les dades d'OCR de les fotos del document, la comparació biomètrica facial i la verificació de sumes de control de l'MRZ.**7. Resultat i puntuació de confiança**El resultat final de la verificació inclou:| Sortida | Descripció |
| - | - |
| **Estat de la verificació NFC** | Satisfactori, fallit o omès |
| **Puntuació de coherència de les dades** | Grau de coincidència entre les dades NFC i les dades visuals |
| **Validació de certificats** | Estat de verificació de la cadena completa |
| **Increment de confiança** | L'NFC aporta un augment significatiu de la confiança en la verificació global |***## Documents admesosLa verificació NFC funciona amb **passaports electrònics** i **documents d'identitat electrònics** que contenen un xip NFC, normalment indicat per aquest símbol al document:La majoria dels passaports emesos després del 2006 contenen xips NFC. La cobertura varia segons el país per als documents d'identitat nacionals. Consulta tots els [documents admesos](https://docs.didit.me/ca/core-technology/nfc-verification/supported-documents-nfc-verification.md).La targeta My Number del Japó té un tipus de xip diferent, que es llegeix mitjançant JPKI en lloc de l'ICAO 9303. Consulta [Targeta My Number del Japó (JPKI)](#japan-my-number-card-jpki).***## Japan My Number Card (JPKI)La Japan My Number Card (マイナンバーカード) té un xip, però aquest no és de tipus ICAO 9303. Conté certificats emesos sota JPKI, la infraestructura de clau pública del Japó, i claus privades que només signen després que el titular introdueixi el PIN de la targeta. Didit la llegeix en el mateix pas d'NFC, mitjançant JPKI en lloc d'ICAO 9303, i cada resultat d'NFC indica quin protocol s'ha utilitzat a `chip_protocol` (`icao` o `jpki`).> [!WARNING]
>
> **Encara no disponible.** La lectura de la My Number Card mitjançant JPKI no està activada a producció. Fins que ho estigui, una My Number Card capturada en un SDK natiu omet el pas d'NFC amb el motiu d'omissió `JPKI_UNAVAILABLE`, i la targeta es verifica amb la captura de documents i la coincidència facial com abans.### Requisits| Requisit | Detall |
| - | - |
| **Document** | Només la Japan My Number Card. Els passaports japonesos mantenen la lectura de xip ICAO 9303. |
| **Integració** | Una versió de l'SDK natiu que llegeixi My Number Cards (iOS, Android o els SDK de React Native i Flutter basats en aquests). L'SDK indica a Didit que pot llegir JPKI; una versió més antiga omet el pas amb `JPKI_UNAVAILABLE`. Les integracions web i WebView l'ometen amb `INTEGRATION_WITHOUT_NFC_ACCESS`. |
| **Dispositiu** | Un telèfon amb lector NFC. Sense aquest, el pas s'omet amb `DEVICE_WITHOUT_NFC`. |
| **Aplicació amfitriona d'iOS** | `D392F000260100000001` als identificadors de selecció ISO7816 de l'aplicació. Consulta la [configuració d'NFC per a iOS](https://docs.didit.me/ca/integration/native-sdks/ios-sdk.md#configuració-de-nfc). |
| **Persona** | Coneix el PIN de 4 dígits de la targeta, i també la contrasenya de signatura quan el teu flux de treball sol·licita les dades del titular. |### Què fa la persona**1. Fotografiar la targeta**La persona captura la My Number Card en el pas de verificació d'identitat, com es fa amb qualsevol document. Didit reconeix la targeta i envia un pas d'NFC amb JPKI en comptes d'una lectura de xip de passaport.**2. Introduir el PIN de la targeta**L'SDK demana el PIN de 4 dígits de la targeta (利用者証明用電子証明書の暗証番号). Quan el paràmetre `jpki_request_attributes` del node d'NFC està activat (per defecte), també demana la contrasenya de signatura, anomenada també PIN de signatura (署名用電子証明書の暗証番号, de 6 a 16 caràcters, formats per lletres majúscules i números).**3. Apropar la targeta al telèfon**L'SDK llegeix els certificats de la targeta, i la targeta signa un desafiament d'un sol ús de Didit amb la seva pròpia clau. L'SDK puja els certificats i les signatures. Els PIN només van a la targeta, mai a Didit.> [!NOTE]
>
> La targeta compta les entrades incorrectes: bloqueja el PIN de 4 dígits després de 3 intents consecutius i la contrasenya de signatura després de 5, i si es bloqueja s'ha de restablir a l'oficina municipal del titular. Després d'un intent incorrecte, l'SDK mostra quants intents queden. Mai realitza l'últim intent: quan només en queda un, s'atura i indica a la persona on pot restablir-lo. Demana als usuaris que tinguin preparats el seu PIN i la contrasenya de signatura abans de començar.### Què comprova Didit| Comprovació | Què verifica Didit | Advertència quan falla (acció per defecte) |
| - | - | - |
| **Cadena de certificats** | Cada certificat enllaça amb l'autoritat de certificació JPKI del seu tipus, està dins del seu període de validesa i és un certificat de My Number Card (`jpki.chain_valid`). | `JPKI_CERTIFICATE_INVALID` (Rebutjar) |
| **Targeta i PIN** | La signatura de la targeta sobre el desafiament d'un sol ús es verifica contra el seu certificat (`jpki.signature_valid`). La targeta només signa després d'introduir el seu PIN, per la qual cosa això demostra que la persona té la targeta i en coneix el PIN. | `JPKI_SIGNATURE_INVALID` (Rebutjar) |
| **Revocació** | Cap certificat ha estat revocat (`jpki.revocation_status`). | `JPKI_CERTIFICATE_REVOKED` quan és `revoked` (Rebutjar), `JPKI_REVOCATION_UNCHECKED` quan és `unchecked` (Revisió) |
| **Dades del titular** | El nom, la data de naixement, el sexe i l'adreça del certificat de signatura coincideixen amb les dades llegides de la foto de la mateixa targeta (`jpki.attributes_match_ocr`, `jpki.mismatched_attributes`). | `JPKI_AND_OCR_DATA_NOT_SAME` (Revisió) |Cada acció és una opció de configuració del node d'NFC, de manera que pots canviar-la a **Sense acció**, **Revisió** o **Rebutjar**. Consulta les [advertències d'NFC](https://docs.didit.me/ca/core-technology/nfc-verification/warnings-nfc-verification.md#japan-my-number-card-jpki) i la [configuració de la funcionalitat d'NFC](https://docs.didit.me/ca/management-api/workflows/feature-configs.md#nfc-/-passaport-electrònic).### Què significa un estat de revocació no comprovat`revocation_status: "unchecked"` significa que Didit ha verificat la cadena de certificats i la signatura de la targeta, però no ha obtingut resposta sobre si algun certificat ha estat revocat. Un certificat es revoca quan, per exemple, es denuncia la pèrdua de la targeta. Com que no es pot descartar una targeta revocada, `unchecked` mai es tracta com a `good`. Genera `JPKI_REVOCATION_UNCHECKED`, la qual cosa envia el pas d'NFC a revisió per defecte. Tria un resultat diferent amb `jpki_revocation_unchecked_action`.Quan la cadena de certificats o la signatura no és vàlida, Didit no consulta sobre la revocació: l'estat es manté en `unchecked` i només es genera l'advertència de la cadena o de la signatura.### Dades del titular i privacitat- Amb `jpki_request_attributes` activat, la decisió inclou el nom, la data de naixement, el sexe i l'adreça del titular del certificat de signatura a `jpki.attributes`. Amb aquesta opció desactivada, la persona només introdueix el PIN de 4 dígits: la lectura continua demostrant la targeta i el PIN, però no conté dades del titular ni es compara amb la foto de la targeta.
- El pas d'NFC mai llegeix del xip el número individual de 12 dígits (My Number) de la targeta.
- La decisió informa d'allò que la targeta ha demostrat, mai dels certificats en si, dels seus números de sèrie ni de les signatures.El resultat complet es descriu a l'[informe de verificació NFC](https://docs.didit.me/ca/core-technology/nfc-verification/report-nfc-verification.md#japan-my-number-card-jpki).***## Exemples d'integració### SDK d'iOS (Ja disponible)```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
)
```**[Documentació completa de l'SDK d'iOS →](https://docs.didit.me/ca/integration/native-sdks/ios-sdk.md)**### SDK d'Android (Ja disponible)```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)
}
```**[Documentació de l'SDK d'Android →](https://docs.didit.me/ca/integration/native-sdks/android-sdk.md)*****## Arquitectura de seguretat```
┌─────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```***## Preguntes freqüents
**Què passa si el telèfon de l'usuari no és compatible amb NFC?**
El flux de verificació detecta automàticament la compatibilitat amb NFC. Si no està disponible, els usuaris continuen amb la verificació estàndard de document + selfie. La verificació continua sent segura, simplement sense l'augment de confiança addicional que aporta l'NFC.
**Què passa si el document no té xip NFC?**
Molts documents (especialment passaports més antics i alguns documents d'identitat nacionals) no tenen xips NFC. El sistema ho detecta i continua sense problemes amb la verificació estàndard.
**Fins a quin punt millora la precisió la verificació NFC?**
La verificació NFC proporciona una prova criptogràfica de l'autenticitat del document directament del govern emissor. Això augmenta significativament la confiança en el resultat de la verificació i detecta falsificacions sofisticades que podrien superar la inspecció visual.
**És obligatòria la verificació NFC?**
No. L'NFC és una millora, no un requisit. El teu flux de treball de verificació es pot configurar per exigir NFC, prioritzar-lo quan estigui disponible o ometre'l completament segons la teva tolerància al risc.
***
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.