DEV Community

Cover image for Cara Menggunakan Stripe Identity API: Panduan Developer untuk Verifikasi Identitas
Walse
Walse

Posted on • Originally published at apidog.com

Cara Menggunakan Stripe Identity API: Panduan Developer untuk Verifikasi Identitas

Memverifikasi identitas dunia nyata pengguna seringkali terlihat sederhana, namun implementasinya bisa memakan waktu berbulan-bulan karena kebutuhan fitur seperti pengambilan dokumen, OCR, pencocokan wajah, deteksi keaktifan, pencegahan penipuan, dan dukungan untuk berbagai jenis ID dari banyak negara. Stripe Identity API mengemas semua fitur tersebut dalam satu integrasi sehingga Anda bisa menyiapkan proses verifikasi ID siap produksi hanya dalam hitungan hari.

Coba Apidog hari ini

Panduan ini memandu langkah demi langkah implementasi Stripe Identity: mulai dari aktivasi di dasbor, pembuatan VerificationSession, pemilihan antara redirect hosted atau komponen Stripe.js embedded, penanganan webhook, hingga membaca output verifikasi. Disertakan juga contoh curl dan Node.js, pola penanganan error, serta cara menguji seluruh alur secara lokal menggunakan Apidog. Jika Anda ingin membandingkan dengan solusi lain, cek juga rangkuman API KYC terbaik sebelum menentukan pilihan.

Stripe Identity sangat cocok untuk tim yang sudah menggunakan Stripe untuk pembayaran, namun juga berfungsi sebagai produk mandiri. Dokumentasi resmi Stripe Identity menjelaskan permukaan produknya, sedangkan artikel ini fokus pada pengalaman implementasi: apa yang terjadi di jaringan, bidang mana yang penting, dan jebakan umum yang perlu dihindari.

TL;DR

  • Stripe Identity memverifikasi pengguna dengan ID pemerintah plus selfie liveness; biaya mulai $1.50/verifikasi di AS.
  • Objek inti: VerificationSession — buat di server, lalu arahkan user ke session URL atau gunakan komponen Stripe.js.
  • Atur field yang dibutuhkan lewat options.document.require_matching_selfie, require_id_number, dan allowed_types.
  • Gunakan webhook identity.verification_session.verified & identity.verification_session.requires_input untuk sinkronisasi status aplikasi.
  • Data hasil verifikasi (nama, DOB, alamat, nomor ID) hanya tersedia jika verified_outputs diatur saat pembuatan sesi.
  • Dukungan lebih dari 35 negara dengan dokumen lokal.

Apa itu API Stripe Identity?

Stripe Identity adalah API verifikasi identitas berbasis dokumen dan liveness selfie di atas infrastruktur Stripe. Endpoint utamanya, /v1/identity/verification_sessions, mengorkestrasi upload dokumen, ekstraksi data, pencocokan wajah, dan deteksi penipuan. Outputnya berupa data terstruktur yang telah diverifikasi (nama, tanggal lahir, alamat, nomor ID) beserta foto dokumen yang tersimpan aman di vault Stripe.

Prosesnya berbasis pola sesi dan webhook: Anda create session di backend, Stripe handle UI pengambilan data di sisi user, dan backend Anda akan menerima notifikasi begitu hasil verifikasi siap. Jika Anda familiar dengan Stripe Checkout, workflow-nya mirip dan cepat dipahami.

Autentikasi dan Penyiapan

  1. Aktifkan Stripe Identity di Dashboard: masuk ke Dashboard > Pengaturan > Identitas, setujui syarat, dan isi data bisnis yang diperlukan Stripe untuk compliance KYC.
  2. Gunakan kunci rahasia Stripe standar (format sk_test_ untuk uji & sk_live_ untuk produksi).
  3. Install Stripe Node SDK: 
    npm install stripe
  4. Inisialisasi klien dengan versi API agar skema tidak berubah tanpa pemberitahuan: 
    import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: "2024-06-20",
});

Setelah itu, Anda siap memanggil endpoint stripe.identity.verificationSessions.

Endpoint Inti

Membuat VerificationSession

Satu VerificationSession dibuat untuk setiap upaya verifikasi user. Di sini Anda tentukan dokumen yang diterima, apakah selfie diperlukan, serta field apa saja yang dikembalikan ke backend.

Contoh 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"

Contoh 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 ke client salah satu:
// session.url           // Hosted redirect
// session.client_secret // Embedded Stripe.js

Beberapa hal penting:

  • type: "document" untuk pemeriksaan dokumen. Tipe id_number (khusus AS) hanya untuk verifikasi SSN tanpa upload dokumen.
  • allowed_types membatasi jenis dokumen yang diterima.
  • verified_outputs hanya expose data yang Anda minta — minimalisasi data by design.

