Skip to main content

In-app Payments SDK for Kotlin/Java (version 11.0.0)

With RuStore you can integrate payments in your mobile app.

tip

Getting started​

Adding the repository

build.gradle
repositories {
    maven {
        url = uri("https://nexus-external.vkteam.ru/repository/maven-rustore-exposed/")
    }
}

Adding the dependency

Connecting the dependency

Add the following code to your configuration file to add the dependency.

build.gradle
dependencies {
    implementation(platform("ru.rustore.sdk:bom:2026.07.01"))
    implementation("ru.rustore.sdk:pay")
}

Deeplink handling in the RuStore SDK allows you to efficiently interact with third-party applications when processing payments via banking applications (SBP, SberPay, etc.). This makes it possible to redirect the user to the payment screen and, after the transaction is completed, return them to your app.

To configure deeplink handling in your app and Pay SDK, specify the deeplinkScheme using sdk_pay_scheme_value in your AndroidManifest.xml file and override the onNewIntent method of your Activity.

Warning
  • When using deeplinks, specifying the scheme is mandatory.
  • If a payment is initiated without a scheme, an error will occur.
  • Only ASCII characters are allowed. The format must comply with RFC-3986.

Specifying deeplinkScheme:

AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="your.app.package.name">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.App"
        tools:targetApi="n">
        
          <activity
            android:name=".YourPayActivity">

            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>

            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="yourappscheme" />
            </intent-filter>

        </activity>


        <meta-data
            android:name="sdk_pay_scheme_value"
            android:value="yourappscheme" />

    </application>
</manifest>
tip

Replace yourappscheme with your own scheme name, for example ru.package.name.rustore.scheme. Then add the following code to the Activity you want to return to after the payment is completed (your app page):

Calling the getPurchaseAvailability method
class YourBillingActivity: AppCompatActivity() {
      
    private val intentInteractor: IntentInteractor by lazy {
        RuStorePayClient.instance.getIntentInteractor()
    }
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (savedInstanceState == null) {
            intentInteractor.proceedIntent(intent, sdkTheme = SdkTheme.LIGHT)  // Optional theme
        }
    }
  
    override fun onNewIntent(intent: Intent?) {
        super.onNewIntent(intent)    
        intentInteractor.proceedIntent(intent, sdkTheme = SdkTheme.LIGHT)  // Optional theme
    }
}

To restore your app state when returning via a deeplink, add the android:launchMode="singleTop" attribute to AndroidManifest.xml.

Specifying console app id
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="your.app.package.name">
    <!-- ... -->

    <application>
      <!-- ... -->
        <activity
            android:name=".YourPayActivity"
            android:launchMode="singleTop"
            android:exported="true"
            android:screenOrientation="portrait"
            android:windowSoftInputMode="adjustResize">

            <!-- ... -->

        </activity>
      <!-- ... -->
    </application>

</manifest>

SDK initialization​

Initialize the library before calling its methods. The initialization itself is done automatically, however, for your SDK to work, define console_app_id_key in your manifest.xml.

You can so it the following way:

manifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        package="your.app.package.name">
 
    <application
            android:allowBackup="true"
            android:icon="@mipmap/ic_launcher"
            android:label="@string/app_name"
            android:roundIcon="@mipmap/ic_launcher_round"
            android:supportsRtl="true"
            android:theme="@style/Theme.App"
            tools:targetApi="n">
        ...
 
        <meta-data
                android:name="console_app_id_value"
                android:value="@string/CONSOLE_APPLICATION_ID" />

        <meta-data
                android:name="sdk_pay_scheme_value"
                android:value="@string/APP_SCHEME" />
 
    </application>
</manifest>

  • CONSOLE_APPLICATION_ID — product ID form the RuStore Console.

    Example: https://console.rustore.ru/apps/111111.
Where are app IDs in the RuStore Console?
  1. Navigate to the Applications tab and selected the needed app.
  2. Copy the ID from the URL address of the app page — it is a set of numbers between apps/ and /versions. FOr example, for URL address https://console.rustore.ru/apps/123456/versions the app ID is 123456.

Important
  • ApplicationId specified in build.gradle must match the applicationId of the APK file that you published in RuStore Console.
  • To work correctly with deeplink, AndroidManifest must have a <meta-data> attribute with the name "sdk_pay_scheme_value". The value is the schema of your application.

  • The keystore signature must match the signature that was used to sign the app published in the RuStore Console. Make sure that buildType used (example: debug) uses the same signature as the published app (example: release).

Required Permissions and Security Parameters​

The Pay SDK automatically adds some permissions and parameters to the application's manifest that are necessary for the functionality related to payment security.

Other Permissions

The Pay SDK may also require other standard permissions, such as:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

SDK methods​

Available public interactors:

  • PurchaseInteractor — an interactor that allows you to work with payments and provides several public methods.

    • getPurchase(purchaseId: PurchaseId): Task<Purchase> — returns information about a purchase by its ID.
    • getPurchases(productType: ProductType? = null, purchaseStatus: PurchaseStatus? = null, acknowledgementState: AcknowledgementState? = null): Task<List<Purchase>> — returns the user's purchases. This method supports optional filtering by product type (consumable products, non-consumable products, or subscriptions), by purchase status (supported statuses: PAID, CONFIRMED, ACTIVE, and PAUSED), and by product acknowledgement state (acknowledgementState). Possible values: PENDING, ACKNOWLEDGED, UNKNOWN. By default, filters are disabled, and all user purchases are returned regardless of product type, with statuses PAID, CONFIRMED, ACTIVE, and PAUSED.
    • getPurchaseAvailability(): Task<PurchaseAvailabilityResult> — returns the result of checking whether payments are available.
    • purchase(params: ProductPurchaseParams, preferredPurchaseType: PreferredPurchaseType = PreferredPurchaseType.ONE_STEP, sdkTheme: SdkTheme = SdkTheme.LIGHT, purchaseEventListener: PurchaseEventListener? = null): Task<ProductPurchaseResult> — starts a product purchase with the preferred payment type: one-step (ONE_STEP) or two-step (TWO_STEP). For this method, all payment methods are available in the payment sheet. If the parameter is not specified, one-step payment is used by default.
    Important!

    If the TWO_STEP payment type is specified, the SDK will attempt to start a two-step payment, but the actual result depends directly on which payment method the user selects (card, Faster Payments System, and so on).

    Please note that the TWO_STEP payment type is not available:

    • when the user selects Faster Payments System;
    • when purchasing subscriptions.

    Two-step payment is available only for a limited set of payment methods, currently cards and SberPay. If the selected payment method does not support fund holding, the purchase is started as a one-step payment.

    • purchaseTwoStep(params: ProductPurchaseParams, sdkTheme: SdkTheme = SdkTheme.LIGHT, purchaseEventListener: PurchaseEventListener? = null): Task<ProductPurchaseResult> — starts a guaranteed two-step product purchase flow. When using this method, the user sees only payment methods that support two-step payment in the payment sheet. During the payment process, the buyer's funds are first put on hold and are charged only after the purchase is confirmed using confirmTwoStepPurchase.
    • confirmTwoStepPurchase(purchaseId: PurchaseId, developerPayload: DeveloperPayload? = null) — confirms a purchase made with two-step payment.
    • cancelTwoStepPurchase(purchaseId: PurchaseId) — cancels a purchase made with two-step payment.
    • updateAcknowledgementState(purchaseId: PurchaseId, state: AcknowledgementState, developerPayload: DeveloperPayload? = null): Task<AcknowledgementState> — updates the product acknowledgement state.

  • ProductInteractor — an interactor that allows you to work with products:

    • getProducts(productsId: List<ProductId>): Task<List<Product>> — returns information about active products published in the RuStore Console.
    Important

    This method returns no more than 1000 products and works without user authorization and without RuStore being installed on the user's device.

  • UserInteractor — an interactor that allows you to get the user's authorization status as UserAuthorizationStatus. This model has two possible states:

    • Authorized — the user is authorized in RuStore.
    • Unauthorized — the user is not authorized in RuStore.

  • IntentInteractor — an interactor that allows you to process intents and deeplinks. It is required to correctly return from the banking app back to your app and to correctly restore the state of the payment sheet.

    • proceedIntent(intent: Intent?, sdkTheme: SdkTheme = SdkTheme.LIGHT) — a method for processing deeplinks and restoring the payment sheet state when returning to your app from a banking app. Calling this method is required for the payment sheet to be displayed correctly after returning from the banking app.

  • RuStoreUtils — a set of public methods such as:

    • isRuStoreInstalled — checks whether RuStore is installed on the user's device.
    • openRuStoreDownloadInstruction — opens the web page for downloading the RuStore app.
    • openRuStore — launches the RuStore app.
    • openRuStoreAuthorization — launches the RuStore app for authorization. After the user is successfully authorized, the RuStore app closes automatically.

