Integrasi KYB: Panduan Arsitektur & Pola

Panduan ini merupakan pelengkap untuk quickstart. Panduan ini membahas arsitektur, setiap keputusan integrasi, serta pola operasional yang membuat KYB dapat diandalkan di lingkungan produksi.

Arsitektur

Autentikasi

Semua permintaan memerlukan header x-api-key dengan kunci API aplikasi Anda. Lihat autentikasi API untuk rotasi kunci, pemisahan lingkungan, dan cakupan.

Pembuatan sesi

Endpoint tunggal: POST /v3/session/. Tipe alur kerja menentukan apakah sesi tersebut berupa KYC atau KYB — tidak diperlukan tanda “business” eksplisit. Kolom yang disarankan saat pembuatan:

Kolom	Tujuan
`workflow_id`	Wajib — mereferensikan alur kerja KYB Anda.
`vendor_data`	Pengidentifikasi bisnis Anda. Menautkan sesi ke sebuah entitas Bisnis.
`callback_url`	Opsional — tujuan pengalihan pengguna setelah selesai.
`expected_details`	Opsional — `{ company_name, registry_country, registration_number }`. Mengisi awal pencarian registri perusahaan: negara tempat perusahaan didirikan telah dipilih sebelumnya dan terkunci (`registry_country` sebagai `XX`, atau `XX-YY` untuk registri tingkat negara bagian, mis. `US-CA`), kolom nama perusahaan dan nomor registrasi diisi otomatis, serta pencarian berdasarkan data yang diberikan berjalan secara otomatis — menggabungkan kedua pengidentifikasi saat keduanya tersedia. Hanya pengisian awal — ketidakcocokan tidak memunculkan peringatan.
`metadata`	JSON opsional yang dilampirkan ke sesi.

Skema lengkap: buat sesi.

Mengirimkan tautan yang di-hosting

url respons berupa tautan verifikasi yang di-hosting. Pilihan untuk pengiriman:

Kirimkan melalui email dari platform Anda sendiri.
Sematkan pada UI onboarding Anda sebagai tautan.
Buka di webview dalam aplikasi (iOS / Android / React Native).

Anda dapat menyesuaikan pengalaman yang di-hosting — logo, warna, domain, templat email — melalui White Label.

Polling vs webhook

Webhook merupakan pola yang direkomendasikan. Didit mengirimkan event penyelesaian melalui POST ke endpoint langganan Anda segera setelah pemrosesan selesai. Polling didukung untuk pengembangan atau ketika endpoint webhook Anda tidak dapat dijangkau:

Lakukan polling ke GET /v3/session/{id}/decision/ dengan backoff eksponensial (awalnya setiap 10 detik, hingga 60 detik).
Hentikan polling jika status adalah salah satu dari "Approved", "Declined", "In Review".

Melakukan polling dengan frekuensi tinggi dapat terkena batas laju. Selalu prioritaskan webhook di lingkungan produksi.

Penanganan webhook

Berlanggananlah ke event yang Anda perlukan — event yang sama mencakup KYC dan KYB, dengan session_kind: "business" di dalam payload untuk mengidentifikasi event sesi bisnis:

status.updated — status sesi berubah. Filter pada session_kind === "business" untuk sesi KYB.
data.updated — peninjau mengedit data registri atau Pihak Kunci di konsol, atau registri melaporkan adanya perubahan. Ini tidak dikirimkan ketika pemohon mengunggah dokumen atau mengirimkan Pihak Kunci: pantau status.updated untuk hal tersebut. Filter session_kind yang sama berlaku.
business.status.updated / business.data.updated — entitas Bisnis yang ditautkan berubah.

Katalog event lengkap: webhook KYB. Verifikasi tanda tangan dan semantik percobaan ulang: referensi webhook.

Menangani keputusan

switch (decision.status) {
  case 'Approved':
    await onboardBusiness(decision);
    break;
  case 'Declined':
    // The KYB decision has no single reason code: collectWarnings is your helper
    // that flattens warnings[] from registry_checks, document_verifications,
    // key_people_checks and aml_screenings
    await logRejection(collectWarnings(decision), decision);
    break;
  case 'In Review':
    // Wait for analyst decision — another webhook will fire
    await markPending(decision);
    break;
  case 'Resubmitted':
    // The business was asked to re-upload a document
    await notifyBusiness(decision);
    break;
}

Lihat status KYB untuk mesin status lengkap, dan peringatan KYB untuk tag yang menjelaskan keputusan.

Alur pengiriman ulang

Ketika sesi Verifikasi Bisnis (KYB) bertransisi ke Resubmitted (atau suatu fitur ditandai untuk pengiriman ulang), bisnis tersebut perlu mengunggah data yang telah diperbaiki atau data tambahan. Anda dapat:

Mengirimkan kembali url yang sama — alur yang di-hosting akan melanjutkan ke bagian yang memerlukan pengiriman ulang.
Menerbitkan ulang tautan pihak kunci yang tidak aktif — pihak yang sesi KYC anaknya dihapus atau kedaluwarsa sebelum pihak tersebut memulainya, mendapatkan sesi baru dengan Regenerate Key People KYC Session.
Membuka kasus di Business Console untuk melacak komunikasi bolak-balik secara internal.

Menjalankan langkah-langkah dari frontend Anda sendiri

