Skip to main content

How to Migrate to Pay SDK

There are differences in the functioning principles of Pay SDK compared to billingClient SDK.

This section provides a list of key changes compared to billingClient SDK that are important to note. Detailed information with code examples can be found in the documentation for the specific version of Pay SDK.

List of Dependencies​

The list of dependencies for Pay SDK has been reduced.

Project Integration​

When integrating the dependency, note the difference in SDK naming (pay instead of 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")
}

Initialization​

The method of specifying consoleApplicationId during initialization has changed:

  • BillingClient SDK: In the build.gradle file, you need to call the method RuStoreBillingClientFactory.create(consoleApplicationId) and pass consoleApplicationId to it.

  • Pay SDK: In the AndroidManifest.xml file, you need to add the parameter console_app_id_value.

    The parameters themeProvider, externalPaymentLoggerFactory, and debugLogs are not specified.

  • To specify the deeplink scheme in billingClient SDK, the method RustoreBillingClientFactory.create() is used.
  • In Pay SDK, the file AndroidManifest.xml is used to specify the deeplink scheme, where sdk_pay_scheme_value is specified.

A public interactor IntentInteractor has been added for handling Deeplinks.

Checking Payment Availability​

  • The method for checking payment availability has changed:

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

  • The method responses have changed:

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

Retrieving Product List​

  • In Pay SDK, retrieving the product list does not require user authorization.

  • You can now request up to 1000 items in one request, whereas in BillingClient SDK — up to 100.

  • The method for retrieving the product list has changed:

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

  • The structure of the returned product model has changed. The table below shows the field correspondences returned by both SDKs. For detailed field descriptions, see the documentation for billingClient SDK and Pay SDK.

BillingClient SDKPay SDK
productIdproductId
productTypetype
productStatus—
priceLabelamountLabel
priceprice
currencycurrency
language—
titletitle
descriptiondescription
imageUrlimageUrl
promoImageUrl—
subscription—

Retrieving Purchase List​

The method for retrieving the purchase list has changed:

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

Retrieving Purchase Details​

  • The method for retrieving purchase details has changed:

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

  • The structure of the returned purchase model has changed. The following table lists the fields returned by both SDKs. For field descriptions, see the documentation for billingClient SDK and Pay SDK.

BillingClient SDKPay SDK
purchaseIdpurchaseId
productIdproductId
invoiceIdinvoiceId
language—
purchaseTimepurchaseTime
orderIdorderId
—purchaseType
—productType
—description
amountLableamountLable
amountprice
currencycurrency
quantityquantity
purchaseStateStatus
developerPayloaddeveloperPayload
subscriptionToken-
sandboxsandbox

  • The purchase status model (Status) and the list of possible statuses have changed.

    There are no longer separate status models for consumable or non-consumable products. Instead, purchase models for single-stage and two-stage payments are used.

    The following table lists the possible statuses for each SDK. For a description of the status model and status values, see the documentation for billingClient SDK and Pay SDK.

BillingClient SDKPay SDK
CREATED—
INVOICE_CREATEDINVOICE_CREATED
PAIDPAID
CONFIRMEDCONFIRMED
CONSUMED—
CANCELLEDCANCELLED
PAUSED—
TERMINATED—
—PROCESSING
—EXPIRED
—REJECTED
—REVERSED
—REFUNDED

Product Purchase​

  • The method for product purchase has been replaced with two new methods:

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

    • Pay SDK:

      RuStorePayClient.instance.getPurchaseInteractor().purchase(params, preferredPurchaseType: PreferredPurchaseType = PreferredPurchaseType.ONE_STEP) — A universal method for initiating a purchase. Allows you to choose the payment type — single-stage or two-stage.

      • Single-stage payment (PreferredPurchaseType.ONE_STEP): The purchase amount is debited immediately.

      • Two-stage payment (PreferredPurchaseType.TWO_STEP): An attempt is made to perform a two-stage payment. If the payment method chosen by the buyer does not support holding, the purchase is made using the single-stage payment scenario.

      RuStorePayClient.instance.getPurchaseInteractor().purchaseTwoStep() — a method for guaranteed two-stage payment initiation. Only payment methods that support holding are displayed on the payment sheet.

  • The method responses have changed:

    • BillingClient SDK: Success, Failure, Cancelled, and InvalidPaymentState.
    • Pay SDK: Separate cancellation and error classes are no longer used. For error handling, OnFailureListener is used, where behavior is specified for RustorePaymentException.ProductPurchaseException (general error) and RustorePaymentException.ProductPurchaseCancelled (cancellation by the user).

  • In Pay SDK, an optional parameter appUserId has been added to the purchase methods.

Payment Error Handling​

If an error occurs during payment or the user cancels the purchase, the execution of the payment method (both with purchase type selection and the two-stage method) will complete with an error.

For error handling, OnFailureListener is used, inside which the error type is determined and behavior is specified for its occurrence:

  • ProductPurchaseException - product purchase error.
  • ProductPurchaseCancelled - error caused by product purchase cancellation (the user closed the payment sheet) before receiving the purchase result. In this case, it is recommended to additionally check the purchase status using the purchase information retrieval method.

More detailed information and code examples are provided on the Pay SDK page.

Payment Error Handling in Pay SDK versions prior to 8.0.0

In Pay SDK versions prior to 8.0.0, payment error handling was implemented using separate purchase result classes CancelProductPurchaseResult and FailureProductPurchaseResult.

Server Validation​

For server validation of one-time purchases, the following is used:

Purchase Confirmation​

The method for purchase confirmation has changed:

  • BillingClient SDK: billingClient.purchases purchasesUseCase.confirmPurchase().
  • Pay SDK: RuStorePayClient.getPurchaseInteractor().confirmTwoStepPurchase() — confirmation of purchase with two-stage payment.

Purchase Cancellation​

The method for purchase cancellation has changed:

  • BillingClient SDK: billingClient.purchases purchasesUseCase.deletePurchase()
  • Pay SDK: RuStorePayClient.getPurchaseInteractor().cancelTwoStepPurchase() — cancellation of purchase with two-stage payment.

Features in Development​

Pay SDK is in beta launch, so it currently does not include some features of billingClient SDK:

  • working with app subscriptions;
  • dark theme for the payment sheet.

We will announce the launch of new features additionally. Stay tuned for updates.

See Also​

Changelog​

Pay SDK 9.0.1​

  • Added payment outside RuStore.
  • Added payment and card saving for VK ID.
  • Added the function to create and apply coupons.

Pay SDK 8.0.0​

  • The single-stage payment method purchaseOneStep was replaced with a universal method purchase, which allows specifying the payment type (single-stage or two-stage).
  • Two-stage payment (TWO_STEP) is now available only for a limited set of payment methods.
  • Improved the purchaseTwoStep method, which now provides guaranteed two-stage payment.
  • Added the error RuStorePayInvalidActivePurchase when attempting to pay for a product of unknown type.
  • Added the ability to conduct test payments (sandbox).

Pay SDK 7.0.0​

  • The unified purchase method was replaced with two new methods for single-stage and two-stage payments.
  • Instead of status models for consumable or non-consumable products, status models for single-stage and two-stage payments are now used.
  • The CONSUMED status was replaced with CONFIRMED.
  • The purchase confirmation (consumption) method consumePurchase was replaced with confirmTwoStepPurchase for two-stage payments.
  • A method for canceling a purchase with two-stage payment was introduced.

Pay SDK 6.1.0​

The first version of the guide for migrating from BillingClient SDK to Pay SDK 6.1.0.