Getting the product list​

To retrieve the products added to your application via the RuStore Console, you must use the method:s getProducts.

Calling the getProducts method
RuStorePayClient.instance.getProductInteractor().getProducts(productsId = listOf(ProductId("id1"), ProductId("id2")))
    .addOnSuccessListener { products: List<Product> ->
        // Logic for working with a grocery list
    }
    .addOnFailureListener { throwable: Throwable ->
        // Error handling
    }

productsId: List<ProductId> — the list of product IDs that are set when products are created in the RuStore Console. The list is limited by 1000 items.

Where are product IDs in the RuStore Console?
  1. Navigate to the Applications tab and selected the needed app.
  2. Select Monetization in the left menu.
  3. Select product type: Subscriptions or In-App purchases.
  4. Copy the IDs of the required products.

The method returns a list of active products. Below is the product model.

Product Structure
public class Product internal constructor(
    public val productId: ProductId,
    public val type: ProductType,
    public val amountLabel: AmountLabel,
    public val price: Price?,
    public val currency: Currency,
    public val imageUrl: Url,
    public val title: Title,
    public val description: Description?,
    public val subscriptionInfo: SubscriptionInfo?,
)
  • productId — product ID assigned to product in RuStore Console (mandatory).
  • type — product type. CONSUMABLE_PRODUCT/NON_CONSUMABLE_PRODUCT/SUBSCRIPTION (потребляемый/непотребляемый/подписка).
  • amountLabel — formatted purchase price, including currency symbol.
  • price — price in minimum currency units.
  • currency — ISO 4217 currency code.
  • imageUrl — image URL.
  • title — product name in language.
  • description — descriptions in language.
    • subscriptionInfo — subscription information (will be non-null if product type is SUBSCRIPTION).
    .

The subscriptionInfo model contains information about the subscription product.

Attention

The presence of fields does not mean that the user still has access to a free or starter period: he may have previously exhausted these periods.

Below is the model itself.

Структура информации о подписке
public class SubscriptionInfo internal constructor(
    public val periods: List<SubscriptionPeriod>,
)
 
public sealed interface SubscriptionPeriod
 
public class TrialPeriod internal constructor(
    public val duration: String,
    public val currency: String,
    public val price: Int,
) : SubscriptionPeriod
 
public class PromoPeriod internal constructor(
    public val duration: String,
    public val currency: String,
    public val price: Int,
) : SubscriptionPeriod
 
public class MainPeriod internal constructor(
    public val duration: String,
    public val currency: String,
    public val price: Int,
) : SubscriptionPeriod
 
public class GracePeriod internal constructor(
    public val duration: String,
) : SubscriptionPeriod
 
public class HoldPeriod internal constructor(
    public val duration: String,
) : SubscriptionPeriod
  • duration - длительность периода в формате ISO 8601 (как в Public API)
  • currency - код валюты ISO 4217
  • price - цена в минимальных единицах (копейках).

Периоды подписки

  • TrialPeriod — бесплатный период

  • PromoPeriod — стартовый период

  • MainPeriod — стандартный период подписки

  • GracePeriod — грэйс-период

  • HoldPeriod — холд-период

tip

Подробнее о работе периодов подписки описано в статье.

Пример работы с subscriptionInfo

Работа с subscriptionInfo
RuStorePayClient.instance.getProductInteractor().getProducts(productsId = listOf(ProductId("id1"), ProductId("id2")))
    .addOnSuccessListener { products: List<Product> ->
        products.forEach { product ->
            val periods = product.subscriptionInfo?.periods
            when (period) {
                is TrialPeriod -> {
                    println("Бесплатный период: ${period.duration} за ${period.price} ${period.currency}")
                }
                is PromoPeriod -> {
                    println("Стартовый период: ${period.duration} за ${period.price} ${period.currency}")
                }
                is MainPeriod -> {
                    println("Основной период: ${period.duration} за ${period.price} ${period.currency}")
                }
                is GracePeriod -> {
                    println("Период отсрочки: ${period.duration}")
                }
                is HoldPeriod -> {
                    println("Период удержания: ${period.duration}")
                }
                null -> {
                  println("subscriptionInfo is null")
                }
            }
        }
    }
    .addOnFailureListener { throwable: Throwable ->
        // Обработка ошибки
    }

Answer Examples

Illustration of model structure in the answer (not compiled code - model builders are not available outside the SDK).

Example of a Consumable Product model
Product(
    productId = ProductId("conProduct1"),
    type = ProductType.CONSUMABLE_PRODUCT,
    amountLabel = AmountLabel("100.00 руб."),
    price = Price(10000),
    currency = Currency("RUB"),
    imageUrl = Url("https://your_image_consumable_product.png"),
    title = Title("Name of the Consumed Product"), 
    description = Description("Description of the product consumed"),
 )
Non-Consumable Product Model Example
Product(
    productId = ProductId("nonConProduct1"),
    type = ProductType.NON_CONSUMABLE_PRODUCT,
    amountLabel = AmountLabel("200.00 руб."),
    price = Price(20000),
    currency = Currency("RUB"),
    imageUrl = Url("https://your_image_non_consumable_product.png"),
    title = Title("Name of the Non-Consumable Product"), 
    description = Description("Description of the Non-Consumable Product"),
 )
