Начальная интеграция со Stripe

Adapty поддерживает web2app флоу подписок, отслеживая веб-платежи и подписки, совершённые через Stripe.

Эта интеграция охватывает покупки, совершённые через веб (Stripe Checkout, хостинговые платёжные страницы, Payment Links или кастомные веб-флоу), и синхронизирует их с доступом в мобильном приложении и аналитикой.

Она пригодится в следующих случаях:

• Автоматически предоставлять доступ к платным функциям пользователям, которые купили подписку на сайте, а потом установили приложение и вошли в свой аккаунт
• Собирать всю аналитику по подпискам в едином дашборде Adapty (включая когорты, прогнозы и остальной инструментарий аналитики)

Несмотря на то что веб-покупки становятся всё популярнее, Apple App Store разрешает систему, отличную от встроенных покупок для цифровых товаров, только в США. Не продвигайте веб-подписки внутри приложения для пользователей из других стран — иначе ваше приложение может быть отклонено или заблокировано.

Ниже описаны шаги по настройке интеграции со Stripe.

1. Подключите Stripe к Adapty

Интеграция в основном базируется на том, что Adapty получает данные о подписках от Stripe через вебхук. Поэтому нужно связать аккаунт Adapty с аккаунтом Stripe: предоставить API-ключи и настроить URL вебхука Adapty в Stripe. Чтобы автоматизировать настройку вебхука, установите приложение Adapty в Stripe:

0. Определите, в каком режиме вы подключаете Stripe — тестовом или боевом. Если сначала вы настраиваете в тестовом режиме, шаги ниже нужно будет повторить и для боевого.

1. Перейдите в Stripe App Marketplace и установите приложение Adapty. Обратите внимание, что режим песочницы не поддерживает установку приложений — это можно сделать только в Production- или Test-режиме.

2. Выдайте приложению необходимые разрешения — это позволит Adapty получать доступ к данным и истории подписок. Затем нажмите Continue to app settings, чтобы продолжить.

В нижней части всплывающего окна с разрешениями можно выбрать, устанавливать приложение в Live- или Test-режиме.

3. Во всплывающем окне сгенерируйте новый ограниченный ключ. Для этого потребуется подтвердить личность через email, Touch ID или ключ безопасности. После генерации ключ больше не будет доступен для просмотра, поэтому сразу сохраните его в менеджере паролей или защищённом хранилище.

4. Скопируйте сгенерированный ключ из всплывающего окна и перейдите в App Settings → Stripe в Adapty. Вставьте ключ в поле Stripe App Restricted API Key соответствующего режима. Обратите внимание, что для Test- и Live-режима нужны разные ключи.

Готово! Теперь создайте продукты в Stripe и добавьте их в Adapty.

Устаревший способ установки

1. Перейдите в Developers → API Keys в Stripe:

2. Нажмите кнопку Reveal live (test) key button рядом с заголовком Secret key, скопируйте ключ и перейдите в App Settings → Stripe в Adapty. Вставьте ключ туда:

3. Затем скопируйте URL вебхука из нижней части той же страницы в Adapty. Перейдите в Developers → Webhooks в Stripe и нажмите кнопку Add endpoint:

4. Вставьте URL вебхука из Adapty в поле Endpoint URL. Выберите Latest API version в поле Version вебхука. Затем выберите следующие события:

• 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», затем нажмите «Reveal» под разделом «Signing secret». Этот ключ используется для декодирования данных вебхука на стороне Adapty — скопируйте его после раскрытия:

6. Наконец, вставьте этот ключ в App Settings → Stripe в Adapty в поле «Stripe Webhook Secret»:

2. Создайте продукты в Stripe

Перейдите в Product catalog в Stripe и создайте продукты, которые хотите продавать, а также их тарифные планы. Обратите внимание, что Stripe позволяет создавать несколько тарифных планов для одного продукта — это удобно для настройки предложений без необходимости создавать дополнительные продукты.

3. Добавьте продукты Stripe в Adapty

Мы относимся к Stripe так же, как к App Store и Google Play: это просто ещё один стор, где вы продаёте цифровые продукты. Настройка аналогична: просто добавьте продукты Stripe (а именно их product_id и price_id) в раздел Products в Adapty:

ID продуктов в Stripe выглядят как prod_..., а ID цен — как price_.... Их легко найти для каждого продукта в Product Catalog в Stripe, открыв любой продукт:

После добавления всех необходимых продуктов следующий шаг — сообщить Stripe, какой пользователь совершает покупку, чтобы Adapty мог её зафиксировать.

4. Обогащение веб-покупок идентификатором пользователя

Adapty использует вебхуки от Stripe как единственный источник информации для предоставления и обновления уровней доступа пользователей. Однако для корректной работы интеграции вам необходимо передавать дополнительные данные со своей стороны при работе со Stripe.

Чтобы уровни доступа были согласованы на разных платформах (веб или мобильные), необходимо использовать единый идентификатор пользователя, по которому Adapty сможет опознать пользователя из вебхуков. Это может быть email, номер телефона или любой другой ID из вашей системы авторизации. В Adapty это значение называется customer_user_id.

Adapty считывает ID пользователя из одного источника — того, который выбран в Profile creation behavior в App Settings → Stripe. Это не цепочка резервных вариантов: если выбранный источник пуст для конкретной транзакции, покупка остаётся анонимной, даже если ID присутствует в другом месте данных Stripe. См. Profile creation behavior — там описаны все доступные источники.

Выберите вариант, соответствующий тому, как вы создаёте покупки в Stripe.

Сессии оформления заказа и подписки, созданные через Stripe API

Оставьте параметр Profile creation behavior в значении Use customer_user_id from metadata (default). Затем найдите в своём коде место, где инициализируется платёж через Stripe, и добавьте этот идентификатор пользователя в объект metadata объекта Stripe Subscription (sub_...) или Checkout Session (ses_...) под ключом customer_user_id:

{'customer_user_id': "YOUR_USER_ID"}

Это единственное, что нужно добавить в ваш код. После этого Adapty будет обрабатывать все вебхуки от Stripe, извлекать metadata и правильно связывать подписки с вашими пользователями.

Payment Links (без кода)

Если вы продаёте через Stripe Payment Links и у вас нет бэкенда для установки metadata, передайте ID пользователя в параметре запроса client_reference_id в ссылке:

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

Stripe сохраняет это значение в Checkout Session и передаёт его в Adapty в событии checkout.session.completed. Это работает как для подписок, так и для разовых покупок.

5. Предоставьте доступ пользователям на мобильном устройстве

Чтобы мобильные пользователи, пришедшие с веба, могли получить доступ к платным функциям, просто вызовите Adapty.activate() или Adapty.identify() с тем же customer_user_id, который вы передали на предыдущем шаге (см. Идентификация пользователей iOS, Android, React Native, Flutter и Unity для получения подробной информации).

6. Протестируйте интеграцию

Убедитесь, что вы выполнили все шаги выше как для Sandbox, так и для Production. Транзакции, совершённые в Test-режиме Stripe, будут считаться Sandbox-транзакциями в Adapty.

Поведение при создании профиля

Adapty должна привязать покупку к профилю пользователя, чтобы он был доступен на мобильном устройстве — поэтому по умолчанию профили создаются при получении вебхуков от Stripe. Вы можете выбрать, что использовать в качестве идентификатора пользователя в Adapty:

1. По умолчанию и рекомендуется: используйте customer_user_id из метаданных — customer_user_id, который вы указали в метаданных на шаге 4 выше
2. Используйте email из объекта Customer в Stripe (см. документацию Stripe)
3. Используйте client_reference_id из объекта Session в Stripe (см. документацию Stripe) — этот вариант подходит для Payment Links

Вы можете настроить, какой ID использовать, в App Settings → Stripe. Adapty использует только выбранный вами источник для каждой транзакции Stripe в приложении — резервный вариант с другими источниками не используется.

Есть и четвёртый вариант — вообще не создавать профили, но это не рекомендуется из-за перечисленных выше ограничений в Analytics.

Текущие ограничения

Повышение, понижение тарифа и пропорциональный расчёт

