Stripe Identity API Kullanımı: Kimlik Doğrulama Geliştirici Rehberi

Bir kullanıcının gerçek dünyadaki kimliğini doğrulamak, başlangıçta basit görünse de uygulamada oldukça karmaşık ve zaman alıcı bir süreçtir. Belge yakalama, OCR, yüz eşleştirme, canlılık tespiti, sahtekarlık analizi ve onlarca ülkeye göre kimlik türü desteği gerekir. Stripe Identity API, tüm bu adımları tek entegrasyonla bir araya getirir ve üretime hazır bir kimlik doğrulama akışını saatler içinde kurmanızı sağlar.

Apidog'u bugün deneyin

Bu rehberde Stripe Identity'nin kurulumundan, VerificationSession oluşturma ve seçenekleri belirlemeden, doğrulanan sonuçları alma ve webhook ile otomasyon süreçlerine kadar tüm entegrasyon adımlarını bulacaksınız. Her aşamada cURL ve Node.js örnek kodları, hata yönetimi yaklaşımları ve Apidog ile lokal test ipuçları sunulacak. Alternatifleri karşılaştırmak isterseniz, öncelikle en iyi KYC API'leri özetimize göz atabilirsiniz.

Stripe Identity, Stripe Payments kullanan ekipler için olduğu kadar bağımsız bir ürün olarak da uygundur. Resmi dokümantasyon, ürün özelliklerini kapsarken, bu rehberde entegrasyonun pratik yönlerine, dikkat etmeniz gereken alanlara ve tipik hatalara odaklanıyoruz.

TL;DR

Stripe Identity, kullanıcıları devlet kimliği ve selfie canlılık kontrolü ile doğrular. ABD'de işlem başına 1,50$’dan başlar.
Temel obje VerificationSession'dır. Sunucuda oluşturulur, ardından kullanıcıya yönlendirme yapılır veya Stripe.js ile gömülü entegrasyon sağlanır.
Gereken alanları options.document.require_matching_selfie, require_id_number ve allowed_types ile belirleyin.
Durum yönetimi için identity.verification_session.verified ve identity.verification_session.requires_input webhook'larını dinleyin.
Doğrulanan veriler (ad, doğum tarihi, adres, kimlik no) yalnızca verified_outputs ile talep edilirse döner.
Stripe Identity, yerelleştirilmiş belge desteğiyle 35+ ülkeyi kapsar.

Stripe Identity API Nedir?

Stripe Identity, Stripe'ın API altyapısı üzerinde çalışan bir kimlik doğrulama servisidir. Tek bir uç nokta ailesi (/v1/identity/verification_sessions), belge yakalama, veri çıkarma, yüz eşleştirme ve dolandırıcılık puanlama işlemlerini yönetir. Sonuç olarak doğrulanmış ad, doğum tarihi, adres ve kimlik numarası gibi imzalı ve yapılandırılmış veriler sunar. Orijinal belge görüntüleri Stripe kasasında tutulur.

Arka planda, Stripe Checkout ve Payment Intents’te alışık olduğunuz oturum + webhook mimarisi kullanılır. Oturumu sunucuda oluşturur, kullanıcıyı Stripe UI'ına yönlendirir ve sonuç hazır olunca webhook ile haberdar edilirsiniz.

Kimlik Doğrulama ve Kurulum

Öncelikle Stripe Dashboard’da Settings > Identity bölümünden Stripe Identity’yi aktif edin, şartları kabul edin ve gerekli iş bilgilerini girin.
Test ve canlı modda anahtarlarınız sk_test_ ve sk_live_ ile başlar. Ayrı bir kimlik bilgisi gerekmez.
Node SDK kurulumu:

npm install stripe

Client başlatma ve API versiyonunu sabitleme:

import Stripe from "stripe";

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

Artık stripe.identity.verificationSessions ile tüm uç noktaları kullanabilirsiniz.

Çekirdek Uç Noktalar

VerificationSession Oluşturma

Kullanıcı başına bir VerificationSession oluşturursunuz. Hangi belge türlerinin kabul edileceğini, selfie zorunluluğu ve hangi verilerin döneceğini burada belirlersiniz.

cURL örneği:

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"

Node.js örneği:

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" },
});

// İstemciye gönderebileceğiniz iki bilgi:
// session.url              // Barındırılan yönlendirme
// session.client_secret    // Stripe.js ile gömülü entegrasyon

Notlar: type: "document" ile belge kontrolü istenir. allowed_types ile kabul edilen belge türleri kısıtlanır. verified_outputs ile hangi alanların döneceğini seçersiniz. Stripe gereksiz hiçbir veriyi paylaşmaz.

Barındırılmış Yönlendirme vs. Stripe.js ile Gömülü Entegrasyon

