Laporan Autentikasi Biometrik: Skema JSON

Laporan Autentikasi Biometrik adalah cara Didit melaporkan kembali hasil verifikasi ulang pengguna lama. Alur kerja ini menjalankan pemeriksaan liveness baru dan, saat Pencocokan Wajah diaktifkan dalam alur kerja, pencocokan wajah 1:1 terhadap wajah referensi yang ditentukan saat pembuatan sesi (portrait_image yang Anda berikan, atau wajah tersimpan pengguna yang dicari berdasarkan vendor_data). Kedua pemeriksaan muncul sebagai item fitur standar dalam respons keputusan sesi V3.

Laporan autentikasi biometrik Didit yang menggabungkan pemeriksaan liveness dan pencocokan wajah terhadap potret tersimpan

Gambaran umum

Autentikasi Biometrik adalah jenis alur kerja (workflow_type: "biometric_authentication"), bukan objek respons terpisah. Saat alur kerja berjalan, alur kerja ini menghasilkan:

Satu pemeriksaan liveness yang mengambil swafoto langsung dan menilainya untuk spoofing.
Satu pencocokan wajah yang membandingkan wajah yang diambil dengan wajah referensi yang ditentukan saat pembuatan sesi (hanya jika Pencocokan Wajah diaktifkan dalam alur kerja).

Setiap kali alur kerja menyertakan Pencocokan Wajah, pembuatan sesi memerlukan wajah referensi. Kirimkan portrait_image (gambar yang dikodekan dalam base64, maks 2MB), atau abaikan dan Didit akan menggunakan kembali wajah yang sudah tersimpan untuk pengguna vendor_data: wajah liveness yang disetujui terlebih dahulu, kemudian foto chip ePassport, lalu potret dokumen identitas, kemudian wajah profil yang didaftarkan secara manual. Jika baik portrait_image maupun wajah yang tersimpan tidak tersedia, pembuatan sesi mengembalikan 400 dengan

{"portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first."}

. Dalam kedua kasus, referensi yang ditentukan dicatat di bawah sesi baru, sehingga source_image_session_id pada item pencocokan wajah diatur ke session_id dari sesi itu sendiri (ini memberi tahu Anda bahwa referensi berasal dari potret tersimpan sesi alih-alih dari potret dokumen yang diambil pada sesi yang sama, yang akan membuat kolom tersebut bernilai null).

Tempat kemunculannya

Kunci respons keputusan	Jamak	Skema item
`liveness_checks[]`	Satu per langkah liveness (biasanya 1 dalam autentikasi biometrik)	data-models#liveness-check
`face_matches[]`	Satu per langkah pencocokan wajah (`null` dalam alur kerja liveness saja)	data-models#face-match

Kedua array dikembalikan oleh GET /v3/session/{sessionId}/decision/ untuk sesi yang jenis alur kerjanya adalah biometric_authentication. Keduanya selalu berupa array — tidak pernah berupa objek tunggal — dan masing-masing bernilai null sampai langkahnya menghasilkan data. Setiap item membawa node_id sehingga alur kerja multi-instance dapat membedakan langkah-langkah yang ada.

Referensi skema

Daftar kolom lengkap didefinisikan satu kali di halaman model data sehingga setiap laporan yang menampilkan fitur-fitur ini berbagi satu sumber kebenaran:

Skema item liveness — status, method, score, reference_image, video_url, age_estimation, matches[], face_quality, face_luminance, warnings[], node_id.
Skema item pencocokan wajah — status, score, source_image_session_id, source_image, target_image, warnings[], node_id.
Bentuk entri peringatan — feature, risk, additional_data, log_type, short_description, long_description, node_id.

Nilai status

Baik liveness_checks[].status maupun face_matches[].status menggunakan siklus hidup fitur bersama (status tingkat fitur):

Status	Arti
`Not Finished`	Langkah belum menghasilkan hasil akhir (pengguna belum menyelesaikannya, atau drop-off). Sebelum langkah dimulai sama sekali, array-nya bernilai `null` dalam respons keputusan.
`Approved`	Pemeriksaan lolos semua ambang batas yang dikonfigurasi.
`In Review`	Skor berada dalam rentang peninjauan, atau peringatan yang dapat dikonfigurasi diatur ke peninjauan.
`Declined`	Skor berada pada atau di bawah ambang batas penolakan, atau peringatan penolakan otomatis terpicu (serangan wajah, tidak ada wajah terdeteksi, wajah ada di daftar blokir, tidak ada gambar referensi untuk pencocokan wajah).
`Resub Requested`	Peninjau meminta pengguna untuk mencoba lagi langkah ini.

