Bir kullanıcının gerçek dünyadaki kimliğini doğrulamak, beyaz tahtada basit görünen ve inşa etmeye başladığınız anda aylarca süren bir projeye dönüşen görevlerden biridir. Belge yakalama, OCR, yüz eşleştirme, canlılık tespiti, dolandırıcılık sinyalleri ve ülkeler arasında düzinelerce kimlik türü için kapsama alanına ihtiyacınız var. Stripe Identity API, tüm bunları tek bir entegrasyonda bir araya getirerek, üretim-hazır bir kimlik doğrulama akışını bir çeyrek yerine bir öğleden sonra kurmanızı sağlar.
Bu kılavuz, bir geliştiricinin Stripe Identity'yi kullanıma sunmak için ihtiyaç duyduğu her adımı adım adım açıklar: kontrol panelinde etkinleştirme, bir VerificationSession oluşturma, barındırılan yönlendirme ile gömülü Stripe.js bileşeni arasında seçim yapma, webhook'ları işleme ve doğrulanmış çıktıları okuma. Curl ve Node örnekleri, hata işleme kalıpları ve Apidog ile tüm akışı yerel olarak nasıl test edeceğinizi göreceksiniz. Önce alternatifleri değerlendiriyorsanız, taahhütte bulunmadan önce en iyi KYC API'leri özetimize göz atın.
Stripe Identity, ödemeler için zaten Stripe kullanan ekipler için doğal bir uyumdur, ancak bağımsız bir ürün olarak da çalışır. Resmi Stripe Identity belgeleri ürün yüzeyini kapsar ve bu gönderi geliştirici deneyimi eksikliklerini doldurur: ağda neler oluyor, hangi alanlar önemli ve yaygın tuzaklar nerede bulunuyor.
TL;DR
- Stripe Identity, kullanıcıları bir devlet kimliği ve selfie canlılık kontrolü ile doğrular; ABD'de doğrulama başına fiyatlandırma 1,50 dolardan başlar.
- Çekirdek ilkel,
VerificationSessionnesnesidir; bir tanesini sunucu tarafında oluşturursunuz, ardından kullanıcıyı yönlendirir veya Stripe.js bileşenini bağlarsınız. - İhtiyaç duyduğunuz alanları
options.document.require_matching_selfie,require_id_numberveallowed_typesaracılığıyla isteyin. - Uygulama durumunuzu yönlendirmek için
identity.verification_session.verifiedveidentity.verification_session.requires_inputwebhook'larını dinleyin. - Doğrulanmış çıktılar (ad, doğum tarihi, adres, kimlik numarası) yalnızca oturum oluşturma sırasında
verified_outputsayarladığınızda gösterilir. - Stripe Identity, yerelleştirilmiş belge desteği ile 35'ten fazla ülkeyi kapsar.
Stripe Identity API Nedir?
Stripe Identity, Stripe'ın temel API yüzeyi üzerine inşa edilmiş bir kimlik doğrulama ürünüdür. Belge yakalama, veri çıkarma, yüz eşleştirme ve dolandırıcılık puanlamayı düzenleyen tek bir uç nokta ailesi (/v1/identity/verification_sessions) sunar. Çıktı, güvenebileceğiniz imzalı, yapılandırılmış bir kayıttır: doğrulanmış tam ad, doğum tarihi, adres ve isteğe bağlı kimlik numarası, Stripe kasasında saklanan orijinal belge görüntüleriyle eşleştirilir.
Arka planda Stripe, Checkout ve Payment Intents'ten zaten bildiğiniz oturum-artı-webhook kalıbını kullanır. Sunucu tarafında bir oturum oluşturursunuz, Stripe kullanıcıya yönelik yakalama kullanıcı arayüzünü halleder ve sonuç hazır olduğunda size bildirim gelir. Daha önce bir Checkout akışı oluşturduysanız, Identity dakikalar içinde tanıdık gelecektir.
Kimlik Doğrulama ve Kurulum
API'yi çağırmadan önce, kontrol panelinde Stripe Identity'yi açın. Kontrol Paneli > Ayarlar > Identity'ye gidin, şartları kabul edin ve Stripe'ın kendi tarafında KYC uyumluluğu için ihtiyaç duyduğu iş detaylarını doldurun. Anahtar, hesabınızda hem test modunu hem de canlı modu etkinleştirir.
Kimlik doğrulama, standart Stripe gizli anahtarınızı kullanır. Test anahtarları sk_test_ ile, canlı anahtarlar ise sk_live_ ile başlar. Stripe Identity ayrı bir kimlik bilgisi gerektirmez, bu da entegrasyon yüzeyini küçük tutar.
Node SDK'sını yükleyin:
npm install stripe
Ardından bir istemciyi başlatın. Stripe'ın sizi şema değişikliğiyle asla şaşırtmaması için API sürümünü sabitleyin:
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
apiVersion: "2024-06-20",
});
Artık stripe.identity.verificationSessions altındaki her uç noktayı çağırabilirsiniz.
Çekirdek Uç Noktalar
Bir VerificationSession Oluşturma
VerificationSession, kullanıcı doğrulama denemesi başına oluşturduğunuz tek nesnedir. Hangi belge türlerinin kabul edildiğini, bir selfie'nin gerekli olup olmadığını ve hangi alanların arka ucunuza döndürüleceğini kontrol eder.
Curl ile:
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 SDK ile:
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" },
});
// Send one of these to the client:
// session.url -> hosted redirect
// session.client_secret -> Stripe.js embedded component
Birkaç alan dikkat çekiyor. type: "document", Stripe'a bir belge kontrolü yapmasını söyler; alternatif olan id_number, bir kimlik toplamadan yalnızca ABD'ye özgü SSN tarzı bir arama yapar. allowed_types, kullanıcının hangi belge kategorilerini yükleyebileceğini kısıtlar; bu, yalnızca devlet tarafından verilmiş fotoğraflı kimliği kabul eden uyumluluk programları için önemlidir. verified_outputs, geri döndürmek istediğiniz alanların izin verilenler listesidir; Stripe, istemediğiniz hiçbir veriyi ifşa etmez, bu da veri minimizasyon duruşunuzu temiz tutar.
Barındırılan doğrulama yönlendirmesi ve gömülü Stripe.js
Stripe size iki entegrasyon şekli sunar. Barındırılan yönlendirme en hızlı yoldur: kullanıcıyı session.url adresine gönderirsiniz, Stripe tüm yakalama deneyimini bir stripe.com alan adında halleder ve kullanıcı sizin return_url adresinize geri döner. Yaklaşık on satır kod yazarsınız.
Gömülü akış, kendi uygulamanız içinde bir doğrulama modalı bağlamak için Stripe.js ve @stripe/stripe-js paketini kullanır. session.client_secret'ı ön uca geçirir ve stripe.verifyIdentity(clientSecret) çağırırsınız. Bu, kullanıcıları ürününüzde tutar ve çevresindeki sayfa üzerinde tasarım kontrolü sağlar. Doğrulama bir kayıt veya KYC adımında akışın ortasında gerçekleştiğinde bunu seçin; doğrulama ayrı bir görev olduğunda yönlendirmeyi seçin.
Webhook'lar
Bir doğrulamanın başarılı olduğunu size bildirmek için asla istemci yönlendirmesine güvenmeyin; her zaman arka uçta webhook'lar aracılığıyla onaylayın. Kontrol Paneli > Geliştiriciler > Webhook'lar adresinde bir uç nokta kaydedin ve şunlara abone olun:
identity.verification_session.verified, tüm kontroller geçtiğinde ve doğrulanmış veriler hazır olduğunda tetiklenir.identity.verification_session.requires_input, kullanıcı bir kontrolü geçtiğinde veya okunaksız bir belge yüklediğinde tetiklenir. Yeniden denemek için onları geri yönlendirebilirsiniz.identity.verification_session.processing, Stripe eşzamansız kontrolleri çalıştırırken tetiklenir; döndürme durumlarını göstermek için kullanışlıdır.identity.verification_session.canceled, oturumu programatik olarak iptal ederseniz tetiklenir.
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 yükü, oturumun doğrulandığını size bildirir, ancak hassas alanları içermez. Doğrulanmış çıktıları okumak için verificationSessions.retrieve'yi expand: ["verified_outputs"] ile çağırı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 kez döndürür; hemen kendi tarafınızda şifrelenmiş olarak saklayın. Belge görüntüleri Stripe'ın kasasında kalır ve denetim için kontrol paneli aracılığıyla erişilebilir.
Yaygın hatalar ve hız limitleri
En sık görülen hata, document_unverified_other veya selfie_face_mismatch gibi bir kodla birlikte verification_session.requires_input'tır. Bunları, kullanıcıya dostça bir tekrar deneme kullanıcı arayüzü sunarak ele alın; aynı oturum, verificationSessions.cancel çağrılarak ve yeni bir tane oluşturularak veya hala açıkken aynı session.url adresine yönlendirilerek yeniden kullanılabilir.
Stripe, canlı modda saniyede 100, test modunda ise saniyede 25 istek olmak üzere standart API hız limitlerini uygular. /identity/verification_sessions uç noktaları, API'nin geri kalanıyla aynı pakete girer. Limitlere ulaşırsanız, bir Retry-After başlığıyla HTTP 429 göreceksiniz; üstel geri çekilme kullanın ve başlığa uyun.
Dikkat edilmesi gereken diğer hatalar: kullanıcının allowed_types listenizin dışında bir kimlik yüklediğinde unsupported_document_type ve Stripe Identity'nin henüz kapsamadığı ülkelerden birinden bir belge denediğinde country_not_supported.
Stripe Identity Fiyatlandırması
Stripe Identity, Amerika Birleşik Devletleri'nde doğrulama başına 1,50 ABD dolarıdır. Uluslararası fiyatlandırma değişiklik gösterir; çoğu Avrupa ülkesi 1,50 ila 2,00 ABD doları civarındadır ve Stripe, tam ülke bazında dökümü fiyatlandırma sayfasında yayınlar. requires_input ile biten bir doğrulama girişimi faturalandırılabilir bir olay olarak sayılmaz; yalnızca tamamlanmış verified oturumlar faturalandırılır.
Hacimli müşteriler için Stripe, çek başına ücreti önemli ölçüde azaltabilecek özel fiyatlandırma sunar. Ayda 10.000'den fazla doğrulama işlemi yapıyorsanız, satış departmanıyla görüşün.
Stripe Identity'yi Apidog ile Test Etme
API oyun alanları, özellikle webhook yükleri üzerinde çalışırken, her zaman elle curl komutları yazmaktan daha iyidir. Apidog, Stripe'ın OpenAPI spesifikasyonunu doğrudan içe aktarır, böylece VerificationSession nesnesindeki her alan satır içi belgelerle görünür. Stripe'ın test ortamına gerçek istekler gönderebilir, yanıtı inceleyebilir ve istediğiniz kadar yeniden oynatabilirsiniz.
Webhook test tarafı, Apidog'un en çok zaman kazandırdığı yerdir. identity.verification_session.verified olaylarını yerel olarak taklit edebilir, geliştirme sunucunuza gönderebilir ve gerçek bir doğrulamanın tamamlanmasını beklemeye gerek kalmadan işleyicinizi adım adım takip edebilirsiniz. İş akışlarını karşılaştırıyorsanız, 2026'da Postman olmadan API testi hakkındaki kılavuzumuzda daha derin bir açıklama bulunmaktadır. Masaüstü istemcisini almak 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'si, Connect ve Ödeme hesapları için işletme sahiplerini doğrular. Stripe Identity, son kullanıcılarınızı doğrulamak için bağımsız bir API'dir; iki sistem doğrulama sonuçlarını paylaşmaz.
Doğrulanmış bir kimliği birden fazla oturumda yeniden kullanabilir miyim? Evet. Bir oturum doğrulandıktan sonra, verified_outputs o oturum nesnesinde kalıcıdır. Yeni bir olay için yeniden doğrulamanız gerekiyorsa, yeni bir oturum oluşturun ve bunu kendi tarafınızdaki kullanıcı kaydına bağlayın.
Stripe Identity ödemeler dışında da çalışır mı? Kesinlikle. Birçok müşteri bunu yalnızca bir KYC katmanı olarak kullanır ve Stripe'ın ödeme yüzeyine asla dokunmaz. Kimlik doğrulamasının yanı sıra daha geniş yaptırım taramasına ihtiyacınız varsa, bunu özel bir AML tarama API'si ile eşleştirin.
Stripe Identity, Plaid Identity Verification ile nasıl karşılaştırılır? Stripe belge artı selfie'ye odaklanırken; Plaid banka onaylı kimlik verilerine eğilimlidir. Diğer yaklaşım için Plaid API kılavuzumuza bakın.
Selfie canlılığı zorunlu mu? Hayır. Yalnızca bir belge kontrolüne ihtiyacınız varsa options.document.require_matching_selfie değerini false olarak ayarlayın. Çoğu dolandırıcılık ekibi bunu açık tutar, çünkü pasif canlılık birçok düşük çabalı saldırıyı yakalar.
Stripe Identity hangi ülkeleri kapsar? Kuzey Amerika, Avrupa ve Asya-Pasifik'in bazı bölgelerinde 35'ten fazla ülke ve her biri için yerelleştirilmiş belge ayrıştırıcıları mevcuttur. Stripe, canlı ülke listesini belgelerinde yayınlar ve düzenli olarak yeni pazarlar ekler.