Stripe ile başlangıç entegrasyonu

Adapty, Stripe üzerinden yapılan web ödemelerini ve abonelikleri takip ederek web2app abonelik flow’larını destekler.

Bu entegrasyon, web üzerinden başlatılan satın almaları (Stripe Checkout, hosted payment sayfaları, Payment Links veya özel web flow’ları) kapsar ve bunları mobil uygulama erişimi ve analitiğiyle senkronize eder.

Aşağıdaki senaryolarda kullanışlıdır:

• Web’den satın alma yapan ancak daha sonra uygulamayı yükleyip hesabına giriş yapan kullanıcılara ücretli özelliklere otomatik olarak erişim sağlamak
• Tüm abonelik analizlerini tek bir Adapty Kontrol Paneli’nde toplamak (kohortlar, tahminler ve diğer analitik araçlarımız dahil)

Web satın almaları uygulamalar için giderek daha popüler hale gelse de Apple App Store, dijital ürünler için yalnızca ABD’de uygulama içi satın almalardan farklı bir sisteme izin vermektedir. Web aboneliklerinizi diğer ülkelerdeki kullanıcılara uygulama içinde tanıtmadığınızdan emin olun. Aksi takdirde uygulamanız reddedilebilir veya yasaklanabilir.

Aşağıdaki adımlar, Stripe entegrasyonunun nasıl yapılandırılacağını açıklamaktadır.

1. Stripe’ı Adapty’ye bağlama

Bu entegrasyon, esas itibarıyla Adapty’nin webhook aracılığıyla Stripe’tan abonelik verilerini çekmesine dayanır. Bu nedenle, API Anahtarlarını sağlayarak ve Stripe’ta Adapty’nin webhook URL’sini kullanarak Adapty hesabınızı Stripe hesabınıza bağlamanız gerekir. Webhook yapılandırmanızı otomatikleştirmek için Stripe’a Adapty uygulamasını yükleyin:

0. Stripe’ı test modunda mı yoksa canlı modda mı bağlayacağınızı belirleyin. Başlangıçta bunu test modunda yapıyorsanız, aşağıdaki adımları canlı mod için de tekrarlamanız gerekecektir.

1. Stripe App Marketplace’e gidin ve Adapty uygulamasını yükleyin. Sandbox modunun uygulama yüklemeyi desteklemediğini unutmayın. Bunu yalnızca production veya test modunda yapabilirsiniz.

2. Uygulamaya gerekli izinleri verin. Bu, Adapty’nin abonelik verilerine ve geçmişine erişmesini sağlayacaktır. Ardından devam etmek için Continue to app settings düğmesine tıklayın.

İzin açılır penceresinin alt kısmında, uygulamayı canlı modda mı yoksa test modunda mı yükleyeceğinizi seçebilirsiniz.

3. Açılır pencerede yeni bir kısıtlı anahtar oluşturun. E-postanız, Touch ID veya güvenlik anahtarınızı kullanarak kimliğinizi doğrulamanız gerekecektir. Anahtarı oluşturduktan sonra tekrar göremezsiniz; bu nedenle bir parola yöneticisinde veya güvenli bir depoda saklayın.

4. Açılan pencereden oluşturulan anahtarı kopyalayın ve Adapty’nin App Settings → Stripe sayfasına gidin. Anahtarı, modunuza göre Stripe App Restricted API Key bölümüne yapıştırın. Test ve canlı modlar için farklı anahtarlar oluşturmanız gerektiğini unutmayın. Stripe’ın Sandbox ortamındaki değil, Test mode ortamındaki anahtarı kullanın — Adapty, Stripe Sandbox’larını desteklememektedir.

Harika! Şimdi Stripe’ta ürünlerinizi oluşturun ve Adapty’ye ekleyin.

Deprecated installation flow

1. Stripe’ta Developers → API Keys sayfasına gidin:

2. Secret key başlığının yanındaki Reveal live (test) key button düğmesine tıklayın, ardından anahtarı kopyalayıp Adapty’nin App Settings → Stripe sayfasına gidin. Anahtarı buraya yapıştırın:

3. Ardından, Adapty’deki aynı sayfanın alt kısmından Webhook URL’sini kopyalayın. Stripe’ta Developers → Webhooks bölümüne gidin ve Add endpoint butonuna tıklayın:

4. Adapty’deki webhook URL’sini Endpoint URL alanına yapıştırın. Ardından webhook Version alanında Latest API version seçeneğini belirleyin. Ardından aşağıdaki olayları seçin:

   • charge.refunded
   • checkout.session.completed
   • customer.subscription.created
   • customer.subscription.deleted
   • customer.subscription.paused
   • customer.subscription.resumed
   • customer.subscription.updated
   • invoice.created
   • invoice.updated
   • payment_intent.succeeded

5. “Add endpoint” düğmesine basın ve ardından “Signing secret” altındaki “Reveal” düğmesine basın. Bu, webhook verilerini Adapty tarafında çözmek için kullanılan anahtardır; ortaya çıkardıktan sonra kopyalayın:

6. Son olarak, bu anahtarı Adapty’nin App Settings → Stripe bölümündeki “Stripe Webhook Secret” alanına yapıştırın:

2. Stripe’ta ürün oluşturma

Stripe’ın Product catalog bölümüne gidin ve satmak istediğiniz ürünleri ve fiyatlandırma planlarını oluşturun. Stripe’ın ürün başına birden fazla fiyatlandırma planına izin verdiğini unutmayın; bu, ek ürünler oluşturmaya gerek kalmadan teklifinizi özelleştirmek için kullanışlıdır.

3. Stripe ürünlerini Adapty’ye ekleme

Stripe’a App Store ve Google Play ile aynı şekilde davranıyoruz: dijital ürünlerinizi sattığınız başka bir mağazadır. Yapılandırması da benzer şekildedir: Stripe ürünlerini (product_id ve price_id değerleriyle birlikte) Adapty’nin Ürünler bölümüne ekleyin:

Stripe’taki ürün kimlikleri prod_..., fiyat kimlikleri ise price_... şeklinde görünür. Bunları Stripe’ın Product Catalog bölümünde herhangi bir ürünü açtığınızda kolayca bulabilirsiniz:

Gerekli tüm ürünleri ekledikten sonra, bir sonraki adım Stripe’a satın almayı kimin yaptığını bildirmektir; böylece Adapty tarafından işlenebilir.

4. Web’de yapılan satın almaları kullanıcı kimliğinizle zenginleştirin

Adapty, kullanıcıların access level’larını sağlamak ve güncellemek için Stripe’tan gelen webhook’lara tek bilgi kaynağı olarak güvenir. Ancak bu entegrasyonun düzgün çalışması için Stripe ile çalışırken kendi tarafınızdan ek bilgi sağlamanız gerekir.

Platformlar (web veya mobil) arasında access level’ların tutarlı olması için, Adapty’nin webhook’lardan tanıyabileceği tek bir kullanıcı kimliğine ihtiyaç vardır. Bu, kullandığınız yetkilendirme sistemindeki kullanıcının e-postası, telefon numarası veya herhangi bir başka kimlik olabilir. Adapty bu değeri customer_user_id olarak adlandırır.

Adapty, kullanıcı kimliğini tek bir kaynaktan okur — App Settings → Stripe sayfasındaki Profile creation behavior ayarından seçilen kaynak. Bu bir yedek zinciri değildir: seçilen kaynak belirli bir işlem için boşsa, kimlik Stripe verisinde başka bir yerde mevcut olsa bile satın alma anonim kalır. Mevcut tüm kaynaklar için Profil oluşturma davranışı bölümüne bakın.

Stripe’ta satın alma işlemlerini nasıl oluşturduğunuzla eşleşen seçeneği belirleyin.

Stripe API aracılığıyla oluşturulan Checkout Session’lar ve Abonelikler

Profile creation behavior ayarını Use customer_user_id from metadata (default) olarak bırakın. Ardından, Stripe üzerinden ödemeyi başlatan kod bölümünüzü bulun ve bu kullanıcı ID’sini Stripe Subscription (sub_...) veya Checkout Session nesnesinin (ses_...) metadata objesine customer_user_id olarak şu şekilde ekleyin:

{'customer_user_id': "YOUR_USER_ID"}

Bu tek basit ekleme, kodunuzda yapmanız gereken tek şeydir. Bundan sonra Adapty, Stripe’tan aldığı tüm webhook’ları ayrıştıracak, bu metadata’yı çıkaracak ve abonelikleri müşterilerinizle doğru şekilde ilişkilendirecektir.

Ödeme Bağlantıları (kod olmadan)

Stripe Payment Links üzerinden satış yapıyorsanız ve metadata ayarlamak için bir backend’iniz yoksa, kullanıcı kimliğini bağlantının client_reference_id sorgu parametresine ekleyin:

https://buy.stripe.com/your_link?client_reference_id=YOUR_USER_ID

Stripe bu değeri Checkout Session’da saklar ve checkout.session.completed etkinliği aracılığıyla Adapty’ye iletir. Hem abonelikler hem de tek seferlik satın almalar için çalışır.

5. Mobil kullanıcılara erişim sağlama

Web’den gelen mobil kullanıcıların ücretli özelliklere erişebilmesini sağlamak için, bir önceki adımda sağladığınız customer_user_id ile Adapty.activate() veya Adapty.identify() fonksiyonunu çağırmanız yeterlidir (daha fazlası için Kullanıcıları tanımlama iOS, Android, React Native, Flutter ve Unity bölümlerine bakın).

6. Entegrasyonunuzu test etme

Yukarıdaki adımları hem Sandbox hem de Production için tamamladığınızdan emin olun. Stripe’ın Test modundan yaptığınız işlemler Adapty’de Sandbox olarak değerlendirilecektir.

Profil oluşturma davranışı

Adapty, bir satın almanın mobilde kullanılabilir olması için onu bir müşteri profiline bağlamak zorundadır; bu nedenle varsayılan olarak Stripe’tan webhook aldığında profil oluşturur. Adapty’de müşteri kullanıcı kimliği olarak ne kullanmak istediğinizi seçebilirsiniz:

1. Varsayılan ve önerilen: Metadata’daki customer_user_id’yi kullanın — yukarıdaki 4. adımda metadata’ya eklediğiniz customer_user_id
2. Stripe’ın Customer nesnesindeki e-postayı kullanın (bkz. Stripe dokümantasyonu)
3. Stripe’ın Session nesnesindeki client_reference_id’yi kullanın (bkz. Stripe dokümantasyonu) — Payment Links ile kullanılacak seçenek

App Settings → Stripe bölümünde hangi ID’yi kullanmak istediğinizi yapılandırabilirsiniz. Adapty, uygulamadaki her Stripe işlemi için yalnızca burada seçtiğiniz kaynağı kullanır; diğer kaynaklara geri dönmez.

Profil oluşturmamak için dördüncü bir seçeneğiniz de var; ancak Analytics’teki yukarıda belirtilen kısıtlamalar nedeniyle bu önerilmez.

Mevcut kısıtlamalar

Yükseltme, düşürme ve proration

Yükseltme veya düşürme gibi abonelik değişiklikleri, orantılı ücretlere (proration) yol açabilir. Adapty bu ücretleri gelir hesaplamalarında dikkate almaz. Bu seçenekleri Stripe kontrol paneli üzerinden manuel olarak devre dışı bırakmanız en iyisi olacaktır. Ayrıca Stripe API üzerinden proration_behaviour öznitelik değerini none olarak ayarlayarak da devre dışı bırakabilirsiniz.

İptaller

Stripe’ın iki abonelik iptal seçeneği vardır:

1. Anlık iptal: Abonelik, herhangi bir proration seçeneğiyle ya da seçeneği olmaksızın hemen iptal edilir
2. Dönem sonunda iptal: Abonelik, mevcut fatura döneminin sonunda iptal edilir (uygulama mağazalarındaki uygulama içi aboneliklere benzer şekilde).

Adapty her iki seçeneği de destekler; ancak anlık iptal için gelir hesaplaması proration seçeneğini göz ardı eder.

Fatura Sorunları ve Ek Süre

Müşteri ödemeyle ilgili bir sorunla karşılaştığında, Adapty bir fatura sorunu olayı oluşturur ve erişim iptal edilir. Şu an için Stripe’ın ek süresini (Grace Period) desteklemiyoruz; bu, gelecek sürümlerde eklenecektir.

Geri ödemeler

Adapty yalnızca tam geri ödemeleri takip eder. Proration veya kısmi geri ödemeler şu anda desteklenmemektedir.

İşlem kimliği benzersizliği

Adapty, profilleri ve işlemleri store_transaction_id ve store_original_transaction_id kullanarak eşleştirir. Bunların Test ve Production ortamları arasında benzersiz olması gerekir.

Bu neden önemlidir

Aynı işlem kimliği her iki ortamda da mevcutsa Adapty bunları tek bir işlem olarak değerlendirir ve şu sorunlara yol açar:

• Production satın almalarının Test access level’larını ve ürün kimliklerini devralması
• API yanıtlarında yanlış ürün kimlikleri ve ortamlar
• Profil bağlantısının ve abonelik olaylarının bozulması

