Переход с BillingClient SDK на Pay SDK: полный гайд для разработчиков

Pay SDK устроен иначе, и часть логики теперь выносится из кода в конфигурацию.

1. Подключение зависимости

Название SDK меняется (pay вместо billingclient), а список зависимостей становится короче — лишние параметры больше не нужны. По сути, теперь это более компактная и чистая интеграция.

2. Инициализация

В BillingClient SDK consoleApplicationId передавался в коде при создании клиента. В Pay SDK он указывается в AndroidManifest.xml. Туда же переносится и deeplink-схема. Это упрощает старт SDK: меньше ручной инициализации в коде, больше — декларативной настройки.

3. Работа с deeplink

Если раньше deeplink настраивался через фабрику клиента, то теперь схема прописывается в AndroidManifest, а для обработки используется отдельный IntentInteractor.

4. Проверка доступности платежей

Метод проверки меняется, а вместе с ним — типы ответов. Теперь возвращается PurchaseAvailabilityResult, а в случае ошибки приходит Throwable, а не RuStoreException. То есть обработка становится более универсальной.

5. Получение продуктов

В Pay SDK список продуктов можно запрашивать без авторизации пользователя. Плюс увеличен лимит: до 1000 товаров за один запрос вместо 100. Это упрощает загрузку каталога и снижает количество запросов.

Что изменилось в модели продукта

Структура Product обновлена: часть полей переименована или убрана, а для подписок появилось отдельное поле subscriptionInfo с детальной информацией о периодах — бесплатный (trial), стартовый (promo), основной (main), льготный (grace) и заморозка (hold). Если у вас есть кастомная логика отображения подписок, её нужно будет адаптировать под новую модель.

Всё это даёт более точную модель подписки и позволяет более гибко отображать информацию в интерфейсе.

6. Получение покупок

Метод получения покупок меняется, и появляется удобная фильтрация: по типу товара (разовые / подписки) и по статусу покупки.

Главное архитектурное изменение — теперь есть общий интерфейс Purchase и две реализации: ProductPurchase для разовых покупок, SubscriptionPurchase для подписок.

• ProductPurchase для разовых покупок,
• SubscriptionPurchase для подписок.

Это разделение делает модель чище, но потребует обновить обработку разных типов покупок в коде.

Статусы покупок

Статусная модель Pay SDK переработана:

• статусы стали более детализированными,
• логика различается для разовых покупок и подписок,
• для подписок появились отдельные состояния (например, ACTIVE, PAUSED, EXPIRED).

Если в проекте есть собственная логика маппинга статусов, её может потребоваться обновить для подписок, где появились дополнительные состояния. Логика разовых покупок не меняется.

Запуск покупки

Теперь используется универсальный метод purchase(), в котором можно выбрать тип оплаты:

• одностадийную (ONE_STEP),
• двухстадийную (TWO_STEP, с холдированием средств на карте пользователя)

Раньше стадийность была жёстко привязана к типу товара. Теперь разработчик может управлять этим параметром самостоятельно. Для гарантированной двухстадийной оплаты используется отдельный метод purchaseTwoStep().

Важно:

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

Обработка ошибок

В Pay SDK:

• успешная покупка возвращается единым результатом,
• отмена и ошибки обрабатываются через OnFailureListener,
• добавлены отдельные типы исключений для отмены пользователем

Это немного меняет паттерн обработки результата, особенно если раньше логика была завязана на Success / Failure / Cancelled.

Серверная валидация

В BillingClient SDK для серверной проверки использовался purchaseToken. В Pay SDK для разовых покупок используется invoiceId, а для подписок — purchaseId. Если у вас настроена серверная проверка, этот блок нужно обновить отдельно.

Подтверждение и отмена двухстадийной покупки

Методы подтверждения и отмены изменились:

• подтверждение — confirmTwoStepPurchase(),
• отмена — cancelTwoStepPurchase().

Это актуально только для двухстадийной оплаты.

С 1 августа 2026 года метод getPurchases() в BillingClient SDK перестанет возвращать список покупок и подписок. Это означает, что прежний сценарий работы через BillingClient SDK станет недоступен.

Разовые покупки, которые пользователи уже совершили через BillingClient SDK, сохраняются и остаются доступными после перехода на Pay SDK при вызове методов getPurchases()/getPurchase(). Данные по таким покупкам также можно получать через Public API, используя этот метод.

Подписки требуют отдельного внимания при миграции на Pay SDK. У них другой жизненный цикл, поэтому переход обычно включает не только технические изменения, но и работу с текущей базой подписчиков.

Если на 1 августа 2026 года у пользователя будет активная подписка, она продолжит действовать до конца уже оплаченного периода. После его завершения автоматическое продление через BillingClient SDK не произойдёт, и подписка перейдёт в неактивный статус.

Данные по действующим подпискам можно получать через Public API (метод 1, метод 2) до конца декабря 2026 года.

1. Снять «срез» действующих подписок через Public API

Соберите у себя актуальную картину: кто подписан, до какой даты оплачен период, какой сейчас статус у подписки. Это база, от которой дальше строится переход.

2. Интегрировать как можно скорее Pay SDK для покупки новых подписок

Важно, чтобы Pay SDK был не просто подключён, а протестирован на реальных сценариях: покупка, обработка ошибок, аналитика. Чем раньше новые пользователи начнут оформлять подписки через Pay SDK, тем меньше пользователей потребуется переводить при отключении старого решения.

3. Подготовить сценарий «мягкого переезда» подписок

Автоматической миграции подписок «как есть» не будет, поэтому задача — сделать так, чтобы пользователь без стресса оформил подписку заново уже на Pay SDK:

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

4. Запустить реактивацию подписок

Предложите пользователям остановить продление текущей подписки: для этого до 1 августа 2026 г. направьте их в RuStore в раздел управления подписками. Когда текущий период закончится и подписка станет неактивной, важно сразу предложить пользователю понятное действие: «Продлить доступ» или «Возобновить подписку» с одним чётким CTA.

Также можно заранее настроить новую подписку с бесплатным периодом и предложить пользователю оформить её до окончания текущей. Это позволит продолжить пользоваться сервисом без перерыва и необходимости возвращаться к покупке после завершения действующей подписки.

Чтобы переход не стал для пользователей неожиданностью, заранее предупредите их об изменениях. Достаточно короткого сообщения в продукте, письме или push-уведомления с пояснением:

• когда это повлияет на продление,
• что доступ сохранится до конца оплаченного периода,
• что нужно будет сделать дальше (переоформить подписку).

5. Обновить версию приложения у всех пользователей до актуальной версии с Pay SDK

Рекомендуем заранее позаботиться о том, чтобы пользователи перешли на актуальную версию приложения с поддержкой Pay SDK. Это поможет избежать ситуации, когда после 1 августа часть аудитории останется на старой версии и столкнётся с невозможностью совершить покупку. Для ускорения перехода можно использовать механизмы принудительного обновления (force update), например через RuStore SDK Update.

Если у вас остались вопросы или нужна помощь с переходом, напишите нам: support@rustore.ru.