Как перейти на Pay SDK

В принципах функционирования Pay SDK есть отличия от billingClient SDK.

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

Список зависимостей

У Pay SDK сократился список зависимостей.

Подключение в проект

При подключения зависимости учитывайте отличие в названии SDK (pay вместо billingclient):

• BillingClient SDK:

dependencies {
  implementation(platform("ru.rustore.sdk:bom:2025.02.01"))
  implementation("ru.rustore.sdk:billingclient")
}

• Pay SDK:

dependencies {
    implementation(platform("ru.rustore.sdk:bom:2025.08.01"))
    implementation("ru.rustore.sdk:pay")
}

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

Изменился способ указания consoleApplicationId при инициализации:

• BillingClient SDK: * для инициализации необходимо создать экземпляр RuStoreBillingClient с помощью метода RuStoreBillingClientFactory.create() в коде вашего приложения и передать туда consoleApplicationId
• Pay SDK: в файле AndroidManifest.xml необходимо добавить параметр console_app_id_value. Параметры themeProvider, externalPaymentLoggerFactory и debugLogs не указываются.

Обработка deeplink

• Для указания deeplink схемы в biilingClient SDK используется метод RustoreBillingClientFactory.create().
• В Pay SDK для указания deeplink схемы используется файл AndroidManifest.xml, где указывается sdk_pay_scheme_value. Для обработки Deeplinks добавлен публичный интерактор IntentInteractor.

Проверка доступности работы с платежами

• Изменился метод проверки доступности работы с платежами:

  • BillingClient SDK: RuStoreBillingClient.Companion.checkPurchasesAvailability().
  • Pay SDK: RuStorePayClient.instance.getPurchaseInteractor().getPurchaseAvailability().

• Поменялись ответы метода:

  • BillingClient SDK: FeatureAvailabilityResult.Available и FeatureAvailabilityResult.Unavailable(val cause: RuStoreException).
  • Pay SDK: PurchaseAvailabilityResult.Available и PurchaseAvailabilityResult.Unavailable(val cause: Throwable).

Получение списка продуктов

• В Pay SDK получение списка продуктов не требует авторизации пользователя.

• Теперь можно запрашивать до 1000 элементов за один запрос, в то время как в BillingClient SDK — до 100.

• Изменился метод получения списка продуктов:

  • BillingClient SDK: billingClient.products productsUseCase.getProducts().
  • Pay SDK: RuStorePayClient.getProductInteractor().getProducts(productsId: List<ProductId>).

• В возвращаемой модели продукта изменилась структура. В таблице ниже приведены соответствия полей, возвращаемых обоими SDK. Подробное описание полей см. в документации billingClient SDK и Pay SDK.

BillingClient SDK	Pay SDK
productId	productId
productType	type
productStatus	—
priceLabel	amountLabel
price	price
currency	currency
language	—
title	title
description	description
imageUrl	imageUrl
promoImageUrl	—
subscription	—

Получение списка покупок

Изменился метод получения списка покупок:

• BillingClient SDK: billingClient.purchases purchasesUseCase.getPurchases().
• Pay SDK: RuStorePayClient.getPurchaseInteractor().getPurchases().

Метод поддерживает фильтрацию:

• по типу товара (productType): потребляемые, непотребляемые товары, подписки;
• по статусу покупки (purchaseStatus):
  • для товаров: PAID, CONFIRMED.
  • для подписок: ACTIVE, PAUSED.

Типы покупок

Изменилась структура ответа методов получения сведений о покупке и списка покупок, появился общий интерфейс Purchase и две его реализации:

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

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

В следующей таблице приведены списки полей, которые возвращают оба SDK.

