Принятие платежей Stripe в iOS-флоу
Вы можете продавать подписки Stripe через флоу, созданное в Flow & Paywall Builder. Флоу отображает ваши цены Stripe, а его кнопки открывают PaymentSheet Stripe поверх флоу. После оплаты Stripe уведомляет Adapty. Adapty предоставляет пользователю уровень доступа и атрибутирует выручку флоу, его плейсменту и варианту A/B-теста. Используйте эту схему для продажи подписок на услуги, которыми пользователи пользуются за пределами вашего приложения: членства на офлайн-мероприятия, абонементы на занятия или регулярные доставки. Если вы также продаёте план для реального сервиса как продукт App Store, вы можете добавить Stripe в то же флоу как ещё один способ оплаты.
App Store требует использования встроенных покупок для цифрового контента и функций (правило 3.1.1). Оплата через Stripe предназначена для физических товаров и услуг, которые пользователи потребляют за пределами приложения (правило 3.1.3(e)). Чтобы отправить пользователей на веб-оформление заказа для цифрового контента, используйте веб-пейвол.
Как это работает
- Ваше приложение получает цены Stripe от вашего бэкенда, передаёт их во флоу как пользовательские теги и показывает флоу.
- Пользователь нажимает кнопку во флоу. Кнопка запускает кастомное действие, и приложение получает его ID.
- Приложение просит бэкенд создать подписку Stripe. Бэкенд добавляет ID пользователя и ID вариации флоу в метаданные подписки.
- Приложение открывает PaymentSheet поверх флоу, и пользователь оплачивает первый счёт подписки.
- Stripe отправляет вебхук в Adapty. Adapty предоставляет уровень доступа профилю с ID пользователя и атрибутирует покупку вариации флоу.
- Приложение закрывает флоу и ждёт, пока профиль не получит уровень доступа.
Прежде чем начать
Убедитесь, что у вас есть:
- Stripe подключён к вашему приложению Adapty: Следуйте инструкции Подключение Stripe к Adapty — для тестового режима и для боевого. Оставьте Profile creation behavior в значении Use customer_user_id from metadata (default).
- Продукт и цена в Stripe для каждого плана: Создайте продукты в Stripe с повторяющимися ценами — например, ежемесячными или годовыми.
- Продукт Adapty для каждой цены Stripe: Добавьте Stripe product ID и price ID в продукт Adapty и назначьте уровень доступа, который открывает этот план. Уровень доступа означает право на пользование сервисом — например, активное членство, — а не цифровые возможности внутри приложения. Без продукта Adapty покупка не будет зафиксирована.
- Adapty iOS SDK 4.0.0 или выше: Инициализируйте SDK с ключом приложения Adapty, которое вы подключили к Stripe. Adapty получает вебхуки Stripe только для этого приложения. Идентифицируйте пользователей через customer user ID и показывайте этот флоу только авторизованным и идентифицированным пользователям. Adapty использует этот ID, чтобы найти профиль, которому присваивается уровень доступа.
- Stripe iOS SDK с модулем
StripePaymentSheetв вашем приложении. См. раздел Accept a payment в документации Stripe. - Бэкенд с доступом к Stripe API — с вашим Stripe секретным ключом или ограниченным ключом, у которого есть права на запись Customers и Subscriptions. Не используйте ограниченный ключ, который вы создали для Adapty: это ключ Adapty, и у него нет прав на запись, необходимых вашему бэкенду. Храните ключ на сервере.
Отображение цен Stripe во флоу
Флоу отображает цены Stripe с помощью пользовательских тегов. Пользовательский тег — это текстовое значение, которое ваше приложение передаёт во флоу при его загрузке. Adapty не форматирует значение пользовательского тега, поэтому передавайте каждую цену в том виде, в каком её увидит пользователь, например «$29.00».
- В Flow & Paywall Builder создайте переменную типа String для каждой цены, например
stripe_monthly_priceиstripe_annual_price, и выберите Value comes from outside the app. Укажите Initial value для каждой переменной — ваши текущие цены. Если приложение не сможет загрузить цены, пользователи увидят это значение, поэтому оно должно совпадать с вашими ценами в Stripe. - Вставьте каждый тег в текстовый элемент, например в подпись кнопки тарифного плана.
- В приложении получите цены с бэкенда до загрузки флоу.
- Передайте цены в параметре
tagResolverфункцииgetFlowConfiguration.
Следующая функция загружает флоу с вашими ценами Stripe. Она также возвращает variationId флоу, потому что ваш бэкенд записывает этот ID в подписку Stripe. Флоу отображается в разделе Открыть PaymentSheet из флоу.
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 — это клиент для эндпоинтов вашего бэкенда, из раздела Создание подписки на вашем бэкенде.
Типы представлений Adapty требуют iOS 16. Если ваше приложение поддерживает более ранние версии, добавьте @available(iOS 16.0, *) к коду в этом руководстве, который их использует.
Добавьте кнопки, открывающие PaymentSheet
Каждая кнопка, продающая план Stripe, запускает пользовательское действие. Ваше приложение получает ID действия и открывает PaymentSheet для этого плана.
- В Flow & Paywall Builder добавьте кнопку для каждого плана Stripe.
- Назначьте каждой кнопке действие Custom Action и укажите ID действия, например
buy_stripe_monthlyиbuy_stripe_annual. - Опубликуйте флоу и добавьте его в плейсмент.
Ваше приложение сопоставляет каждый ID действия с планом. Флоу не передаёт приложению никаких данных вместе с действием, поэтому ID действия должен однозначно определять план.
Добавьте Stripe как дополнительный способ оплаты продуктов App Store
Используйте эту настройку только для планов, связанных с физическими товарами или услугами, которые пользователи потребляют за пределами приложения (рекомендация 3.1.3(e)), например для членства в очных мероприятиях. Для цифрового контента или функций предлагайте другой способ оплаты через веб-пейвол.
Флоу показывает ваши продукты App Store как обычно, а ссылка вроде «Оплатить другим способом» открывает PaymentSheet. Кнопки покупки через App Store продолжают работать без изменений.
- Назначьте ссылке действие Custom Action с идентификатором, например
pay_with_stripe. - Для каждого продукта App Store во флоу создайте Stripe-цену для того же плана.
- В приложении сопоставьте каждый идентификатор продукта App Store с соответствующим планом Stripe.
- Сохраните продукт, который выбирает пользователь. Флоу сообщает о каждом выборе в
flowController(_:didSelectProduct:)в UIKit или в замыканиеdidSelectProductмодификатора.flowв SwiftUI. Флоу, собранный во Flow & Paywall Builder, по умолчанию не сообщает о выбранном продукте, поэтому начните с продукта, заданного как выбранный в билдере. Если варианты A/B-теста выбирают разные продукты, сохраните дефолтный продукт для каждого варианта. - Когда приложение получает
pay_with_stripe, вызовитеStripeCheckout.pay(plan:variationId:over:)из раздела Открытие PaymentSheet из флоу, передав план Stripe для сохранённого продукта.
Флоу показывает цены App Store для этих продуктов, которые различаются в зависимости от сторфронта. PaymentSheet списывает цену Stripe. Чтобы пользователи видели цену Stripe до того, как нажмут кнопку, передайте её в виде пользовательского тега и отобразите её в карточке каждого плана, например «или 29,00 $/месяц картой». Значения пользовательских тегов не меняются, пока флоу открыт, поэтому одна ссылка не может показывать цену выбранного плана.
Создайте подписку на бэкенде
PaymentSheet оплачивает объект Stripe, который создаёт ваш бэкенд. В этом гайде бэкенд создаёт подписку Stripe, а PaymentSheet оплачивает первый счёт этой подписки. Бэкенд задаёт два ключа в метаданных подписки:
customer_user_id: ID пользователя в Adapty. Adapty предоставляет уровень доступа профилю с этим ID.variation_id: ID вариации флоу, который ваше приложение отправляет на бэкенд. Adapty относит выручку к этой вариации флоу, её плейсменту и её A/B-тесту.
Adapty не фиксирует платёж для PaymentIntent, созданного отдельно — без подписки или инвойса. Пользователь платит, но уровень доступа не получает.
Создайте два эндпоинта. Первый возвращает отформатированные цены для пользовательских тегов. Второй создаёт подписку и возвращает значения, необходимые для PaymentSheet. Перед созданием подписки второй эндпоинт проверяет, нет ли у пользователя активной подписки, — чтобы исключить двойную оплату одного и того же тарифа.
В этом примере используется Node.js с ES-модулями ("type": "module" в package.json), Express и библиотека stripe версии 18 и выше. Замените db на свою базу данных:
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' подписка ожидает первого платежа. Stripe активирует её, когда пользователь оплачивает через PaymentSheet. Если пользователь закрывает PaymentSheet, не заплатив, Stripe аннулирует подписку примерно через 23 часа, и Adapty её не фиксирует. Полная инструкция по настройке Stripe — в документации Stripe: Build a subscriptions integration.
Код считывает клиентский секрет из latest_invoice.confirmation_secret — для этого нужна версия Stripe API 2025-03-31.basil или новее. Библиотека stripe использует эту версию начиная с версии 18. Если вы обращаетесь к Stripe API напрямую без библиотеки, укажите заголовок Stripe-Version. При использовании более ранней версии API разверните latest_invoice.payment_intent и читайте payment_intent.client_secret.
В приложении вызовите два эндпоинта. Передавайте данные аутентификации пользователя с каждым запросом, как того требует ваш бэкенд:
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)
}
}
Открытие PaymentSheet из флоу
Приложение открывает PaymentSheet, когда кнопка во флоу запускает кастомное действие, и закрывает флоу после успешной оплаты:
- Сопоставьте ID кастомного действия с планом. Игнорируйте нажатия, пока приложение ожидает ответа бэкенда или показывает PaymentSheet, а также игнорируйте кнопку закрытия флоу. Так одно нажатие создаёт одну подписку.
- Запросите у бэкенда подписку и передайте план и
variationIdфлоу. - Покажите PaymentSheet поверх флоу и обработайте результат:
- Completed: Закройте флоу. После закрытия дождитесь уровня доступа.
- Canceled: Ничего не делайте. Пользователь остаётся во флоу и может выбрать другой план.
- Failed: Покажите ошибку. Пользователь остаётся во флоу и может попробовать снова.
- Обработайте действия закрытия флоу и открытия URL. Ваш обработчик действий заменяет стандартный обработчик SDK, который закрывает флоу и открывает URL.
- Реализуйте обработчики покупки и восстановления, а в SwiftUI — обработчик ошибок. SDK требует их, даже если во флоу нет продуктов App Store.
Шаги 2 и 3 одинаковы для UIKit и SwiftUI, поэтому в этом гайде они объединены в один класс:
@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 возвращается в ваше приложение через return URL после методов оплаты, открывающих другое приложение. Зарегистрируйте URL scheme в приложении, как описано в Set up a return URL в документации Stripe, и передайте URL в Stripe при открытии приложения:
Затем представьте флоу и передайте его действия в StripeCheckout:
Если ваш флоу также продаёт продукты App Store, обрабатывайте их покупки в обработчиках покупок, как описано в Обработка событий флоу.
Открываем доступ после оплаты
После оплаты Adapty получает вебхук от Stripe и предоставляет уровень доступа в течение нескольких секунд. SDK обновляет профиль раз в минуту, поэтому запрашивайте профиль до тех пор, пока уровень доступа не станет активным:
@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
}
Обычно уровень доступа активируется в течение нескольких секунд. Если он не активен спустя 60 секунд, проверьте доставку вебхуков в настройках вебхуков Stripe.
Чтобы показать подтверждение после оплаты (например, экран приветствия), отображайте его в приложении, когда уровень доступа станет активным. Также можно создать этот экран как второй флоу, добавить его в отдельный плейсмент и показывать после закрытия первого флоу. В статье Реагирование на результаты покупки описано, как настроить второй флоу для этого.
Дайте пользователям управлять подпиской
Подписка Stripe не отображается в подписках App Store в настройках iOS. Чтобы пользователи могли отменить подписку или изменить способ оплаты, добавьте в приложение кнопку — например, на экране аккаунта — которая открывает портал для клиентов Stripe. Ваш бэкенд создаёт портальную сессию для Stripe-клиента пользователя и возвращает её URL.
Когда пользователь отменяет подписку, Stripe уведомляет Adapty, и Adapty обновляет уровень доступа. О том, как Adapty обрабатывает немедленную отмену и отмену по истечении периода, см. в разделе Отмены.
Протестируйте интеграцию
Используйте тестовый режим Stripe, подключённый к вашему приложению в Adapty:
- Запустите приложение с SDK-ключом Adapty того приложения, которое вы подключили к Stripe.
- Откройте флоу. На кнопках должны отображаться цены, которые передаёт ваше приложение, а не начальные значения пользовательских тегов.
- Нажмите на кнопку плана Stripe. В PaymentSheet оплатите с помощью тестовой карты Stripe
4242 4242 4242 4242, любой будущей даты истечения срока действия и любого CVC. - Убедитесь, что флоу закрылся и уровень доступа профиля стал активным в течение нескольких секунд.
- В дашборде Adapty откройте Event Feed. В событии покупки должны быть:
store:stripe,flow_idиflow_nameвашего флоу,flow_variation_id, равныйvariationId, который отправило ваше приложение, и идентификатор вашего плейсмента вdeveloper_id. Для покупки через Stripe значениеvariation_idсовпадает сflow_variation_id.
Тестовые покупки имеют среду Sandbox. Они отображаются в ленте событий и в профиле, но не в аналитике и не в метриках флоу — там учитываются только производственные покупки.
Если покупка не появляется в Adapty, убедитесь, что приложение использует SDK-ключ Adapty, подключённого к Stripe, что для цены Stripe существует продукт Adapty и что метаданные подписки содержат customer_user_id. Также см. раздел Устранение неполадок в руководстве по интеграции Stripe.
Ограничения
- Флоу не получает результат Stripe: Флоу не может перейти на другой экран после успешной, отменённой или неудачной оплаты через Stripe. Ваше приложение закрывает флоу и показывает то, что идёт следующим.
- Цены в кастомных тегах — это текст: Флоу отображает значение кастомного тега именно таким, каким его передаёт приложение, и не вычисляет на его основе другие значения — например, цену за неделю или размер скидки. Передавайте каждое такое значение отдельным тегом.
- Значения кастомных тегов фиксируются при открытии флоу: Чтобы показать новые цены, загрузите флоу заново.