Subscription Model Example
Product(
    productId = ProductId("sub_1"),
    type = ProductType.SUBSCRIPTION,
    amountLabel = AmountLabel("300.00 руб."),
    price = Price(30000),
    currency = Currency("RUB"),
    imageUrl = Url("https://your_image_subscription.png"),
    title = Title("Name of your subscription"), 
    description = Description("Description of your subscription"),
    subscriptionInfo = SubscriptionInfo(
        periods = listOf(
            TrialPeriod(
                duration = "P1M",
                currency = "RUB",
                price = 0
            ),
            PromoPeriod(
                duration = "P5D",
                currency = "RUB",
                price = 149
            ),
            MainPeriod(
                duration = "P1Y",
                currency = "RUB",
                price = 299
            ),
            GracePeriod(
                duration = "P3D"
            ),
            HoldPeriod(
                duration = "P5D"
            )
        )
    )
 )

Checking whether the user is authorized​

To check the user's authorization status, call the getUserAuthorizationStatus method of UserInteractor. The result is returned as a UserAuthorizationStatus class.

Two values are available:

  • AUTHORIZED — the user is authorized in RuStore or via VK ID in the payment sheet.
  • UNAUTHORIZED — the user is not authorized. This value is also returned if RuStore is not installed on the user's device.
Calling getUserAuthorizationStatus
RuStorePayClient.instance.getUserInteractor().getUserAuthorizationStatus()
    .addOnSuccessListener { result ->
        when (result) {
            UserAuthorizationStatus.AUTHORIZED -> {
                 // Logic when the user is authorized in RuStore or in the payment sheet
            }
 
            UserAuthorizationStatus.UNAUTHORIZED -> {
                // Logic when the user is NOT authorized
            }
        }
    }.addOnFailureListener { throwable ->
        // Error handling
    }

Checking payment availability​

To check payment availability, call the getPurchaseAvailability method on PurchaseInteractor. When called, the following conditions are checked:

  • The company has monetization enabled via the RuStore Developer Console.
  • The application must not be banned in RuStore.
  • The user must not be banned in RuStore.

If all conditions are met, PurchaseAvailabilityResult.Available is returned. Otherwise, PurchaseAvailabilityResult.Unavailable(val cause: Throwable) is returned, where cause is the error indicating the unmet condition. To check the reason for this result, you should check the error type for RuStoreException (these errors are described in the Error Handling section).

The reason for unavailability of payments is in the cause: Throwable field of the PurchaseAvailabilityResult.Unavailable result.

Call the getPurchaseAvailability method
RuStorePayClient.instance.getPurchaseInteractor().getPurchaseAvailability()
    .addOnSuccessListener { result ->
        when (result) {
            is PurchaseAvailabilityResult.Available -> {
                 // Processing the payment availability result
            }
 
            is PurchaseAvailabilityResult.Unavailable -> {
                // Processing the result of unavailable payments
            }
        }
    }.addOnFailureListener { throwable ->
       // Error handling
    }

Purchasing a product​

One-step and two-step payment notes
  • When using a single-stage payment, the purchase does not require confirmation; the funds are immediately debited from the buyer’s account, and a commission is charged to the developer. In this case, if a refund to the customer is required (for example, if the product cannot be delivered for some reason), a refund can only be processed via the RuStore Console, and the funds will be returned to the buyer within a few days. The full purchase amount is refunded, but the commission previously withheld from the developer is not reimbursed.
  • In the case of a two-stage payment, the funds are first held (authorized) on the buyer’s account. No commission is charged at this stage. After the hold, the purchase requires either confirmation or cancellation. The commission is charged to the developer upon purchase confirmation. Cancelling the purchase releases the hold, and the funds instantly become available to the buyer again.
Restrictions for subscription payment types

At this time, a subscription purchase (SubscriptionPurchase) can only be made using the one-step payment flow (PurchaseType.ONE_STEP).

Important

Two-stage payment is available only for a specific set of payment methods (currently — only for cards). SBP technologies do not support two-stage payment. If a payment method that does not support holding funds is selected, the purchase will be processed using the single-stage scenario.

Payment with choice of purchase type

To call a product purchase with a choice of stages of payment, use the purchase method.

Calling the product purchase method
val params = ProductPurchaseParams(
    productId = ProductId("productId"),
    orderId = null,
    quantity = null,
    developerPayload = null,
    appUserId = null,
    appUserEmail = null,
)
RuStorePayClient.instance.getPurchaseInteractor()
    .purchase(params = params, preferredPurchaseType = PreferredPurchaseType.ONE_STEP, sdkTheme = SdkTheme.LIGHT, purchaseEventListener = null)
    .addOnSuccessListener { result ->
        // Logic for processing a successful purchase result
    }
    .addOnFailureListener { throwable: Throwable ->
        when(throwable){
            is RuStorePaymentException.ProductPurchaseException -> // Handling a product purchase error
            is RuStorePaymentException.ProductPurchaseCancelled -> // Processing a product purchase cancellation
            else -> //Error handling
        }
    }
  • productId — product ID assigned to product in RuStore Console (mandatory).
  • quantity — product amount (optional, value 1 will be used if not specified).
  • orderId — payment ID generated by the app (optional). If you specify this parameter in your system, you will receive it via our API. If not specified, will be generated automatically (uuid). 150 characters max.
  • developerPayload — an additional order information string that you can set when confirming a purchase. This string overrides the value set during initialization. Maximum length: 250 characters. Characters are not escaped (if quotes are used, escaping is required). Maximum length is 250 characters. Characters are not escaped.
  • <AppUserId name="appUserId"/>
  • appUserEmail is an optional parameter that lets you set the user’s email address in your app. If the customer’s email address was specified during registration in your app, you can pass it to automatically prefill the email field when sending a receipt — both for payments outside RuStore and in cases where the user is not authorized in RuStore. This removes the need for the user to enter their email manually, shortens the path to purchase, and helps improve conversion.
  • preferredPurchaseType – the desired purchase flow type: one-step (ONE_STEP) or two-step (TWO_STEP).
  • sdkTheme – the color theme of the payment screen. Two options are available: LIGHT and DARK (light and dark themes, respectively). To preserve backward compatibility between SDK versions, this parameter has the default value LIGHT.
  • purchaseEventListener — a set of callback functions that lets you receive invoiceId and purchaseId at different stages of the purchase flow — optional.
  • preferredPurchaseType — the desired purchase type: single-stage (ONE_STEP) or two-stage (TWO_STEP).
Important

This method is launched by default using the single-stage payment scenario (preferredPurchaseType = PreferredPurchaseType.ONE_STEP), i.e., without funds being held.

For two-stage payment, you need to specify preferredPurchaseType = PreferredPurchaseType.TWO_STEP. Two-stage payment (i.e., payment with funds being held) is not guaranteed for this method and directly depends on the payment method (card, SPB, etc.) selected by the user.

