> ## 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. # Laporan Verifikasi NFC: Data Chip & Keaslian > Pahami laporan NFC/ePassport Didit: status, data chip, keaslian sertifikat, lokasinya di respons API, serta contoh payload. ## Gambaran umum **Laporan verifikasi NFC** merekam apa yang dibaca dan divalidasi Didit dari chip NFC dokumen — ePassport, kartu identitas elektronik, atau e-dokumen ICAO 9303 lainnya. Laporan ini mencakup data biografis chip, pemeriksaan integritas kriptografi (hash SOD dan Data Group), serta ringkasan Document Signer Certificate (DSC) yang digunakan oleh negara penerbit. Laporan dibuat setelah pengguna menyelesaikan langkah NFC dalam alur kerja. Didit membaca Data Group chip di perangkat pengguna, memverifikasi tanda tangan Document Security Object (SOD) terhadap sertifikat CSCA negara penerbit, memeriksa setiap hash Data Group terhadap nilai yang ditandatangani SOD, dan melakukan pemeriksaan silang MRZ chip terhadap MRZ yang diperoleh dari OCR pada sisi dokumen yang terlihat. Japan My Number Card dibaca melalui JPKI sebagai gantinya (`chip_protocol: "jpki"`): laporannya memuat pemeriksaan sertifikat, tanda tangan, pencabutan, dan data pemegang di bawah `jpki`, dan kolom ICAO tetap bernilai `null`. Lihat [Japan My Number Card (JPKI)](#japan-my-number-card-jpki). Setiap laporan memuat `status`-nya sendiri — terlepas dari status sesi secara keseluruhan — yang mencerminkan bagaimana langkah NFC diselesaikan secara tersendiri: * **Approved** — chip berhasil dibaca dan tidak ada peringatan yang muncul yang dikonfigurasikan untuk mengarahkan langkah ke peninjauan atau penolakan. * **In Review** — setidaknya satu peringatan muncul dengan tindakan yang dikonfigurasikan sebagai **Review** (misalnya `NFC_CHIP_NOT_VERIFIED` atau `NFC_TRUST_ANCHOR_MISSING` saat tindakan untuk chip yang tidak terverifikasi diatur ke Review, atau `JPKI_REVOCATION_UNCHECKED` dengan tindakan default-nya). * **Declined** — setidaknya satu peringatan muncul dengan tindakan yang dikonfigurasikan sebagai **Decline** (misalnya `NFC_AND_OCR_DATA_NOT_SAME` saat tindakan ketidakkonsistenan data diatur ke Decline). * **Not Finished** — pengguna tidak pernah menyelesaikan langkah NFC; pembacaan chip ditinggalkan atau perangkat tidak mendukung NFC. * **Resub Requested** — peninjau meminta pengguna untuk mengirimkan ulang; laporan akan digantikan oleh upaya baru. ## Lokasi kemunculannya dalam respons API Laporan NFC dimuat di dalam array `nfc_verifications[]` — **selalu berupa array JSON**, tidak pernah berupa objek tunggal `nfc`. Beberapa entri akan muncul saat alur kerja menjalankan NFC lebih dari sekali (misalnya alur step-up); setiap entri membawa `node_id`-nya sendiri. * **API keputusan sesi** — muncul sebagai `nfc_verifications[]` di tingkat atas `GET /v3/session/{sessionId}/decision/`. Lihat [Ambil keputusan sesi](https://docs.didit.me/id/sessions-api/retrieve-session.md). * **Webhook** — payload `status.updated` menyertakan array `nfc_verifications[]` yang sama setelah langkah NFC menghasilkan data. Lihat [Webhook](https://docs.didit.me/id/integration/webhooks.md). * **NFC mandiri** — untuk pengiriman chip langsung, lihat [Gambaran umum NFC](https://docs.didit.me/id/core-technology/nfc-verification/overview.md). Ketika alur kerja Anda menyertakan langkah NFC yang dilewati atau diabaikan, payload keputusan juga memuat kolom tingkat atas `nfc_skip_reason` yang menyatakan secara tepat alasannya — dokumen tidak memiliki chip, sertifikat negara penerbit tidak tersedia, perangkat tidak memiliki pembaca NFC, verifikasi berjalan tanpa SDK native (tidak ada akses NFC dari browser), kunci akses chip tidak dapat diperoleh dari MRZ, My Number Card tidak dapat dibaca melalui JPKI, atau pengguna memilih untuk melewati. Kolom ini tetap bernilai `null` untuk hasil di luar taksonomi tersebut — paling umum adalah pengguna yang meninggalkannya di tengah proses (status laporan `Not Finished`) atau sesi di mana NFC masih tertunda. Lihat [Alasan dilewati](https://docs.didit.me/id/core-technology/nfc-verification/warnings-nfc-verification.md#alasan-pelewatan) untuk nilai pastinya. > [!NOTE] > > Dokumentasi lama merujuk pada kolom tunggal `nfc`. Format tersebut **tidak** ada pada endpoint keputusan v3 — format tersebut hanya muncul pada tujuan yang secara eksplisit dikonfigurasi untuk webhook V2, yang juga memuat `chip_protocol` dan `jpki`. Selalu baca `response.nfc_verifications[0]` dan lakukan iterasi pada array tersebut. ## Skema Skema kanonik kolom demi kolom tersedia di halaman referensi [Model data](https://docs.didit.me/id/reference/data-models.md#verifikasi-nfc). Kolom-kolom di bawah ini mencerminkan skema kanonik tersebut. | Kolom | Tipe | Deskripsi | | - | - | - | | `status` | `"Not Finished" \| "Approved" \| "Declined" \| "In Review" \| "Resub Requested"` | Status langkah NFC (lihat maknanya di atas). | | `node_id` | string \| null | Node graf alur kerja yang menghasilkan laporan ini. Memungkinkan Anda membedakan dua pemeriksaan NFC dalam alur kerja multilangkah. | | `is_nfc_skipped` | boolean | `true` ketika langkah NFC ini secara eksplisit dilewati dan bukannya dibaca. | | `skip_reason` | string \| null | Alasan langkah dilewati — hanya diatur ketika `is_nfc_skipped` bernilai `true`. Nilainya sama dengan `nfc_skip_reason` tingkat sesi; lihat [Alasan lewati](https://docs.didit.me/id/core-technology/nfc-verification/warnings-nfc-verification.md#alasan-pelewatan). | | `chip_protocol` | `"icao"` \| `"jpki"` | Cara chip dibaca. `icao`: chip ePassport atau eID ICAO 9303. `jpki`: Japan My Number Card, yang hasilnya berada di bawah `jpki`; kolom ICAO di bawah ini (`portrait_image`, `signature_image`, `chip_data`, `authenticity`, `certificate_summary`) nantinya bernilai `null`. Juga diatur pada langkah yang dilewati. | | `jpki` | object \| null | Hal yang dibuktikan dari pembacaan My Number Card; lihat [Kolom JPKI](#kolom-jpki). `null` untuk chip ICAO, untuk langkah yang dilewati, dan saat langkah ditutup tanpa ada kartu yang dibaca. | | `portrait_image` | string (URL yang ditandatangani) \| null | Potret yang diekstrak dari chip (DG2). Tautan yang telah ditandatangani dan berumur pendek — unduh segera; ambil ulang keputusan untuk mendapatkan URL baru. | | `signature_image` | string (URL yang ditandatangani) \| null | Gambar tanda tangan pemegang dari chip (DG7), jika ada. Perilaku tautan yang telah ditandatangani dan berumur pendek yang sama. | | `chip_data` | object \| null | Objek datar dengan data biografis yang diuraikan dari chip. Selalu ada setelah pembacaan berhasil: `dgs` (daftar Data Group yang dibaca), `surname`, `name`, `country`, `nationality`, `birth_date` (`YYYY-MM-DD`), `expiry_date` (`YYYY-MM-DD`), `sex` (`M`/`F`), `document_type` (kode dokumen MRZ, mis. `P`), `document_number`, `optional_data`, digit pemeriksa MRZ (`birth_date_hash`, `expiry_date_hash`, `document_number_hash`, `optional_data_hash`, `final_hash`), `mrz_string`, dan `mrz_type` (`TD1`/`TD2`/`TD3`). Ketika chip memuat DG11, `place_of_birth` dan `address` ditambahkan (serta `full_name` / `full_name_non_latin` untuk dokumen dengan nama non-Latin); kunci-kunci ini **tidak ada**, bukan null, jika chip tidak memuat DG11. `null` saat langkah NFC dilewati. | | `authenticity` | object \| null | Hasil autentikasi pasif ICAO, di bawah. `null` untuk pembacaan JPKI. | | `authenticity.sod_integrity` | boolean | `true` ketika tanda tangan SOD terhubung ke CSCA negara penerbit yang valid dan DSC tidak dicabut maupun kedaluwarsa. | | `authenticity.dg_integrity` | boolean | `true` ketika hash setiap Data Group cocok dengan nilai yang ditandatangani SOD. Nilai `false` berarti data chip telah diubah atau hanya terbaca sebagian. | | `certificate_summary` | object \| null | Ringkasan DSC yang menandatangani chip ini: `issuer`, `subject`, `serial_number`, `not_valid_before`, `not_valid_after` (stempel waktu sebagai `YYYY-MM-DD HH:MM:SS`), ditambah objek `validation` dengan hasil pemeriksaan masing-masing (`csca_verified`, `csca_missing`, `dsc_revoked`, `dsc_expired`, `csca_expired`). `csca_missing` bernilai `true` ketika jangkar kepercayaan CSCA penerbit DSC tidak tersedia. `null` ketika SOD tidak dapat dimuat atau langkah dilewati. | | `warnings[]` | array | Peringatan tingkat modul, masing-masing berisi `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, dan `node_id` — lihat [Peringatan NFC](https://docs.didit.me/id/core-technology/nfc-verification/warnings-nfc-verification.md). | ## Nilai status | Status | Makna | Dampak hilir | | - | - | - | | `Approved` | Chip dibaca dan tidak ada peringatan yang terpicu dengan tindakan Review atau Decline — termasuk kasus ketika peringatan terpicu tetapi tindakan yang dikonfigurasikan adalah "No action". | Dihitung sebagai pemeriksaan NFC yang berhasil; tidak akan, dengan sendirinya, mendorong sesi ke peninjauan. | | `In Review` | Peringatan terpicu dengan tindakan yang dikonfigurasikan adalah Review (`SKIPPED_NFC_VALIDATION`, `NFC_CHIP_NOT_VERIFIED`, `NFC_TRUST_ANCHOR_MISSING`, `NFC_AND_OCR_DATA_NOT_SAME`, atau salah satu dari peringatan `JPKI_*`, tergantung pengaturan Anda). | Sesi juga beralih ke `In Review` hingga peninjau mengambil tindakan. | | `Declined` | Peringatan terpicu dengan tindakan yang dikonfigurasikan adalah Decline. | Sesi ditolak kecuali cabang lain yang disetujui memenuhi alur kerja. | | `Not Finished` | Pengguna meninggalkan langkah NFC, perangkat tidak memiliki dukungan NFC, atau pembacaan chip tidak pernah selesai. | Cabang NFC tidak menghasilkan hasil; periksa mekanisme pengganti alur kerja. | | `Resub Requested` | Peninjau meminta pengiriman ulang langkah ini. | Upaya baru akan menggantikan laporan ini setelah pengguna mencoba lagi. | > [!NOTE] > > Dua peringatan sertifikat (`DSC_CERTIFICATE_REVOKED`, `DSC_CERTIFICATE_EXPIRED`) bersifat informasional: keduanya muncul di `warnings[]` tetapi tidak pernah mengubah `status` NFC dengan sendirinya. Lihat [Peringatan NFC](https://docs.didit.me/id/core-technology/nfc-verification/warnings-nfc-verification.md) untuk matriks perilaku lengkapnya. ## Contoh ### Approved — chip dibaca dan valid secara kriptografis ```json theme={null} { "nfc_verifications": [ { "status": "Approved", "node_id": "nfc_primary", "portrait_image": "https:///.../epassport/_face.jpg?signature=...", "signature_image": "https:///.../epassport/_signature.jpg?signature=...", "chip_data": { "dgs": ["DG1", "DG2", "DG7", "DG11"], "surname": "DOE", "name": "JOHN", "country": "ESP", "nationality": "ESP", "birth_date": "1990-05-15", "expiry_date": "2030-01-01", "sex": "M", "document_type": "P", "document_number": "AAB000123", "optional_data": "", "birth_date_hash": "4", "expiry_date_hash": "7", "document_number_hash": "3", "optional_data_hash": "", "final_hash": "4", "mrz_string": "P/.../epassport/_face.jpg?signature=...", "signature_image": null, "chip_data": { "dgs": ["DG1", "DG2"], "surname": "DOE", "name": "JOHN", "country": "ESP", "nationality": "ESP", "birth_date": "1990-05-15", "expiry_date": "2030-01-01", "sex": "M", "document_type": "P", "document_number": "AAB000254", "optional_data": "", "birth_date_hash": "4", "expiry_date_hash": "7", "document_number_hash": "6", "optional_data_hash": "", "final_hash": "6", "mrz_string": "P [!WARNING] > > Pembacaan My Number Card melalui JPKI belum diaktifkan di produksi. Hingga diaktifkan, My Number Card akan melewati langkah NFC dengan alasan pelewatan `JPKI_UNAVAILABLE`. ### Kolom JPKI | Kolom | Tipe | Deskripsi | | - | - | - | | `jpki.certificate_types` | array of `"user_authentication"` \| `"signature"` | Sertifikat kartu yang dibaca. `user_authentication` (PIN 4 digit) selalu dibaca; `signature` (PIN tanda tangan) dibaca saat pengaturan `jpki_request_attributes` pada node NFC aktif, yang merupakan pengaturan default. | | `jpki.chain_valid` | boolean | `true` ketika setiap sertifikat terhubung ke otoritas sertifikasi JPKI untuk tipenya, berada dalam masa berlakunya, dan merupakan sertifikat My Number Card dari tipe tersebut. | | `jpki.signature_valid` | boolean | `true` ketika setiap tanda tangan yang dibuat kartu atas tantangan sekali pakai terverifikasi. Kartu hanya menandatangani setelah PIN-nya dimasukkan, sehingga hal ini membuktikan bahwa orang tersebut memegang kartu dan mengetahui PIN-nya. | | `jpki.revocation_status` | `"good"` \| `"revoked"` \| `"unchecked"` | `good`: setiap sertifikat dikonfirmasi tidak dicabut. `revoked`: sertifikat dicabut, misalnya karena kartu dilaporkan hilang. `unchecked`: tidak ada jawaban pencabutan yang tersedia, sehingga kartu yang dicabut tidak dapat dikesampingkan; tidak pernah diperlakukan sebagai `good`. Pencabutan hanya diperiksa setelah rantai dan tanda tangan valid. | | `jpki.ca_generation` | string \| null | Generasi otoritas sertifikasi JPKI yang menerbitkan sertifikat, misalnya `"2023"`. `null` jika tidak ada sertifikat yang terhubung ke salah satunya. | | `jpki.certificate_expires_at` | string (ISO 8601) \| null | Tanggal kedaluwarsa paling awal di antara sertifikat yang dibaca. | | `jpki.certificates[]` | array | Satu entri per sertifikat yang dibaca: `type`, `chain_valid`, `signature_valid`, `ca_generation`, `not_valid_before`, `not_valid_after`, dan `failure`. `failure` bernilai `null` jika rantainya valid, jika tidak maka salah satu dari `unreadable_certificate`, `untrusted_issuer`, `expired`, `not_yet_valid`, `wrong_policy` (bukan sertifikat My Number Card untuk tipe tersebut), atau `key_usage`. | | `jpki.attributes` | object \| null | Data pemegang dari sertifikat tanda tangan, setelah rantainya valid: `full_name` (sesuai yang terdaftar, biasanya dalam aksara Jepang), `date_of_birth` (`YYYY-MM-DD`), `gender` (`M`, `F`, atau `null`), `address`, serta `name_substitute_characters` / `address_substitute_characters`, yang menandai karakter yang diganti dengan karakter pengganti karena berada di luar set karakter standar (`null` jika tidak ada). `null` jika sertifikat tanda tangan tidak diminta atau rantainya tidak valid. | | `jpki.attributes_match_ocr` | boolean \| null | `true` ketika atribut cocok dengan data yang dibaca dari foto kartu yang sama, `false` jika ada yang berbeda (`JPKI_AND_OCR_DATA_NOT_SAME`), `null` ketika tidak ada yang dapat dibandingkan, termasuk setiap kali `attributes` bernilai `null`. | | `jpki.mismatched_attributes` | array of string | Atribut yang berbeda dari data foto (`full_name`, `date_of_birth`, `gender`, `address`), bukan nilainya. | Laporan tidak pernah memuat sertifikat itu sendiri, nomor serinya, tanda tangan, atau 12 digit Nomor Individu (My Number) kartu, yang tidak pernah dibaca oleh langkah NFC. ### Contoh: Pembacaan My Number Card ```json theme={null} { "nfc_verifications": [ { "status": "Approved", "node_id": "nfc_primary", "portrait_image": null, "signature_image": null, "chip_data": null, "is_nfc_skipped": false, "skip_reason": null, "chip_protocol": "jpki", "jpki": { "certificate_types": ["user_authentication", "signature"], "chain_valid": true, "signature_valid": true, "revocation_status": "good", "ca_generation": "2023", "certificate_expires_at": "2029-05-15T14:59:59Z", "certificates": [ { "type": "user_authentication", "chain_valid": true, "signature_valid": true, "ca_generation": "2023", "not_valid_before": "2024-06-03T01:12:40+00:00", "not_valid_after": "2029-05-15T14:59:59+00:00", "failure": null }, { "type": "signature", "chain_valid": true, "signature_valid": true, "ca_generation": "2023", "not_valid_before": "2024-06-03T01:12:40+00:00", "not_valid_after": "2029-05-15T14:59:59+00:00", "failure": null } ], "attributes": { "full_name": "山田 太郎", "date_of_birth": "1990-05-15", "gender": "M", "address": "東京都千代田区千代田1番1号", "name_substitute_characters": null, "address_substitute_characters": null }, "attributes_match_ocr": true, "mismatched_attributes": [] }, "authenticity": null, "certificate_summary": null, "warnings": [] } ] } ``` Ketika pemeriksaan pencabutan tidak tersedia untuk suatu pembacaan, laporan yang sama memiliki `revocation_status: "unchecked"`, peringatan `JPKI_REVOCATION_UNCHECKED`, dan `status: "In Review"` berdasarkan pengaturan default. Lihat [peringatan NFC](https://docs.didit.me/id/core-technology/nfc-verification/warnings-nfc-verification.md#japan-my-number-card-jpki). ## Catatan keamanan Data chip NFC ditandatangani oleh otoritas penerbit, sehingga laporan Disetujui dengan `sod_integrity: true` dan `dg_integrity: true` merupakan bukti identitas terkuat yang dapat dihasilkan Didit. Perlakukan URL gambar yang ditandatangani (`portrait_image`, `signature_image`) sebagai URL berumur pendek: unduh dengan segera dan jangan melakukan cache secara publik — minta ulang keputusan saat Anda memerlukan tautan baru. ## Terkait * [Peringatan NFC](https://docs.didit.me/id/core-technology/nfc-verification/warnings-nfc-verification.md) — enum peringatan lengkap, penyebab, dan penanganannya. * [Webhook](https://docs.didit.me/id/integration/webhooks.md) — pantau event `status.updated` untuk menerima laporan NFC. * [Model data — Verifikasi NFC](https://docs.didit.me/id/reference/data-models.md#verifikasi-nfc) — skema kanonikal dengan setiap kolom. * [Dokumen yang didukung](https://docs.didit.me/id/core-technology/nfc-verification/supported-documents-nfc-verification.md) — dokumen elektronik mana saja yang dapat dibaca Didit melalui NFC. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.