> ## 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 для биометрических паспортов и eID
> Didit верифицирует e-паспорта и eID через NFC: криптографическая проверка чипов и защита от подделок. Оплата за вызов: $0.15.
Аутентификация на основе NFC позволяет верифицировать документы, удостоверяющие личность, считывая защищённый чип, встроенный в современные паспорта и ID-карты, с помощью модуля 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 |
| **Защита от подделок** | Выявляет манипуляции с документом, невидимые невооружённым глазом |
| **Полнота данных** | Извлекает дополнительные данные, недоступные с помощью одного лишь OCR |
| **Гибкий фолбэк** | Корректно переключается на стандартную верификацию, если NFC недоступен |***## Как включить NFC-верификацию### Интеграция с помощью нативных SDK (рекомендуется)NFC-верификация доступна через наши **нативные SDK**, которые предоставляют полный доступ к возможностям NFC устройства:| Платформа | Поддержка NFC | Документация |
| - | - | - |
| **iOS** | ✅ Полная поддержка | [Документация iOS SDK](https://docs.didit.me/ru/integration/native-sdks/ios-sdk.md) |
| **Android** | ✅ Полная поддержка | [Документация Android SDK](https://docs.didit.me/ru/integration/native-sdks/android-sdk.md) |iOS SDK берёт на себя всю настройку NFC в автоматическом режиме, включая:- Идентификаторы приложений ISO7816 для электронных паспортов
- Настройку разрешений и системных возможностей
- Считывание чипа в реальном времени с визуальной обратной связью### Веб-интеграция> ⚠️ **Ограничения браузеров**
>
> NFC-верификация **недоступна в веб-браузерах** из-за ограничений платформ:
>
> | Браузер | Поддержка NFC |
> | - | - |
> | **Chrome (Android)** | Экспериментальный Web NFC API - нестабилен, требует явных разрешений |
> | **Safari (iOS)** | Нет поддержки Web NFC API |
> | **Другие браузеры** | Поддержка отсутствует |
>
> При веб-интеграциях NFC-верификация автоматически пропускается, и пользователи переходят к стандартной верификации «документ + селфи».***## Как это работает**1. Инициация сессии**Пользователь начинает процесс верификации через ваше приложение или платформу:- **Нативный SDK**: запуск процесса верификации напрямую в вашем приложении
- **Веб/Мобильный веб**: пользователю предлагается использовать Didit App для верификации с поддержкой NFC, либо продолжить стандартную верификацию**2. Фотографирование документа**Пользователь фотографирует свой документ, удостоверяющий личность, фиксируя:- **MRZ** (машиночитаемую зону) — используется для получения ключей доступа к чипу
- **Изображения лицевой и оборотной сторон документа** — визуальные данные и элементы защиты
- **Визуальные элементы защиты** — голограммы, водяные знаки, микропечать**3. Определение поддержки NFC**Система автоматически проверяет совместимость устройства и документа:| Проверка | Описание |
| - | - |
| **Тип документа** | Является ли это электронным паспортом/eID с 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] Валидация цепочки сертификатов
>
> Проверяется цепочка доверия: **сертификат документа → удостоверяющий центр страны → корневой сертификат ICAO PKD**, со сверкой по мастер-спискам CSCA и каталогу открытых ключей ICAO.> [accordion] Проверка отзыва сертификатов
>
> Сертификаты проверяются по спискам отзыва сертификатов (CRL), чтобы убедиться, что они не были отозваны, а документ не числится украденным или скомпрометированным.> [accordion] Перекрёстная проверка
>
> Данные, извлечённые через NFC, перекрёстно сверяются с данными OCR с фотографий документа, результатами биометрического сравнения лиц и проверкой контрольных сумм MRZ.**7. Результат и оценка уверенности**Итоговый результат верификации включает:| Выходные данные | Описание |
| - | - |
| **Статус NFC-верификации** | Успешно, неуспешно или пропущено |
| **Оценка согласованности данных** | Насколько точно данные NFC совпадают с визуальными данными |
| **Валидация сертификата** | Статус полной проверки цепочки |
| **Повышение уверенности** | NFC значительно повышает итоговую уверенность в результатах верификации |***## Поддерживаемые документыNFC-верификация работает с **электронными паспортами** и **eID**, содержащими NFC-чип. Обычно на таких документах присутствует следующий символ:Большинство паспортов, выданных после 2006 года, содержат NFC-чипы. Доступность чипов в национальных удостоверениях личности зависит от страны. Ознакомьтесь со списком [поддерживаемых документов](https://docs.didit.me/ru/core-technology/nfc-verification/supported-documents-nfc-verification.md).Карта Japan My Number Card оснащена чипом другого типа, считываемым через JPKI вместо ICAO 9303. См. раздел [Japan My Number Card (JPKI)](#карта-my-number-в-японии-jpki).***## Карта My Number в Японии (JPKI)Японская карта My Number (マイナンバーカード) оснащена чипом, но не стандарта ICAO 9303. На ней хранятся сертификаты, выпущенные в рамках JPKI (инфраструктуры открытых ключей Японии), и закрытые ключи, которые создают подпись только после того, как владелец введет PIN-код карты. Didit считывает ее на том же шаге NFC через JPKI вместо ICAO 9303, и каждый результат NFC указывает использованный протокол в поле `chip_protocol` (`icao` или `jpki`).> [!WARNING]
>
> **Пока недоступно.** Считывание карты My Number через JPKI еще не включено в продакшене. До его включения карта My Number, отсканированная в нативном SDK, пропускает шаг NFC с причиной пропуска `JPKI_UNAVAILABLE`, а карта верифицируется с помощью съемки документа и сравнения лиц, как и раньше.### Требования| Требование | Детали |
| - | - |
| **Документ** | Только японская карта My Number. Для японских паспортов сохраняется считывание чипа по стандарту ICAO 9303. |
| **Интеграция** | Релиз нативного SDK, поддерживающий считывание карт My Number (iOS, Android или созданные на их базе SDK для React Native и Flutter). SDK сообщает Didit, что может считывать JPKI; более старые релизы пропускают шаг с причиной `JPKI_UNAVAILABLE`. Интеграции Web и WebView пропускают его с причиной `INTEGRATION_WITHOUT_NFC_ACCESS`. |
| **Устройство** | Телефон с NFC-модулем. Без него шаг пропускается с причиной `DEVICE_WITHOUT_NFC`. |
| **Хост-приложение для iOS** | `D392F000260100000001` среди идентификаторов выбора ISO7816 в приложении. См. [конфигурацию NFC для iOS](https://docs.didit.me/ru/integration/native-sdks/ios-sdk.md#настройка-nfc). |
| **Человек** | Знает 4-значный PIN-код карты, а также пароль для подписи, если ваш сценарий запрашивает данные владельца. |### Что делает человек**1. Сфотографировать карту**Человек фотографирует карту My Number на шаге верификации личности, как и любой другой документ. Didit распознает карту и отправляет шаг JPKI NFC вместо считывания чипа паспорта.**2. Ввести PIN-код карты**SDK запрашивает 4-значный PIN-код карты (利用者証明用電子証明書の暗証番号). Если в узле NFC включена настройка `jpki_request_attributes` (по умолчанию), он также запрашивает пароль для подписи, называемый также PIN-кодом для подписи (署名用電子証明書の暗証番号, от 6 до 16 заглавных букв и цифр).**3. Приложить карту к телефону**SDK считывает сертификаты карты, и карта подписывает одноразовый вызов от Didit своим ключом. SDK загружает сертификаты и подписи. PIN-коды передаются только на карту и никогда не попадают в Didit.> [!NOTE]
>
> Карта считает неверные попытки ввода: она блокирует 4-значный PIN-код после 3 неверных попыток подряд и пароль для подписи после 5, а заблокированный PIN-код или пароль необходимо сбросить в муниципальном учреждении по месту жительства владельца. После неверного ввода SDK показывает, сколько попыток осталось. Он никогда не выполняет последнюю попытку: когда остается только одна, он останавливается и сообщает человеку, где можно выполнить сброс. Просите пользователей подготовить PIN-код и пароль для подписи перед началом.### Что проверяет Didit| Проверка | Что проверяет Didit | Предупреждение при сбое (действие по умолчанию) |
| - | - | - |
| **Цепочка сертификатов** | Каждый сертификат ведет к удостоверяющему центру JPKI своего типа, находится в пределах срока действия и является сертификатом карты My Number (`jpki.chain_valid`). | `JPKI_CERTIFICATE_INVALID` (Отклонить) |
| **Карта и PIN-код** | Подпись карты для одноразового запроса проверяется с помощью ее сертификата (`jpki.signature_valid`). Карта ставит подпись только после ввода PIN-кода, что подтверждает наличие карты у человека и знание им PIN-кода. | `JPKI_SIGNATURE_INVALID` (Отклонить) |
| **Отзыв** | Ни один сертификат не был отозван (`jpki.revocation_status`). | `JPKI_CERTIFICATE_REVOKED` при значении `revoked` (Отклонить), `JPKI_REVOCATION_UNCHECKED` при значении `unchecked` (Проверка) |
| **Данные владельца** | Имя, дата рождения, пол и адрес в сертификате подписи совпадают с данными, считанными с фотографии той же карты (`jpki.attributes_match_ocr`, `jpki.mismatched_attributes`). | `JPKI_AND_OCR_DATA_NOT_SAME` (Проверка) |Каждое действие настраивается в узле NFC, поэтому его можно изменить на **Без действия**, **Проверка** или **Отклонить**. См. [предупреждения NFC](https://docs.didit.me/ru/core-technology/nfc-verification/warnings-nfc-verification.md#японская-карта-my-number-card-jpki) и [конфигурацию функции NFC](https://docs.didit.me/ru/management-api/workflows/feature-configs.md#nfc-/-epassport).### Что означает статус отзыва unchecked`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/ru/core-technology/nfc-verification/report-nfc-verification.md#японская-карта-my-number-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/ru/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/ru/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 │ │
│ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```***## FAQ
**Что если телефон пользователя не поддерживает 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.