Laporan Verifikasi NFC: Data Chip & Keaslian

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). 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.
Webhook — payload status.updated menyertakan array nfc_verifications[] yang sama setelah langkah NFC menghasilkan data. Lihat Webhook.
NFC mandiri — untuk pengiriman chip langsung, lihat Gambaran umum NFC.

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 untuk nilai pastinya.

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. 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.
`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. `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.

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.

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 untuk matriks perilaku lengkapnya.

Contoh

Approved — chip dibaca dan valid secara kriptografis

{
  "nfc_verifications": [
    {
      "status": "Approved",
      "node_id": "nfc_primary",
      "portrait_image": "https://<media-host>/.../epassport/<session-id>_face.jpg?signature=...",
      "signature_image": "https://<media-host>/.../epassport/<session-id>_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<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000123ESP9005154M3001017<<<<<<<<<<<<<<04",
        "mrz_type": "TD3",
        "place_of_birth": "MADRID, MADRID",
        "address": "CALLE MAYOR 1, MADRID"
      },
      "is_nfc_skipped": false,
      "skip_reason": null,
      "authenticity": {
        "sod_integrity": true,
        "dg_integrity": true
      },
      "certificate_summary": {
        "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "not_valid_before": "2020-11-18 10:21:11",
        "not_valid_after": "2031-02-18 10:21:11",
        "serial_number": 118120836164494130086420187336801405660,
        "validation": {
          "csca_verified": true,
          "dsc_revoked": false,
          "dsc_expired": false,
          "csca_expired": false
        }
      },
      "warnings": []
    }
  ]
}

Declined — ketidakcocokan OCR / chip

{
  "nfc_verifications": [
    {
      "status": "Declined",
      "node_id": "nfc_primary",
      "portrait_image": "https://<media-host>/.../epassport/<session-id>_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<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000254ESP9005154M3001017<<<<<<<<<<<<<<06",
        "mrz_type": "TD3"
      },
      "is_nfc_skipped": false,
      "skip_reason": null,
      "authenticity": {
        "sod_integrity": true,
        "dg_integrity": true
      },
      "certificate_summary": {
        "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "not_valid_before": "2020-11-18 10:21:11",
        "not_valid_after": "2031-02-18 10:21:11",
        "serial_number": 118120836164494130086420187336801405660,
        "validation": {
          "csca_verified": true,
          "dsc_revoked": false,
          "dsc_expired": false,
          "csca_expired": false
        }
      },
      "warnings": [
        {
          "feature": "NFC",
          "risk": "NFC_AND_OCR_DATA_NOT_SAME",
          "additional_data": {
            "ocr_mrz": ["P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<", "AAB000123ESP9005154M3001017<<<<<<<<<<<<<<04"],
            "nfc_mrz": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000254ESP9005154M3001017<<<<<<<<<<<<<<06"
          },
          "log_type": "error",
          "short_description": "NFC and OCR data not same",
          "long_description": "The Near Field Communication (NFC) chip data and the OCR data don't match, indicating potential document tampering or data inconsistency.",
          "node_id": "nfc_primary"
        }
      ]
    }
  ]
}

Japan My Number Card (JPKI)

Japan My Number Card dibaca melalui JPKI pada SDK native: orang tersebut memasukkan PIN kartu dan kartu menandatangani tantangan sekali pakai (lihat cara kerjanya). Laporannya memiliki chip_protocol: "jpki" dan memuat bukti di bawah jpki. portrait_image, signature_image, chip_data, authenticity, dan certificate_summary bernilai null, karena kartu tersebut tidak menyimpan data ICAO.

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

{
  "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.

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 — enum peringatan lengkap, penyebab, dan penanganannya.
Webhook — pantau event status.updated untuk menerima laporan NFC.
Model data — Verifikasi NFC — skema kanonikal dengan setiap kolom.
Dokumen yang didukung — dokumen elektronik mana saja yang dapat dibaca Didit melalui NFC.

Autentikasi

Verifikasi

Pemantauan

Platform

Laporan Verifikasi NFC: Data Chip & Keaslian

Gambaran umum

Lokasi kemunculannya dalam respons API

Skema

Nilai status

Contoh

Approved — chip dibaca dan valid secara kriptografis

Declined — ketidakcocokan OCR / chip

Japan My Number Card (JPKI)

Kolom JPKI

Contoh: Pembacaan My Number Card

Catatan keamanan

Terkait

​Gambaran umum

​Lokasi kemunculannya dalam respons API

​Skema

​Nilai status

​Contoh

​Approved — chip dibaca dan valid secara kriptografis

​Declined — ketidakcocokan OCR / chip

​Japan My Number Card (JPKI)

​Kolom JPKI

​Contoh: Pembacaan My Number Card

​Catatan keamanan

​Terkait

Gambaran umum

Lokasi kemunculannya dalam respons API

Skema

Nilai status

Contoh

Approved — chip dibaca dan valid secara kriptografis

Declined — ketidakcocokan OCR / chip

Japan My Number Card (JPKI)

Kolom JPKI

Contoh: Pembacaan My Number Card

Catatan keamanan

Terkait