When launching this method (with the preferred preferredPurchaseType = twoStep), until the user selects a payment method, the purchase stage will be UNDEFINED. Please take this behavior into account when handling purchase cancellation results (ProductPurchaseCancelled) or purchase errors (ProductPurchaseException).

Two-stage payment (with holding funds)

To invoke the purchase of a product in a two-step scenario, use the purchaseTwoStep method.

info

When calling this method, the user will have access to a limited set of payment methods - only those that support two-step payment.

Restrictions on payment types for subscriptions

At the moment, subscription purchases (SubscriptionPurchase) can only be made using a one-step payment (PurchaseType.ONE_STEP).

Calling the product purchase method
val params = ProductPurchaseParams(
    productId = ProductId("productId"),
    orderId = null,
    quantity = null,
    developerPayload = null,
    appUserId = null,
    appUserEmail = null,
)
RuStorePayClient.instance.getPurchaseInteractor()
    .purchaseTwoStep(params = params, sdkTheme = SdkTheme.LIGHT, purchaseEventListener = null)
    .addOnSuccessListener { result ->
        // Logic for processing a successful purchase result
    }
    .addOnFailureListener { throwable: Throwable ->
        when(throwable){
            is RuStorePaymentException.ProductPurchaseException -> // Handling a product purchase error
            is RuStorePaymentException.ProductPurchaseCancelled -> // Processing a product purchase cancellation
            else -> // Error handling
        }
    }
  • productId — product ID assigned to product in RuStore Console (mandatory).
  • quantity — product amount (optional, value 1 will be used if not specified).
  • orderId — payment ID generated by the app (optional). If you specify this parameter in your system, you will receive it via our API. If not specified, will be generated automatically (uuid). 150 characters max.
  • developerPayload — an additional order information string that you can set when confirming a purchase. This string overrides the value set during initialization. Maximum length: 250 characters. Characters are not escaped (if quotes are used, escaping is required). Maximum length is 250 characters. Characters are not escaped.
  • <AppUserId name="appUserId"/>
  • appUserEmail is an optional parameter that lets you set the user’s email address in your app. If the customer’s email address was specified during registration in your app, you can pass it to automatically prefill the email field when sending a receipt — both for payments outside RuStore and in cases where the user is not authorized in RuStore. This removes the need for the user to enter their email manually, shortens the path to purchase, and helps improve conversion.
  • preferredPurchaseType – the desired purchase flow type: one-step (ONE_STEP) or two-step (TWO_STEP).
  • sdkTheme – the color theme of the payment screen. Two options are available: LIGHT and DARK (light and dark themes, respectively). To preserve backward compatibility between SDK versions, this parameter has the default value LIGHT.
  • purchaseEventListener — a set of callback functions that lets you receive invoiceId and purchaseId at different stages of the purchase flow — optional.

Structure of purchase parameters

Purchase Options Structure
public class ProductPurchaseParams(
    public val productId: ProductId,
    public val quantity: Quantity? = null,
    public val orderId: OrderId? = null,
    public val developerPayload: DeveloperPayload? = null,
    public val appUserId: AppUserId? = null,
    public val appUserEmail: AppUserEmail? = null,
)
  • productId — product ID assigned to product in RuStore Console (mandatory).
  • quantity — product amount (optional, value 1 will be used if not specified).
  • orderId — payment ID generated by the app (optional). If you specify this parameter in your system, you will receive it via our API. If not specified, will be generated automatically (uuid). 150 characters max.
  • developerPayload — an additional order information string that you can set when confirming a purchase. This string overrides the value set during initialization. Maximum length: 250 characters. Characters are not escaped (if quotes are used, escaping is required). Maximum length is 250 characters.
  • appUserId — the internal user ID in your application (optional parameter). A string with a maximum length of 128 characters.
    tip

    For example, this parameter can be used to detect cases of fraud in your application, which will help improve its security.

  • appUserEmail — this is an optional parameter that allows you to specify the user's email address in your application. If the buyer's email address was provided during registration in the app, it can be passed for automatic filling of the email field when sending a receipt — both for payments outside RuStore and in cases where the user is not authorized in RuStore. This saves the user from having to manually enter their email, shortens the purchase flow, and helps increase conversion.

Working with PurchaseEventListener

This interface is a set of callback functions for purchase events that are called during the purchase process.

PurchaseEventListener Interface
public interface PurchaseEventListener {
    public fun onPurchaseCreated(purchaseId: PurchaseId, invoiceId: InvoiceId)
    public fun onPaymentStarted(purchaseId: PurchaseId, invoiceId: InvoiceId)
    public fun onPaymentCompleted(purchaseId: PurchaseId, invoiceId: InvoiceId)
    public fun onPaymentFailed(purchaseId: PurchaseId?, invoiceId: InvoiceId?)
    public fun onPurchaseCancelled(purchaseId: PurchaseId?, invoiceId: InvoiceId?)
}

The implementation is passed to the purchase() and purchaseTwoStep() methods. Thanks to these notifications, you can receive data about the purchaseId and invoiceId at different stages of the purchase in order to interact with this information. For example, transfer a value to analytics or write to a database.

Example of using PurchaseEventListener
val params = ProductPurchaseParams(
    productId = ProductId("productId"),
    orderId = null,
    quantity = null,
    developerPayload = null,
    appUserId = null,
    appUserEmail = null,
)
val purchaseEventListener = object : PurchaseEventListener {
    override fun onPurchaseCreated(purchaseId: PurchaseId, invoiceId: InvoiceId) {
        // Implementing a method when creating a purchase
    }
    override fun onPaymentStarted(purchaseId: PurchaseId, invoiceId: InvoiceId) {
        // Implementation of the method at the start of the purchase
    }
    override fun onPaymentCompleted(purchaseId: PurchaseId, invoiceId: InvoiceId) {
        // Implementation of the method upon successful completion of the purchase
    }
    override fun onPaymentFailed(purchaseId: PurchaseId?, invoiceId: InvoiceId?) {
        // Implementing a method when a purchase is unsuccessful
    }
    override fun onPurchaseCancelled(purchaseId: PurchaseId?, invoiceId: InvoiceId?) {
        // Implementing a method when canceling a purchase
    }
}
RuStorePayClient.instance.getPurchaseInteractor()
    .purchase(params = params, sdkTheme = SdkTheme.LIGHT, purchaseEventListener = purchaseEventListener)
    .addOnSuccessListener { result ->
        // Logic for processing a successful purchase result
    }
    .addOnFailureListener { throwable: Throwable ->
        when(throwable){
            is RuStorePaymentException.ProductPurchaseException -> // Handling product purchase error
            is RuStorePaymentException.ProductPurchaseCancelled -> // Processing product cancellations
            else -> // Error handling
        }
    }

Purchase result structure​

ProductPurchaseResult is the result of a successful digital product or subscription payment for one-step payments, or a successful funds hold for two-step payments.