Status keseluruhan sesi (status) menggabungkan kedua item: fitur apa pun yang berstatus Declined akan menolak sesi, fitur apa pun yang berstatus In Review membuat sesi menjadi In Review, jika tidak maka Approved (setelah setiap fitur selesai). Untuk perilaku ambang batas dan daftar lengkap kode peringatan, lihat Peringatan Autentikasi Biometrik.

Contoh — liveness + pencocokan wajah (disetujui)

Contoh telah diringkas: respons keputusan lengkap juga memuat session_url, metadata, callback, reviews, contact_details, expected_details, environment, created_at, dan expires_at.

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_kind": "user",
  "session_number": 1234,
  "status": "Approved",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "features": ["LIVENESS", "FACE_MATCH"],
  "vendor_data": "user-123",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 89.92,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 92.4,
      "face_luminance": 58.1,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Approved",
      "score": 88.47,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": []
    }
  ],
  "id_verifications": null,
  "nfc_verifications": null,
  "poa_verifications": null,
  "phone_verifications": null,
  "email_verifications": null,
  "aml_screenings": null
}

Contoh — liveness saja (Pencocokan Wajah dinonaktifkan dalam alur kerja)

{
  "session_id": "22222222-3333-4444-5555-666666666666",
  "session_kind": "user",
  "status": "Approved",
  "workflow_id": "018e7b2c-6666-7777-9999-bbbbbbbbbbbb",
  "features": ["LIVENESS"],
  "vendor_data": "user-456",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "ACTIVE_3D",
      "score": 96.10,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": null,
      "face_luminance": null,
      "warnings": []
    }
  ],
  "face_matches": null
}

Mode liveness saja adalah konfigurasi alur kerja: saat Pencocokan Wajah dinonaktifkan, tidak ada wajah referensi yang diperlukan saat pembuatan sesi dan face_matches tetap bernilai null. Saat Pencocokan Wajah diaktifkan, mengabaikan portrait_image tidak akan beralih ke mode liveness saja: Didit menggunakan kembali wajah yang tersimpan untuk pengguna vendor_data, dan jika tidak ada wajah tersimpan maka pembuatan sesi gagal dengan kode 400.

Contoh — pencocokan wajah ditolak karena kemiripan rendah

{
  "session_id": "33333333-4444-5555-6666-777777777777",
  "status": "Declined",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 91.20,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 90.15,
      "face_luminance": 55.30,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Declined",
      "score": 41.18,
      "source_image_session_id": "33333333-4444-5555-6666-777777777777",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "error",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match"
        }
      ]
    }
  ]
}

Catatan keamanan

reference_image, video_url, source_image, dan target_image adalah URL bertanda tangan yang kedaluwarsa setelah masa berlaku terbatas (secara default 4 jam). Tautan ini mengarah ke data biometrik — jangan menyimpannya dalam cache atau menampilkannya secara publik. Simpan hasil verifikasi (status, skor, source_image_session_id) di pihak Anda; panggil kembali endpoint keputusan jika Anda memerlukan URL baru.

Terkait

Peringatan Autentikasi Biometrik

Kode peringatan, ambang batas, dan kondisi penolakan otomatis.

Laporan liveness

Referensi kolom lengkap untuk item liveness_checks[].

Laporan Pencocokan Wajah

Referensi kolom lengkap untuk item face_matches[].

Autentikasi

Verifikasi

Pemantauan

Platform

Laporan Autentikasi Biometrik: Skema JSON

Gambaran umum

Tempat kemunculannya

Referensi skema

Nilai status

Contoh — liveness + pencocokan wajah (disetujui)

Contoh — liveness saja (Pencocokan Wajah dinonaktifkan dalam alur kerja)

Contoh — pencocokan wajah ditolak karena kemiripan rendah

Catatan keamanan

Terkait

Peringatan Autentikasi Biometrik

Laporan liveness

Laporan Pencocokan Wajah

​Gambaran umum

​Tempat kemunculannya

​Referensi skema

​Nilai status

​Contoh — liveness + pencocokan wajah (disetujui)

​Contoh — liveness saja (Pencocokan Wajah dinonaktifkan dalam alur kerja)

​Contoh — pencocokan wajah ditolak karena kemiripan rendah

​Catatan keamanan

​Terkait

Peringatan Autentikasi Biometrik

Laporan liveness

Laporan Pencocokan Wajah

Gambaran umum

Tempat kemunculannya

Referensi skema

Nilai status

Contoh — liveness + pencocokan wajah (disetujui)

Contoh — liveness saja (Pencocokan Wajah dinonaktifkan dalam alur kerja)

Contoh — pencocokan wajah ditolak karena kemiripan rendah

Catatan keamanan

Terkait