Langkah dokumen dan Pihak Kunci juga dapat dijalankan dari server Anda dengan kunci API Anda, sehingga Anda tetap mempertahankan antarmuka pengguna sementara Didit menangani verifikasi dan keputusannya. Setiap panggilan terkait dengan sesi KYB, memerlukan izin write:businesses (membaca pihak yang diekstrak juga dapat menggunakan read:businesses atau read:sessions), serta menjalankan pemeriksaan, penagihan, dan kemajuan ke langkah berikutnya dengan cara yang sama seperti halaman yang di-hosting.

Unggah dokumen perusahaan saat sesi berada pada langkah Dokumen KYB.
Baca pihak-pihak yang tercantum dalam dokumen, termasuk pemegang saham dan persentase kepemilikan, lalu tampilkan kepada pemohon Anda.
Buat, edit, dan hapus draf pihak. Draf belum dideklarasikan dan tidak dikenakan biaya.
Kirim draf tersebut. Didit menentukan pihak mana yang harus diverifikasi, membuat sesi KYC untuk masing-masing pihak, dan mengembalikan kyc_session_url untuk Anda kirimkan atau sematkan.
Baca keputusan terkonsolidasi dari sesi, sama seperti alur yang di-hosting.

Panggilan yang dilakukan saat sesi berada pada langkah lain akan menghasilkan respons 409 kyb_step_mismatch beserta informasi langkah yang sedang aktif, dan sesi yang telah selesai akan menghasilkan respons 409 kyb_session_not_writable.

Agregasi profil bisnis

Jika Anda meneruskan vendor_data pada saat pembuatan sesi, Didit mengagregasikan semua sesi untuk bisnis tersebut ke dalam satu entitas Bisnis. Gunakan pemetaan features entitas untuk menjawab “apakah bisnis ini sudah diverifikasi sepenuhnya saat ini?” tanpa perlu mengiterasi sesi. Manfaat:

Alur re-KYB berkala ditambahkan ke profil yang sama.
Transaksi yang dipantau terhadap vendor_data yang sama membawa konteks risiko bisnis tersebut.
UBO dan pengurus yang ditautkan ke entitas Pengguna akan mengisi relasi lintas entitas.

Praktik terbaik

Praktik	Mengapa
Selalu teruskan `vendor_data`	Tanpa parameter ini, sesi menjadi tidak terkait dan tidak dapat diagregasikan.
Gunakan webhook, bukan polling	Latensi lebih rendah, tidak menekan batas laju.
Verifikasi tanda tangan webhook	Mencegah event yang dipalsukan.
Simpan `session_id` di sisi Anda	Diperlukan untuk mengambil keputusan dan menghasilkan PDF.
Tandai sesi dengan `metadata`	Menyederhanakan pelaporan dan penelusuran kesalahan.
Siapkan alur kerja pengujian	Gunakan alur kerja sandbox untuk pengujian integrasi sebelum produksi.

Penanganan kesalahan

Skenario	Respons
`workflow_id` tidak valid	`400 Bad Request`
Sesi duplikat dengan `vendor_data` yang sama	Membuat sesi baru — ini memang sengaja dirancang demikian, karena verifikasi ulang diperkirakan terjadi.
Negara perusahaan di luar negara yang diizinkan dalam alur kerja	Pemeriksaan registri memunculkan peringatan `KYB_COUNTRY_RESTRICTED`.
Gangguan penyedia registri selama pencarian perusahaan	`POST /v3/kyb/search/` mengembalikan `502` dengan `code: "kyb_registry_provider_unavailable"`. Tidak ditagih - coba lagi, atau buat percabangan berdasarkan `code` untuk menawarkan input manual perusahaan. Dalam alur yang di-hosting Didit, bisnis diarahkan ke input manual secara otomatis alih-alih kesalahan yang hanya mengharuskan percobaan ulang. Lihat Pencarian Registri KYB.
Batas laju	`429 Too Many Requests` dengan header `Retry-After`.

Referensi batas laju lengkap.

Langkah berikutnya

Webhook

Setiap event dan payload KYB.

Status

Referensi mesin status.

Skema respons

Mendekode keputusan KYB.

Memulai

Fitur

Profil Bisnis

Referensi

Konsol

Integrasi KYB: Panduan Arsitektur & Pola

Arsitektur

Autentikasi

Pembuatan sesi

Mengirimkan tautan yang di-hosting

Polling vs webhook

Penanganan webhook

Menangani keputusan

Alur pengiriman ulang

Menjalankan langkah-langkah dari frontend Anda sendiri

Agregasi profil bisnis

Praktik terbaik

Penanganan kesalahan

Langkah berikutnya

Webhook

Status

Skema respons

​Arsitektur

​Autentikasi

​Pembuatan sesi

​Mengirimkan tautan yang di-hosting

​Polling vs webhook

​Penanganan webhook

​Menangani keputusan

​Alur pengiriman ulang

​Menjalankan langkah-langkah dari frontend Anda sendiri

​Agregasi profil bisnis

​Praktik terbaik

​Penanganan kesalahan

​Langkah berikutnya

Webhook

Status

Skema respons

Arsitektur

Autentikasi

Pembuatan sesi

Mengirimkan tautan yang di-hosting

Polling vs webhook

Penanganan webhook

Menangani keputusan

Alur pengiriman ulang

Menjalankan langkah-langkah dari frontend Anda sendiri

Agregasi profil bisnis

Praktik terbaik

Penanganan kesalahan

Langkah berikutnya