Как перейти на 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.02.01"))
    implementation("ru.rustore.sdk:pay")
}

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

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

• BillingClient SDK: * в файле build.gradle необходимо вызывать метод RuStoreBillingClientFactory.create(consoleApplicationId) и передать в него consoleApplicationId.

• Pay SDK: в файле AndroidManifest.xml необходимо добавить параметр console_app_id_value.

  Параметры themeProvider, externalPaymentLoggerFactory и debugLogs не указываются.

Обработка Deeplinks

• Для указания 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().

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

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

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

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

BillingClient SDK	Pay SDK
purchaseId	purchaseId
productId	productId
invoiceId	invoiceId
language	—
purchaseTime	purchaseTime
orderId	orderId
—	purchaseType
—	productType
—	description
amountLable	amountLable
amount	price
currency	currency
quantity	quantity
purchaseState	Status
developerPayload	developerPayload
subscriptionToken	-
sandbox	sandbox

• Изменилась статусная модель покупки (Status) и список возможных статусов.

  Теперь нет отдельных статусных моделей для потребляемых или непотребляемых продуктов. Вместо них используются модели покупки по одностадийной и двухстадийной оплате.

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

BillingClient SDK	Pay SDK
CREATED	—
INVOICE_CREATED	INVOICE_CREATED
PAID	PAID
CONFIRMED	CONFIRMED
CONSUMED	—
CANCELLED	CANCELLED
PAUSED	—
TERMINATED	—
—	PROCESSING
—	EXPIRED
—	REJECTED
—	REVERSED
—	REFUNDED

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

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

  • 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: Success, Failure, Cancelled и InvalidPaymentState.
  • Pay SDK: Отдельные классы отмены и ошибки больше не используются. Для обработки ошибок используется OnFailureListener, в котором указывается поведение при возникновении RustorePaymentException.ProductPurchaseException(общая ошибка) и RustorePaymentException.ProductPurchaseCancelled` (отмена пользователем).

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

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

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

Для обработки ошибок используется 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 (идентификатор счёта). См. 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 находится в бета-запуске, поэтому он пока не включает некоторые функции billingClient SDK:

• оплата покупок без установки RuStore на устройстве пользователя;
• работа с подписками на приложения;
• дополнительные способы оплаты кроме банковской карты;
• тёмная тема для шторки оплаты.

О запуске новой функциональности мы сообщим дополнительно. Следите за обновлениями.

См. также

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

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

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.