Benzersizlik nasıl sağlanır

Stripe fatura kimlikleri, Test ve Live ortamları arasında örtüşebilir. Ortamlar arası çakışmaları önlemek için aşağıdaki yaklaşımlardan birini seçin:

1. Seçenek: Ortam önekleri ile hesap düzeyinde numaralandırma

Her ortam için ayrı ayrı önekler yapılandırın:

1. Stripe Dashboard’da Test moduna geçin.
2. Settings → Billing → Invoices bölümüne gidin.
3. Invoice numbering değerini Sequentially across your account olarak ayarlayın.
4. Invoice prefix değerini TEST- (veya test ortamına özgü başka bir önek) olarak ayarlayın.
5. Live moda geçin ve LIVE- (veya canlı ortama özgü başka bir önek) önekini kullanarak 2-4. adımları tekrarlayın.

2. Seçenek: Müşteri düzeyinde numaralandırma

Stripe settings -> Billing -> Invoices sekmesindeki Invoice numbering değerini Sequentially for each customer (customer-level) olarak ayarlayın.

Yukarıdaki yapılandırmayla bile bir faturayı silerseniz Stripe aynı müşterinin yeni faturaları için bu kimliği yeniden kullanabilir. Mümkün olduğunca fatura silmekten kaçınmak en iyisidir.

Stripe Checkout veya Payment Links aracılığıyla tek seferlik satın almalar

Adapty, Stripe Checkout (mode=payment) veya Payment Links aracılığıyla yapılan tek seferlik (abonelik dışı) satın almaları checkout.session.completed olayından kaydeder. Bu olayın Stripe’taki Adapty webhook uç noktanızda etkinleştirildiğinden emin olun — Adapty Payment Links desteği eklemeden önce oluşturulan uç noktalar bunu içermez. Nasıl kontrol edeceğinizi öğrenmek için 4. adıma bakın.

Adapty, ürünü oturumun ilk satır öğesinden alır; bu nedenle birden fazla ürün satan bir oturum yalnızca ilk ürünü kaydeder.

Stripe bu satın alımlar için iadeleri henüz uygulamıyor: Stripe charge.refunded olayını iletir, ancak Adapty, Checkout veya Ödeme Bağlantısı üzerinden yapılan bir tek seferlik satın alma için erişimi iptal etmez. Stripe faturası üzerinden faturalandırılan abonelik ve tek seferlik satın alma iadeleri her zamanki gibi çalışır.

Birden fazla Adapty uygulamasına bağlı tek bir Stripe hesabı

Bir olayı alan webhook endpoint’i, hangi Adapty uygulamasının onu işleyeceğini belirler; her Adapty uygulamasının kendine ait bir endpoint URL’si vardır ve kısıtlı API anahtarı bu kararı vermez. Stripe’a kaydettiğiniz her endpoint, tüm olayları alır ve her uygulama kendi kopyasını bağımsız olarak işler. Bir uygulama, kendisine eklenmemiş ürünlere ait olayları yok sayar; dolayısıyla farklı ürün setlerine sahip uygulamalar sorunsuz biçimde bir arada çalışabilir. Ancak aynı Stripe ürünü ve fiyatı birden fazla uygulamaya eklenirse, bu uygulamaların her biri söz konusu işlemi kaydeder.

Stripe verilerinizden daha fazla yararlanın

Stripe ile entegrasyon sağladıktan sonra Adapty hemen içgörüler sunmaya hazır olur. Stripe verilerinizden en iyi şekilde yararlanmak için, tüm abonelik analitiğinizi tek bir Adapty Kontrol Paneli’nde toplayarak Stripe olaylarını iletmek amacıyla ek Adapty entegrasyonları kurabilirsiniz.

{
  'customer_user_id': "YOUR_USER_ID",
  'variation_id': "YOUR_VARIATION_ID"
}

Stripe olaylarınızı iletmek ve analiz etmek için kullanabileceğiniz entegrasyonlar:

• Amplitude
• Webhook
• Firebase
• Mixpanel
• Posthog

Desteklenen Stripe etkinlikleri

Adapty aşağıdaki Stripe etkinliklerini destekler:

• charge.refunded
• checkout.session.completed
• customer.subscription.created
• customer.subscription.deleted
• customer.subscription.paused
• customer.subscription.resumed
• customer.subscription.updated
• invoice.created
• invoice.updated
• payment_intent.succeeded