Barındırılan yönlendirme: Kullanıcıyı session.url adresine yönlendirin, Stripe tüm süreci stripe.com alanında yönetir ve işlem sonrası return_url'a döner. Kod miktarı az, entegrasyon hızlıdır.
Gömülü Stripe.js: @stripe/stripe-js ile uygulamanıza modal ekleyin. session.client_secret’ı ön uca aktarın ve stripe.verifyIdentity(clientSecret) fonksiyonunu çağırın. Kullanıcı uygulamanızdan çıkmaz; özelleştirilebilir bir akış sağlar.

Webhook'lar

Kullanıcı doğrulamasının tamamlandığını teyit etmek için istemci yönlendirmesine güvenmeyin. Her zaman webhook ile arka uç doğrulaması yapın.

identity.verification_session.verified: Doğrulama başarılı oldu, veriler hazır.
identity.verification_session.requires_input: Kullanıcı yeniden giriş yapmalı (ör. belge okunamadı).
identity.verification_session.processing: Stripe kontrolleri çalıştırıyor.
identity.verification_session.canceled: Oturum iptal edildi.

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 });
});

Doğrulanmış Çıktıları Alma

Webhook yalnızca durum bilgisini iletir. Gerçek doğrulanan verileri almak için verificationSessions.retrieve ile expand: ["verified_outputs"] parametresini kullanın:

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 id_number’ı yalnızca bir defa döndürür. Hemen şifreli olarak saklayın. Belge görselleri Stripe kasasında kalır ve yalnızca Dashboard’dan erişilebilir.

Yaygın Hatalar ve Hız Limitleri

En yaygın hata: verification_session.requires_input ile birlikte document_unverified_other veya selfie_face_mismatch hataları. Kullanıcıya tekrar deneme imkanı sunun. Oturumu verificationSessions.cancel ile iptal edip yenisini oluşturabilir veya hala açıksa aynı session.url’a yönlendirebilirsiniz.
Hız limiti: Canlıda saniyede 100, testte saniyede 25 istek sınırı var. Limit aşılırsa Retry-After başlığı ile 429 döner. Üstel geri çekilme uygulayın.
Diğer hatalar: unsupported_document_type (izin verilmeyen belge), country_not_supported (desteklenmeyen ülke).

Stripe Identity Fiyatlandırması

ABD’de işlem başına $1,50. Avrupa’da genellikle $1,50-$2,00 arası.
requires_input ile biten girişimler faturalandırılmaz. Sadece başarılı verified oturumlar ücretlendirilir.
Büyük hacimli (10.000+ işlem/ay) müşteriler için indirimli fiyatlandırma mevcut.

Stripe Identity'yi Apidog ile Test Etme

API entegrasyonunu test etmek için Apidog ile Stripe’ın OpenAPI şemasını içe aktarın. Tüm VerificationSession alanlarını, parametrelerini ve örnek yanıtları görebilirsiniz. Stripe test ortamına gerçek istekler gönderebilir, sonuçları inceleyebilir ve farklı senaryoları kolayca tekrarlayabilirsiniz.

Webhook testinde Apidog büyük kolaylık sağlar: identity.verification_session.verified olaylarını lokal olarak tetikleyebilir, geliştirme sunucunuza gönderebilir ve gerçek doğrulamayı beklemeden otomasyonunuzu test edebilirsiniz. Daha fazla detay için Postman olmadan API test etme rehberimizi inceleyebilirsiniz. Masaüstü istemcisi için Apidog'u indirin.

Sıkça Sorulan Sorular

Stripe Identity ile Stripe'ın normal KYC'si arasındaki fark nedir? Stripe’ın yerleşik KYC süreci Connect ve Ödeme hesapları için işletme sahiplerini doğrular. Stripe Identity ise, son kullanıcılarınızı bağımsız olarak doğrulamanızı sağlar. Sonuçlar iki sistem arasında paylaşılmaz.

Doğrulanan kimliği tekrar kullanabilir miyim? Evet, bir oturum doğrulandıktan sonra verified_outputs oturumda kalıcıdır. Ancak yeni bir işlem için yeni oturum açmanız gerekir; bunu kullanıcı kaydınıza bağlayabilirsiniz.

Stripe Identity ödemeler dışında kullanılabilir mi? Evet, sadece KYC için kullanabilirsiniz. Geniş yaptırım taraması gerekiyorsa, bunu özel bir AML tarama API’si ile tamamlayabilirsiniz.

Stripe Identity, Plaid Identity Verification ile nasıl karşılaştırılır? Stripe belge + selfie doğrulamasına odaklanırken, Plaid daha çok banka onaylı kimlik verisi sunar. Plaid ile ilgili detaylar için Plaid API kılavuzumuza bakabilirsiniz.

Selfie canlılığı zorunlu mu? Hayır. Sadece belge kontrolü için options.document.require_matching_selfie parametresini false yapabilirsiniz. Çoğu durumda dolandırıcılığı önlemek için açık bırakılır.

Stripe Identity hangi ülkeleri kapsar? Kuzey Amerika, Avrupa ve Asya-Pasifik’te 35’ten fazla ülke ve her ülke için yerelleştirilmiş belge ayrıştırıcıları desteklenir. Güncel ülke listesi Stripe belgelerinde bulunur ve sürekli güncellenir.