iOS flow'larında Stripe ödemelerini kabul etme
Adapty’nin Flow & Paywall Builder’ında oluşturduğunuz bir flow üzerinden Stripe abonelikleri satabilirsiniz. Flow, Stripe fiyatlarınızı gösterir ve düğmeler, flow’un üzerine Stripe’ın PaymentSheet sayfasını açar. Ödeme sonrasında Stripe, Adapty’yi bilgilendirir. Adapty, kullanıcıya access level tanır ve geliri flow’a, ilgili placement’a ve A/B testi varyantına atar. Bu yapıyı; etkinlik üyelikleri, ders kartları veya düzenli teslimatlar gibi kullanıcıların uygulama dışında yararlandığı hizmetlerin aboneliklerini satmak için kullanabilirsiniz. Gerçek dünya hizmetine ait bir planı App Store ürünü olarak da satıyorsanız, Stripe’ı aynı flow’a alternatif bir ödeme yöntemi olarak ekleyebilirsiniz.
App Store, dijital içerik ve özellikler için uygulama içi satın alma gerektirir (kılavuz 3.1.1). Stripe üzerinden yapılan uygulama içi ödeme, fiziksel ürünler ve kullanıcıların uygulama dışında tükettiği hizmetler içindir (kılavuz 3.1.3(e)). Dijital içerik için kullanıcıları web ödeme sayfasına yönlendirmek istiyorsanız web paywall kullanın.
Nasıl çalışır
- Uygulamanız Stripe fiyatlarını backend’inizden alır. Ardından bunları özel etiketler aracılığıyla flow’a iletir ve flow’u gösterir.
- Kullanıcı flow içindeki bir butona dokunur. Buton bir özel aksiyon tetikler ve uygulamanız aksiyon ID’sini alır.
- Uygulamanız backend’inizden bir Stripe aboneliği oluşturmasını ister. Backend’iniz kullanıcının ID’sini ve flow’un varyasyon ID’sini aboneliğin meta verilerine ekler.
- Uygulamanız flow’un üzerine PaymentSheet açar ve kullanıcı aboneliğin ilk faturasını öder.
- Stripe, Adapty’ye bir webhook gönderir. Adapty, kullanıcının ID’sine sahip profile access level tanır ve satın almayı flow varyasyonuna atar.
- Uygulamanız flow’u kapatır ve profilde access level bulunana kadar bekler.
Başlamadan önce
Aşağıdakilere sahip olduğunuzdan emin olun:
- Stripe, Adapty uygulamanıza bağlı olmalı: Test modu ve canlı mod için Stripe’ı Adapty’e Bağla adımlarını izleyin. Profile creation behavior ayarını Use customer_user_id from metadata (default) olarak bırakın.
- Her plan için bir Stripe ürünü ve fiyatı: Aylık veya yıllık gibi yinelenen fiyatlarla Stripe’ta ürünler oluşturun.
- Her Stripe fiyatı için bir Adapty ürünü: Stripe ürün kimliğini ve fiyat kimliğini bir Adapty ürününe ekleyin ve planın kilidini açacağı access level’ı atayın. Access level, uygulamanızdaki dijital özellikleri değil, aktif bir üyelik gibi hizmete erişim hakkını temsil eder. Adapty ürünü olmadan Adapty satın alımı kaydetmez.
- Adapty iOS SDK 4.0.0 veya üzeri: SDK’yı Stripe’a bağladığınız Adapty uygulamasının anahtarıyla etkinleştirin. Adapty, Stripe webhook’larını yalnızca o uygulama için alır. Kullanıcıları bir customer user ID ile tanımlayın ve bu flow’u yalnızca giriş yapmış ve tanımlanmış kullanıcılara gösterin. Adapty, access level’ı alacak profili bulmak için bu kimliği kullanır.
- Stripe iOS SDK, uygulamanızda
StripePaymentSheetmodülü ile birlikte. Stripe belgelerindeki Ödeme kabul et sayfasına bakın. - Stripe API’sini çağırabilen bir backend, Stripe gizli anahtarınızla ya da Müşteri ve Abonelik yazma iznine sahip kısıtlı bir anahtarla. Adapty için oluşturduğunuz kısıtlı anahtarı yeniden kullanmayın: bu anahtar Adapty’e aittir ve backend’inizin ihtiyaç duyduğu yazma izinlerine sahip değildir. Anahtarı sunucunuzda saklayın.
Flow’da Stripe fiyatlarını gösterme
Flow, Stripe fiyatlarını özel etiketler aracılığıyla gösterir. Özel etiket, uygulamanızın flow’u yüklerken flow’a ilettiği bir metin değeridir. Adapty özel etiket değerini biçimlendirmez; bu nedenle her fiyatı kullanıcıların gördüğü biçimde iletin, örneğin “$29.00”.
- Flow & Paywall Builder’da her fiyat için bir String değişkeni oluşturun, örneğin
stripe_monthly_pricevestripe_annual_price, ve Value comes from outside the app seçeneğini belirleyin. Her değişkenin Initial value alanını mevcut fiyatınıza ayarlayın. Uygulamanız fiyatları yükleyemezse kullanıcılar bu başlangıç değerini görür; bu nedenle başlangıç değerlerini Stripe fiyatlarınızla aynı tutun. - Her etiketi bir metin öğesine ekleyin, örneğin bir plan düğmesinin etiketine.
- Uygulamanızda, flow’u yüklemeden önce fiyatları backend’inizden alın.
- Fiyatları
getFlowConfigurationfonksiyonununtagResolverparametresine aktarın.
Aşağıdaki fonksiyon, Stripe fiyatlarınızla birlikte flow’u yükler. Ayrıca flow’un variationId değerini döndürür; çünkü backend’iniz bu ID’yi Stripe aboneliğine yazar. Flow’u Flow’dan PaymentSheet Açma bölümünde sunarsınız.
struct StripeFlow {
let configuration: AdaptyUI.FlowConfiguration
let variationId: String
}
@MainActor
func loadStripeFlow() async throws -> StripeFlow {
// If the prices fail to load, the flow shows the tags' initial values
let prices = (try? await Backend.fetchPrices()) ?? [:]
let flow = try await Adapty.getFlow(placementId: "YOUR_PLACEMENT_ID")
let configuration = try await AdaptyUI.getFlowConfiguration(
forFlow: flow,
tagResolver: [
"stripe_monthly_price": prices["monthly"],
"stripe_annual_price": prices["annual"],
].compactMapValues { $0 }
)
return StripeFlow(configuration: configuration, variationId: flow.variationId)
}
Backend, Backend’inizde aboneliği oluşturma bölümünden gelen backend uç noktalarınızın istemcisidir.
Adapty sunum türleri iOS 16 gerektirir. Uygulamanız daha eski sürümleri destekliyorsa, bu kılavuzdaki ilgili koda @available(iOS 16.0, *) ekleyin.
PaymentSheet’i açan düğmeler ekleyin
Bir Stripe planı satan her düğme, özel bir eylem tetikler. Uygulamanız eylem ID’sini alır ve o plan için PaymentSheet’i açar.
- Flow & Paywall Builder’da her Stripe planı için bir düğme ekleyin.
- Her düğmeye Custom Action eylemini atayın ve
buy_stripe_monthlyilebuy_stripe_annualgibi bir eylem ID’si girin. - Flow’u yayınlayın ve bir placement’a ekleyin.
Uygulamanız her aksiyon ID’sini bir plana eşler. Flow, aksiyonla birlikte uygulamanıza herhangi bir veri göndermez; bu nedenle aksiyon ID’si planı tanımlamalıdır.
Stripe’ı App Store ürünleri için ek bir ödeme yöntemi olarak ekleyin
Bu kurulumu yalnızca kullanıcıların uygulama dışında tükettiği fiziksel ürün veya hizmetler (kural 3.1.3(e)) için kullanın; örneğin yüz yüze etkinliklere üyelikler. Dijital içerik veya özellikler için ödeme almak üzere bir web paywall kullanın.
Flow, App Store ürünlerinizi olağan şekilde gösterir; “Başka yöntemle öde” gibi bir bağlantıya tıklandığında PaymentSheet açılır. App Store satın alma düğmeleri değişiklik yapılmadan çalışmaya devam eder.
- Bağlantıya Custom Action eylemini atayın ve
pay_with_stripegibi bir eylem kimliği kullanın. - Flow’daki her App Store ürünü için, aynı plan adına karşılık gelen bir Stripe fiyatı oluşturun.
- Uygulamanızda, her App Store ürün kimliğini ilgili Stripe planıyla eşleştirin.
- Kullanıcının seçtiği ürünü saklayın. Flow, her seçimi UIKit’te
flowController(_:didSelectProduct:)fonksiyonuna veya SwiftUI’da.flowmodifier’ınındidSelectProductclosure’ına bildirir. Flow & Paywall Builder’da oluşturulan bir flow, varsayılan olarak seçilen ürünü bildirmez; bu nedenle builder’da seçili olarak ayarladığınız ürünle başlayın. Bir A/B testinin varyantları farklı ürünler seçiyorsa, her varyant için varsayılan ürünü saklayın. - Uygulama
pay_with_stripeeylemini aldığında, saklanan ürünün Stripe planıyla birlikte Flow’dan PaymentSheet’i açma bölümündekiStripeCheckout.pay(plan:variationId:over:)fonksiyonunu çağırın.
Flow, App Store’un vitrine göre farklılık gösteren ürün fiyatlarını gösterir. PaymentSheet ise Stripe fiyatını uygular. Kullanıcılar bir plana dokunmadan önce Stripe fiyatını görmelerini sağlamak için bunu özel bir etiket olarak geçirin ve her planın kartında gösterin; örneğin “veya aylık 29,00 $/kart ile”. Özel etiket değerleri flow açıkken değişmediğinden, seçili planın fiyatını tek bir bağlantıyla göstermek mümkün değildir.
Backend’inizde aboneliği oluşturun
PaymentSheet, backend’inizin oluşturduğu bir Stripe nesnesinin ödemesini yapar. Bu kılavuzda backend’iniz bir Stripe aboneliği oluşturur ve PaymentSheet bu aboneliğin ilk faturasını öder. Backend’iniz aboneliğin metadata alanına iki anahtar ayarlar:
customer_user_id: Adapty’deki kullanıcının customer user ID’si. Adapty, access level’ı bu ID’ye sahip profile verir.variation_id: Uygulamanızın backend’e gönderdiği flow’un variation ID’si. Adapty, geliri bu flow varyantına, onun placement’ına ve A/B testine atfeder.
Adapty, kendi başına oluşturduğunuz — bir abonelik veya fatura olmaksızın — PaymentIntent için ödeme kaydetmez. Kullanıcı ödeme yapar, ancak access level almaz.
Create two endpoints. The first returns the formatted prices for the custom tags. The second creates the subscription and returns the values that PaymentSheet needs. Before it creates a subscription, the second endpoint verifies that the user has no active one, so a user can’t pay twice for the same plan.
This example uses Node.js with ES modules ("type": "module" in package.json), Express, and the stripe library version 18 or later. Replace db with your own database:
const app = express();
app.use(express.json());
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const prices = {
monthly: 'price_...', // your Stripe price IDs
annual: 'price_...',
};
// Prices for the custom tags, such as { "monthly": "$29.00", "annual": "$249.00" }.
// You can cache the response.
app.get('/prices', async (req, res) => {
try {
const result = {};
for (const [plan, priceId] of Object.entries(prices)) {
const price = await stripe.prices.retrieve(priceId);
// Assumes a currency with two decimal places. Format for your users' locale.
result[plan] = new Intl.NumberFormat('en-US', {
style: 'currency',
currency: price.currency.toUpperCase(),
}).format(price.unit_amount / 100);
}
res.json(result);
} catch (error) {
console.error(error);
res.status(500).json({ error: 'Could not load prices' });
}
});
app.post('/subscriptions', async (req, res) => {
// req.user comes from your authentication middleware. Its ID is the same
// customer user ID that your app passes to Adapty.identify().
const customerUserId = req.user.id;
// variationId affects only attribution, so the backend doesn't need to trust it
const { plan, variationId } = req.body;
if (!prices[plan]) {
return res.status(400).json({ error: 'Unknown plan' });
}
try {
// One Stripe customer per user, stored in your database
let customerId = await db.getStripeCustomerId(customerUserId);
if (!customerId) {
const customer = await stripe.customers.create({ metadata: { customer_user_id: customerUserId } });
customerId = customer.id;
await db.saveStripeCustomerId(customerUserId, customerId);
}
// Don't sell a second subscription to a user who already has one
for (const status of ['active', 'trialing', 'past_due']) {
const existing = await stripe.subscriptions.list({ customer: customerId, status, limit: 1 });
if (existing.data.length > 0) {
return res.status(409).json({ error: 'You already have a subscription' });
}
}
const subscription = await stripe.subscriptions.create({
customer: customerId,
items: [{ price: prices[plan] }],
payment_behavior: 'default_incomplete',
payment_settings: { save_default_payment_method: 'on_subscription' },
metadata: {
customer_user_id: customerUserId,
variation_id: variationId,
},
expand: ['latest_invoice.confirmation_secret'],
});
res.json({
subscriptionId: subscription.id,
clientSecret: subscription.latest_invoice.confirmation_secret.client_secret,
publishableKey: process.env.STRIPE_PUBLISHABLE_KEY,
});
} catch (error) {
console.error(error);
res.status(500).json({ error: 'Could not create the subscription' });
}
});
app.listen(process.env.PORT ?? 3000);
payment_behavior: 'default_incomplete' ile abonelik, ilk ödemeyi bekler. Kullanıcı PaymentSheet üzerinden ödeme yaptığında Stripe aboneliği etkinleştirir. Kullanıcı ödeme yapmadan PaymentSheet’i kapatırsa, Stripe aboneliği yaklaşık 23 saat sonra sona erdirir ve Adapty bunu kaydetmez. Stripe kurulumunun tamamı için Stripe belgelerindeki Build a subscriptions integration sayfasına bakın.
Kod, latest_invoice.confirmation_secret alanından client secret’ı okur; bunun için 2025-03-31.basil veya daha yeni bir Stripe API sürümü gerekir. stripe kütüphanesi bu sürümü 18. sürümden itibaren kullanır. Stripe API’yi kütüphane kullanmadan çağırıyorsanız Stripe-Version başlığını ayarlayın. Daha eski bir API sürümünde latest_invoice.payment_intent alanını genişleterek payment_intent.client_secret değerini okuyun.
Uygulamanızda iki endpoint’i çağırın. Backend’inizin gerektirdiği şekilde her istekte kullanıcınızın kimlik doğrulama bilgilerini gönderin:
enum Backend {
static let baseURL = URL(string: "https://YOUR_BACKEND")!
struct Subscription: Decodable {
let subscriptionId: String
let clientSecret: String
let publishableKey: String
}
struct BackendError: LocalizedError, Decodable {
let error: String
var errorDescription: String? { error }
}
struct HTTPError: LocalizedError {
let statusCode: Int
var errorDescription: String? { "The server returned HTTP \(statusCode)." }
}
static func fetchPrices() async throws -> [String: String] {
let request = URLRequest(url: baseURL.appendingPathComponent("prices"))
return try await send(request)
}
static func createSubscription(plan: String, variationId: String) async throws -> Subscription {
var request = URLRequest(url: baseURL.appendingPathComponent("subscriptions"))
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
// add your authentication header
request.httpBody = try JSONEncoder().encode([
"plan": plan,
"variationId": variationId,
])
return try await send(request)
}
private static func send<T: Decodable>(_ request: URLRequest) async throws -> T {
let (data, response) = try await URLSession.shared.data(for: request)
let statusCode = (response as? HTTPURLResponse)?.statusCode ?? 0
guard statusCode == 200 else {
// Use the backend's message when the response has one
throw (try? JSONDecoder().decode(BackendError.self, from: data)) ?? HTTPError(statusCode: statusCode)
}
return try JSONDecoder().decode(T.self, from: data)
}
}
Flow içindeki PaymentSheet’i açma
Uygulamanız, flow içindeki bir düğme özel bir eylem tetiklediğinde PaymentSheet’i açar ve ödeme başarılı olduğunda flow’u kapatır:
-
Özel aksiyon ID’sini bir plana eşleyin. Uygulamanız backend’i beklerken veya PaymentSheet gösterirken dokunuşları ve flow’un kapat düğmesini yoksayın. Bu sayede tek bir dokunuş tek bir abonelik oluşturur.
-
Backend’inizden bir abonelik isteyin ve planı ile flow’un
variationIddeğerini gönderin. -
PaymentSheet’i flow’un üzerinde gösterin ve sonucunu işleyin:
- Tamamlandı: Flow’u kapatın. Kapandıktan sonra access level’ı bekleyin.
- İptal Edildi: Hiçbir şey yapmayın. Kullanıcı flow’da kalır ve başka bir plan seçebilir.
- Başarısız: Hatayı gösterin. Kullanıcı flow’da kalır ve tekrar deneyebilir.
-
Flow’un kapat ve URL aç aksiyonlarını işleyin. Aksiyon handler’ınız, flow’u kapatan ve URL’leri açan SDK’nın varsayılan handler’ının yerini alır.
-
Satın alma ve geri yükleme handler’larını, SwiftUI’da ise hata handler’ını uygulayın. SDK bunları zorunlu kılar; flow’da App Store ürünü olmasa bile.
-
ve 3. adımlar UIKit ve SwiftUI’da aynı olduğundan, bu kılavuz bunları tek bir sınıfta ele alır:
@MainActor
final class StripeCheckout {
// Custom action IDs from the flow, mapped to your backend's plan keys
static let plans = [
"buy_stripe_monthly": "monthly",
"buy_stripe_annual": "annual",
]
private(set) var isPaying = false
/// Opens PaymentSheet for a plan over the flow. Returns `true` when the user paid.
func pay(plan: String, variationId: String, over presenter: UIViewController) async -> Bool {
guard !isPaying else { return false }
isPaying = true
defer { isPaying = false }
do {
let subscription = try await Backend.createSubscription(
plan: plan,
variationId: variationId
)
// The flow may have closed, or opened a link, while the backend responded
guard presenter.viewIfLoaded?.window != nil, presenter.presentedViewController == nil else {
return false
}
STPAPIClient.shared.publishableKey = subscription.publishableKey
var configuration = PaymentSheet.Configuration()
configuration.merchantDisplayName = "YOUR_BUSINESS_NAME"
// For payment methods that redirect to another app, such as bank apps
configuration.returnURL = "your-app://stripe-redirect"
let paymentSheet = PaymentSheet(
paymentIntentClientSecret: subscription.clientSecret,
configuration: configuration
)
let result = await withCheckedContinuation { continuation in
paymentSheet.present(from: presenter) { continuation.resume(returning: $0) }
}
switch result {
case .completed:
return true
case .canceled:
return false // the user stays on the flow
case let .failed(error):
showError(error, over: presenter)
return false
}
} catch {
showError(error, over: presenter)
return false
}
}
/// Opens a URL from the flow in the browser that the flow's button specifies.
func open(_ url: URL, presentation: AdaptyWebPresentation, over presenter: UIViewController) {
let isWebURL = url.scheme == "https" || url.scheme == "http"
if presentation == .inAppBrowser, isWebURL {
presenter.present(SFSafariViewController(url: url), animated: true)
} else {
UIApplication.shared.open(url)
}
}
private func showError(_ error: Error, over presenter: UIViewController) {
let alert = UIAlertController(
title: "The payment didn't go through",
message: error.localizedDescription,
preferredStyle: .alert
)
alert.addAction(UIAlertAction(title: "OK", style: .default))
presenter.present(alert, animated: true)
}
}
Ödeme yöntemlerinin başka bir uygulama açmasının ardından PaymentSheet, dönüş URL’si aracılığıyla uygulamanıza geri döner. URL şemasını uygulamanıza kaydedin; bunun için Stripe belgelerindeki Dönüş URL’si ayarlama bölümüne bakın ve uygulama bu URL’yi açtığında Stripe’a iletin:
Ardından flow’u sunun ve aksiyonlarını StripeCheckout’a aktarın:
Flow’unuz aynı zamanda App Store ürünleri de satıyorsa, satın alma işlemlerini Flow olaylarını yönetme bölümünde açıklandığı şekilde satın alma handler’larında yönetin.
Ödemeden sonra erişimin kilidini açma
Ödeme sonrasında Adapty, Stripe’ın webhook’unu alır ve birkaç saniye içinde access level’ı tanımlar. SDK, profili dakikada bir yeniler; bu nedenle access level etkin olana kadar profili sorgulamaya devam edin:
@MainActor
func waitForAccess() async -> Bool {
for _ in 1...20 {
if let profile = try? await Adapty.getProfile(),
profile.accessLevels["YOUR_ACCESS_LEVEL"]?.isActive == true {
return true
}
try? await Task.sleep(for: .seconds(3))
}
return false
}
Access level genellikle birkaç saniye içinde aktif olur. 60 saniye sonra hâlâ aktif değilse, Stripe’ın webhook ayarları üzerinden Adapty webhook endpoint’ine yapılan teslimatları kontrol edin.
Ödeme sonrası bir onay ekranı (örneğin hoş geldiniz ekranı) göstermek istiyorsanız, bunu access level aktif olduğunda uygulamanızdan gösterin. Ekranı ayrı bir flow olarak oluşturup kendi placement’ına ekleyebilir ve ilk flow kapandıktan sonra gösterebilirsiniz. Satın alma sonuçlarına yanıt verme sayfasında bunun nasıl yapılacağı anlatılmaktadır.
Kullanıcıların aboneliği yönetmesine izin verin
Bir Stripe aboneliği, iOS Ayarları’ndaki kullanıcının App Store abonelikleri arasında görünmez. Kullanıcıların aboneliği iptal etmesine veya ödeme yöntemini değiştirmesine izin vermek için uygulamanıza, örneğin hesap ekranına, Stripe müşteri portalını açan bir düğme ekleyin. Backend’iniz, kullanıcının Stripe müşterisi için bir portal oturumu oluşturur ve URL’sini döndürür.
Bir kullanıcı iptal ettiğinde, Stripe Adapty’yi bilgilendirir ve Adapty access level’ı günceller. Adapty’nin anlık ve dönem sonu iptalleri nasıl ele aldığını öğrenmek için İptaller bölümüne bakın.
Entegrasyonu test edin
Adapty uygulamanıza bağlı Stripe’ın test modunu kullanın:
- Uygulamanızı, Stripe’a bağladığınız Adapty uygulamasının Adapty SDK anahtarıyla çalıştırın.
- Flow’u açın. Düğmeler, özel etiketlerin başlangıç değerlerini değil, uygulamanızın ilettiği fiyatları göstermelidir.
- Bir Stripe plan düğmesine dokunun. PaymentSheet’te Stripe test kartı
4242 4242 4242 4242, gelecekte herhangi bir son kullanma tarihi ve herhangi bir CVC ile ödeme yapın. - Flow’un kapandığını ve profilin access level’ının birkaç saniye içinde aktif hale geldiğini doğrulayın.
- Adapty Kontrol Paneli’nde Event Feed sayfasını açın. Satın alma etkinliğinde
store:stripe, flow’unuzunflow_idveflow_namedeğerleri, uygulamanızın gönderdiğivariationId’ye eşit birflow_variation_idvedeveloper_idalanında placement ID’niz yer almalıdır. Stripe satın alımlarındavariation_id,flow_variation_idile aynı değere sahiptir.
Test modu satın almaları Sandbox ortamına sahiptir. Bunlar Event Feed’de ve profilde görünür, ancak yalnızca üretim satın almalarını sayan analizlerde veya flow’un metriklerinde görünmez.
Satın alma Adapty’de görünmüyorsa, uygulamanızın Stripe’a bağlı Adapty uygulamasının SDK anahtarını kullandığını, Stripe fiyatı için bir Adapty ürününün mevcut olduğunu ve aboneliğin meta verilerinde customer_user_id bulunduğunu doğrulayın. Ayrıca Stripe entegrasyon kılavuzundaki Sorun Giderme bölümüne bakın.
Sınırlamalar
- Flow, Stripe sonucunu almaz: Flow, başarılı, iptal edilmiş veya başarısız bir Stripe ödemesinin ardından başka bir ekrana geçemez. Uygulamanız flow’u kapatır ve sıradaki içeriği gösterir.
- Özel etiketlerdeki fiyatlar metindir: Flow, özel etiket değerini uygulamanızın ilettiği şekliyle gösterir; haftaya düşen fiyat veya indirim gibi başka değerleri bu değerden hesaplamaz. Bu değerlerin her birini ayrı bir etiket olarak iletin.
- Özel etiket değerleri flow açıkken sabit kalır: Yeni fiyatları göstermek için flow’u yeniden yükleyin.