Изменения подписки — например, переход на более дорогой или дешёвый тариф — могут приводить к пропорциональным начислениям. Adapty не учитывает их при расчёте дохода. Лучше всего отключить эти опции вручную через дашборд Stripe. Также можно отключить их, установив значение атрибута proration_behaviour в none через Stripe API.

Отмена подписок

В Stripe есть два варианта отмены подписки:

1. Немедленная отмена: подписка отменяется сразу с пропорциональным расчётом или без него
2. Отмена в конце периода: подписка отменяется по истечении текущего расчётного периода (аналогично встроенным подпискам в сторах).

Adapty поддерживает оба варианта, однако при расчёте дохода в случае немедленной отмены пропорциональный расчёт не учитывается.

Проблемы с оплатой и льготный период

Когда у пользователя возникает проблема с оплатой, Adapty генерирует событие billing issue и доступ отзывается. Льготный период Stripe пока не поддерживается — это будет реализовано в будущих версиях.

Возвраты

Adapty отслеживает только полные возвраты. Частичные возвраты и пропорциональные расчёты в настоящее время не поддерживаются.

Уникальность идентификаторов транзакций

Adapty сопоставляет профили и транзакции с помощью store_transaction_id и store_original_transaction_id. Они должны быть уникальными в рамках тестовой и Production-среды.

Почему это важно

Если один и тот же ID транзакции существует в обеих средах, Adapty считает их одной транзакцией, что приводит к:

• Переносу тестовых уровней доступа и ID продуктов на Production-покупки
• Некорректным ID продуктов и средам в ответах API
• Нарушению привязки профилей и событий подписок

Как обеспечить уникальность

ID счетов (invoice) в Stripe могут совпадать в Test- и Live-средах. Чтобы избежать конфликтов между средами, выберите один из подходов:

Вариант 1: Нумерация счетов на уровне аккаунта с префиксами для каждой среды

Настройте префиксы отдельно для каждой среды:

1. В дашборде Stripe переключитесь в Test mode.
2. Перейдите в Settings → Billing → Invoices.
3. Установите Invoice numbering в значение Sequentially across your account.
4. Задайте Invoice prefix как TEST- (или другой префикс, уникальный для тестовой среды).
5. Переключитесь в Live mode и повторите шаги 2–4, используя LIVE- (или другой префикс, уникальный для боевой среды) в качестве префикса.

Вариант 2: Нумерация счетов на уровне пользователя

Установите Invoice numbering в Stripe settings -> Billing -> Invoices в значение Sequentially for each customer (customer-level).

Даже при такой настройке, если вы удалите счёт, Stripe может повторно использовать этот ID для новых счетов того же пользователя. Поэтому по возможности избегайте удаления счетов.

Разовые покупки через Stripe Checkout или Payment Links

Adapty фиксирует разовые покупки (не подписки), совершённые через Stripe Checkout (mode=payment) или Payment Links, на основе события checkout.session.completed. Убедитесь, что это событие включено на вашем вебхук-эндпойнте Adapty в Stripe — эндпойнты, созданные до того, как Adapty добавила поддержку Payment Links, его не содержат. Как проверить — см. шаг 4.

Adapty берёт продукт из первой позиции сессии, поэтому если сессия включает несколько продуктов, будет записан только первый.

Возвраты средств за такие покупки пока не применяются: Stripe отправляет charge.refunded, но Adapty не отзывает доступ для разовой покупки, оформленной через Checkout или Payment Link. Возвраты по подпискам и разовым покупкам, выставленным через счёт Stripe, работают в обычном режиме.

Получите больше от данных Stripe

После интеграции со Stripe Adapty сразу готова предоставлять аналитику. Чтобы максимально использовать данные Stripe, вы можете настроить дополнительные интеграции Adapty для пересылки событий Stripe — и собрать всю аналитику подписок в едином дашборде Adapty.

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

Интеграции, которые можно использовать для пересылки и анализа событий Stripe:

• Amplitude
• Webhook
• Firebase
• Mixpanel
• Posthog

Поддерживаемые события Stripe

Adapty поддерживает следующие события Stripe:

• 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