Accept Stripe payments in iOS flows
You can sell Stripe subscriptions from a flow that you build in the Flow & Paywall Builder. The flow shows your Stripe prices, and its buttons open Stripe’s PaymentSheet over the flow. After the payment, Stripe notifies Adapty. Adapty grants the access level to the user and attributes the revenue to the flow, its placement, and its A/B test variation. Use this setup to sell subscriptions to services that users consume outside your app, such as memberships to in-person events, class passes, or recurring deliveries. If you also sell a plan for a real-world service as an App Store product, you can add Stripe to the same flow as another way to pay for it.
The App Store requires in-app purchases for digital content and features (guideline 3.1.1). An in-app payment through Stripe is for physical goods and for services that users consume outside the app (guideline 3.1.3(e)). To send users to a web checkout for digital content, use a web paywall.
How it works
- Your app gets the Stripe prices from your backend. Then it passes them to the flow as custom tags, and presents the flow.
- The user taps a button in the flow. The button triggers a custom action, and your app receives the action ID.
- Your app asks your backend to create a Stripe subscription. Your backend adds the user’s ID and the flow’s variation ID to the subscription’s metadata.
- Your app opens PaymentSheet over the flow, and the user pays the subscription’s first invoice.
- Stripe sends a webhook to Adapty. Adapty grants the access level to the profile with the user’s ID, and attributes the purchase to the flow variation.
- Your app closes the flow and waits until the profile has the access level.
Before you start
Make sure that you have:
- Stripe connected to your Adapty app: Follow Connect Stripe to Adapty, for test mode and for live mode. Keep Profile creation behavior set to Use customer_user_id from metadata (default).
- A Stripe product and price for each plan: Create the products on Stripe with recurring prices, for example monthly or annual.
- An Adapty product for each Stripe price: Add the Stripe product ID and price ID to an Adapty product, and assign the access level that the plan unlocks. The access level stands for the right to the service, such as an active membership, not for digital features in your app. Without the Adapty product, Adapty doesn’t record the purchase.
- The Adapty iOS SDK 4.0.0 or later: Activate the SDK with the key of the Adapty app that you connected to Stripe. Adapty receives Stripe’s webhooks only for that app. Identify users by a customer user ID, and show this flow only to users who are logged in and identified. Adapty uses this ID to find the profile that gets the access level.
- The Stripe iOS SDK with the
StripePaymentSheetmodule in your app. See Accept a payment in the Stripe docs. - A backend that can call the Stripe API with your Stripe secret key, or with a restricted key of your own that can write Customers and Subscriptions. Don’t reuse the restricted key that you generated for Adapty: it’s Adapty’s key, and it doesn’t have the write permissions that your backend needs. Keep the key on your server.
Show Stripe prices in the flow
The flow shows Stripe prices through custom tags. A custom tag is a text value that your app passes to the flow when it loads the flow. Adapty doesn’t format a custom tag value, so pass each price in the form that users see, such as “$29.00”.
- In the Flow & Paywall Builder, create a String variable for each price, for example
stripe_monthly_priceandstripe_annual_price, and select Value comes from outside the app. Set each variable’s Initial value to your current price. Users see the initial value if your app can’t load the prices, so keep the initial values equal to your Stripe prices. - Insert each tag into a text element, such as the label of a plan button.
- In your app, get the prices from your backend before you load the flow.
- Pass the prices in the
tagResolverparameter ofgetFlowConfiguration.
The following function loads the flow with your Stripe prices. It also returns the flow’s variationId, because your backend writes this ID into the Stripe subscription. You present the flow in Open PaymentSheet from the flow.
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 is the client for your backend’s endpoints, from Create the subscription on your backend.
The Adapty presentation types require iOS 16. If your app supports earlier versions, add @available(iOS 16.0, *) to the code in this guide that uses them.
Add buttons that open PaymentSheet
Each button that sells a Stripe plan triggers a custom action. Your app receives the action ID and opens PaymentSheet for that plan.
- In the Flow & Paywall Builder, add a button for each Stripe plan.
- Assign the Custom Action action to each button, and enter an action ID, such as
buy_stripe_monthlyandbuy_stripe_annual. - Publish the flow, and add it to a placement.
Your app maps each action ID to a plan. The flow doesn’t send your app any data with the action, so the action ID must identify the plan.
Add Stripe as another way to pay for App Store products
Use this setup only for plans that are physical goods or services that users consume outside the app (guideline 3.1.3(e)), such as memberships to in-person events. For digital content or features, offer another way to pay through a web paywall.
The flow shows your App Store products as usual, and a link such as “Pay another way” opens PaymentSheet. The App Store purchase buttons keep working without changes.
- Assign the Custom Action action to the link, with an action ID such as
pay_with_stripe. - For each App Store product in the flow, create a Stripe price for the same plan.
- In your app, map each App Store product ID to its Stripe plan.
- Store the product that the user selects. The flow reports each selection to
flowController(_:didSelectProduct:)in UIKit, or to thedidSelectProductclosure of the.flowmodifier in SwiftUI. A flow built in the Flow & Paywall Builder doesn’t report the product that is selected by default, so start with the product that you set as selected in the builder. If the variations of an A/B test select different products, store the default for each variation. - When the app receives
pay_with_stripe, callStripeCheckout.pay(plan:variationId:over:)from Open PaymentSheet from the flow with the Stripe plan of the stored product.
The flow shows the App Store prices of these products, which differ by storefront. PaymentSheet charges the Stripe price. To show users the Stripe price before they tap, pass it as a custom tag and show it in each plan’s card, for example “or $29.00/month by card”. Custom tag values don’t change while the flow is open, so one link can’t show the price of the selected plan.
Create the subscription on your backend
PaymentSheet pays for a Stripe object that your backend creates. In this guide, your backend creates a Stripe subscription, and PaymentSheet pays the subscription’s first invoice. Your backend sets two keys in the subscription’s metadata:
customer_user_id: The customer user ID of the user in Adapty. Adapty grants the access level to the profile with this ID.variation_id: The flow’s variation ID, which your app sends to the backend. Adapty attributes the revenue to this flow variation, its placement, and its A/B test.
Adapty doesn’t record a payment for a PaymentIntent that you create on its own, without a subscription or an invoice. The user pays, but doesn’t get the access level.
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:
import express from 'express';
import Stripe from 'stripe';
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);
With payment_behavior: 'default_incomplete', the subscription waits for the first payment. Stripe activates it when the user pays in PaymentSheet. If the user closes PaymentSheet without paying, Stripe expires the subscription after about 23 hours, and Adapty doesn’t record it. For the full Stripe setup, see Build a subscriptions integration in the Stripe docs.
The code reads the client secret from latest_invoice.confirmation_secret, which needs Stripe API version 2025-03-31.basil or later. The stripe library uses this version from version 18. If you call the Stripe API without the library, set the Stripe-Version header. On an earlier API version, expand latest_invoice.payment_intent and read payment_intent.client_secret instead.
In your app, call the two endpoints. Send your user’s authentication with each request, as your backend requires:
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)
}
}
Open PaymentSheet from the flow
Your app opens PaymentSheet when a button in the flow triggers a custom action, and closes the flow when the payment succeeds:
- Map the custom action ID to a plan. Ignore taps, and the flow’s close button, while your app waits for the backend or shows PaymentSheet. Then one tap creates one subscription.
- Ask your backend for a subscription, and pass the plan and the flow’s
variationId. - Present PaymentSheet over the flow, and handle its result:
- Completed: Close the flow. After it closes, wait for the access level.
- Canceled: Do nothing. The user stays on the flow and can choose another plan.
- Failed: Show the error. The user stays on the flow and can try again.
- Handle the flow’s close and open-URL actions. Your action handler replaces the SDK’s default one, which closes the flow and opens URLs.
- Implement the purchase and restore handlers, and in SwiftUI the error handler. The SDK requires them, even if the flow has no App Store products.
Steps 2 and 3 are the same in UIKit and SwiftUI, so this guide puts them in one class:
import Adapty
import SafariServices
import StripePaymentSheet
import UIKit
@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)
}
}
PaymentSheet returns to your app through the return URL after payment methods that open another app. Register the URL scheme in your app, as described in Set up a return URL in the Stripe docs, and pass the URL to Stripe when your app opens it:
Then present the flow, and pass its actions to StripeCheckout:
If your flow also sells App Store products, handle their purchases in the purchase handlers as described in Handle flow events.
Unlock access after the payment
After the payment, Adapty receives Stripe’s webhook and grants the access level within a few seconds. The SDK refreshes the profile once a minute, so request the profile until the access level is active:
@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
}
Usually the access level is active within a few seconds. If it isn’t active after 60 seconds, verify the deliveries of the Adapty webhook endpoint in Stripe’s webhook settings.
To show a confirmation after the payment, such as a welcome screen, show it from your app when the access level is active. You can also build the screen as a second flow, add it to its own placement, and present it after the first flow closes. Respond to purchase outcomes shows how to set up a second flow for this.
Let users manage the subscription
A Stripe subscription doesn’t appear in the user’s App Store subscriptions in iOS Settings. To let users cancel or change their payment method, add a button to your app, for example on the account screen, that opens the Stripe customer portal. Your backend creates a portal session for the user’s Stripe customer and returns its URL.
When a user cancels, Stripe notifies Adapty, and Adapty updates the access level. For how Adapty treats immediate and end-of-period cancellations, see Cancellations.
Test the integration
Use Stripe’s test mode, connected to your Adapty app:
- Run your app with the Adapty SDK key of the Adapty app that you connected to Stripe.
- Open the flow. The buttons should show the prices that your app passes, not the initial values of the custom tags.
- Tap a Stripe plan button. In PaymentSheet, pay with the Stripe test card
4242 4242 4242 4242, any future expiration date, and any CVC. - Verify that the flow closes and that the profile’s access level becomes active within a few seconds.
- In the Adapty Dashboard, open the Event Feed. The purchase event should have
store:stripe, theflow_idandflow_nameof your flow, aflow_variation_idequal to thevariationIdthat your app sent, and your placement ID indeveloper_id. For a Stripe purchase,variation_idhas the same value asflow_variation_id.
Test-mode purchases have the Sandbox environment. They appear in the Event Feed and on the profile, but not in analytics or in the flow’s metrics, which count only production purchases.
If the purchase doesn’t appear in Adapty, verify that your app uses the SDK key of the Adapty app connected to Stripe, that an Adapty product exists for the Stripe price, and that the subscription’s metadata has customer_user_id. Also see Troubleshooting in the Stripe integration guide.
Limitations
- The flow doesn’t receive the Stripe result: The flow can’t go to another screen after a successful, canceled, or failed Stripe payment. Your app closes the flow and shows what comes next.
- Prices in custom tags are text: The flow shows a custom tag value as your app passes it, and doesn’t calculate other values from it, such as a price per week or a discount. Pass each of these values as its own tag.
- Custom tag values are fixed while the flow is open: To show new prices, load the flow again.