Stripe entegrasyonu, modern e-ticaret ve SaaS projelerinde ödeme altyapısı kurmak için tercih edilen en güçlü çözümlerden biridir. Stripe'ın kapsamlı API'si, webhook sistemi ve gelişmiş fraud koruması sayesinde tek bir platform üzerinden kartlı ödemeler, abonelikler ve çoklu para birimi işlemlerini yönetebilirsiniz. Bu rehberde Stripe'ı sıfırdan kurmanız için gereken her adımı bulacaksınız.
Stripe Hesabı Kurulumu ve API Key Yönetimi
Stripe entegrasyonuna başlamak için öncelikle stripe.com üzerinde bir hesap oluşturmanız gerekir. Hesap onaylandıktan sonra Dashboard üzerinden iki tür API anahtarına erişirsiniz: Publishable Key (istemci tarafında kullanılır, açık paylaşılabilir) ve Secret Key (yalnızca sunucu tarafında kullanılmalı, kesinlikle gizli tutulmalı). Test ve canlı ortam için ayrı ayrı anahtar setleri mevcuttur; geliştirme sürecinde her zaman test anahtarlarını kullanın.
- Publishable Key: Frontend JavaScript kodunda Stripe.js başlatmak için kullanılır, güvenli şekilde istemciye gönderilebilir.
- Secret Key: Sunucu tarafı API çağrıları için kullanılır; .env dosyasında saklanmalı, kaynak koduna eklenmemelidir.
- Restricted Keys: Belirli API işlemlerine sınırlı erişim tanımak için oluşturulabilir; güvenlik açısından önerilen yaklaşımdır.
- Webhook Signing Secret: Gelen webhook olaylarının gerçekten Stripe'tan geldiğini doğrulamak için kullanılır.
Stripe Elements ve Stripe.js ile Ödeme Formu Kurulumu
Stripe, ödeme formu oluşturmak için iki temel yaklaşım sunar: Stripe.js ile özelleştirilebilir form bileşenleri ve tamamen hazır bir ödeme sayfası olan Stripe Checkout. Her ikisi de PCI-DSS uyumludur; kart verileri doğrudan Stripe sunucularına gönderilir, sizin sunucularınıza uğramaz.
Stripe Elements ile Özel Form
Stripe Elements, markanıza özel tasarlanmış ödeme formları oluşturmanızı sağlar. HTML'de bir div tanımlayıp JavaScript ile Stripe örneği oluşturduktan sonra CardElement veya ayrı bileşenler (CardNumberElement, CardExpiryElement, CardCvcElement) yerleştirirsiniz. Kullanıcı kart bilgilerini girdiğinde Stripe.js bu verileri tokenize ederek bir PaymentMethod ID'si üretir. Bu ID'yi sunucunuza göndererek server-side'da ödemeyi tamamlarsınız. Elements, tema desteği, RTL uyumu ve mobil klavye optimizasyonu sunarak mükemmel bir kullanıcı deneyimi sağlar.
Webhook Entegrasyonu: Gerçek Zamanlı Olay Yönetimi
Stripe webhook'ları, ödeme tamamlandığında, abonelik yenilendiğinde veya ödeme başarısız olduğunda sunucunuzu gerçek zamanlı bilgilendiren HTTP POST istekleridir. Webhook endpoint'inizi Stripe Dashboard üzerinden tanımladıktan sonra gelen istekleri Stripe-Signature başlığını kullanarak doğrulamanız zorunludur. En kritik webhook olayları şunlardır: payment_intent.succeeded (ödeme başarılı), payment_intent.payment_failed (ödeme başarısız), invoice.paid (fatura ödendi), customer.subscription.deleted (abonelik iptal edildi). Webhook işleme kodunuzun idempotent olması, yani aynı olayı birden fazla kez aldığınızda duplikasyon yaratmaması kritik önem taşır.
Stripe ile Abonelik (Subscription) Ödemeleri
Stripe Billing modülü, SaaS ürünleri ve abonelik bazlı e-ticaret için kapsamlı altyapı sunar. Bir abonelik sistemi kurmak için sırasıyla Product (ürün), Price (fiyatlandırma planı) ve Customer (müşteri) nesneleri oluşturursunuz. Ardından müşteriyi bir Price'a bağlayan Subscription oluşturulur. Stripe otomatik olarak faturaları oluşturur, ödemeyi dener ve başarısız ödemelerde retry mantığını (akıllı yeniden deneme) uygular.
Çoklu Para Birimi ve Türkiye'de Stripe Kullanımı
Stripe, 135'ten fazla para birimini destekler. Türk Lirası (TRY) da desteklenen para birimleri arasındadır; ancak 2022 itibarıyla Stripe Türkiye merkezli şirketlere doğrudan hesap açmamaktadır. Bu nedenle Türk geliştiriciler genellikle yurt dışı tüzel kişilik veya Stripe Atlas aracılığıyla hesap oluşturmaktadır. Alternatif olarak, Türk pazarı için İyzico veya PayTR'yi birincil ödeme sağlayıcısı olarak kullanırken uluslararası işlemler için Stripe entegrasyonu tercih edilen bir yaklaşımdır.
Stripe Radar ile Fraud Koruması
Stripe Radar, makine öğrenmesi tabanlı bir fraud tespit sistemidir. Her işlemi gerçek zamanlı olarak analiz ederek risk skoru atar. Radar, Stripe ağındaki milyonlarca işletmeden gelen veriyle eğitildiği için bireysel kural tabanlı sistemlere kıyasla çok daha isabetli sonuçlar üretir. Özel kurallar (custom rules) ile belirli kart ülkelerini engelleyebilir, yüksek tutarlı işlemlere ekstra doğrulama ekleyebilir veya şüpheli e-posta pattern'larını kara listeye alabilirsiniz. Radar for Fraud Teams paketi ile müdahale edilen ve incelenen işlemleri ayrıntılı raporlarla takip edebilirsiniz.
- Block Rules: Belirli koşulları karşılayan işlemleri otomatik engeller.
- Review Rules: Şüpheli işlemleri manuel inceleme kuyruğuna alır.
- Allow Rules: Güvenilir müşterilerin işlemlerini doğrulamadan geçirir.
- 3DS Tetikleme: Risk skoru yüksek işlemlerde otomatik 3D Secure tetiklenebilir.
Test Ortamı Kurulumu ve Best Practices
Stripe, test ortamı için kapsamlı test kart numaraları sunar. 4242 4242 4242 4242 numaralı kart başarılı ödeme simüle ederken, 4000 0000 0000 0002 numaralı kart reddedilen ödemeyi test etmek için kullanılır. 3DS gerektiren senaryolar için özel test kartları mevcuttur. İdeal bir entegrasyon için şu best practice'lere uyun: Secret Key'i asla frontend koduna eklemeyin; webhook imzalarını her zaman doğrulayın; idempotency key kullanarak duplikasyon riskini ortadan kaldırın; hata mesajlarını kullanıcı dostu biçimde gösterin ve Stripe'ın güncel SDK versiyonunu kullanın.
Sık Sorulan Sorular
Stripe entegrasyonu ne kadar sürer?
Basit bir tek seferlik ödeme entegrasyonu deneyimli bir geliştirici için 1-2 günde tamamlanabilir. Webhook, abonelik ve gelişmiş Radar kurallarını içeren kapsamlı bir entegrasyon ise genellikle 1-2 hafta sürer. Test ve staging ortamı kurulumunu bu süreye dahil etmeyi unutmayın.
Stripe komisyon oranları nedir?
Stripe'ın standart oranı işlem başına yüzde 2.9 artı 30 cent'tir (USD bazında). Türk Lirası işlemlerde ve farklı ülkelerde oranlar değişebilir. Yüksek hacimli işletmeler için özel fiyatlandırma müzakere edilebilir. Abonelik ödemeleri için ek Billing ücreti uygulanmaktadır.
Stripe Türkiye'den kullanılabilir mi?
Stripe, Türkiye'deki şirketlere doğrudan hesap açmamaktadır. Ancak yurt dışı tüzel kişilik (örneğin ABD LLC veya İngiltere Ltd) aracılığıyla veya Stripe Atlas programıyla hesap oluşturulabilir. Türkiye'den ödeme almak için yerli PSP'lerle birlikte hibrit bir yaklaşım önerilmektedir.
Stripe webhook'ları nasıl test edilir?
Stripe CLI aracıyla yerel geliştirme ortamınıza webhook olaylarını yönlendirebilirsiniz. Komut satırında stripe listen --forward-to localhost:3000/webhook komutuyla webhook'ları local endpoint'inize iletebilir, stripe trigger payment_intent.succeeded komutuyla test olayı gönderebilirsiniz.
Sonuç
Stripe entegrasyonu, doğru yapılandırıldığında güvenli, esnek ve ölçeklenebilir bir ödeme altyapısı sunar. API key yönetiminden webhook güvenliğine, abonelik sisteminden fraud korumasına kadar her detayı titizlikle ele almak uzun vadede hem operasyonel verimlilik hem de müşteri memnuniyeti açısından büyük fark yaratır. Toserof Tech. olarak e-ticaret entegrasyon projeleriniz için iletişime geçin.