public class ProductPurchaseResult internal constructor(
public val orderId: OrderId?,
public val purchaseId: PurchaseId,
public val productId: ProductId,
public val invoiceId: InvoiceId,
public val purchaseType: PurchaseType,
public val productType: ProductType,
public val quantity: Quantity,
public val sandbox: Boolean,
)

  • ProductPurchaseResult — the result of a successful digital product payment for one-step payments, or a successful funds hold for two-step payments.

    • purchaseId — purchase identifier. Used to get purchase details from the SDK and for server-side subscription validation.
    • productId — the identifier of the purchased product specified when creating it in the RuStore developer console.
    • invoiceId — invoice identifier. Used for server-side payment validation, searching for payments in the developer console, and displayed to the buyer in payment history in the RuStore mobile app.
    • orderId — unique payment identifier specified by the developer or generated automatically (uuid).
    • purchaseType — purchase type (ONE_STEP/TWO_STEP/UNDEFINED — one-step/two-step/undefined purchase stage).
    • productType — product type (NON_CONSUMABLE_PRODUCT — non-consumable product, CONSUMABLE_PRODUCT — consumable product, SUBSCRIPTION — subscription).
    • quantity — quantity of the product specified when starting the purchase.
    • sandbox — flag indicating a sandbox test payment. If TRUE, the purchase was made in test mode.

Confirming a purchase​

Only purchases that were initiated using a two-step payment scenario require confirmation, i.e. with holding funds. Such purchases, after successful holding, will be in the status PurchaseStatus.PAID.

Proof of purchase is required to charge the customer's card. To do this you must use the confirmTwoStepPurchase method.

Calling confirmation method
RuStorePayClient.instance.getPurchaseInteractor().confirmTwoStepPurchase(
    purchaseId = PurchaseId("purchaseId"),
    developerPayload = null,
    )
    .addOnSuccessListener {
        // Logic for successful purchase confirmation
    }.addOnFailureListener { throwable: Throwable ->
        // Error handling
    }
  • purchaseId — product ID.
  • developerPayload — an additional order information string that you can set when confirming a purchase. This string overrides the value set during initialization. Maximum length: 250 characters. Characters are not escaped (if quotes are used, escaping is required). Maximum 250 characters (characters are not escaped). If passed, replaces the value recorded when the purchase was started using the purchase/purchaseTwoStep method.

Canceling a purchase​

With our SDK you can cancel only the purchases that undergo a two-stage payment process, i.e. when the user's money is put on hold. After a successful hold, such purchases are in the PurchaseStatus.PAID status. If a purchase is canceled it has the PurchaseStatus.REVERSED status.

tip