Redirect Hosted vs Stripe.js Embedded

Dua opsi integrasi:

  1. Hosted Redirect: Redirect user ke session.url (domain stripe.com), Stripe handle seluruh proses, user kembali via return_url. Kode minimal.
  2. Stripe.js Embedded: Gunakan session.client_secret di frontend, panggil stripe.verifyIdentity(clientSecret) (dengan @stripe/stripe-js). User tetap di aplikasi Anda, cocok untuk verifikasi di tengah alur registrasi.

Webhook

Selalu gunakan webhook untuk memastikan status verifikasi, bukan hanya rely pada redirect client.

  1. Daftarkan webhook di Dashboard > Pengembang > Webhook dan subscribe ke event berikut:
    • identity.verification_session.verified: verifikasi sukses & data siap.
    • identity.verification_session.requires_input: user gagal atau dokumen tidak terbaca.
    • identity.verification_session.processing: Stripe masih memproses.
    • identity.verification_session.canceled: sesi dibatalkan.

Contoh handler webhook dengan Express:

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

Webhook hanya memberitahu Anda status; field verifikasi sensitif diambil manual via API: 

const session = await stripe.identity.verificationSessions.retrieve(
  "vs_1N...",
  { expand: ["verified_outputs"] }
);

const { first_name, last_name, dob, address, id_number } = session.verified_outputs;

id_number hanya dikembalikan sekali — simpan secara terenkripsi segera. Gambar dokumen hanya dapat diakses via dashboard Stripe untuk audit.

Kesalahan Umum dan Batas Kecepatan

  • Error paling umum: verification_session.requires_input dengan kode seperti document_unverified_other atau selfie_face_mismatch. Solusi: tampilkan UI retry; Anda bisa pakai ulang session URL selama masih aktif, atau cancel & create session baru.
  • Rate limit: 100 request/detik (live) atau 25/detik (test). Jika dapat HTTP 429, patuhi header Retry-After dan gunakan exponential backoff.
  • Error lain: unsupported_document_type (dokumen tidak sesuai allowed_types), country_not_supported (negara belum didukung Stripe Identity).

Harga Stripe Identity

  • Harga mulai $1.50/verifikasi di AS. Negara Eropa umumnya $1.50–$2.00; detail lengkap di halaman harga Stripe.
  • Hanya sesi dengan status verified yang ditagih. Sesi requires_input tidak dikenakan biaya.
  • Untuk volume >10.000/bulan, hubungi tim sales Stripe untuk negosiasi harga bulk.

Menguji Stripe Identity dengan Apidog

Testing API lebih efisien menggunakan playground seperti Apidog daripada manual curl, apalagi saat menguji payload webhook.

  • Import OpenAPI Stripe: Semua field VerificationSession tersedia dengan dokumentasi inline. Kirim request langsung ke environment test Stripe, inspeksi response, dan replay sebanyak yang dibutuhkan.
  • Webhook testing: Mock event identity.verification_session.verified secara lokal, kirim ke server dev, dan debug handler Anda tanpa harus menunggu proses verifikasi real. Untuk workflow comparison, cek panduan pengujian API tanpa Postman tahun 2026. Unduh Apidog untuk klien desktop.

FAQ

Apa bedanya Stripe Identity dengan KYC reguler Stripe? KYC Stripe built-in hanya untuk verifikasi pemilik bisnis (Connect/Payments). Stripe Identity adalah API mandiri untuk verifikasi end-user; hasilnya tidak saling berbagi.

Bisa reuse identitas yang sudah diverifikasi? Bisa. verified_outputs pada sesi yang sudah diverifikasi bersifat permanen. Untuk verifikasi ulang, buat sesi baru & tautkan ke user di backend.

Apakah Stripe Identity bisa digunakan di luar pembayaran? Ya, banyak yang menggunakannya khusus KYC tanpa pakai pembayaran Stripe. Untuk AML screening tambahan, kombinasikan dengan API AML screening.

Bagaimana perbandingan Stripe Identity dengan Plaid Identity Verification? Stripe fokus pada dokumen + selfie, Plaid lebih ke data identitas bank. Lihat juga panduan API Plaid.

Apakah selfie liveness wajib? Tidak. Set options.document.require_matching_selfie ke false jika hanya perlu dokumen. Namun, kebanyakan tim tetap mengaktifkan untuk mencegah serangan low-effort.

Negara apa saja yang didukung Stripe Identity? Lebih dari 35 negara di Amerika Utara, Eropa, dan Asia-Pasifik. Daftar lengkap negara didukung tersedia di dokumentasi Stripe.

Top comments (0)