Memverifikasi identitas dunia nyata pengguna adalah salah satu tugas yang terlihat sederhana di papan tulis dan berubah menjadi proyek berbulan-bulan saat Anda mulai membangunnya. Anda memerlukan pengambilan dokumen, OCR, pencocokan wajah, deteksi keaktifan, sinyal penipuan, dan cakupan untuk puluhan jenis ID di berbagai negara. API Stripe Identity mengemas semua itu ke dalam satu integrasi, sehingga Anda dapat menyiapkan alur verifikasi ID yang siap produksi dalam waktu singkat, bukan berbulan-bulan.
Panduan ini membahas setiap langkah yang perlu dilakukan pengembang untuk meluncurkan Stripe Identity: mengaktifkannya di dasbor, membuat VerificationSession, memilih antara pengalihan yang dihosting dan komponen Stripe.js yang disematkan, menangani webhook, dan membaca output yang diverifikasi. Anda akan melihat contoh curl dan Node, pola penanganan kesalahan, dan cara menguji seluruh alur secara lokal dengan Apidog. Jika Anda mengevaluasi alternatif terlebih dahulu, telusuri rangkuman kami tentang API KYC terbaik sebelum berkomitmen.
Stripe Identity sangat cocok untuk tim yang sudah menggunakan Stripe untuk pembayaran, tetapi juga berfungsi sebagai produk mandiri. Dokumentasi resmi Stripe Identity mencakup permukaan produk, dan postingan ini mengisi celah pengalaman pengembang: apa yang terjadi di jaringan, bidang mana yang penting, dan di mana jebakan umum berada.
TL;DR
- Stripe Identity memverifikasi pengguna dengan ID pemerintah plus pemeriksaan keaktifan swafoto; harga mulai dari $1.50 per verifikasi di AS.
- Primitif intinya adalah objek
VerificationSession; Anda membuatnya di sisi server, lalu mengarahkan pengguna atau memasang komponen Stripe.js. - Minta bidang yang Anda butuhkan melalui
options.document.require_matching_selfie,require_id_number, danallowed_types. - Dengarkan webhook
identity.verification_session.verifieddanidentity.verification_session.requires_inputuntuk menggerakkan status aplikasi Anda. - Output yang diverifikasi (nama, tanggal lahir, alamat, nomor ID) hanya ditampilkan saat Anda mengatur
verified_outputssaat pembuatan sesi. - Stripe Identity mencakup lebih dari 35 negara dengan dukungan dokumen lokal.
Apa itu API Stripe Identity?
Stripe Identity adalah produk verifikasi ID yang dibangun di atas permukaan API inti Stripe. Ini memberi Anda satu keluarga endpoint (/v1/identity/verification_sessions) yang mengorkestrasi pengambilan dokumen, ekstraksi data, pencocokan wajah, dan penilaian penipuan. Hasilnya adalah catatan terstruktur yang ditandatangani yang dapat Anda percayai: nama lengkap yang diverifikasi, tanggal lahir, alamat, dan nomor ID opsional, dipasangkan dengan gambar dokumen asli yang disimpan di vault Stripe.
Di balik layar, Stripe menggunakan pola sesi-plus-webhook yang sama yang sudah Anda kenal dari Checkout dan Payment Intents. Anda membuat sesi di sisi server, Stripe menangani UI pengambilan yang menghadap pengguna, dan Anda akan diberitahu saat hasilnya siap. Jika Anda pernah membangun alur Checkout sebelumnya, Identity akan terasa akrab dalam beberapa menit.
Autentikasi dan penyiapan
Sebelum Anda memanggil API, aktifkan Stripe Identity di dasbor. Buka Dasbor > Pengaturan > Identitas, terima persyaratan, dan isi detail bisnis yang dibutuhkan Stripe untuk kepatuhan KYC di pihaknya. Tombol tersebut mengaktifkan Identitas untuk mode uji dan mode langsung di akun Anda.
Autentikasi menggunakan kunci rahasia Stripe standar Anda. Kunci uji dimulai dengan sk_test_, dan kunci langsung dimulai dengan sk_live_. Stripe Identity tidak memerlukan kredensial terpisah, yang menjaga permukaan integrasi tetap kecil.
Instal Node SDK:
npm install stripe
Kemudian inisialisasi klien. Sematkan versi API agar Stripe tidak pernah mengejutkan Anda dengan perubahan skema:
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
apiVersion: "2024-06-20",
});
Anda sekarang dapat memanggil setiap endpoint di bawah stripe.identity.verificationSessions.
Endpoint inti
Membuat VerificationSession
VerificationSession adalah objek tunggal yang Anda buat per upaya verifikasi pengguna. Objek ini mengontrol jenis dokumen apa yang diterima, apakah swafoto diperlukan, dan bidang mana yang dikembalikan ke backend Anda.
Dengan curl:
curl https://api.stripe.com/v1/identity/verification_sessions \
-u "$STRIPE_SECRET_KEY:" \
-d "type=document" \
-d "options[document][require_matching_selfie]=true" \
-d "options[document][require_id_number]=true" \
-d "options[document][allowed_types][]=driving_license" \
-d "options[document][allowed_types][]=passport" \
-d "verified_outputs[]=first_name" \
-d "verified_outputs[]=last_name" \
-d "verified_outputs[]=dob" \
-d "verified_outputs[]=address" \
-d "verified_outputs[]=id_number" \
-d "metadata[user_id]=usr_7f3k2"
Dengan Node SDK:
const session = await stripe.identity.verificationSessions.create({
type: "document",
options: {
document: {
require_matching_selfie: true,
require_id_number: true,
allowed_types: ["driving_license", "passport", "id_card"],
},
},
verified_outputs: [
"first_name",
"last_name",
"dob",
"address",
"id_number",
],
metadata: { user_id: "usr_7f3k2" },
});
// Kirim salah satu dari ini ke klien:
// session.url -> pengalihan yang dihosting
// session.client_secret -> komponen Stripe.js yang disematkan
Beberapa bidang patut diperhatikan. type: "document" memberi tahu Stripe untuk menjalankan pemeriksaan dokumen; alternatifnya, id_number, melakukan pencarian gaya SSN khusus AS tanpa mengumpulkan ID. allowed_types membatasi kategori dokumen mana yang dapat diunggah pengguna, yang penting untuk program kepatuhan yang hanya menerima ID foto yang dikeluarkan pemerintah. verified_outputs adalah daftar bidang yang diizinkan yang ingin Anda kembalikan; Stripe tidak akan mengekspos data apa pun yang tidak Anda minta, yang menjaga postur minimalisasi data Anda tetap bersih.
Pengalihan verifikasi yang dihosting vs. Stripe.js yang disematkan
Stripe memberi Anda dua bentuk integrasi. Pengalihan yang dihosting adalah jalur tercepat: kirim pengguna ke session.url, Stripe menangani seluruh pengalaman pengambilan di domain stripe.com, dan pengguna kembali ke return_url Anda. Anda menulis sekitar sepuluh baris kode.
Alur yang disematkan menggunakan Stripe.js dan paket `@stripe/stripe-js` untuk memasang modal verifikasi di dalam aplikasi Anda sendiri. Anda meneruskan session.client_secret ke frontend dan memanggil stripe.verifyIdentity(clientSecret). Ini menjaga pengguna tetap berada di produk Anda dan memberi Anda kendali desain atas halaman di sekitarnya. Pilih ini ketika verifikasi terjadi di tengah alur dalam langkah pendaftaran atau KYC; pilih pengalihan ketika verifikasi adalah tugas yang terpisah.
Webhook
Jangan pernah mengandalkan pengalihan klien untuk memberi tahu Anda bahwa verifikasi berhasil; selalu konfirmasi di backend melalui webhook. Daftarkan endpoint di Dasbor > Pengembang > Webhook dan berlangganan ke:
identity.verification_session.verifiedterpicu ketika semua pemeriksaan lulus dan data yang diverifikasi siap.identity.verification_session.requires_inputterpicu ketika pengguna gagal dalam pemeriksaan atau mengunggah dokumen yang tidak dapat dibaca. Anda dapat mengarahkan mereka kembali untuk mencoba lagi.identity.verification_session.processingterpicu saat Stripe menjalankan pemeriksaan asinkron; berguna untuk menampilkan status pemintal.identity.verification_session.canceledterpicu jika Anda membatalkan sesi secara terprogram.
app.post("/webhooks/stripe", express.raw({ type: "application/json" }), async (req, res) => {
const event = stripe.webhooks.constructEvent(
req.body,
req.headers["stripe-signature"],
process.env.STRIPE_WEBHOOK_SECRET
);
if (event.type === "identity.verification_session.verified") {
const session = event.data.object;
await markUserVerified(session.metadata.user_id, session.id);
}
if (event.type === "identity.verification_session.requires_input") {
await notifyUserToRetry(event.data.object.metadata.user_id);
}
res.json({ received: true });
});
Mengambil output yang diverifikasi
Payload webhook memberi tahu Anda bahwa sesi telah diverifikasi, tetapi tidak menyertakan bidang sensitif. Untuk membaca output yang diverifikasi, panggil verificationSessions.retrieve dengan expand: ["verified_outputs"]:
const session = await stripe.identity.verificationSessions.retrieve(
"vs_1N...",
{ expand: ["verified_outputs"] }
);
const { first_name, last_name, dob, address, id_number } = session.verified_outputs;
Stripe mengembalikan id_number hanya sekali; segera simpan terenkripsi di sisi Anda. Gambar dokumen itu sendiri tetap berada di vault Stripe dan dapat diakses melalui dasbor untuk audit.
Kesalahan umum dan batas kecepatan
Kegagalan yang paling sering terjadi adalah verification_session.requires_input dengan kode seperti document_unverified_other atau selfie_face_mismatch. Tangani ini dengan menampilkan UI coba lagi yang ramah; sesi yang sama dapat digunakan kembali dengan memanggil verificationSessions.cancel dan membuat yang baru, atau dengan mengarahkan ke session.url yang sama saat masih terbuka.
Stripe menerapkan batas kecepatan API standar 100 permintaan per detik dalam mode langsung dan 25 per detik dalam mode uji. Endpoint /identity/verification_sessions termasuk dalam kategori yang sama dengan API lainnya. Jika Anda mencapai batas, Anda akan melihat HTTP 429 dengan header Retry-After; gunakan exponential backoff dan patuhi header tersebut.
Kesalahan lain yang perlu diperhatikan: unsupported_document_type ketika pengguna mengunggah ID di luar daftar allowed_types Anda, dan country_not_supported ketika seseorang mencoba dokumen dari salah satu negara yang belum dicakup oleh Stripe Identity.
Harga Stripe Identity
Stripe Identity berharga $1.50 per verifikasi di Amerika Serikat. Harga internasional bervariasi; sebagian besar negara Eropa berada di sekitar $1.50 hingga $2.00, dan Stripe menerbitkan rincian lengkap per negara di halaman harganya. Upaya verifikasi yang berakhir dengan requires_input tidak dihitung sebagai acara yang dapat ditagih; hanya sesi verified yang selesai yang ditagih.
Untuk pelanggan bervolume, Stripe menawarkan harga khusus yang dapat memangkas biaya per-pemeriksaan secara signifikan. Jika Anda memproses lebih dari 10.000 verifikasi sebulan, bicarakan dengan tim penjualan.
Menguji Stripe Identity dengan Apidog
Tempat bermain API selalu mengalahkan perintah curl yang dibuat secara manual, terutama ketika Anda mengulang payload webhook. Apidog mengimpor spesifikasi OpenAPI Stripe secara langsung, sehingga setiap bidang pada objek VerificationSession muncul dengan dokumentasi inline. Anda dapat mengirim permintaan nyata ke lingkungan uji Stripe, memeriksa respons, dan memutarnya ulang sebanyak yang Anda butuhkan.
Sisi pengujian webhook adalah tempat Apidog menghemat waktu paling banyak. Anda dapat membuat mock peristiwa identity.verification_session.verified secara lokal, mengirimkannya ke server dev Anda, dan melangkah melalui penangan Anda tanpa memerlukan verifikasi nyata untuk selesai. Jika Anda membandingkan alur kerja, panduan kami tentang pengujian API tanpa Postman di tahun 2026 memiliki panduan yang lebih mendalam. Unduh Apidog untuk mendapatkan klien desktop.
FAQ
Apa perbedaan antara Stripe Identity dan KYC reguler Stripe? KYC bawaan Stripe memverifikasi pemilik bisnis untuk akun Connect dan Pembayaran. Stripe Identity adalah API mandiri untuk memverifikasi pengguna akhir Anda; kedua sistem tidak berbagi hasil verifikasi.
Bisakah saya menggunakan kembali identitas yang diverifikasi di beberapa sesi? Ya. Setelah sesi diverifikasi, verified_outputs bersifat permanen pada objek sesi tersebut. Jika Anda perlu memverifikasi ulang untuk acara baru, buat sesi baru dan tautkan ke catatan pengguna di sisi Anda.
Apakah Stripe Identity berfungsi di luar pembayaran? Tentu saja. Banyak pelanggan menggunakannya murni sebagai lapisan KYC dan tidak pernah menyentuh permukaan pembayaran Stripe. Jika Anda memerlukan penyaringan sanksi yang lebih luas di atas verifikasi ID, pasangkan dengan API penyaringan AML khusus.
Bagaimana perbandingan Stripe Identity dengan Verifikasi Identitas Plaid? Stripe berfokus pada dokumen plus swafoto; Plaid cenderung ke data identitas yang diverifikasi bank. Lihat panduan API Plaid kami untuk pendekatan lainnya.
Apakah pemeriksaan keaktifan swafoto wajib? Tidak. Atur options.document.require_matching_selfie ke false jika Anda hanya memerlukan pemeriksaan dokumen. Sebagian besar tim penipuan tetap menyalakannya, karena keaktifan pasif menangkap banyak serangan dengan usaha rendah.
Negara mana saja yang dicakup oleh Stripe Identity? Lebih dari 35 negara di Amerika Utara, Eropa, dan sebagian Asia-Pasifik, dengan pemroses dokumen lokal untuk setiap negara. Stripe menerbitkan daftar negara yang didukung di dokumentasinya dan menambahkan pasar baru secara teratur.