BillingClient SDK	Pay SDK (общий интерфейс)	Pay SDK ProductPurchase	Pay SDK SubscriptionPurchase
purchaseId	purchaseId	purchaseId	purchaseId
productId	—	productId	productId
invoiceId	invoiceId	invoiceId	invoiceId
language	—	—	—
purchaseTime	purchaseTime	purchaseTime	purchaseTime
orderId	orderId	orderId	orderId
—	purchaseType	purchaseType	purchaseType
—	description	description	description
amountLabel	amountLabel	amountLabel	amountLabel
amount	price	price	price
currency	currency	currency	currency
quantity	—	quantity	—
—	—	productType	-
purchaseState	status	status	status
developerPayload	developerPayload	developerPayload	developerPayload
subscriptionToken	—	—	—
sandbox	sandbox	sandbox	sandbox
—	—	—	expirationDate
—	—	—	gracePeriodEnabled

Получение сведений о покупке

• Изменился метод получения сведений о покупке:

  • BillingClient SDK: billingClient.purchases purchasesUseCase.getPurchaseInfo(PurchaseId("purchaseId")).
  • Pay SDK: RuStorePayClient.getPurchaseInteractor().getPurchase(PurchaseId("purchaseId")).

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

BillingClient SDK	Pay SDK ProductPurchase	Pay SDK SubscriptionPurchase
CREATED	-	-
INVOICE_CREATED	INVOICE_CREATED	INVOICE_CREATED
CANCELLED	CANCELLED	CANCELLED
-	PROCESSING	PROCESSING
-	REJECTED	REJECTED
CONFIRMED	CONFIRMED	-
CONSUMED	-	-
-	REFUNDED	-
-	REFUNDING	-
-	EXECUTING	-
-	EXPIRED	EXPIRED
PAID	PAID	-
-	REVERSED	-
-	-	ACTIVE
PAUSED	-	PAUSED
TERMINATED	-	TERMINATED
-	-	CLOSED

Покупка продукта

• Метод покупки продукта заменён на два новых метода:

  • BillingClient SDK: billingClient.purchases purchasesUseCase.purchaseProduct().

  • Pay SDK:

    RuStorePayClient.instance.getPurchaseInteractor().purchase(params, preferredPurchaseType: PreferredPurchaseType = PreferredPurchaseType.ONE_STEP) — Универсальный метод для запуска покупки. Позволяет выбрать тип оплаты — одностадийную или двухстадийную.

    • Одностадийная оплата (PreferredPurchaseType.ONE_STEP): Средства за покупку списываются сразу.

    • Двухстадийная оплата (PreferredPurchaseType.TWO_STEP): Выполняется попытка двухстадийной оплаты. Если выбранный покупателем способ оплаты не поддерживает холдирование, покупка выполняется по сценарию одностадийной оплаты.

    RuStorePayClient.instance.getPurchaseInteractor().purchaseTwoStep() — метод для гарантированного запуска двухстадийной оплаты. На платёжной шторке отображаются только те способы оплаты, которые поддерживают холдирование.

• В billingClient SDK стадийность платежа была привязана к типу продукта (потребляемый/непотребялемый), в Pay SDK вы сами определяете стадийность платежа при запуске оплаты.

• Изменились ответы метода:

  • BillingClient SDK: Success, Failure, Cancelled и InvalidPaymentState.
  • Pay SDK: Для успешной покупки результат возвращается в виде класса ProductPurchaseResult. Отдельные классы отмены и ошибки больше не используются. Для обработки ошибок используется OnFailureListener, в котором указывается поведение при возникновении RustorePaymentException.ProductPurchaseException (общая ошибка) и RustorePaymentException.ProductPurchaseCancelled (отмена пользователем).

• В Pay SDK для методов покупки добавлены необязательные параметры appUserId и appUserEmail.

Обработка ошибок оплаты

Если в процессе оплаты возникает ошибка или пользователь отменяет покупку, выполнение метода оплаты (как с выбором типа покупки, так и двухстадийного метода) завершается с ошибкой.

Для обработки ошибок используется OnFailureListener, внутри которого определяется тип ошибки и указывается поведение при ее возникновении:

• ProductPurchaseException - ошибка покупки продукта.
• ProductPurchaseCancelled - ошибка, вызванная отменой покупки продукта (пользователь закрыл платежную шторку) до получения результата покупки. В таком случае рекомендуется дополнительно проверить статус покупки методом получения информации о покупке.

Более подробная информация и примеры кода приведены на странице Pay SDK

Обработка ошибок оплаты в версиях Pay SDK до 8.0.0

В версиях Pay SDK до 8.0.0 данный обработка ошибок оплаты была реализована с помощью отдельных классов результата покупки CancelProductPurchaseResult и FailureProductPurchaseResult.

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

Для серверной валидации разовых покупок используется:

• BillingClient SDK: subscriptionToken, который можно получить при успешной покупке продукта из PaymentResult.Success.
• Pay SDK: invoiceId (идентификатор счёта) используется для серверной валидации платежей, purchase id — для получения информации по подписке. См. API: Получение данных о платеже по его идентификатору (v2), Валидация подписок, Подтверждение получения подписок.

Подтверждение покупки

Изменился метод подтверждения покупки:

• BillingClient SDK: billingClient.purchases purchasesUseCase.confirmPurchase().
• Pay SDK: RuStorePayClient.getPurchaseInteractor().confirmTwoStepPurchase() — подтверждение покупки при двухстадийной оплате.

Отмена покупки

Изменился метод отмены покупки:

• BillingClient SDK: billingClient.purchases purchasesUseCase.deletePurchase()
• Pay SDK: RuStorePayClient.getPurchaseInteractor().cancelTwoStepPurchase() — отмена покупки при двухстадийной оплате.

См. также

• Описание Pay SDK
• Pay SDK Kotlin/Java
• Pay SDK Godot
• Pay SDK Unity
• Pay SDK Flutter

История изменений

Pay SDK 10.0.0

• Добавлена возможность покупки подписок в SDK.
• Добавлены новые статусы покупок (для подписок) и тип покупок для фильтрации списка покупок.
• Добавлен новый метод оплаты SberPay.
• Добавлена подпись к лоадеру на экранах проверки статуса покупки.
• Публичная модель PurchaseStatus заменена на ProductPurchaseStatus и SubscriptionPurchaseStatus, представляющие разные статусные модели продуктов.
• Удалён статус ProductPurchaseStatus.CONSUMED и добавлен ProductPurchaseStatus.REFUNDING.
• Добавлено новое поле productType: ProductType в модель ответа успешной покупки, в модели ошибки и отмены покупки продукта.
• Подключена новая зависимость в виде Tracer Light.
• Исправлена критическая ошибка при отмене покупки.

Pay SDK 9.0.1

• Добавлена оплата вне RuStore.
• Добавлена оплата и сохранение карты VK ID.
• Добавлена функция создания и применения купонов.

Pay SDK 8.0.0

• Метод одностадийной оплаты purchaseOneStep заменён универсальным методом purchase, который позволяет указать тип оплаты (одностадийная или двухстадийная).
• Двухстадийная оплата (TWO_STEP) теперь доступна только для ограниченного набора способов оплаты.
• Улучшен метод purchaseTwoStep, который теперь обеспечивает гарантированную двухстадийную оплату.
• Добавлена ошибка RuStorePayInvalidActivePurchase при попытке оплаты продукта неизвестного типа.
• Добавлена возможность проводить тестовые платежи (sandbox)

Pay SDK 7.0.0

• Единый метод покупки заменён на два новых метода для одностадийной и двухстадийной оплате.
• Вместо статусных моделей потребляемых или непотребляемых продуктов теперь используются статусные модели покупки по одностадийной и двухстадийной оплате.
• Статус CONSUMED заменён на CONFIRMED.
• Метод подтверждения покупки consumePurchase заменен на confirmTwoStepPurchase для двухстадийной оплаты.
• Появился метод отмены покупки при двухстадийной оплате.

Pay SDK 6.1.0

Первая версия инструкции по переходу с BillingClient SDK на Pay SDK 6.1.0.