> ## 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 验证 API：电子护照与电子身份证芯片 > Didit 通过读取 NFC 芯片验证电子护照与电子身份证。提供密码学校验和防篡改检测，实现最高安全级别的身份核验。按次计费 $0.15。 基于 NFC 的认证允许您利用手机的 NFC 功能读取嵌入在现代护照和身份证件中的安全芯片，从而验证身份证件。这为身份证件验证提供了**目前可用的最高安全级别**。 NFC 验证集成提示词 将提示词复制到剪贴板 \

\````# 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````

\
粘贴到 ![NFC 交互](https://didit-public-assets.s3.eu-west-1.amazonaws.com/icons/docs/nfc-id.gif)***## 核心优势| 优势 | 描述 | | - | - | | **最高安全性** | 直接核验来自政府签发机构的密码学签名 | | **简单易用** | 可在任何支持 NFC 的手机上自动运行 | | **防篡改** | 检测肉眼无法察觉的证件篡改 | | **数据更全面** | 提取仅凭 OCR 无法获取的额外数据 | | **灵活回退** | 如果 NFC 不可用，可平滑回退至标准验证 |***## 如何启用 NFC 验证### 原生 SDK 集成 (推荐)NFC 验证可通过我们的**原生 SDK**实现，这些 SDK 提供了对设备 NFC 功能的完全访问权限：| 平台 | NFC 支持 | 文档 | | - | - | - | | **iOS** | ✅ 完全支持 | [iOS SDK 文档](https://docs.didit.me/zh/integration/native-sdks/ios-sdk.md) | | **Android** | ✅ 完全支持 | [Android SDK 文档](https://docs.didit.me/zh/integration/native-sdks/android-sdk.md) |iOS SDK 会自动处理所有 NFC 配置，包括：- 针对电子护照的 ISO7816 应用程序标识符 - 权限和功能的设置 - 带有直观视觉反馈的实时芯片读取### Web 集成> ⚠️ **浏览器限制** > > 由于平台限制，NFC 验证在 **Web 浏览器中不可用**： > > | 浏览器 | NFC 支持 | > | - | - | > | **Chrome (Android)** | 实验性 Web NFC API - 不稳定，需要明确的权限授权 | > | **Safari (iOS)** | 不支持 Web NFC API | > | **其他浏览器** | 不支持 | > > 对于 Web 集成，系统会自动跳过 NFC 验证，用户将继续进行标准的证件加自拍照验证。***## 工作原理**1. 会话发起**用户通过您的应用或平台启动验证流程：- **原生 SDK**：直接在您的应用内启动验证工作流 - **Web/移动端 Web**：引导用户使用 Didit App 进行支持 NFC 的验证，或继续进行标准验证**2. 证件拍照采集**用户拍摄其身份证件照片，采集以下内容：- **MRZ**（机读区）：用于派生芯片访问密钥 - **证件正反面图像**：视觉数据与防伪特征 - **视觉防伪特征**：全息图、水印、缩微印刷**3. NFC 支持检测**系统自动检查设备与证件的兼容性：| 检查项 | 描述 | | - | - | | **证件类型** | 是否为带有 NFC 芯片的电子护照/电子身份证？ | | **设备功能** | 手机是否支持 NFC 读取？ | | **权限** | 是否已授予必要的 NFC 权限？ |> [!NOTE] > > 若 NFC 不可用，验证将无缝切换为标准的证件 + 生物识别验证继续进行。**4. NFC 芯片读取**对于兼容的设备与证件：1) 引导用户将证件贴近手机的 NFC 读取区域 2) 视觉反馈实时显示读取进度 3) 使用 PACE/BAC 协议与芯片建立安全通信**5. 数据提取**系统遵循 **ICAO 9303** 标准从芯片中提取完整数据：| 数据组 | 内容 | 描述 | | - | - | - | | **SOD** | 证件安全对象 | 所有数据组的数字签名 | | **DG1** | 个人数据 | 姓名、证件号码、出生日期、到期日期 | | **DG2** | 人脸图像 | 持证人的高分辨率数字照片 | | **DG7** | 签名 | 持证人签名的数字表示 | | **DG11-14** | 附加数据 | 可能包含指纹、虹膜扫描（若有存储） |**6. 密码学验证**提取的数据将经过严格的密码学验证：> [accordion] 数字签名验证 > > 将每个数据组的哈希值与 SOD 中存储的签名进行核对验证，确保数据完整性。> [accordion] 证书链验证 > > 验证信任链：**证件证书 → 国家签名 CA → ICAO PKD 根证书**，对照 CSCA 主列表和 ICAO 公钥目录进行核验。> [accordion] 证书吊销检查 > > 对照证书吊销列表（CRL）核验证书，确保其未被吊销且证件未被报告为失窃或已遭到泄露。> [accordion] 交叉验证 > > 将 NFC 提取的数据与证件照片的 OCR 数据、人脸生物特征比对结果以及 MRZ 校验和验证进行交叉核验。**7. 结果与置信度分数**最终验证结果包括：| 输出项 | 描述 | | - | - | | **NFC 验证状态** | 成功、失败或已跳过 | | **数据一致性分数** | NFC 数据与视觉数据的匹配程度 | | **证书验证** | 完整信任链的验证状态 | | **置信度提升** | NFC 为整体验证带来显著的置信度提升 |***## 支持的证件NFC 验证适用于包含 NFC 芯片的**电子护照**和**电子身份证**，证件上通常带有此标识：![ePassport Logo](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/epassport-logo.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=89cd90281e6ff1cd96f5a3d6a2200cad)2006 年之后签发的大多数护照均包含 NFC 芯片。国民身份证的支持情况因国家/地区而异。查看所有[支持的证件](https://docs.didit.me/zh/core-technology/nfc-verification/supported-documents-nfc-verification.md)。日本个人编号卡（My Number Card）采用不同类型的芯片，通过 JPKI 而非 ICAO 9303 读取。请参阅[日本个人编号卡 (JPKI)](#日本个人编号卡（jpki）)。***## 日本个人编号卡（JPKI）日本个人编号卡（マイナンバーカード）内含芯片，但并非 ICAO 9303 芯片。它包含依据日本公钥基础设施（JPKI）签发的证书，以及仅在持卡人输入卡片 PIN 码后才进行签名的私钥。Didit 在相同的 NFC 步骤中通过 JPKI（而非 ICAO 9303）读取该卡片，每个 NFC 结果都会在 `chip_protocol`（`icao` 或 `jpki`）中指明所使用的协议。> [!WARNING] > > \*\*尚未开放。\*\*通过 JPKI 读取个人编号卡的功能尚未在生产环境中启用。在启用之前，原生 SDK 中捕获的个人编号卡将跳过 NFC 步骤，跳过原因标记为 `JPKI_UNAVAILABLE`，卡片将一如既往地通过证件采集和人脸比对进行验证。### 要求| 要求 | 详情 | | - | - | | **证件** | 仅限日本个人编号卡。日本护照仍使用 ICAO 9303 芯片读取。 | | **集成** | 支持读取个人编号卡的原生 SDK 版本（iOS、Android，或基于它们构建的 React Native 和 Flutter SDK）。SDK 会告知 Didit 其支持读取 JPKI；旧版本将跳过该步骤并提示 `JPKI_UNAVAILABLE`。Web 和 WebView 集成则会以 `INTEGRATION_WITHOUT_NFC_ACCESS` 跳过。 | | **设备** | 带有 NFC 读取器的手机。若缺少此项，该步骤将以 `DEVICE_WITHOUT_NFC` 跳过。 | | **iOS 宿主应用** | 在应用的 ISO7816 选择标识符中包含 `D392F000260100000001`。请参阅 [iOS NFC 配置](https://docs.didit.me/zh/integration/native-sdks/ios-sdk.md#nfc-配置)。 | | **个人** | 知晓卡片的 4 位 PIN 码；在工作流要求获取持卡人数据时，还需知晓卡片的签名密码。 |### 用户的操作步骤**1. 拍摄卡片照片**用户在身份证件验证步骤中拍摄个人编号卡，与处理任何其他证件一致。Didit 会识别该卡片，并发起 JPKI NFC 步骤，而不是护照芯片读取。**2. 输入卡片 PIN 码**SDK 会提示输入卡片的 4 位 PIN 码（利用者証明用電子証明書の暗証番号）。当 NFC 节点的 `jpki_request_attributes` 设置开启时（默认开启），还会要求输入签名密码，也称签名 PIN 码（署名用電子証明書の暗証番号，6 至 16 位大写英文字母和数字）。**3. 将卡片贴近手机**SDK 读取卡片证书，卡片会使用其自身的密钥对来自 Didit 的一次性挑战进行签名。SDK 上传证书和签名。PIN 码仅发送给卡片，绝不会传输给 Didit。> [!NOTE] > > 卡片会记录错误输入次数：连续输入错误 3 次后将锁定 4 位 PIN 码，连续输入错误 5 次后将锁定签名密码，被锁定的 PIN 码或签名密码必须由持卡人在所属的市区町村役所进行重置。输入错误后，SDK 会显示剩余尝试次数。SDK 绝不会进行最后一次尝试：当只剩一次机会时，它会停止尝试并告知用户在何处进行重置。请提醒用户在开始前准备好其 PIN 码和签名密码。### Didit 核验的内容| 核验项 | Didit 验证的内容 | 失败时的警告（默认操作） | | - | - | - | | **证书链** | 每个证书均可链接至其对应类型的 JPKI 认证机构，处于有效期内，且为个人编号卡证书（`jpki.chain_valid`）。 | `JPKI_CERTIFICATE_INVALID`（已拒绝） | | **卡片和 PIN** | 卡片对一次性挑战的签名可通过其证书完成验证（`jpki.signature_valid`）。卡片仅在输入 PIN 码后才进行签名，因此这证明了该个人持有该卡片且知晓 PIN 码。 | `JPKI_SIGNATURE_INVALID`（已拒绝） | | **吊销状态** | 无任何证书被吊销（`jpki.revocation_status`）。 | `revoked` 时为 `JPKI_CERTIFICATE_REVOKED`（已拒绝），`unchecked` 时为 `JPKI_REVOCATION_UNCHECKED`（审核中） | | **持卡人数据** | 签名证书中的姓名、出生日期、性别和地址与同一张卡片照片中读取的数据相符（`jpki.attributes_match_ocr`、`jpki.mismatched_attributes`）。 | `JPKI_AND_OCR_DATA_NOT_SAME`（审核中） |每项操作都是 NFC 节点上的配置项，因此您可以将其更改为**无操作**、**审核中**或**已拒绝**。请参阅 [NFC 警告](https://docs.didit.me/zh/core-technology/nfc-verification/warnings-nfc-verification.md#日本个人编号卡-jpki)和 [NFC 功能配置](https://docs.didit.me/zh/management-api/workflows/feature-configs.md#nfc-/-电子护照)。### 未核查吊销状态的含义`revocation_status: "unchecked"` 表示 Didit 已验证证书链和卡片签名，但未能获取证书是否已被吊销的响应。例如，当卡片挂失时，证书会被吊销。由于无法排除卡片已被吊销的可能性，`unchecked` 绝不会被视为 `good`。它会触发 `JPKI_REVOCATION_UNCHECKED`，默认情况下将 NFC 步骤转入审核中。您可以通过 `jpki_revocation_unchecked_action` 选择其他结果。当证书链或签名无效时，Didit 不会查询吊销状态：状态将保持为 `unchecked`，且仅触发证书链或签名警告。### 持卡人数据与隐私- 开启 `jpki_request_attributes` 后，决策结果将在 `jpki.attributes` 下包含签名证书中的持卡人姓名、出生日期、性别和地址。关闭该项时，用户只需输入 4 位 PIN 码：读取过程仍会验证卡片和 PIN 码，但不携带持卡人数据，亦不会与卡片照片进行比对。 - NFC 步骤绝不会从芯片中读取卡片的 12 位个人编号（My Number）。 - 决策结果仅报告卡片所证明的内容，绝不会包含证书本身、其序列号或签名。完整结果详见 [NFC 验证报告](https://docs.didit.me/zh/core-technology/nfc-verification/report-nfc-verification.md#日本个人番号卡-jpki)。***## 集成示例### iOS SDK（现已开放）```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 ) ```**[完整 iOS SDK 文档 →](https://docs.didit.me/zh/integration/native-sdks/ios-sdk.md)**### Android SDK（现已开放）```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 文档 →](https://docs.didit.me/zh/integration/native-sdks/android-sdk.md)*****## 安全架构``` ┌─────────────────────────────────────────────────────────────┐ │ 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 │ │ │ └──────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ```***## 常见问题
**如果用户的手机不支持 NFC 怎么办？** 验证流程会自动检测 NFC 功能。如果不可用，用户将继续进行标准的证件 + 自拍照验证。验证仍然安全可靠，只是没有额外的 NFC 置信度加成。
**如果证件没有 NFC 芯片怎么办？** 许多证件（特别是较旧的护照和某些身份证件）没有 NFC 芯片。系统会检测到这一点，并无缝继续进行标准验证。
**NFC 验证能在多大程度上提高准确性？** NFC 验证提供由签发政府直接出具的、证明证件真实性的密码学证据。这显著提升了对验证结果的置信度，并能识别出可能通过视觉检查的高级伪造。
**NFC 验证是强制要求的吗？** 不是。NFC 是一项增强功能，而非强制要求。您可以根据自身的风险承受能力，将验证工作流配置为强制要求 NFC、在可用时优先使用，或完全跳过。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.