workflow_id.
Backend Anda memulai verifikasi dan mengambil hasilnya; antarmuka Anda memandu orang tersebut melalui autentikasi yang diwajibkan dompet.
Integrasi API tetap mengharuskan orang tersebut mengautentikasi dan menyetujui pembagian identitasnya.
Anda tidak dapat memverifikasi seseorang dengan mengirimkan pengenal pribadinya tanpa interaksi tersebut.
Cara kerja verifikasi
- Backend Anda memeriksa katalog dompet, lalu memanggil endpoint mulai milik dompet yang tersedia menggunakan kunci API aplikasi Anda.
- Didit mengembalikan referensi verifikasi dan tindakan yang perlu dilakukan orang tersebut.
- Aplikasi Anda membuka halaman autentikasi atau menampilkan instruksi persetujuan dari dompet.
- Orang tersebut mengautentikasi diri dengan dompetnya.
- Backend Anda mengambil hasil verifikasi dan menangani notifikasi penyelesaian.
Integrasi backend
Gunakan Daftar dompet identitas digital untuk memperoleh endpoint, kolom wajib, dan ketersediaan terkini untuk aplikasi Anda. Simpanx-api-key Anda di backend.
Jangan letakkan di bundle browser atau aplikasi seluler.
Gunakan Idempotency-Key yang berbeda untuk setiap percobaan verifikasi baru, dan gunakan kembali kunci tersebut saat mencoba ulang permintaan mulai yang sama.
Mengubah permintaan sambil menggunakan kembali kuncinya merupakan konflik, bukan percobaan verifikasi baru.
Setiap dompet memiliki URL mulai sendiri, misalnya /v3/id-verification/wallets/ftn/ untuk Finnish Trust Network.
request_id mengidentifikasi verifikasi terpisah untuk operasi berikutnya.
Gunakan vendor_data sebagai referensi Anda sendiri, hingga 2.000 byte UTF-8, dan metadata untuk objek JSON opsional.
Keduanya dikembalikan bersama hasil dan webhook penyelesaian.
Operasi ini menggunakan kunci API aplikasi yang memulai verifikasi.
Ketersediaan polling dan autentikasi bergantung pada dompet yang dipilih.
Pembatalan menolak verifikasi yang tertunda tanpa dikenai biaya, dan mengembalikan verifikasi yang sudah selesai tanpa perubahan.
Untuk Smart-ID dan Mobile-ID, pembatalan yang masuk saat polling sedang memeriksa persetujuan akan menunggu beberapa detik untuk polling tersebut.
Setelah itu, pembatalan menolak verifikasi, atau mengembalikannya sebagai
verified jika orang tersebut sudah menyetujui.
Verifikasi yang sedang diselesaikan orang tersebut pada saat itu tidak dapat dibatalkan: responsnya adalah 409 dengan error: "verification_in_progress" dan header Retry-After.
Coba lagi setelah menunggu selama jumlah detik tersebut untuk membaca hasil yang telah selesai.
Daftarkan tujuan pengembalian Anda
Dompet redirect mengembalikan orang tersebut ke aplikasi Anda setelah autentikasi. Daftarkan nama host yang tepat sebelum memulai verifikasi:return_url HTTPS, misalnya https://app.example.com/identity/complete, dalam permintaan mulai.
Gunakan nama host saja di allowed_return_hosts, tanpa skema, path, atau wildcard.
Daftarkan setiap subdomain yang Anda gunakan secara terpisah, hingga 20 nama host.
Memperbarui allowed_return_hosts menggantikan daftar yang terdaftar, jadi sertakan setiap nama host yang ingin Anda pertahankan.
GET /v3/webhook/ mengembalikan daftar saat ini; lihat Konfigurasi webhook.
Anda tidak memerlukan alur kerja atau domain White Label untuk mendaftarkan tujuan pengembalian.
Tujuan tersebut adalah halaman pengembalian browser; konfigurasikan webhook penyelesaian secara terpisah untuk backend Anda.
Contoh: Finnish Trust Network
Setelah mendaftarkan nama host pengembalian Anda, mulai verifikasi Finnish Trust Network:request_id yang dikembalikan dan kirim browser orang tersebut ke wallet_verification.next_action.url ketika type-nya redirect.
Setelah orang tersebut kembali, ambil hasilnya dari backend Anda:
wallet_verification.outcome:
Hanya gunakan identitas ketika hasil adalah
verified dan simulated bernilai false untuk pemeriksaan identitas nyata.
Respons pending dapat memuat tindakan berikutnya; respons terminal tidak memiliki tindakan berikutnya.
Pengalaman autentikasi
Dompet dengan pengalihan mengembalikan URL autentikasi. Buka URL tersebut di browser pengguna, biarkan mereka menyelesaikan proses autentikasi dompet, lalu arahkan mereka kembali ke tujuan yang sudah Anda daftarkan. Baca hasilnya dari backend Anda, jangan mempercayai parameter URL pengembalian sebagai bukti identitas. Smart-ID dan Mobile-ID menggunakan permintaan persetujuan di ponsel pengguna. Antarmuka Anda mengumpulkan pengenal pribadi yang diperlukan; Mobile-ID juga memerlukan nomor telepon yang terkait. Tampilkan kode perbandingan dan minta pengguna menyetujui hanya jika kode tersebut sama dengan kode di ponsel mereka. PIN mereka harus dimasukkan di dompet atau pada permintaan di ponsel, jangan pernah di formulir Anda atau dalam permintaan API. Lakukan polling dari backend Anda padapoll_interval_seconds yang dikembalikan untuk mendapatkan umpan balik atas permintaan tersebut.
Didit juga memeriksa persetujuan telepon yang masih tertunda di latar belakang, sehingga penyelesaian dapat sampai ke webhook Anda setelah pengguna menutup halaman Anda.
Google Wallet diminta dari halaman atau aplikasi Anda sendiri melalui Digital Credentials API, tanpa redirect; lihat Dompet Digital Credentials (Google Wallet).
Interaksi yang tersedia bergantung pada dompet yang dipilih.
Jangan berasumsi bahwa setiap dompet mendukung formulir yang tertanam, kode QR, atau autentikasi tanpa browser.
Dompet Digital Credentials (Google Wallet)
Google Wallet diminta langsung oleh halaman web atau aplikasi Android Anda, menggunakan W3C Digital Credentials API. Tidak ada redirect, tidak ada halaman yang di-hosting Didit, dan tidak ada kode QR Didit. Layanan ini tersedia di produksi dan di sandbox. Aplikasi sandbox tidak memerlukan pendaftaran; setiap aplikasi produksi mendaftar sekali dari konsol (langkah Verifikasi Identitas, baris Google Wallet, Daftar ke Google) sebelum dapat menggunakan Google Wallet. Periksa Daftar dompet identitas digital untuk mengetahui dompet mana yang dapat mulai digunakan oleh aplikasi Anda sekarang.1
Mulai dengan origin Anda
Backend Anda memanggil
POST /v3/id-verification/wallets/google-wallet/ dengan country pengguna (USA, GBR, BRA, SGP atau TWN) dan origin yang akan digunakan untuk meminta dompet.
origin adalah origin HTTPS dari halaman Anda, misalnya https://app.example.com, yang host-nya harus salah satu dari nama host pengembalian yang terdaftar atau domain White Label Anda.
Untuk aplikasi Android, nilainya adalah android:apk-key-hash: diikuti SHA-256 base64 dari sertifikat penandatanganan aplikasi Anda, tanpa padding.
Dompet menolak permintaan yang dibuat dari origin lain.
Tidak ada return_url.2
Minta dompet di dalam gestur pengguna
Respons memiliki
wallet_verification.interaction = "digital_credentials" dan next_action.type = "request_digital_credential".
Teruskan next_action.digital_credentials.request ke browser atau ke Android Credential Manager, dari ketukan atau klik pada origin yang Anda gunakan untuk memulai.
Di desktop, browser menampilkan kode QR-nya sendiri jika dompet berada di perangkat lain.3
Kirim respons dari dompet
Kirim
{protocol, data} yang dikembalikan ke backend Anda, lalu dari sana ke POST /v3/id-verification/wallets/verifications/{request_id}/response/ sebagai {"response": {...}}.
Permintaan hanya dapat dikirim sekali; pengiriman kedua akan mengembalikan verifikasi yang sudah diputuskan.4
Baca hasilnya
Respons pengiriman adalah verifikasi yang sudah diputuskan.
Anda juga dapat membacanya dengan
GET /v3/id-verification/wallets/verifications/{request_id}/ atau menerimanya di webhook penyelesaian."DigitalCredential" in window bernilai true.
navigator.credentials.get harus berjalan dalam gestur pengguna, jadi panggil dari penangan klik, bukan setelah langkah asinkron.
Di Android, gunakan Jetpack Credential Manager (androidx.credentials 1.5.0 atau yang lebih baru) dengan permintaan yang sama:
Kredensial yang gagal verifikasi berupa verifikasi yang sudah diputuskan dengan hasil
failed, bukan respons error.
Hanya kolom yang diminta oleh verifikasi yang diberikan oleh dompet, dan hasilnya berisi atribut identitas yang dikembalikan dompet.
ID pass Google Wallet atau lisensi mengemudi seluler negara bagian AS tidak mengembalikan foto potret.
Di aplikasi sandbox, alur ini disimulasikan dengan langkah-langkah yang sama dan mengembalikan simulated: true.
Setiap respons yang dikirim akan memutuskan verifikasi sesuai sandbox_scenario, sehingga Anda dapat membangun alur browser atau aplikasi secara lengkap tanpa kredensial asli.
Webhook penyelesaian
Konfigurasikan tujuan webhook aplikasi untukstatus.updated menggunakan panduan integrasi webhook.
Gunakan webhook_version: "v3" untuk struktur keputusan yang dijelaskan di sini.
Verifikasi tanda tangan webhook di backend Anda sebelum memprosesnya.
session_id pada webhook sama dengan request_id yang dikembalikan oleh API dompet.
Identitas pengguna yang telah selesai diverifikasi melalui dompet muncul dalam array decision.id_verifications pada webhook dengan verification_method: "wallet".
Anda juga dapat menggunakan pengenal tersebut untuk mengambil hasil khusus dari API dompet.
Tangani notifikasi persetujuan dan penolakan, termasuk verifikasi yang dibatalkan dan kedaluwarsa.
Buat handler webhook Anda idempoten karena pengiriman yang gagal akan dicoba ulang.
Kembalinya pengguna dari browser bukan webhook penyelesaian, dan parameter query-nya bukan bukti identitas.
Identitas yang dikembalikan
Gunakan kolom identitas yang dinormalisasi untuk nama dan tanggal lahir jika kolom tersebut dikembalikan. Atribut khusus dompet menjelaskan informasi identitas yang dibagikan oleh dompet yang dipilih. Atribut yang tersedia berbeda-beda menurut dompet dan negara. Identitas yang terautentikasi tidak berarti bahwa potret, alamat, atau atribut lain yang diminta tersedia.Uji di sandbox
Aplikasi dalam mode sandbox Didit mensimulasikan verifikasi dompet tanpa menghubungi penyedia dompet atau membebankan kredit. Respons menandai permintaan ini denganwallet_verification.simulated: true.
Persetujuan simulasi adalah data contoh, bukan identitas dunia nyata yang telah diverifikasi.
Untuk dompet dengan pengalihan, ikuti URL yang dikembalikan untuk menguji callback dan kembali ke aplikasi Anda.
Untuk Smart-ID atau Mobile-ID, gunakan endpoint polling untuk menyelesaikan persetujuan simulasi; tidak ada notifikasi yang dikirim ke ponsel.
Untuk menguji penanganan kegagalan, atur sandbox_scenario ke wallet_cancelled, wallet_timeout, atau wallet_provider_error saat memulai permintaan.
Aplikasi produksi menolak sandbox_scenario.
Simulasi sandbox Didit terpisah dari pengujian terhadap lingkungan uji milik penyedia.
Simulasi yang berhasil tidak menetapkan akses ke penyedia produksi atau ketersediaan produksi.
Sandbox penyedia ConnectID
Sandbox penyedia ConnectID menggunakan bank uji dan terpisah dari simulasi sandbox Didit. Ketika akses sandbox penyedia dikonfigurasi untuk integrasi Anda, teruskanauthorisation_server_id bank yang dipilih ke endpoint untuk memulai ConnectID.
Gunakan ID yang dikembalikan oleh pemilih bank ConnectID; jangan kirim URL bank atau penerbit yang sembarang.
Jika kolom ini dihilangkan, bank uji default akan dipilih.
Kolom ini khusus untuk ConnectID dan tidak mengubah atribut identitas yang diminta.
Bundel awal meminta nama depan, nama belakang, dan tanggal lahir.
Ikuti next_action yang dikembalikan untuk melakukan autentikasi, lalu ambil hasil verifikasi atau lakukan polling.
Hanya hasil yang sudah selesai dengan status disetujui yang mengonfirmasi bahwa verifikasi berhasil; kembali ke aplikasi Anda tidak mengonfirmasi keberhasilan verifikasi.
ConnectID tetap berstatus Segera hadir di produksi selama onboarding dan sertifikasi masih berlangsung.