> ## 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 Verifikasi NFC: Chip e-Paspor & eID
> Verifikasi e-paspor & eID via chip NFC dengan Didit. Validasi kriptografi, anti-tamper, autentikasi ID berkeamanan tertinggi. $0.15/panggilan.
Autentikasi berbasis NFC memungkinkan Anda memverifikasi dokumen identitas dengan membaca chip aman yang tersemat pada paspor dan tanda pengenal modern menggunakan kapabilitas NFC ponsel. Hal ini memberikan **tingkat keamanan tertinggi yang tersedia** untuk Verifikasi Identitas.
Prompt Integrasi Verifikasi NFC
Salin prompt ke papan klip
\
\````# 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````
\
Tempel ke
***## Manfaat Utama| Manfaat | Deskripsi |
| - | - |
| **Keamanan Tertinggi** | Memverifikasi tanda tangan kriptografis langsung dari penerbit pemerintah |
| **Mudah Digunakan** | Berfungsi secara otomatis dengan ponsel apa pun yang mendukung NFC |
| **Tahan Manipulasi** | Mendeteksi manipulasi dokumen yang tidak terlihat oleh mata manusia |
| **Data Komprehensif** | Mengekstrak data tambahan yang tidak tersedia hanya melalui OCR |
| **Fallback yang Fleksibel** | Beralih secara mulus ke verifikasi standar jika NFC tidak tersedia |***## Cara Mengaktifkan Verifikasi NFC### Integrasi SDK Native (Direkomendasikan)Verifikasi NFC tersedia melalui **SDK native** kami, yang menyediakan akses penuh ke kapabilitas NFC perangkat:| Platform | Dukungan NFC | Dokumentasi |
| - | - | - |
| **iOS** | ✅ Dukungan Penuh | [Dokumentasi SDK iOS](https://docs.didit.me/id/integration/native-sdks/ios-sdk.md) |
| **Android** | ✅ Dukungan Penuh | [Dokumentasi SDK Android](https://docs.didit.me/id/integration/native-sdks/android-sdk.md) |SDK iOS menangani semua konfigurasi NFC secara otomatis, termasuk:- Pengidentifikasi aplikasi ISO7816 untuk ePassport
- Penyiapan entitlement dan kapabilitas
- Pembacaan chip real-time dengan umpan balik visual### Integrasi Web> ⚠️ **Batasan Browser**
>
> Verifikasi NFC **tidak tersedia di browser web** karena pembatasan platform:
>
> | Browser | Dukungan NFC |
> | - | - |
> | **Chrome (Android)** | Web NFC API eksperimental - tidak stabil, memerlukan izin eksplisit |
> | **Safari (iOS)** | Tidak ada dukungan Web NFC API |
> | **Browser Lainnya** | Tidak ada dukungan |
>
> Untuk integrasi web, verifikasi NFC secara otomatis dilewati dan pengguna melanjutkan dengan verifikasi dokumen + swafoto standar.***## Cara Kerja**1. Inisiasi Sesi**Pengguna memulai proses verifikasi melalui aplikasi atau platform Anda:- **SDK native**: Meluncurkan alur verifikasi secara langsung di aplikasi Anda
- **Web/Web Seluler**: Pengguna dipandu untuk menggunakan Didit App untuk verifikasi yang mendukung NFC, atau melanjutkan dengan verifikasi standar**2. Pengambilan Foto Dokumen**Pengguna memfoto dokumen identitas mereka, mengambil:- **MRZ** (Zona yang Dapat Dibaca Mesin) — digunakan untuk memperoleh kunci akses chip
- **Gambar bagian depan dan belakang dokumen** — data visual dan fitur keamanan
- **Fitur keamanan visual** — hologram, tanda air, cetak mikro**3. Deteksi Dukungan NFC**Sistem secara otomatis memeriksa kompatibilitas perangkat dan dokumen:| Pemeriksaan | Deskripsi |
| - | - |
| **Tipe dokumen** | Apakah ini ePassport/eID dengan chip NFC? |
| **Kemampuan perangkat** | Apakah ponsel mendukung pembacaan NFC? |
| **Izin** | Apakah izin NFC yang diperlukan telah diberikan? |> [!NOTE]
>
> Jika NFC tidak tersedia, verifikasi berlanjut dengan lancar menggunakan verifikasi dokumen + biometrik standar.**4. Pembacaan Chip NFC**Untuk perangkat dan dokumen yang kompatibel:1) Pengguna diarahkan untuk menempatkan dokumen mereka di dekat pembaca NFC ponsel
2) Umpan balik visual menampilkan progres pembacaan secara real-time
3) Komunikasi aman dibuat dengan chip menggunakan protokol PACE/BAC**5. Ekstraksi Data**Sistem mengekstrak data komprehensif dari chip sesuai standar **ICAO 9303**:| Grup Data | Konten | Deskripsi |
| - | - | - |
| **SOD** | Objek Keamanan Dokumen | Tanda tangan digital untuk semua grup data |
| **DG1** | Data Pribadi | Nama, nomor identitas, tanggal lahir, tanggal kedaluwarsa |
| **DG2** | Gambar Wajah | Foto digital beresolusi tinggi dari pemegang dokumen |
| **DG7** | Tanda Tangan | Representasi digital dari tanda tangan pemegang dokumen |
| **DG11-14** | Data Tambahan | Dapat mencakup sidik jari, pemindaian iris (jika tersimpan) |**6. Verifikasi Kriptografis**Data yang diekstrak menjalani verifikasi kriptografis yang ketat:> [accordion] Verifikasi Tanda Tangan Digital
>
> Hash setiap grup data diverifikasi terhadap tanda tangan yang tersimpan di SOD, memastikan integritas data.> [accordion] Validasi Rantai Sertifikat
>
> Rantai kepercayaan divalidasi: **Sertifikat Dokumen → Country Signing CA → ICAO PKD Root**, dengan memeriksa daftar induk CSCA dan ICAO Public Key Directory.> [accordion] Pemeriksaan Pencabutan Sertifikat
>
> Sertifikat diverifikasi terhadap Daftar Pencabutan Sertifikat (CRL) untuk memastikan sertifikat belum dicabut dan dokumen belum dilaporkan dicuri/dikompromikan.> [accordion] Validasi Silang
>
> Data yang diekstrak dari NFC divalidasi silang terhadap data OCR dari foto dokumen, perbandingan biometrik wajah, dan verifikasi checksum MRZ.**7. Hasil & Skor Keyakinan**Hasil verifikasi akhir mencakup:| Keluaran | Deskripsi |
| - | - |
| **Status verifikasi NFC** | Berhasil, gagal, atau dilewati |
| **Skor konsistensi data** | Seberapa baik data NFC cocok dengan data visual |
| **Validasi sertifikat** | Status verifikasi seluruh rantai |
| **Peningkatan keyakinan** | NFC menambahkan keyakinan signifikan pada verifikasi secara keseluruhan |***## Dokumen yang DidukungVerifikasi NFC berfungsi dengan **ePassport** dan **eID** yang memiliki chip NFC, biasanya ditandai dengan simbol ini pada dokumen:Sebagian besar paspor yang diterbitkan setelah 2006 memiliki chip NFC. Cakupan kartu identitas nasional bervariasi menurut negara. Periksa semua [dokumen yang didukung](https://docs.didit.me/id/core-technology/nfc-verification/supported-documents-nfc-verification.md).Japan My Number Card memiliki jenis chip yang berbeda, dibaca melalui JPKI bukan ICAO 9303. Lihat [Japan My Number Card (JPKI)](#japan-my-number-card-jpki).***## Japan My Number Card (JPKI)Japan My Number Card (マイナンバーカード) memiliki chip, tetapi bukan chip ICAO 9303. Kartu ini menyimpan sertifikat yang diterbitkan di bawah JPKI, infrastruktur kunci publik Jepang, serta kunci privat yang hanya dapat menandatangani setelah pemegang memasukkan PIN kartu. Didit membacanya dalam langkah NFC yang sama, melalui JPKI dan bukan ICAO 9303, dan setiap hasil NFC mencantumkan protokol mana yang digunakan di `chip_protocol` (`icao` atau `jpki`).> [!WARNING]
>
> **Belum tersedia.** Pembacaan My Number Card melalui JPKI belum diaktifkan di produksi. Hingga fitur ini aktif, My Number Card yang diambil di SDK native akan melewati langkah NFC dengan alasan pelewatan `JPKI_UNAVAILABLE`, dan kartu diverifikasi dengan pengambilan dokumen serta pencocokan wajah seperti sebelumnya.### Persyaratan| Persyaratan | Detail |
| - | - |
| **Dokumen** | Hanya Japan My Number Card. Paspor Jepang tetap menggunakan pembacaan chip ICAO 9303. |
| **Integrasi** | Rilis SDK native yang membaca My Number Card (iOS, Android, atau SDK React Native dan Flutter yang dibangun di atasnya). SDK memberi tahu Didit bahwa SDK tersebut dapat membaca JPKI; rilis yang lebih lama melewati langkah ini dengan `JPKI_UNAVAILABLE`. Integrasi Web dan WebView melewatinya dengan `INTEGRATION_WITHOUT_NFC_ACCESS`. |
| **Perangkat** | Ponsel dengan pembaca NFC. Tanpa pembaca NFC, langkah ini dilewati dengan `DEVICE_WITHOUT_NFC`. |
| **Aplikasi host iOS** | `D392F000260100000001` dalam pengidentifikasi pemilihan ISO7816 aplikasi. Lihat [konfigurasi NFC iOS](https://docs.didit.me/id/integration/native-sdks/ios-sdk.md#konfigurasi-nfc). |
| **Orang** | Mengetahui PIN 4 digit kartu, serta kata sandi tanda tangannya ketika alur kerja Anda meminta data pemegang. |### Apa yang dilakukan pengguna**1. Foto kartu**Pengguna mengambil foto My Number Card pada langkah verifikasi identitas, seperti halnya dokumen lainnya. Didit mengenali kartu tersebut dan mengirimkan langkah NFC JPKI alih-alih pembacaan chip paspor.**2. Masukkan PIN kartu**SDK meminta PIN 4 digit kartu (利用者証明用電子証明書の暗証番号). Jika pengaturan `jpki_request_attributes` pada node NFC aktif (secara bawaan), SDK juga meminta kata sandi tanda tangan, yang juga disebut PIN tanda tangan (署名用電子証明書の暗証番号, 6 hingga 16 huruf besar dan angka).**3. Tempelkan kartu ke ponsel**SDK membaca sertifikat kartu, dan kartu menandatangani tantangan sekali pakai dari Didit dengan kuncinya sendiri. SDK mengunggah sertifikat dan tanda tangan. PIN hanya dikirimkan ke kartu, tidak pernah ke Didit.> [!NOTE]
>
> Kartu menghitung entri yang salah: kartu mengunci PIN 4 digit setelah 3 kali salah berturut-turut dan kata sandi tanda tangan setelah 5 kali salah, dan kartu yang terkunci harus diatur ulang di kantor pemerintah daerah pemegang kartu. Setelah entri salah, SDK menampilkan jumlah percobaan yang tersisa. SDK tidak pernah melakukan percobaan terakhir: ketika hanya tersisa satu kali percobaan, SDK berhenti dan memberi tahu pengguna tempat untuk mengatur ulangnya. Minta pengguna untuk menyiapkan PIN dan kata sandi tanda tangan mereka sebelum memulai.### Apa yang diperiksa Didit| Pemeriksaan | Apa yang diverifikasi Didit | Peringatan saat gagal (tindakan default) |
| - | - | - |
| **Rantai sertifikat** | Rantai setiap sertifikat berujung pada otoritas sertifikasi JPKI sesuai jenisnya, berada dalam masa berlakunya, dan merupakan sertifikat My Number Card (`jpki.chain_valid`). | `JPKI_CERTIFICATE_INVALID` (Tolak) |
| **Kartu dan PIN** | Tanda tangan kartu atas tantangan sekali pakai terverifikasi terhadap sertifikatnya (`jpki.signature_valid`). Kartu hanya menandatangani setelah PIN-nya dimasukkan, sehingga hal ini membuktikan pengguna memegang kartu dan mengetahui PIN-nya. | `JPKI_SIGNATURE_INVALID` (Tolak) |
| **Pencabutan** | Tidak ada sertifikat yang telah dicabut (`jpki.revocation_status`). | `JPKI_CERTIFICATE_REVOKED` saat `revoked` (Tolak), `JPKI_REVOCATION_UNCHECKED` saat `unchecked` (Peninjauan) |
| **Data pemegang** | Nama, tanggal lahir, jenis kelamin, dan alamat pada sertifikat tanda tangan cocok dengan data yang dibaca dari foto kartu yang sama (`jpki.attributes_match_ocr`, `jpki.mismatched_attributes`). | `JPKI_AND_OCR_DATA_NOT_SAME` (Peninjauan) |Setiap tindakan merupakan pengaturan pada node NFC, sehingga Anda dapat mengubahnya menjadi **Tidak ada tindakan**, **Peninjauan**, atau **Tolak**. Lihat [peringatan NFC](https://docs.didit.me/id/core-technology/nfc-verification/warnings-nfc-verification.md#japan-my-number-card-jpki) dan [konfigurasi fitur NFC](https://docs.didit.me/id/management-api/workflows/feature-configs.md#nfc-/-epassport).### Arti status pencabutan unchecked`revocation_status: "unchecked"` berarti Didit telah memverifikasi rantai sertifikat dan tanda tangan kartu, tetapi tidak mendapatkan jawaban mengenai apakah sertifikat telah dicabut. Sertifikat dicabut ketika, misalnya, kartu dilaporkan hilang. Karena kartu yang dicabut tidak dapat dikesampingkan, `unchecked` tidak pernah dianggap sebagai `good`. Kondisi ini memicu `JPKI_REVOCATION_UNCHECKED`, yang secara default mengarahkan langkah NFC ke peninjauan. Pilih hasil yang berbeda dengan `jpki_revocation_unchecked_action`.Ketika rantai sertifikat atau tanda tangan tidak valid, Didit tidak meminta status pencabutan: status tetap `unchecked` dan hanya peringatan rantai atau tanda tangan yang dimunculkan.### Data pemegang dan privasi- Dengan `jpki_request_attributes` aktif, keputusan menyertakan nama pemegang, tanggal lahir, jenis kelamin, dan alamat dari sertifikat tanda tangan di bawah `jpki.attributes`. Jika dinonaktifkan, pengguna hanya memasukkan PIN 4 digit: pembacaan tetap membuktikan kartu dan PIN, tetapi tidak memuat data pemegang dan tidak dibandingkan dengan foto kartu.
- Langkah NFC tidak pernah membaca Nomor Individu 12 digit (My Number) kartu dari chip.
- Keputusan melaporkan apa yang dibuktikan kartu, tidak pernah melaporkan sertifikat itu sendiri, nomor serinya, maupun tanda tangannya.Hasil lengkap dijelaskan dalam [laporan verifikasi NFC](https://docs.didit.me/id/core-technology/nfc-verification/report-nfc-verification.md#japan-my-number-card-jpki).***## Contoh Integrasi### SDK iOS (Tersedia Sekarang)```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
)
```**[Dokumentasi Lengkap SDK iOS →](https://docs.didit.me/id/integration/native-sdks/ios-sdk.md)**### SDK Android (Tersedia Sekarang)```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)
}
```**[Dokumentasi SDK Android →](https://docs.didit.me/id/integration/native-sdks/android-sdk.md)*****## Arsitektur Keamanan```
┌─────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```***## Pertanyaan yang Sering Diajukan
**Bagaimana jika ponsel pengguna tidak mendukung NFC?**
Alur verifikasi secara otomatis mendeteksi kemampuan NFC. Jika tidak tersedia, pengguna melanjutkan dengan verifikasi dokumen + swafoto standar. Verifikasi tetap aman, hanya saja tanpa peningkatan keyakinan tambahan dari NFC.
**Bagaimana jika dokumen tidak memiliki chip NFC?**
Banyak dokumen (terutama paspor lama dan beberapa kartu identitas nasional) tidak memiliki chip NFC. Sistem mendeteksi hal ini dan melanjutkan dengan verifikasi standar secara lancar.
**Seberapa besar Verifikasi NFC meningkatkan akurasi?**
Verifikasi NFC memberikan bukti kriptografis atas keaslian dokumen langsung dari pemerintah penerbit. Hal ini secara signifikan meningkatkan keyakinan pada hasil verifikasi dan mendeteksi pemalsuan canggih yang mungkin lolos dari pemeriksaan visual.
**Apakah Verifikasi NFC diwajibkan?**
Tidak. NFC adalah peningkatan, bukan persyaratan. Alur kerja verifikasi Anda dapat dikonfigurasi untuk mewajibkan NFC, memprioritaskannya jika tersedia, atau melewatinya sama sekali berdasarkan toleransi risiko Anda.
***
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.