> ## 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 de verificação NFC: chip do e-passaporte e eID
> A Didit verifica e-passaportes e eIDs lendo o chip NFC, com validação criptográfica e detecção de adulteração. A máxima segurança por $0.15 a chamada.
A autenticação por NFC da Didit permite verificar documentos de identidade lendo o chip seguro embutido em passaportes e documentos modernos, usando os recursos de NFC do celular. Isso oferece o **mais alto nível de segurança disponível** na Verificação de identidade.
Prompt de integração da Verificação NFC
Copy prompt to clipboard
\
\````# 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````
\
Paste into
***## Principais benefícios| Benefício | Descrição |
| - | - |
| **Máxima segurança** | Verifica assinaturas criptográficas diretamente dos emissores governamentais |
| **Fácil de usar** | Funciona automaticamente com qualquer celular com NFC |
| **À prova de adulteração** | Detecta manipulações do documento invisíveis a olho nu |
| **Dados completos** | Extrai dados adicionais que o OCR sozinho não fornece |
| **Alternativa flexível** | Volta de forma transparente à verificação padrão se o NFC não estiver disponível |***## Como ativar a verificação NFC### Integração com SDK nativo (recomendada)A verificação NFC está disponível pelos nossos **SDKs nativos**, que dão acesso total aos recursos de NFC do dispositivo:| Plataforma | Suporte a NFC | Documentação |
| - | - | - |
| **iOS** | ✅ Suporte completo | [Documentação do SDK de iOS](https://docs.didit.me/integration/native-sdks/ios-sdk.md) |
| **Android** | ✅ Suporte completo | [Documentação do SDK de Android](https://docs.didit.me/integration/native-sdks/android-sdk.md) |O SDK de iOS cuida automaticamente de toda a configuração de NFC, incluindo:- Identificadores de aplicação ISO7816 para ePassports
- Configuração de entitlements e capabilities
- Leitura do chip em tempo real com feedback visual### Integração web> ⚠️ **Limitações dos navegadores**
>
> A verificação NFC **não está disponível em navegadores web** por restrições das plataformas:
>
> | Navegador | Suporte a NFC |
> | - | - |
> | **Chrome (Android)** | API Web NFC experimental - instável, exige permissões explícitas |
> | **Safari (iOS)** | Sem suporte à API Web NFC |
> | **Outros navegadores** | Sem suporte |
>
> Em integrações web, a verificação NFC é ignorada automaticamente e os usuários seguem com a verificação padrão de documento + selfie.***## Como funciona**1. Início da sessão**O usuário inicia o processo de verificação pelo seu app ou plataforma:- **SDK nativo**: inicie o fluxo de verificação diretamente no seu app
- **Web/Web mobile**: o usuário é orientado a usar o app da Didit para a verificação com NFC, ou segue com a verificação padrão**2. Captura da foto do documento**O usuário fotografa o documento de identidade, capturando:- **MRZ** (Machine Readable Zone) - usada para derivar as chaves de acesso ao chip
- **Imagens da frente e do verso do documento** - dados visuais e elementos de segurança
- **Elementos de segurança visuais** - hologramas, marcas d'água, microimpressão**3. Detecção de suporte a NFC**O sistema verifica automaticamente a compatibilidade do dispositivo e do documento:| Verificação | Descrição |
| - | - |
| **Tipo de documento** | É um ePassport/eID com chip NFC? |
| **Capacidade do dispositivo** | O celular oferece suporte à leitura NFC? |
| **Permissões** | As permissões de NFC necessárias foram concedidas? |> [!NOTE]
>
> Se o NFC não estiver disponível, a verificação continua de forma transparente com a verificação padrão de documento + biometria.**4. Leitura do chip NFC**Para dispositivos e documentos compatíveis:1) O usuário é orientado a aproximar o documento do leitor NFC do celular
2) O feedback visual mostra o progresso da leitura em tempo real
3) Uma comunicação segura com o chip é estabelecida pelos protocolos PACE/BAC**5. Extração de dados**O sistema extrai dados completos do chip seguindo os padrões **ICAO 9303**:| Grupo de dados | Conteúdo | Descrição |
| - | - | - |
| **SOD** | Objeto de segurança do documento | Assinaturas digitais de todos os grupos de dados |
| **DG1** | Dados pessoais | Nome, número do documento, data de nascimento, data de validade |
| **DG2** | Imagem facial | Foto digital de alta resolução do titular |
| **DG7** | Assinatura | Representação digital da assinatura do titular |
| **DG11-14** | Dados adicionais | Podem incluir impressões digitais, varreduras de íris (se armazenadas) |**6. Verificação criptográfica**Os dados extraídos passam por uma rigorosa verificação criptográfica:> **Verificação de assinatura digital**
>
> O hash de cada grupo de dados é verificado contra as assinaturas armazenadas no SOD, garantindo a integridade dos dados.> **Validação da cadeia de certificados**
>
> A cadeia de confiança é validada: **Certificado do documento → Country Signing CA → Raiz do ICAO PKD**, conferindo as listas mestras CSCA e o ICAO Public Key Directory.> **Verificação de revogação de certificados**
>
> Os certificados são verificados contra as Listas de Certificados Revogados (CRLs) para garantir que não foram revogados e que o documento não foi reportado como roubado/comprometido.> **Validação cruzada**
>
> Os dados extraídos por NFC são validados de forma cruzada com os dados de OCR das fotos do documento, a comparação biométrica facial e a verificação do checksum da MRZ.**7. Resultado e pontuação de confiança**O resultado final da verificação inclui:| Saída | Descrição |
| - | - |
| **Status da verificação NFC** | Sucesso, falha ou ignorada |
| **Pontuação de consistência dos dados** | Quanto os dados do NFC coincidem com os dados visuais |
| **Validação de certificados** | Status completo da verificação da cadeia |
| **Reforço de confiança** | O NFC adiciona uma confiança significativa à verificação geral |***## Documentos compatíveisA verificação NFC funciona com **ePassports** e **eIDs** que contêm um chip NFC, normalmente indicado por este símbolo no documento:A maioria dos passaportes emitidos após 2006 contém chips NFC. A cobertura dos documentos nacionais de identidade varia por país. Consulte todos os [documentos compatíveis](https://docs.didit.me/core-technology/nfc-verification/supported-documents-nfc-verification.md).O My Number Card do Japão tem um tipo diferente de chip, lido por JPKI em vez de ICAO 9303. Veja [My Number Card do Japão (JPKI)](#my-number-card-do-japão-jpki).***## My Number Card do Japão (JPKI)O My Number Card do Japão (マイナンバーカード) tem um chip, mas não um chip ICAO 9303. Ele guarda certificados emitidos sob a JPKI, a infraestrutura de chaves públicas do Japão, e chaves privadas que só assinam depois que o titular digita o PIN do cartão. A Didit o lê na mesma etapa de NFC, por JPKI em vez de ICAO 9303, e todo resultado de NFC informa qual protocolo foi usado em `chip_protocol` (`icao` ou `jpki`).> [!WARNING]
>
> **Ainda não disponível.** A leitura do My Number Card por JPKI não está ativada em produção. Até que esteja, um My Number Card capturado em um SDK nativo pula a etapa de NFC com o motivo de omissão `JPKI_UNAVAILABLE`, e o cartão é verificado com captura do documento e correspondência facial, como antes.### Requisitos| Requisito | Detalhe |
| - | - |
| **Documento** | Somente o My Number Card do Japão. Os passaportes japoneses mantêm a leitura do chip ICAO 9303. |
| **Integração** | Uma versão de SDK nativo que lê My Number Cards (iOS, Android ou os SDKs de React Native e Flutter construídos sobre eles). O SDK informa à Didit que consegue ler JPKI; uma versão mais antiga pula a etapa com `JPKI_UNAVAILABLE`. Integrações web e WebView a pulam com `INTEGRATION_WITHOUT_NFC_ACCESS`. |
| **Dispositivo** | Um celular com leitor NFC. Sem ele, a etapa é pulada com `DEVICE_WITHOUT_NFC`. |
| **App host de iOS** | `D392F000260100000001` nos identificadores de seleção ISO7816 do app. Veja a [configuração de NFC no iOS](https://docs.didit.me/integration/native-sdks/ios-sdk.md#nfc-configuration). |
| **Pessoa** | Conhece o PIN de 4 dígitos do cartão e também a senha de assinatura quando o seu fluxo pede os dados do titular. |### O que a pessoa faz**1. Fotografe o cartão**A pessoa captura o My Number Card na etapa de verificação de identidade, como qualquer documento. A Didit reconhece o cartão e envia uma etapa de NFC JPKI em vez de uma leitura de chip de passaporte.**2. Digite o PIN do cartão**O SDK pede o PIN de 4 dígitos do cartão (利用者証明用電子証明書の暗証番号). Quando a configuração `jpki_request_attributes` do nó de NFC está ativada (o padrão), ele também pede a senha de assinatura, também chamada de PIN de assinatura (署名用電子証明書の暗証番号, de 6 a 16 letras maiúsculas e números).**3. Aproxime o cartão do celular**O SDK lê os certificados do cartão, e o cartão assina um desafio de uso único da Didit com a própria chave. O SDK envia os certificados e as assinaturas. Os PINs vão apenas para o cartão, nunca para a Didit.> [!NOTE]
>
> O cartão conta as tentativas erradas: ele bloqueia o PIN de 4 dígitos após 3 seguidas e a senha de assinatura após 5, e um cartão bloqueado precisa ser desbloqueado na prefeitura do titular. Após uma entrada errada, o SDK mostra quantas tentativas restam. Ele nunca faz a última tentativa: quando resta só uma, ele para e diz à pessoa onde redefinir. Peça às pessoas que tenham o PIN e a senha de assinatura à mão antes de começar.### O que a Didit verifica| Verificação | O que a Didit confere | Aviso quando falha (ação padrão) |
| - | - | - |
| **Cadeia de certificados** | Todo certificado se encadeia à autoridade certificadora JPKI do seu tipo, está dentro do prazo de validade e é um certificado de My Number Card (`jpki.chain_valid`). | `JPKI_CERTIFICATE_INVALID` (Recusar) |
| **Cartão e PIN** | A assinatura do cartão sobre o desafio de uso único é verificada contra o seu certificado (`jpki.signature_valid`). O cartão só assina depois que o PIN é digitado, então isso comprova que a pessoa tem o cartão e conhece o PIN. | `JPKI_SIGNATURE_INVALID` (Recusar) |
| **Revogação** | Nenhum certificado foi revogado (`jpki.revocation_status`). | `JPKI_CERTIFICATE_REVOKED` quando `revoked` (Recusar), `JPKI_REVOCATION_UNCHECKED` quando `unchecked` (Em revisão) |
| **Dados do titular** | O nome, a data de nascimento, o sexo e o endereço no certificado de assinatura coincidem com os dados lidos da foto do mesmo cartão (`jpki.attributes_match_ocr`, `jpki.mismatched_attributes`). | `JPKI_AND_OCR_DATA_NOT_SAME` (Em revisão) |Cada ação é uma configuração do nó de NFC, então você pode mudá-la para **Sem ação**, **Em revisão** ou **Recusar**. Veja os [avisos de NFC](https://docs.didit.me/core-technology/nfc-verification/warnings-nfc-verification.md#japan-my-number-card-jpki) e a [configuração de recursos de NFC](https://docs.didit.me/management-api/workflows/feature-configs.md#nfc-/-epassport).### O que significa um status de revogação não verificado`revocation_status: "unchecked"` significa que a Didit verificou a cadeia de certificados e a assinatura do cartão, mas não obteve resposta sobre se algum certificado foi revogado. Um certificado é revogado quando, por exemplo, o cartão é reportado como perdido. Como não é possível descartar que o cartão tenha sido revogado, `unchecked` nunca é tratado como `good`. Ele gera `JPKI_REVOCATION_UNCHECKED`, que por padrão envia a etapa de NFC para revisão. Escolha outro resultado com `jpki_revocation_unchecked_action`.Quando a cadeia de certificados ou a assinatura não é válida, a Didit não consulta a revogação: o status permanece `unchecked` e apenas o aviso da cadeia ou da assinatura é gerado.### Dados do titular e privacidade- Com `jpki_request_attributes` ativado, a decisão inclui o nome, a data de nascimento, o sexo e o endereço do titular a partir do certificado de assinatura em `jpki.attributes`. Com ele desativado, a pessoa digita apenas o PIN de 4 dígitos: a leitura ainda comprova o cartão e o PIN, mas não traz dados do titular e não é comparada com a foto do cartão.
- A etapa de NFC nunca lê do chip o Número Individual de 12 dígitos do cartão (My Number).
- A decisão informa o que o cartão comprovou, nunca os certificados em si, seus números de série ou as assinaturas.O resultado completo está descrito no [relatório de verificação NFC](https://docs.didit.me/core-technology/nfc-verification/report-nfc-verification.md#japan-my-number-card-jpki).***## Exemplos de integração### SDK de iOS (disponível agora)```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
)
```**[Documentação completa do SDK de iOS →](https://docs.didit.me/integration/native-sdks/ios-sdk.md)**### SDK de Android (em breve)```kotlin theme={null}
// Coming soon - use WebView integration in the meantime
// See Android SDK documentation for WebView setup
```**[Documentação do SDK de Android →](https://docs.didit.me/integration/native-sdks/android-sdk.md)*****## Arquitetura de segurança```
┌─────────────────────────────────────────────────────────────┐
│ 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
**E se o celular do usuário não tiver suporte a NFC?**
O fluxo de verificação detecta automaticamente a capacidade de NFC. Se ela não estiver disponível, os usuários seguem com a verificação padrão de documento + selfie. A verificação continua segura, apenas sem o reforço adicional de confiança do NFC.
**E se o documento não tiver chip NFC?**
Muitos documentos (especialmente passaportes mais antigos e alguns documentos nacionais de identidade) não têm chip NFC. O sistema detecta isso e continua de forma transparente com a verificação padrão.
**Quanto a verificação NFC melhora a precisão?**
A verificação NFC fornece prova criptográfica da autenticidade do documento diretamente do governo emissor. Isso aumenta de forma significativa a confiança no resultado da verificação e detecta falsificações sofisticadas que poderiam passar por uma inspeção visual.
**A verificação NFC é obrigatória?**
Não. O NFC é um reforço, não um requisito. O seu fluxo de verificação pode ser configurado para exigir o NFC, preferi-lo quando disponível ou ignorá-lo por completo, de acordo com a sua tolerância a risco.
***
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.