Stripe Entegrasyonu

Stripe, jekcms'in Türk Lirası dışındaki para birimleri için varsayılan ödeme çözümü. Dolar, Euro, Sterlin ve 130+ para birimini kabul ediyor, Apple Pay / Google Pay'i kutudan çıkar çıkmaz destekliyor, Stripe'ın faaliyet gösterdiği her ülkede çalışan şık bir barındırılmış checkout sayfası sunuyor.

Ne zaman lazım olur? Sitenizde lisans satıyorsanız, dijital ürün ya da abonelik satıyorsanız, kısacası Türk Lirası dışında para almak gerekiyorsa Stripe'a ihtiyacınız var. TRY ödemeleri için ayrıca iyzico kurmak gerekir — jekcms sepet para birimine göre ikisi arasında otomatik seçim yapar.

API anahtarlarınızı nereden alacaksınız?

1. dashboard.stripe.com adresinden giriş yapın ya da hesap açın
2. İlk defa açıyorsanız iş profilini doldurmanız lazım — test modunda başlamak için şart değil ama canlıya geçmek için zorunlu
3. Developers → API keys sayfasını açın. İki çift anahtar göreceksiniz:

- Test modu: pk_test_... ve sk_test_... - Live modu: pk_live_... ve sk_live_... (bunlar yalnızca iş profiliniz onaylandıktan sonra görünür)

İki anahtarı da kopyalayın. pk_ ile başlayan publishable key açık şekilde kullanılabilir; sk_ ile başlayan secret key ise kesinlikle Git'e commit etmemeniz gereken şifreniz.

Anahtarları jekcms'e tanıtmak

1. Admin → Settings → Payment Settings
2. Stripe bölümünü bulun
3. Yapıştırın:

- Publishable key → pk_test_... - Secret key → sk_test_...

1. Başlarken Test mode anahtarını ON konumunda bırakın
2. Kaydedin

Anahtarlarınız veritabanında AES-256 ile şifrelenmiş saklanır, düz metin olarak durmaz.

Test mode ne işe yarar?

Test mode açıkken jekcms her Stripe API çağrısında test anahtarlarınızı kullanır. Müşteriler normal checkout sayfası görür ama gerçek para hareket etmez — Stripe'ın test kartlarıyla (örn. 4242 4242 4242 4242) başarılı ödeme, reddedilen ödeme, 3D Secure zorlaması gibi senaryoları oynatabilirsiniz.

Test mode'u kapattığınızda live anahtarlara geçer. Kapatmadan önce live anahtarlar kayıtlı mı mutlaka kontrol edin — boş live anahtar = bozuk checkout.

Webhook kurulumu

Stripe bazı olayları (ödeme tamam, iade geldi, chargeback açıldı) sizin sunucunuza sonradan gelen bir haberle bildirir. jekcms'in bunu dinleyen hazır bir uç noktası var:

https://yourdomain.com/api/payment/stripe-webhook.php

Stripe dashboard'da:

1. Developers → Webhooks → Add endpoint
2. Endpoint URL: yukarıdaki adresi yapıştırın
3. Events to send altında şunları seçin:

- checkout.session.completed - charge.refunded - charge.dispute.created - payment_intent.payment_failed

1. Add endpoint
2. Oluşturulan uç noktanın detay sayfasında Signing secret'ı bulun (whsec_... ile başlar), kopyalayın

Kopyaladığınız secret'ı Admin → Settings → Payment Settings → Stripe webhook secret alanına yapıştırıp kaydedin.

Hangi olay ne yapar?

| Stripe olayı | jekcms'in yaptığı | |---|---| | checkout.session.completed | Siparişi "paid" işaretler, lisans çıkarır ya da satın alımı karşılar, müşteriye e-posta gönderir | | charge.refunded | Siparişi "refunded" yapar; lisans tabanlı ürünse lisansı iptal eder | | charge.dispute.created | Siparişi itirazlı işaretler, çözüm gelene kadar hesabı kilitler | | payment_intent.payment_failed | Denemeyi başarısız işaretler; isterseniz müşteriye yeniden deneme e-postası gönderir |

İmza doğrulama

Stripe her webhook isteğinde Stripe-Signature başlığı yollar. api/payment/stripe-webhook.php, Stripe'ın kendi kütüphanesiyle bu imzayı sizin kayıtlı webhook secret'ınıza karşı doğrular. Doğrulamadan geçemeyen istekler 400 ile geri çevrilir ve asla işlem yapılmaz — yani dışarıdan biri "checkout tamamlandı" taklidi gönderip size bedava lisans üretemez.

Hangi akışlar destekleniyor?

Lisans satışı (en yaygın kullanım)

Ana giriş noktası customer/checkout.php. Bir ziyaretçi "Buy STD license" butonuna tıkladığında şu sırayla olur:

1. customer/checkout.php secret key'le API çağrısı yapıp Stripe Checkout Session yaratır
2. Ziyaretçi Stripe'ın barındırılan checkout sayfasına yönlendirilir
3. Ödeme başarılıysa Stripe customer/checkout-success.php'e geri döner
4. Aynı anda Stripe webhook'unuza checkout.session.completed olayını gönderir — lisansı asıl çıkaran kısım burası. URL yönlendirmesine güvenmiyoruz çünkü o URL taklit edilebilir
5. Müşteri lisans anahtarını e-posta ile alır, hesap dashboard'unda da görür

Başka ürünler

Dijital ürün ya da abonelik satıyorsanız aynı checkout.session.completed olayı tetiklenir; sipariş tipi karşılama mantığını belirler. Detay için orders API referansı sayfasına bakın.

Canlıya geçiş

Test ortamında her şey yolundayken canlıya geçmeden önce şu kontrol listesini geçin:

1. Stripe'ta iş profili tamamlandı — doğrulanmış iş adresi, vergi ID'si, ödemeler için banka hesabı girildi mi?
2. jekcms'te live anahtarlar var — pk_live_... ve sk_live_... ayrı alanlara yapıştırıldı mı? (Test ve live anahtarlar aynı formda yan yana bulunur)
3. Production webhook oluşturuldu — Stripe dashboard'da ayrı bir webhook kaydı açın. Test ve live webhook'lar birbirinden bağımsız çalışır; test secret'ı live modda tanınmaz
4. Production webhook secret yapıştırıldı — live whsec_...'i jekcms'e ekleyin
5. Test mode OFF — jekcms'teki anahtarı kapatıp kaydedin
6. Gerçek bir satın alma deneyin — küçük bir tutarla (1 dolarlık test lisansı) uçtan uca test yapın

Gerçek bir ödeme girdiğinde ve lisans kendiliğinden e-postaya düştüğünde artık canlısınız.

Sorun giderme

Webhook 400 dönüyor. İmza doğrulaması geçmemiş demektir. Genelde sebep: jekcms'teki webhook secret Stripe'takiyle eşleşmiyor ya da test ortamının secret'ı live ortamda kullanılıyor (veya tam tersi).

Müşteri ödedi ama lisans gelmedi. Admin → Orders → Logs'u açın. Sipariş pending'de takıldıysa webhook hiç ulaşmamıştır — Stripe dashboard → Webhooks → uç noktanız → Events sekmesinde başarısız teslimleri görürsünüz.

Stripe log'unda "No such customer". Test'ten live'a geçiş yaptınız ama bir yerdeki eski veri hâlâ test modunun Stripe ID'lerine referans veriyor. Genelde abonelik akışlarında görülür; tek seferlik satın alımlar bu sorunla karşılaşmaz.