Cancel purchases if you cannot deliver your product after payment is made (when the user's money is put on hold).

To cancel a purchase (put the user's money off hold), use the cancelTwoStepPurchase method.

RuStorePayClient.instance.getPurchaseInteractor().cancelTwoStepPurchase(
    purchaseId = PurchaseId("purchaseId"),
    )
    .addOnSuccessListener {
        // Logic for processing a successful purchase cancellation
    }.addOnFailureListener { throwable: Throwable ->
        // Error handling
    }
  • purchaseId — product ID.

Working with product acknowledgement state​

To update the purchase acknowledgement state, use the updateAcknowledgementState method.

Confirmation of delivery of goods upon purchase
RuStorePayClient.instance.getPurchaseInteractor()
    .updateAcknowledgementState(
        purchaseId = purchaseId,
        state = AcknowledgementState.ACKNOWLEDGED,
        developerPayload = null,
    )
    .addOnSuccessListener { state ->
        // The product delivery status has been updated.
    }
    .addOnFailureListener { throwable ->
        // Error handling
    }

Logic is optional and does not affect payments. It allows you to store the state of purchase processing on the RuStore side, so that when you receive a shopping list with separate filtering, you can select only unprocessed purchases and issue goods based on them.

After a successful payment, the default status for issuing goods is PENDING.

For payments made in earlier versions of the SDK, where this logic was not yet supported, the UNKNOWN status is used. If necessary, this status can be changed to any other.

The processing status can be changed in both directions: for example, transferring a purchase from PENDING to ACKNOWLEDGED, and also returning it to the previous status if you need to recall a previously issued product, for example after a payment has been returned.

When this method is called, the value of developerPayload can be updated. If a parameter is passed, the current value will be overwritten. If no parameter is passed, the current value of developerPayload will be retained.

Getting purchase details​

Go get purchase information, use the getPurchase method.
Calling the method to get the user's purchase
RuStorePayClient.instance.getPurchaseInteractor().getPurchase(PurchaseId("purchaseId"))
     .addOnSuccessListener { purchase: Purchase ->
        when(purchase) {
            is ProductPurchase -> {
                // Logic for processing the product purchase result
            }
            is SubscriptionPurchase -> {
                // Логика обработки результата покупки подписки
            }
            else -> {
                // Logic for processing purchase results with basic fields
            }
        }
    }
    .addOnFailureListener { throwable: Throwable ->
        // Обработка ошибки
    }

The method returns information about a specific purchase in any status.

Details of the ProductPurchase and SubscriptionPurchase purchasing models are provided in the relevant sections.

An example response is the output of toString() from the resulting model (illustration of the structure, not compiled code).

Example of a consumable product purchase model
ProductPurchase(
    purchaseId=PurchaseId(value='purchaseId'),
    productId=ProductId(value='game_coins_1000'),
    invoiceId=InvoiceId(value='invoiceId'),
    orderId=OrderId(value='orderId'),
    purchaseType=ONE_STEP,
    productType=CONSUMABLE_PRODUCT,
    description=Description(value='description'),
    purchaseTime=123123123124,
    price=Price(value='14100'),
    amountLabel=AmountLabel(value='141,00 ₽'),
    currency=Currency(value='RUB'),
    quantity=Quantity(value='1'),
    status=CONFIRMED,
    developerPayload='DeveloperPayload(value='developerPayload')',
    sandbox=false,
    acknowledgementState=PENDING
)
Example of a subscription purchase
SubscriptionPurchase(
    purchaseId=PurchaseId(value='sub_purchase_12345'),
    invoiceId=InvoiceId(value='inv_sub_67890'),
    orderId=OrderId(value='order_sub_abcde'),
    purchaseType=ONE_STEP,
    description=Description(value='Premium Monthly Subscription'),
    purchaseTime=123123123124,
    price=Price(value='29900'),
    amountLabel=AmountLabel(value='299 ₽'),
    currency=Currency(value='RUB'),
    status=ACTIVE,
    developerPayload='DeveloperPayload(value='user_id:123;source:profile')',
    sandbox=false,
    productId=ProductId(value='premium_monthly_v1'),
    expirationDate='Sat Aug 01 12:00:00 GMT+03:00 2026',
    gracePeriodEnabled='true',
    acknowledgementState=ACKNOWLEDGED
)

Getting the list of purchases​

Go get the user's purchases list, use the getPurchases method.

Вызов метода получения списка покупок пользователя
RuStorePayClient.instance.getPurchaseInteractor().getPurchases()
     .addOnSuccessListener { purchases: List<Purchase> ->
        // Логика работы со списком покупок пользователя
    }
    .addOnFailureListener { throwable: Throwable ->
       // Обработка ошибки
    }

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

Тип товара (productType):

  • CONSUMABLE_PRODUCT — потребляемый товар;
  • NON_CONSUMABLE_PRODUCT — непотребляемый товар;
  • SUBSCRIPTION— подписка.

Статус покупки (purchaseStatus):

  • PAID — успешное холдирование средств, покупка ожидает подтверждения со стороны разработчика (для продуктов);
  • CONFIRMED — покупка подтверждена, средства списаны (для продуктов);
  • ACTIVE — подписка активна (для подписок);
  • PAUSED — подписка в холд периоде: не удалось провести платеж (например, недостаточно средств на карте), но продолжаются попытки списания (для подписок).

Состояние выдачи товара (acknowledgementState):

  • PENDING — ожидает выдачи товара;
  • ACKNOWLEDGED — товар выдан;
  • UNKNOWN — логика не применима к платежу.

По умолчанию все фильтры выключены и возвращаются все покупки пользователя.

Вызов метода получения списка покупок пользователя с фильтрацией
RuStorePayClient.instance.getPurchaseInteractor().getPurchases(
    productType = ProductType.CONSUMABLE_PRODUCT,
    purchaseStatus = ProductPurchaseStatus.PAID,
)
     .addOnSuccessListener { purchases: List<Purchase> ->
        // Логика работы со списком покупок пользователя
    }
    .addOnFailureListener { throwable: Throwable ->
        // Обработка ошибки
    }

Purchase types​

In the SDK, there is a base Purchase interface that unifies the common fields for all purchase types. It has two implementations:

  • ProductPurchase — for consumable and non-consumable purchases.
  • SubscriptionPurchase — for subscriptions.

This separation allows each purchase type to expose its own specific properties and behavior.

Purchase interface
public interface Purchase {
    public val purchaseId: PurchaseId
    public val invoiceId: InvoiceId
    public val orderId: OrderId?
    public val purchaseType: PurchaseType
    public val status: PurchaseStatus
    public val description: Description
    public val purchaseTime: Date?
    public val price: Price
    public val amountLabel: AmountLabel
    public val currency: Currency
    public val developerPayload: DeveloperPayload?
    public val sandbox: Boolean
}

Product purchase model​

ProductPurchase model
public class ProductPurchase internal constructor(
    public override val purchaseId: PurchaseId,
    public override val invoiceId: InvoiceId,
    public override val orderId: OrderId?,
    public override val purchaseType: PurchaseType,
    public override val status: ProductPurchaseStatus,
    public override val description: Description,
    public override val purchaseTime: Date?,
    public override val price: Price,
    public override val amountLabel: AmountLabel,
    public override val currency: Currency,
    public override val developerPayload: DeveloperPayload?,
    public override val sandbox: Boolean,
    public val productId: ProductId,
    public val quantity: Quantity,
    public val productType: ProductType,
    public val acknowledgementState: AcknowledgementState,
) : Purchase
  • purchaseId — product ID. Purchase identifier. Used for retrieving the information about the purchase in SDK using the getting purchase information method.
  • invoiceId — invoice ID. Bill identifier. Used for payment server validation, searching for payment in the Console and also it's shown in the payment history section in RuStore.
  • orderId - unique payment identifier, specified by the developer or generated automatically (uuid).
  • PurchaseType — purchase type:
    • ONE_STEP - one-stage payment;
    • TWO_STEP - two-stage payment;
    • UNDEFINED — number of payment stages is undefined.
  • status — purchase state:
    • INVOICE_CREATED — purchase invoice is created and awaiting payment;
    • CANCELLED — purchase canceled by the user;
    • PROCESSING — payment initiated;
    • REJECTED — purchase rejected (for example: due to insufficient funds);
    • EXPIRED — payment time expired;
    • PAID — only for two-stage payments, intermediate status, funds are put on hold on the user's account, the purchase is awaiting confirmation from the developer;
    • CONFIRMED — purchase successfully paid for;
    • REFUNDING — refund initiated, request sent to acquirer ;
    • REFUNDED — purchase successfully refunded;
    • REVERSED — only for two-stage payment: wither the purchase was canceled by the developer or there was no payment within 6 hours, the funds on the user's account are put off hold.
  • description - purchase description.
  • purchaseTime — purchase time.
  • price — price in minimum currency units.
  • amountLabel — formatted purchase price, including currency symbol.
  • currency — ISO 4217 currency code.
  • developerPayload — an additional order information string that you can set when confirming a purchase. This string overrides the value set during initialization. Maximum length: 250 characters. Characters are not escaped (if quotes are used, escaping is required)
  • — test payment flag. true — test payment, false — actual payment
  • productId — product ID assigned to product in RuStore Console (mandatory). Product identifier, which was assigned to the product in RuStore Console (required parameter).
  • quantity — product quantity.
  • productType — product type. (CONSUMABLE/NON-CONSUMABLE - consumable/non-consumable.)
  • acknowledgementState — product acknowledgement state. Possible values: PENDING (waiting for item delivery), ACKNOWLEDGED (item delivered), UNKNOWN (this logic does not apply to the payment).

Purchase status model​

One-stage payment status model.

Two-stage payment status model.

Subscription model​

SubscriptionPurchase model
public class SubscriptionPurchase internal constructor(
    public override val purchaseId: PurchaseId,
    public override val invoiceId: InvoiceId,
    public override val orderId: OrderId?,
    public override val purchaseType: PurchaseType,
    public override val status: SubscriptionPurchaseStatus,
    public override val description: Description,
    public override val purchaseTime: Date?,
    public override val price: Price,
    public override val amountLabel: AmountLabel,
    public override val currency: Currency,
    public override val developerPayload: DeveloperPayload?,
    public override val sandbox: Boolean,
    public val productId: ProductId,
    public val expirationDate: Date,
    public val gracePeriodEnabled: Boolean,
    public val acknowledgementState: AcknowledgementState,
) : Purchase

  • purchaseId — product ID — the purchase identifier. Used to retrieve purchase details in the SDK via the purchase info method.

  • invoiceId — invoice ID — the invoice identifier. Used for server-side payment validation, for searching payments in the Developer Console, and is shown to the buyer in their payment history.

  • orderId — a unique payment identifier provided by the developer or generated automatically (UUID).

  • PurchaseType — purchase type:

    • ONE_STEP - one-stage payment;
    • TWO_STEP - two-stage payment;
    • UNDEFINED — number of payment stages is undefined.

  • status — subscription flow status:

    • INVOICE_CREATED — an invoice has been created; the subscription is waiting for payment.
    • CANCELLED — the subscription invoice was canceled.
    • EXPIRED — the time to pay the initial invoice has expired; no subscription was created.
    • PROCESSING — the first subscription payment is being processed.
    • REJECTED — the first subscription payment was rejected. The subscription was not created.
    • ACTIVE — the subscription is active.
    • PAUSED — the subscription is paused due to payment issues.
    • TERMINATED — all retry attempts for the subscription failed. The subscription was automatically closed due to payment issues.
    • CLOSED — the subscription was canceled by the user or the developer. After the paid period ended, the subscription was closed.

  • description — purchase description.

  • purchaseTime — purchase time.

  • price — price in minimum currency units.

  • amountLabel — formatted purchase price, including currency symbol.

  • currency — ISO 4217 currency code.

  • developerPayload — an additional order information string that you can set when confirming a purchase. This string overrides the value set during initialization. Maximum length: 250 characters. Characters are not escaped (if quotes are used, escaping is required).

  • — test payment flag. true — test payment, false — actual payment.

  • productId — product ID assigned to product in RuStore Console (mandatory) — the product identifier assigned in RuStore Console (required).

  • expirationDate — the subscription end date.

  • gracePeriodEnabled — a flag indicating whether the grace period is enabled for the subscription.

    • acknowledgementState — product acknowledgement state. Possible values: PENDING (waiting for item delivery), ACKNOWLEDGED (item delivered), UNKNOWN (this logic does not apply to the payment).

Subscription status model​

Getting the list of subscriptions from SDK Billing Client​

Getting a list of subscriptions issued in the SDK Billing Client
RuStorePayClient.instance.getPurchaseInteractor().getBillingSubscriptions()
     .addOnSuccessListener { subscriptions: List<BillingSubscription> ->
        // Logic for working with a user's subscription list
    }
    .addOnFailureListener { throwable: Throwable ->
       // Error handling
    }

The method returns a list of subscriptions registered in the Billing Client SDK.

Sample answer.

Example of a subscription model issued in the SDK Billing Client
BillingSubscription(
    purchaseId = PurchaseId("sub_purchase_12345"),
    invoiceId = InvoiceId("inv_sub_67890"),
    orderId = OrderId("order_sub_abcde"),
    purchaseType = PurchaseType.ONE_STEP,
    status = SubscriptionPurchaseStatus.ACTIVE,
    description = Description("Monthly subscription to 'Premium''"),
    purchaseTime = Date(),
    price = Price(29900), //Price in kopecks
    amountLabel = AmountLabel("299 ₽"),
    currency = Currency("RUB"),
    developerPayload = DeveloperPayload("user_id:123;source:profile"),
    sandbox = false,
    productId = ProductId("premium_monthly_v1"),
    expirationDate = Date(System.currentTimeMillis() + TimeUnit.DAYS.toMillis(30)),
    gracePeriodEnabled = true,
    subscriptionToken = SubscriptionToken("special_validation_token"),
)

SDK Billing Client Subscription model​

Subscription model created in the Billing Client SDK
public class BillingSubscription internal constructor(
    public override val purchaseId: PurchaseId,
    public override val invoiceId: InvoiceId,
    public override val orderId: OrderId?,
    public override val purchaseType: PurchaseType,
    public override val status: SubscriptionPurchaseStatus,
    public override val description: Description,
    public override val purchaseTime: Date?,
    public override val price: Price,
    public override val amountLabel: AmountLabel,
    public override val currency: Currency,
    public override val developerPayload: DeveloperPayload?,
    public override val sandbox: Boolean,
    public val productId: ProductId,
    public val expirationDate: Date,
    public val gracePeriodEnabled: Boolean,
    public val subscriptionToken: SubscriptionToken,
) : Purchase

Description of BillingSubscription fields

  • purchaseId — product ID. Purchase ID. Used to retrieve purchase information from the SDK.
  • invoiceId — invoice ID. Account ID. Used for server-side payment validation, searching for payments in the developer console, and also displayed to the buyer in the payment history.
  • orderId — a unique payment identifier specified by the developer or automatically generated (uuid).
  • purchaseType — purchase type. Purchase type: ONE_STEP/TWO_STEP - one-stage/two-stage.
  • status — purchase status of the SubscriptionPurchaseStatus type.
  • description — descriptions in language. Description of purchase.
  • purchaseTime — purchase time. Time to buy.
  • price — price in minimum currency units. Price in minimum currency units.
  • amountLabel — formatted purchase price, including currency symbol. Formatted purchase price including currency symbol.
  • currency — ISO 4217 currency code. ISO 4217 currency code.
  • developerPayload — an additional order information string that you can set when confirming a purchase. This string overrides the value set during initialization. Maximum length: 250 characters. Characters are not escaped (if quotes are used, escaping is required). A developer-specified string containing additional information about the order.
  • sandbox — test payment flag. true — test payment, false — actual payment. Flag indicating the sign of a test payment. If true, the purchase was made in testing mode.
  • productId — product ID assigned to product in RuStore Console (mandatory). Subscription product ID.
  • expirationDate — subscription expiration date.
  • gracePeriodEnabled - flag indicating whether the grace period for the subscription is active.
  • subscriptionToken — purchase token for server validation . Token for validating a purchase on the server.

SubscriptionPurchaseStatus:

  • INVOICE_CREATED - an invoice for payment has been created, the subscription is awaiting payment.
  • CANCELLED - subscription was canceled by the user.
  • EXPIRED - subscription has expired.
  • PROCESSING - payment is being processed.
  • REJECTED - payment rejected.
  • ACTIVE - subscription is active.
  • PAUSED - subscription is suspended due to payment problems.
  • TERMINATED - subscription debit attempts have ended (all were unsuccessful). Subscription closed automatically due to payment problems.
  • CLOSED - the subscription was canceled by the user or developer. The paid period has expired and the subscription is closed.

Error handling​

If an error occurs during payment or the user cancels the purchase, the payment method execution ends with an error, both for the method with a selected purchase type and for the two-step method:

  • ProductPurchaseException — product purchase error.
  • ProductPurchaseCancelled — an error caused by canceling a product purchase when 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 details method.

Error and canceled purchase structure:

public class ProductPurchaseException internal constructor(
    public val orderId: OrderId?,
    public val purchaseId: PurchaseId?,
    public val productId: ProductId?,
    public val invoiceId: InvoiceId?,
    public val quantity: Quantity?,
    public val purchaseType: PurchaseType?,
    public val productType: ProductType?,
    public val sandbox: Boolean?,
    public override val cause: Throwable,
) : RuStorePaymentException(message = "Error purchase product", cause = cause)
  • purchaseId — purchase identifier. Used to get purchase details from the SDK using the purchase details method.
  • productId — identifier of the purchased product specified when creating it in the RuStore developer console.
  • invoiceId — invoice identifier. Used for server-side payment validation, searching for payments in the developer console, and displayed to the buyer in payment history in the RuStore mobile app.
  • orderId — unique payment identifier specified by the developer or generated automatically (uuid).
  • purchaseType — purchase type (ONE_STEP/TWO_STEP/UNDEFINED — one-step/two-step/undefined purchase stage).
  • productType — product type (NON_CONSUMABLE_PRODUCT — non-consumable product, CONSUMABLE_PRODUCT — consumable product, SUBSCRIPTION — subscription).
  • quantity — quantity of the product specified when starting the purchase.
  • ProductPurchaseCancelled — digital product purchase canceled. The payment dialog was closed before the purchase result was received, so the purchase status is unknown. It is recommended to request the purchase status separately using the purchase details method.
public class ProductPurchaseCancelled internal constructor(
    public val purchaseId: PurchaseId?,
    public val purchaseType: PurchaseType?,
    public val productType: ProductType?,
) : RuStorePaymentException(message = "Purchase product is cancelled")
  • purchaseId — purchase identifier. Used to get purchase details from the SDK using the purchase details method.
  • purchaseType — purchase type (ONE_STEP/TWO_STEP/UNDEFINED — one-step/two-step/undefined purchase stage).
  • productType — product type (NON_CONSUMABLE_PRODUCT — non-consumable product, CONSUMABLE_PRODUCT — consumable product, SUBSCRIPTION — subscription).

Server-side purchase validation​

If you need to validate a successful purchase in RuStore, you can use public validation APIs. Different methods are used to validate products and subscriptions:

  • To validate a product purchase, use the invoiceId from the ProductPurchaseResult model returned after the purchase is completed.
  • To validate a subscription purchase, use the purchaseId from the ProductPurchaseResult model returned after the purchase is completed.

The type of product purchased can be determined from the data received in the ProductPurchaseResult response.

Getting invoiceId from the purchase result
val params = ProductPurchaseParams(ProductId("productId"))
 
RuStorePayClient.instance.getPurchaseInteractor()
    .purchase(params = params, preferredPurchaseType = PreferredPurchaseType.TWO_STEP)
    .addOnSuccessListener { purchaseResult ->
        when (purchaseResult.productType) {
            CONSUMABLE_PRODUCT,
            NON_CONSUMABLE_PRODUCT -> {
                val invoiceId = purchaseResult.invoiceId.value
                yourApi.validateProduct(invoiceId)
            }
 
            SUBSCRIPTION -> {
                val purchaseId = purchaseResult.purchaseId.value
                yourApi.validateSubscription(purchaseId)
            }
        }
    }

You can also get the invoiceId in the Purchase model. The Purchase model can be obtained using the getPurchases() method or the getPurchase method.

Getting invoiceId/purchaseId from the Purchase model
RuStorePayClient.instance.getPurchaseInteractor().getPurchases()
    .addOnSuccessListener { purchases ->
        purchases.forEach { purchase ->
            if(purchase is SubscriptionPurchase){
                val purchaseId = purchase.purchaseId.value
                yourApi.validateSubscription(purchaseId)       
            } else {
                val invoiceId = purchase.invoiceId.value
                yourApi.validateProduct(invoiceId)
            }
        }
    }

RuStoreUtils​

RuStoreUtils is a block in the native SDK containing a set of public methods intended for interacting with the RuStore app on the user's device.

To access the block's methods in the Unity environment, use the singleton class RuStoreCoreClient.

The IsRuStoreInstalled method checks if the RuStore app is installed on the user's device.

Calling the IsRuStoreInstalled method
if (RuStorePayClient.Instance.IsRuStoreInstalled()) {
    // RuStore is installed on the user's device
} else {
    // RuStore is not installed on the user's device
}

The openRuStoreDownloadInstruction method opens a web page for downloading the RuStore mobile application.

Calling the openRuStoreDownloadInstruction method
RuStoreCoreClient.Instance.openRuStoreDownloadInstruction();

The openRuStore method launches the RuStore mobile application. When this method is called, if the RuStore app is not installed, a Toast notification with the message "Failed to open the application" will be displayed.

Calling the openRuStore method
RuStoreCoreClient.Instance.openRuStore();

The openRuStoreAuthorization method launches the RuStore mobile application for authorization. After successful user authorization, the RuStore app will automatically close. When this method is called, if the RuStore app is not installed, a Toast notification with the message "Failed to open the application" will be displayed.

Calling the openRuStoreAuthorization method
RuStoreCoreClient.Instance.openRuStoreAuthorization();

Error list​

RuStorePaymentNetworkException — SDK network interaction error.
The error model returns an error code in the code field, which can be used to determine the cause.
The table with error codes is available in the error codes section.

The message field contains the cause description.

public class RuStorePaymentNetworkException internal constructor(  
    public val code: String?,  
    public val id: String,  
    public override val message: String,  
    public override val cause: Throwable? = null,  
) : RuStorePaymentException(message, cause)
  • RuStorePaymentNetworkException — SDK network communication error;
  • RuStorePaymentCommonException — general SDK error;
  • RuStorePayClientAlreadyExist — SDK re-initialization error;
  • RuStorePayClientNotCreated — attempt to access public SDK interfaces before initialization;
  • RuStorePayInvalidActivePurchase — payment initiated for unknown product type;
  • RuStorePayInvalidConsoleAppId — the required parameter console_application_id for SDK initialization is not specified;
  • RuStorePaySignatureException — invalid response signature. Occurs when attempting fraudulent actions;
  • EmptyPaymentTokenException — error obtaining payment token;
  • InvalidCardBindingIdException — error when paying with a saved card;
  • ApplicationSchemeWasNotProvided — scheme for the return deeplink is not specified;
  • ProductPurchaseException — product purchase error. The model structure is described in the section purchase result structure;
  • ProductPurchaseCancelled — product purchase was cancelled (the user closed the payment sheet). The model structure is described in the section purchase result structure;
  • ProductPurchaseException — product purchase error;
  • RuStoreNotInstalledException — RuStore is not installed on the user's device;
  • RuStoreOutdatedException — the installed version of RuStore on the device does not support payments;
  • RuStoreUserUnauthorizedException — the user is not authorized in RuStore;
  • RuStoreApplicationBannedException — the application is banned in RuStore;
  • RuStoreUserBannedException — the user is banned in RuStore.

Error Codes​

Error CodeDescription
4000001The request is malformed: a required parameter is missing or incorrectly filled, or the data format is invalid.
4000002, 4000016, 4040005Application not found.
4000003Application is banned.
4000004Application signature does not match the registered one.
4000005Company not found.
4000006Company is banned.
4000007Company monetization is disabled or inactive.
4000014Product not found.
4000015Product not published.
4000017Invalid quantity parameter.
4000018Purchase limit exceeded.
4000020Product already purchased.
4000021Unfinished product purchase.
4000022Purchase not found.
4000025No suitable payment method found.
4000026Invalid purchase type for confirmation (should be two-stage payment).
4000027Invalid purchase status for confirmation.
4000028Invalid purchase type for cancellation (should be two-stage payment).
4000029Invalid purchase status for cancellation.
4000030The issued token does not match the purchased product.
4000041An active subscription already exists for this product code.
4000045Maximum size limit exceeded.
4010001Access to the requested resource is forbidden (unauthorized).
4010002Token lifetime has expired.
4010003Payment token is invalid.
4030001Payment token not provided.
4030002User is blocked due to security requirements.
4040002, 4040003, 4040004Payment system error.
5000***Internal error.