SDK Платежи in-app для Kotlin/Java (версия 9.0.1)

RuStore позволяет интегрировать платежи в мобильное приложение.

提示

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

Подготовка к работе

Добавление репозитория

build.gradle
repositories {
    maven {
        url = uri("https://artifactory-external.vkpartner.ru/artifactory/maven")
    }
}

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

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

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

Обработка deeplink

Обработка deeplink в RuStore SDK позволяет эффективно взаимодействовать со сторонними приложениями, при проведении платежей через банковские приложения (СБП, SberPay, T-Pay и др.). Это позволяет перевести пользователя на экран оплаты, а после завершения транзакции — вернуть в ваше приложение.

Для настройки работы с deeplink в вашем приложении и Pay SDK, укажите deeplinkScheme с помощью sdk_pay_scheme_value
в вашем AndroidManifest.xml файле и переопределите метод onNewIntent вашего Activity

Внимание

При использовании deeplinks указание схемы является обязательным. При попытке платежа без указания схемы будет возникать ошибка.

Указание 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>

提示

Замените yourappscheme на название своей схемы. Например, ru.package.name.rustore.scheme.

Затем, добавьте следующий код в Activity, в которую необходимо вернуться после совершения оплаты (ваша страница приложения):

class YourPayActivity: AppCompatActivity() {

    private val intentInteractor: IntentInteractor by lazy {
        RuStorePayClient.instance.getIntentInteractor()
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (savedInstanceState == null) {
            intentInteractor.proceedIntent(intent)
        }
    }

    override fun onNewIntent(intent: Intent?) {
        super.onNewIntent(intent)
        intentInteractor.proceedIntent(intent)
    }
}

Для восстановления состояния вашего приложения при возврате с deeplink добавьте в AndroidManifest.xml атрибут android:launchMode="singleTop".

Указание launchMode:

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>
      <!-- ... -->
        <activity
            android:name=".YourPayActivity"
            android:launchMode="singleTop"
            android:exported="true"
            android:screenOrientation="portrait"
            android:windowSoftInputMode="adjustResize">

            <!-- ... -->

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

</manifest>

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

Перед вызовом методов библиотеки необходимо выполнить её инициализацию. Сама инициализация происходит автоматически, но для работы SDK в вашем файле Manifest.xml необходимо прописать console_app_id_value. Значение необходимо указать в строковых ресурсах.

Сделать это можно следующим образом.

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" />
 
    </application>
</manifest>

CONSOLE_APPLICATION_ID — идентификатор приложения из RuStore консоли.
Пример: https://console.rustore.ru/apps/111111.

Где в RuStore Консоль отображаются идентификаторы приложений?

Перейдите на вкладку Приложения и выберите нужное приложение.
Скопируйте идентификатор из URL-адреса страницы приложения — это набор цифр между apps/ и /versions. Например, для URL-адреса https://console.rustore.ru/apps/123456/versions ID приложения — 123456.

Важно

ApplicationId, указанный в build.gradle, должен совпадать с applicationId APK-файла, который вы публиковали в RuStore Консоль.
Подпись keystore должна совпадать с подписью, которой было подписано приложение, опубликованное в RuStore Консоль. Убедитесь, что используемый buildType (пр. debug) использует такую же подпись, что и опубликованное приложение (пр. release).

информация

В целях безопасности, SDK устанавливает android:usesCleartextTraffic="false" по умолчанию, чтобы предотвратить передачу данных по незащищённому HTTP и защитить от атак типа "Man-in-the-Middle". Если ваше приложение требует использования HTTP, вы можете изменить этот атрибут на true, но делайте это на свой страх и риск, так как это увеличивает шанс перехвата и подмены данных. Мы рекомендуем разрешать незащищённый трафик только в исключительных случаях и для доверенных доменов, предпочитая HTTPS для всех сетевых взаимодействий. Если необходимо переопределить значение этого атрибута, укажите в манифесте tools:replace="android:usesCleartextTraffic.

Методы SDK

Доступные публичные интеракторы:

PurchaseInteractor - интерактор, который позволяет работать с платежами и имеет несколько публичных методов.
- getPurchase(purchaseId: PurchaseId): Task<Purchase> - позволяет получить информацию о покупке по её ID.
- getPurchases(productType: ProductType? = null, purchaseStatus: PurchaseStatus? = null): Task<List<Purchase>> — позволяет получить покупки пользователя. Данный метод поддерживает опциональную фильтрацию по типу товаров (потребляемые или непотребляемые товары), а также по статусу покупки (поддерживаются статусы PAID и CONFIRMED). По умолчанию фильтры отключены, и вернутся все покупки пользователя (независимо от типа товара) в статусах PAID и CONFIRMED.
- getPurchaseAvailability(): Task<PurchaseAvailabilityResult> - возвращает результат проверки доступности работы с платежами.
- purchase(params: ProductPurchaseParams, preferredPurchaseType: PreferredPurchaseType = PreferredPurchaseType.ONE_STEP): Task<ProductPurchaseResult> - позволяет совершить покупку продукта с указанием желаемого типа оплаты - одностадийной (ONE_STEP) или двухстадийной (TWO_STEP). Для данного метода оплаты на платёжной шторке доступны все способы оплаты. Если параметр не задан, по умолчанию запускается с оплатой в одну стадию.
Важно!
Если указан тип оплаты TWO_STEP, будет произведена попытка запустить двухстадийную оплату, но итоговый результат напрямую будет зависеть от того, какой способ оплаты (карта, СБП и др.) будет выбран пользователем. Двухстадийная оплата доступна только для определенного набора способов оплаты (на текущий момент — только для карт). Технологии СБП не поддерживают двухстадийную оплату. Если выбран способ оплаты, который не поддерживает холдирование, то покупка будет запущена по сценарию с одной стадией.
- purchaseTwoStep(params: ProductPurchaseParams): Task<ProductPurchaseResult> - запускает сценарий гарантированной двухстадийной покупки товара. При использовании данного метода пользователю на платёжной шторке доступен ограниченный набор способов оплаты - только те, которые поддерживают двухстадийную оплату. В процессе платежа сначала осуществляется холдирование денежных средств покупателя, которые списываются только после подтверждения покупки методом confirmTwoStepPurchase.
- confirmTwoStepPurchase(purchaseId: PurchaseId, developerPayload: DeveloperPayload? = null) - подтверждение покупки, совершенной по двухстадийной оплате.
- cancelTwoStepPurchase(purchaseId: PurchaseId) - отмена покупки, совершённой по двухстадийной оплате.
ProductInteractor - интерактор, который позволяет работать с продуктами:
- getProducts(productsId: List<ProductId>): Task<List<Product>> - позволяет получить информацию по активным продуктам, опубликованным в RuStore консоль.
Важно
Данный метод возвращает не более 1000 продуктов и работает без авторизации и наличия установленного RuStore на устройстве пользователя.
UserInteractor - интерактор, который позволяет получить статус авторизации пользователя UserAuthorizationStatus. У данной модели может быть 2 состояния:
- AUTHORIZED - пользователь авторизован в RuStore
- UNAUTHORIZED - пользователь неавторизован в RuStore.
IntentInteractor - интерактор, который позволяет обрабатывать intent-ы:
- proceedIntent(intent: Intent?) - метод для обработки deeplinks, использующихся для оплаты в приложениях банков. Вызов данного метода необходим для корректного отображения шторки оплаты при возвращении в приложение из приложения банка.
блок RuStoreUtils - набор открытых методов, таких как:
- isRuStoreInstalled - проверки наличия приложения RuStore на устройстве пользователя.
- openRuStoreDownloadInstruction - открывает веб-страницу для скачивания приложения RuStore.
- openRuStore - запускает приложение RuStore.
- openRuStoreAuthorization - запускает приложение RuStore для авторизации. После успешной авторизации пользователя приложение RuStore автоматически закроется.

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

Kotlin
Java

Для получения продуктов, добавленных в ваше приложение через RuStore консоль, необходимо использовать метод getProducts.

Вызов метода getProducts
RuStorePayClient.instance.getProductInteractor().getProducts(productsId = listOf(ProductId("id1"), ProductId("id2")))
    .addOnSuccessListener { products: List<Product> ->
        // Process success
    }
    .addOnFailureListener { throwable: Throwable ->
        // Process error
    }

productsId: List<ProductId> — список идентификаторов продуктов (задаются при создании продукта в консоли разработчика). Список продуктов имеет ограничение в размере 1000 элементов.

Где в RuStore Консоль отображаются идентификаторы продуктов?

Перейдите на вкладку Приложения и выберите нужное приложение.
Выберите Монетизация в меню слева.
Выберите тип товара: Подписки или Разовые покупки.
Скопируйте идентификаторы нужных товаров.

Метод возвращает список продуктов. Ниже представлена модель продукта.

Структура продукта
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?,
)

productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
type — тип продукта. CONSUMABLE/NON-CONSUMABLE (потребляемый/непотребляемый).
amountLabel — отформатированная цена покупки, включая валютный знак.
price — цена в минимальных единицах (в копейках).
currency — код валюты ISO 4217.
title — название продукта на языке language.
description — описание на языке language.
imageUrl — ссылка на картинку.

Примеры ответа

Пример модели Потребляемого продукта
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("Название Потребляемого продукта"),
    description = Description("Описание потребляемого продукта"),
 )

Пример модели Непотребляемого продукта
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("Название Непотребляемого продукта"),
    description = Description("Описание Непотребляемого продукта"),
 )

Вызов метода getProducts
List<ProductId> productIds = Arrays.asList(new ProductId("id1"), new ProductId("id2"));
ProductInteractor productInteractor = RuStorePayClient.Companion.getInstance().getProductInteractor();
 
productInteractor.getProducts(productsId)
    .addOnSuccessListener(products -> {
        // Process success
    })
    .addOnFailureListener(throwable -> {
        // Process error
    });

Где в RuStore Консоль отображаются идентификаторы продуктов?

Перейдите на вкладку Приложения и выберите нужное приложение.
Выберите Монетизация в меню слева.
Выберите тип товара: Подписки или Разовые покупки.
Скопируйте идентификаторы нужных товаров.

Метод возвращает список продуктов. Ниже представлена модель продукта:

Структура продукта
public class Product {
    private final ProductId productId;
    private final ProductType type;
    private final AmountLabel amountLabel;
    private final Price price;
    private final Currency currency;
    private final Url imageUrl;
    private final Title title;
    private final Description description;
 
    public Product(ProductId productId, ProductType type, AmountLabel amountLabel, @Nullable Price price, Currency currency, Url imageUrl, Title title, @Nullable Description description) {
        this.productId = productId;
        this.type = type;
        this.amountLabel = amountLabel;
        this.price = price;
        this.currency = currency;
        this.imageUrl = imageUrl;
        this.title = title;
        this.description = description;
    }
 
    public ProductId getProductId() {
        return productId;
    }
 
    public ProductType getType() {
        return type;
    }
 
    public AmountLabel getAmountLabel() {
        return amountLabel;
    }
 
    public @Nullable Price getPrice() {
        return price;
    }
 
    public Currency getCurrency() {
        return currency;
    }
 
    public Url getImageUrl() {
        return imageUrl;
    }
 
    public Title getTitle() {
        return title;
    }
 
    public @Nullable Description getDescription() {
        return description;
    }
}

productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
type — тип продукта. CONSUMABLE/NON-CONSUMABLE (потребляемый/непотребляемый).
amountLabel — отформатированная цена покупки, включая валютный знак.
price — цена в минимальных единицах (в копейках).
currency — код валюты ISO 4217.
title — название продукта на языке language.
description — описание на языке language.
imageUrl — ссылка на картинку.

Примеры ответа

Пример модели Потребляемого продукта
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("Название Потребляемого продукта"),
    description = Description("Описание потребляемого продукта"),
 )

Пример модели Непотребляемого продукта
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("Название Непотребляемого продукта"),
    description = Description("Описание Непотребляемого продукта"),
 )

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

Пояснения по работе с одностадийными и двухстадийными оплатами

При использовании одностадийного платежа покупка не требует подтверждения, денежные средства сразу списываются со счёта покупателя, а с разработчика удерживается комиссия. В таком случае, если требуется вернуть денежные средства клиенту (например, по какой-то причине нет возможности поставить продукт), возможен только возврат средств через RuStore Консоль, денежные средства возвращаются покупателю через несколько дней. Возвращается полная стоимость покупки, при этом удержанная комиссия разработчику не возмещается.
В случае использования двухстадийного платежа сначала производится холдирование средств на счете покупателя. Комиссия в этом случае не удерживается. После холдирования покупка требует подтверждения или отмены. Комиссия с разработчика удерживается при подтверждении покупки. Отмена покупки означает снятие холда - денежные средства мгновенно снова доступны покупателю.

Важно

Не все способы оплаты поддерживают двухстадийную оплату.

Kotlin
Java

Оплата с выбором типа покупки

Для вызова покупки продукта с выбором стадийности оплаты используйте метод purchase.

Вызов метода покупки продукта

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)
    .addOnSuccessListener { result ->
        // Успешный результат покупки
    }
    .addOnFailureListener { throwable: Throwable ->
        when(throwable){
            is RuStorePaymentException.ProductPurchaseException -> // обработка ошибки покупки продукта
            is RuStorePaymentException.ProductPurchaseCancelled -> // обработка отмены покупки продукта
            else -> // обработка ошибки
        }
    }

productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
quantity — количество продукта. Необязательный параметр со стандартным значением 1. Применим только к покупке потребляемых товаров.
orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимальная длина 250 символов.
appUserId — внутренний ID пользователя в вашем приложении (опциональный параметр). Строка с максимальной длиной в 128 символов.
提示
Например, данный параметр может использоваться для выявления случаев мошенничества в вашем приложении, что позволит повысить его безопасность.
appUserEmail - это необязательный параметр, позволяющий задать адрес электронной почты пользователя в вашем приложении. Если адрес электронной почты покупателя был указан при регистрации в приложении, его можно передать для автоматического заполнения поля email при отправке чека — как для платежей вне RuStore, так и для случаев, когда пользователь не авторизован в RuStore. Это избавляет пользователя от необходимости вручную вводить email, сокращает путь до покупки и способствует повышению конверсии.
preferredPurchaseType — желаемый тип покупки: одностадийная (ONE_STEP) или двухстадийная (TWO_STEP).

Важно

Данный метод по умолчанию запускается по одностадийному сценарию оплаты (preferredPurchaseType = PreferredPurchaseType.ONE_STEP), т.е. без холдирования средств.

Для двухстадийной оплаты нужно указать preferredPurchaseType = PreferredPurchaseType.TWO_STEP. Двухстадийная оплата (т.е. оплата с холдированием средств) для данного метода не гарантирована и напрямую зависит от того, какой способ оплаты (карта, СПБ и др.) выбрал пользователь.

При запуске данного метода (с предпочитаемым preferredPurchaseType = twoStep), до тех пор пока пользователь не выберет способ оплаты, стадийность покупки будет UNDEFINED. Учитывайте данное поведение при обработке результатов отмены (ProductPurchaseCancelled) или ошибки (ProductPurchaseException) покупки.

Двухстадийная оплата (с холдированием средств)

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

信息

При вызове данного метода пользователю будет доступен ограниченный набор способов оплаты — только те, которые поддерживают двухстадийную оплату.

Вызов метода покупки продукта

val params = ProductPurchaseParams(
    productId = ProductId("productId"),
    orderId = null,
    quantity = null,
    developerPayload = null,
    appUserId = null,
    appUserEmail = null,
)
RuStorePayClient.instance.getPurchaseInteractor()
    .purchaseTwoStep(params)
    .addOnSuccessListener { result ->
        // Успешный результат покупки
    }
    .addOnFailureListener { throwable: Throwable ->
        when(throwable){
            is RuStorePaymentException.ProductPurchaseException -> // обработка ошибки покупки продукта
            is RuStorePaymentException.ProductPurchaseCancelled -> // обработка отмены покупки продукта
            else -> // обработка ошибки
        }
    }

Структура параметров покупки

Структура параметров покупки
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 — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
quantity — количество продукта. Необязательный параметр со стандартным значением 1. Применим только к покупке потребляемых товаров.
orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимальная длина 250 символов.
appUserId — внутренний ID пользователя в вашем приложении (опциональный параметр). Строка с максимальной длиной в 128 символов.
提示
Например, данный параметр может использоваться для выявления случаев мошенничества в вашем приложении, что позволит повысить его безопасность.
appUserEmail — это необязательный параметр, позволяющий задать адрес электронной почты пользователя в вашем приложении. Если адрес электронной почты покупателя был указан при регистрации в приложении, его можно передать для автоматического заполнения поля email при отправке чека — как для платежей вне RuStore, так и для случаев, когда пользователь не авторизован в RuStore. Это избавляет пользователя от необходимости вручную вводить email, сокращает путь до покупки и способствует повышению конверсии.

Оплата с выбором типа покупки

Для вызова покупки продукта с выбором стадийности оплаты используйте метод purchase.

Вызов метода покупки продукта
ProductPurchaseParams params = new ProductPurchaseParams(new ProductId("productId"), null, null, null, null, null);
 
RuStorePayClient ruStorePayClient = RuStorePayClient.Companion.getInstance();
PurchaseInteractor purchaseInteractor = ruStorePayClient.getPurchaseInteractor();
 
purchaseInteractor.purchase(params, PreferredPurchaseType.ONE_STEP)
    .addOnSuccessListener(result -> {
        // Успешный результат покупки
    })
    .addOnFailureListener(throwable -> {
        if (throwable instanceof ProductPurchaseException) {
            // обработка ошибки покупки продукта
        } else if (throwable instanceof ProductPurchaseCancelled) {
            // обработка отмены покупки продукта
        } else {
            // обработка ошибки
        }
    });

productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
quantity — количество продукта. Необязательный параметр со стандартным значением 1. Применим только к покупке потребляемых товаров.
orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимальная длина 250 символов.
appUserId — внутренний ID пользователя в вашем приложении (опциональный параметр). Строка с максимальной длиной в 128 символов.
提示
Например, данный параметр может использоваться для выявления случаев мошенничества в вашем приложении, что позволит повысить его безопасность.
appUserEmail - это необязательный параметр, позволяющий задать адрес электронной почты пользователя в вашем приложении. Если адрес электронной почты покупателя был указан при регистрации в приложении, его можно передать для автоматического заполнения поля email при отправке чека — как для платежей вне RuStore, так и для случаев, когда пользователь не авторизован в RuStore. Это избавляет пользователя от необходимости вручную вводить email, сокращает путь до покупки и способствует повышению конверсии.
preferredPurchaseType — желаемый тип покупки: одностадийная (ONE_STEP) или двухстадийная (TWO_STEP).

Важно

Двухстадийная оплата (с холдированием средств)

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

信息

Вызов метода покупки продукта
ProductPurchaseParams params = new ProductPurchaseParams(new ProductId("productId"), null, null, null, null, null);
PurchaseInteractor purchaseInteractor = RuStorePayClient.Companion.getInstance().getPurchaseInteractor();
 
purchaseInteractor.purchaseTwoStep(params)
    .addOnSuccessListener(result -> {
        // Успешный результат покупки
    })
    .addOnFailureListener(throwable -> {
        if (throwable instanceof ProductPurchaseException) {
            // обработка ошибки покупки продукта
        } else if (throwable instanceof ProductPurchaseCancelled) {
            // обработка отмены покупки продукта
        } else {
            // обработка ошибки
        }
    });

Структура параметров покупки

Структура параметров покупки
public class ProductPurchaseParams {
    private final ProductId productId;
    private final Quantity quantity;
    private final OrderId orderId;
    private final DeveloperPayload developerPayload;
    private final AppUserId appUserId;
    private final AppUserEmail appUserEmail;
 
    public ProductPurchaseParams(ProductId productId, @Nullable Quantity quantity, @Nullable OrderId orderId, @Nullable DeveloperPayload developerPayload, @Nullable AppUserId appUserId, @Nullable AppUserEmail appUserEmail) {
        this.productId = productId;
        this.quantity = quantity;
        this.orderId = orderId;
        this.developerPayload = developerPayload;
        this.appUserId = appUserId;
        this.appUserEmail = appUserEmail;
    }
 
    public ProductId getProductId() {
        return productId;
    }
 
    public @Nullable Quantity getQuantity() {
        return quantity;
    }
 
    public @Nullable OrderId getOrderId() {
        return orderId;
    }
 
    public @Nullable DeveloperPayload getDeveloperPayload() {
        return developerPayload;
    }
     
    public @Nullable AppUserId getAppUserId() {
        return appUserId;
    }
 
    public @Nullable AppUserEmail getAppUserEmail() {
        return appUserEmail;
    }
}

productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
quantity — количество продукта. Необязательный параметр со стандартным значением 1. Применим только к покупке потребляемых товаров.
orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимальная длина 250 символов.
appUserId — внутренний ID пользователя в вашем приложении (опциональный параметр). Строка с максимальной длиной в 128 символов.
提示
Например, данный параметр может использоваться для выявления случаев мошенничества в вашем приложении, что позволит повысить его безопасность.
appUserEmail — это необязательный параметр, позволяющий задать адрес электронной почты пользователя в вашем приложении. Если адрес электронной почты покупателя был указан при регистрации в приложении, его можно передать для автоматического заполнения поля email при отправке чека — как для платежей вне RuStore, так и для случаев, когда пользователь не авторизован в RuStore. Это избавляет пользователя от необходимости вручную вводить email, сокращает путь до покупки и способствует повышению конверсии.

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

Kotlin
Java

Подтверждения требуют только покупки, которые были запущены по двухстадийному сценарию оплаты, т.е. с холдированием средств. Такие покупки, после успешного холдирования будут находиться в статусе PurchaseStatus.PAID.

Для списания средств с карты покупателя требуется подтверждение покупки. Для этого вы должны использовать метод confirmTwoStepPurchase.

Вызов метода подтверждения
RuStorePayClient.instance.getPurchaseInteractor().confirmTwoStepPurchase(
    purchaseId = PurchaseId("purchaseId"),
    developerPayload = null,
    )
    .addOnSuccessListener {
        // Process success
    }.addOnFailureListener { throwable: Throwable ->
        // Process error
    }

purchaseId — идентификатор покупки.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимум 250 символов. Если передан, заменяет значение, записанное при старте покупки методом purchase/purchaseTwoStep.

Вызов метода подтверждения
PurchaseInteractor purchaseInteractor = RuStorePayClient.Companion.getInstance().getPurchaseInteractor();
 
purchaseInteractor.confirmTwoStepPurchase(
    new PurchaseId("purchaseId"),
    null
).addOnSuccessListener( success -> {
    // Process success
}).addOnFailureListener(throwable -> {
    // Process error
});

purchaseId — идентификатор покупки.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимум 250 символов. Если передан, заменяет значение, записанное при старте покупки методом purchase/purchaseTwoStep.

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

Через SDK можно отменять только те покупки, которые были запущены по двухстадийному сценарию оплаты, т.е. с холдированием средств. Такие покупки после успешного холдирования будут находиться в статусе PurchaseStatus.PAID. После отмены покупки будут переходить в статус PurchaseStatus.REVERSED.

提示

Используйте отмену покупки в случаях, если после оплаты (холдирования средств) вы не можете предоставить покупателю товар.

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

Kotlin
Java

RuStorePayClient.instance.getPurchaseInteractor().cancelTwoStepPurchase(
    purchaseId = PurchaseId("purchaseId"),
    )
    .addOnSuccessListener {
        // Process success
    }.addOnFailureListener { throwable: Throwable ->
        // Process error
    }

purchaseId — идентификатор покупки.

PurchaseInteractor purchaseInteractor = RuStorePayClient.Companion.getInstance().getPurchaseInteractor();
 
purchaseInteractor.cancelTwoStepPurchase(
    new PurchaseId("purchaseId")
).addOnSuccessListener(success -> {
    // Process success
}).addOnFailureListener(throwable -> {
    // Process error
});

purchaseId — идентификатор покупки.

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

Kotlin
Java

Для получения информации о покупке, используйте метод getPurchase.

Вызов метода получения покупки пользователя
RuStorePayClient.instance.getPurchaseInteractor().getPurchase(PurchaseId("purchaseId"))
     .addOnSuccessListener { purchase: Purchase ->
        // Process success
    }
    .addOnFailureListener { throwable: Throwable ->
        // Process error
    }

Метод возвращает информацию о конкретной покупке в любом статусе. Ниже представлена модель покупки.

Структура с информацией о покупке
public class Purchase internal constructor(
    public val purchaseId: PurchaseId,
    public val productId: ProductId,
    public val invoiceId: InvoiceId,
    public val orderId: OrderId?,
    public val purchaseType: PurchaseType,
    public val productType: ProductType,
    public val description: Description,
    public val purchaseTime: Date?,
    public val price: Price,
    public val amountLabel: AmountLabel,
    public val currency: Currency,
    public val quantity: Quantity,
    public val status: PurchaseStatus,
    public val developerPayload: DeveloperPayload?,
    public val sandbox: Boolean,
)

purchaseId — идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке.
productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
invoiceId — идентификатор счёта. Используется для серверной валидации платежа, поиска платежей в консоли разработчика, а также отображается покупателю в истории платежей в мобильном приложении RuStore.
orderId - уникальный идентификатор оплаты, указанный разработчиком или сформированный автоматически (uuid).
PurchaseType — тип покупки:
- ONE_STEP - одностадийная покупка;
- TWO_STEP - двухстадийная покупка;
- UNDEFINED - стадийность не определена.
productType — тип продукта. (CONSUMABLE/NON-CONSUMABLE - потребляемый/непотребляемый.)
description - описание покупки.
purchaseTime — время покупки.
price — цена в минимальных единицах (в копейках).
amountLabel — отформатированная цена покупки, включая валютный знак.
currency — код валюты ISO 4217.
quantity — количество продукта.
status — состояние покупки:
- INVOICE_CREATED — создан счёт на оплату, покупка ожидает оплаты;
- CANCELLED — покупка отменена покупателем;
- PROCESSING — запущена оплата;
- REJECTED — покупка отклонена (например, ввиду недостатка средств);
- EXPIRED — истекло время на оплату покупки;
- PAID — только для двухстадийной оплаты, промежуточный статус, средства на счёте покупателя захолдированы, покупка ожидает подтверждения от разработчика;
- CONFIRMED — покупка успешно оплачена;
- REFUNDING — инициирован возврат, запрос отправлен в эквайер;
- REFUNDED — запрос на возврат средств за покупку совершён успешно;
- REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 6 часов, холдирование средств отменено.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации
sandbox — флаг тестового платежа. Значение true — тестовый платёж, false— реальный платёж.

Пример ответа.

Пример модели покупки потребляемого продукта
Purchase(
    purchaseId = PurchaseId("purchaseId"),
    productId = ProductId("productId"),
    invoiceId = InvoiceId("invoiceId"),
    orderId = OrderId("orderId"),
    purchaseType = PurchaseType.ONE_STEP,
    productType = ProductType.CONSUMABLE_PRODUCT,
    description = Description("description"),
    purchaseTime = Date(123123123124),
    price = Price(14100),
    amountLabel = AmountLabel("141,00 ₽"),
    currency = Currency("RUB"),
    quantity = Quantity(1),
    status = PurchaseStatus.CONFIRMED,
    developerPayload = DeveloperPayload("developerPayload"),
    sandbox = false,
)

Для получения информации о покупке, используйте метод getPurchase.

Вызов метода получения покупки пользователя
PurchaseInteractor purchaseInteractor = RuStorePayClient.Companion.getInstance().getPurchaseInteractor();
 
purchaseInteractor.getPurchase(new PurchaseId("purchaseId"))
    .addOnSuccessListener(purchase -> {
        // Process success
    })
    .addOnFailureListener(throwable -> {
        // Process error
    });

Метод возвращает информацию о конкретной покупке в любом статусе. Ниже представлена модель покупки.

Структура с информацией о покупке
public class Purchase {
    private final PurchaseId purchaseId;
    private final ProductId productId;
    private final InvoiceId invoiceId;
    private final OrderId orderId;
    private final PurchaseType purchaseType;
    private final ProductType productType;
    private final Description description;
    private final Date purchaseTime;
    private final Price price;
    private final AmountLabel amountLabel;
    private final Currency currency;
    private final Quantity quantity;
    private final PurchaseStatus status;
    private final DeveloperPayload developerPayload;
    private boolean sandbox;
 
    public Purchase(PurchaseId purchaseId, ProductId productId, InvoiceId invoiceId, OrderId orderId, PurchaseType purchaseType, ProductType productType, Description description, Date purchaseTime, Price price, AmountLabel amountLabel, Currency currency, Quantity quantity, PurchaseStatus status, @Nullable DeveloperPayload developerPayload, boolean sandbox) {
        this.purchaseId = purchaseId;
        this.productId = productId;
        this.invoiceId = invoiceId;
        this.orderId = orderId;
        this.type = type;
        this.description = description;
        this.purchaseTime = purchaseTime;
        this.price = price;
        this.amountLabel = amountLabel;
        this.currency = currency;
        this.quantity = quantity;
        this.status = status;
        this.developerPayload = developerPayload;
        this.sandbox = sandbox;
    }
 
    public PurchaseId getPurchaseId() {
        return purchaseId;
    }
 
    public ProductId getProductId() {
        return productId;
    }
 
    public InvoiceId getinvoiceId() {
        return invoiceId;
    }
 
    public @Nullable OrderId getOrderId() {
        return orderId;
    }
 
    public PurchaseType getPurchaseType() {
        return purchaseType;
    }
 
    public ProductType getProductType() {
        return productType;
    }
 
    public Description getDescription() {
        return description;
    }
 
    public Date getPurchaseTime() {
        return purchaseTime;
    }
 
    public Price getPrice() {
        return price;
    }
 
    public AmountLabel getAmountLabel() {
        return amountLabel;
    }
 
    public Currency getCurrency() {
        return currency;
    }
 
    public Quantity getQuantity() {
        return quantity;
    }
 
    public PurchaseStatus getStatus() {
        return status;
    }
 
    public @Nullable DeveloperPayload getDeveloperPayload() {
        return developerPayload;
    }
 
    public boolean isSandbox() {
        return sandbox;
    }
}

purchaseId — идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке.
productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
invoiceId — идентификатор счёта. Используется для серверной валидации платежа, поиска платежей в консоли разработчика, а также отображается покупателю в истории платежей в мобильном приложении RuStore.
orderId - уникальный идентификатор оплаты, указанный разработчиком или сформированный автоматически (uuid).
PurchaseType — тип покупки:
- ONE_STEP - одностадийная покупка;
- TWO_STEP - двухстадийная покупка;
- UNDEFINED - стадийность не определена.
productType — тип продукта. (CONSUMABLE/NON-CONSUMABLE - потребляемый/непотребляемый.)
description - описание покупки.
purchaseTime — время покупки.
price — цена в минимальных единицах (в копейках).
amountLabel — отформатированная цена покупки, включая валютный знак.
currency — код валюты ISO 4217.
quantity — количество продукта.
status — состояние покупки:
- INVOICE_CREATED — создан счёт на оплату, покупка ожидает оплаты;
- CANCELLED — покупка отменена покупателем;
- PROCESSING — запущена оплата;
- REJECTED — покупка отклонена (например, ввиду недостатка средств);
- EXPIRED — истекло время на оплату покупки;
- PAID — только для двухстадийной оплаты, промежуточный статус, средства на счёте покупателя захолдированы, покупка ожидает подтверждения от разработчика;
- CONFIRMED — покупка успешно оплачена;
- REFUNDING — инициирован возврат, запрос отправлен в эквайер;
- REFUNDED — запрос на возврат средств за покупку совершён успешно;
- REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 6 часов, холдирование средств отменено.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации
sandbox — флаг тестового платежа. Значение true — тестовый платёж, false— реальный платёж.

Пример ответа.

Пример модели покупки потребляемого продукта
Purchase(
    purchaseId = PurchaseId("purchaseId"),
    productId = ProductId("productId"),
    invoiceId = InvoiceId("invoiceId"),
    orderId = OrderId("orderId"),
    purchaseType = PurchaseType.ONE_STEP,
    productType = ProductType.CONSUMABLE_PRODUCT,
    description = Description("description"),
    purchaseTime = Date(123123123124),
    price = Price(14100),
    amountLabel = AmountLabel("141,00 ₽"),
    currency = Currency("RUB"),
    quantity = Quantity(1),
    status = PurchaseStatus.CONFIRMED,
    developerPayload = DeveloperPayload("developerPayload"),
    sandbox = false,
)

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

Kotlin
Java

Для получения списка покупок пользователя используйте метод getPurchases.

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

Данный метод поддерживает необязательную фильтрацию по типу товаров (потребляемые или непотреблямые товары), а также по статусу покупки (поддерживаются только статусы PAID и CONFIRMED). По умолчанию фильтр выключен и вернет все покупки пользователя (вне зависимости от типа товара) в статусах PAID и CONFIRMED. Статус PAID означает успешное холдирование средств, покупка ожидает подтверждения покупки со стороны разработчика.

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

Ниже представлена модель покупки.

Структура с информацией о покупке
public class Purchase internal constructor(
    public val purchaseId: PurchaseId,
    public val productId: ProductId,
    public val invoiceId: InvoiceId,
    public val orderId: OrderId?,
    public val purchaseType: PurchaseType,
    public val productType: ProductType,
    public val description: Description,
    public val purchaseTime: Date?,
    public val price: Price,
    public val amountLabel: AmountLabel,
    public val currency: Currency,
    public val quantity: Quantity,
    public val status: PurchaseStatus,
    public val developerPayload: DeveloperPayload?,
    public val sandbox: Boolean,
)

purchaseId — идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке.
productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
invoiceId — идентификатор счёта. Используется для серверной валидации платежа, поиска платежей в консоли разработчика, а также отображается покупателю в истории платежей в мобильном приложении RuStore.
orderId - уникальный идентификатор оплаты, указанный разработчиком или сформированный автоматически (uuid).
PurchaseType — тип покупки:
- ONE_STEP - одностадийная покупка;
- TWO_STEP - двухстадийная покупка;
- UNDEFINED - стадийность не определена.
productType — тип продукта. (CONSUMABLE/NON-CONSUMABLE - потребляемый/непотребляемый.)
description - описание покупки.
purchaseTime — время покупки.
price — цена в минимальных единицах (в копейках).
amountLabel — отформатированная цена покупки, включая валютный знак.
currency — код валюты ISO 4217.
quantity — количество продукта.
status — состояние покупки:
- INVOICE_CREATED — создан счёт на оплату, покупка ожидает оплаты;
- CANCELLED — покупка отменена покупателем;
- PROCESSING — запущена оплата;
- REJECTED — покупка отклонена (например, ввиду недостатка средств);
- EXPIRED — истекло время на оплату покупки;
- PAID — только для двухстадийной оплаты, промежуточный статус, средства на счёте покупателя захолдированы, покупка ожидает подтверждения от разработчика;
- CONFIRMED — покупка успешно оплачена;
- REFUNDING — инициирован возврат, запрос отправлен в эквайер;
- REFUNDED — запрос на возврат средств за покупку совершён успешно;
- REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 6 часов, холдирование средств отменено.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации
sandbox — флаг тестового платежа. Значение true — тестовый платёж, false— реальный платёж.

Для получения списка покупок пользователя используйте метод getPurchases.

Вызов метода получения списка покупок пользователя
PurchaseInteractor purchaseInteractor = RuStorePayClient.Companion.getInstance().getPurchaseInteractor();
 
purchaseInteractor.getPurchases(null)
    .addOnSuccessListener(purchases -> {
        // Process PaymentResult
    })
    .addOnFailureListener(error -> {
        // Process error
    });

Данный метод поддерживает необязательную фильтрацию по типу товаров (потребляемые или непотреблямые товары), а также по статусу покупки (поддерживаются только статусы PAID и CONFIRMED).. По умолчанию фильтр выключен и вернет все покупки пользователя (вне зависимости от типа товара) в статусах PAID и CONFIRMED. Статус PAID означает успешное холдирование средств, покупка ожидает подтверждения покупки со стороны разработчика.

Вызов метода получения списка покупок пользователя с фильтрацией
PurchaseInteractor purchaseInteractor = RuStorePayClient.Companion.getInstance().getPurchaseInteractor();
 
purchaseInteractor.getPurchases(ProductType.CONSUMABLE_PRODUCT, PurchaseStatus.PAID)
    .addOnSuccessListener(purchases -> {
        // Process PaymentResult
    })
    .addOnFailureListener(error -> {
        // Process error
    });

Ниже представлена модель покупки.

Структура с информацией о покупке
public class Purchase {
    private final PurchaseId purchaseId;
    private final ProductId productId;
    private final InvoiceId invoiceId;
    private final OrderId orderId;
    private final PurchaseType purchaseType;
    private final ProductType productType;
    private final Description description;
    private final Date purchaseTime;
    private final Price price;
    private final AmountLabel amountLabel;
    private final Currency currency;
    private final Quantity quantity;
    private final PurchaseStatus status;
    private final DeveloperPayload developerPayload;
    private boolean sandbox;
 
    public Purchase(PurchaseId purchaseId, ProductId productId, InvoiceId invoiceId, OrderId orderId, PurchaseType purchaseType, ProductType productType, Description description, Date purchaseTime, Price price, AmountLabel amountLabel, Currency currency, Quantity quantity, PurchaseStatus status, @Nullable DeveloperPayload developerPayload, boolean sandbox) {
        this.purchaseId = purchaseId;
        this.productId = productId;
        this.invoiceId = invoiceId;
        this.orderId = orderId;
        this.type = type;
        this.description = description;
        this.purchaseTime = purchaseTime;
        this.price = price;
        this.amountLabel = amountLabel;
        this.currency = currency;
        this.quantity = quantity;
        this.status = status;
        this.developerPayload = developerPayload;
        this.sandbox = sandbox;
    }
 
    public PurchaseId getPurchaseId() {
        return purchaseId;
    }
 
    public ProductId getProductId() {
        return productId;
    }
 
    public InvoiceId getInvoiceId() {
        return invoiceId;
    }
 
    public @Nullable OrderId getOrderId() {
        return orderId;
    }
 
    public PurchaseType getPurchaseType() {
        return purchaseType;
    }
 
    public ProductType getProductType() {
        return productType;
    }
 
    public Description getDescription() {
        return description;
    }
 
    public Date getPurchaseTime() {
        return purchaseTime;
    }
 
    public Price getPrice() {
        return price;
    }
 
    public AmountLabel getAmountLabel() {
        return amountLabel;
    }
 
    public Currency getCurrency() {
        return currency;
    }
 
    public Quantity getQuantity() {
        return quantity;
    }
 
    public PurchaseStatus getStatus() {
        return status;
    }
 
    public @Nullable DeveloperPayload getDeveloperPayload() {
        return developerPayload;
    }
 
    public boolean isSandbox() {
        return sandbox;
    }
}

purchaseId — идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке.
productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
invoiceId — идентификатор счёта. Используется для серверной валидации платежа, поиска платежей в консоли разработчика, а также отображается покупателю в истории платежей в мобильном приложении RuStore.
orderId - уникальный идентификатор оплаты, указанный разработчиком или сформированный автоматически (uuid).
PurchaseType — тип покупки:
- ONE_STEP - одностадийная покупка;
- TWO_STEP - двухстадийная покупка;
- UNDEFINED - стадийность не определена.
productType — тип продукта. (CONSUMABLE/NON-CONSUMABLE - потребляемый/непотребляемый.)
description - описание покупки.
purchaseTime — время покупки.
price — цена в минимальных единицах (в копейках).
amountLabel — отформатированная цена покупки, включая валютный знак.
currency — код валюты ISO 4217.
quantity — количество продукта.
status — состояние покупки:
- INVOICE_CREATED — создан счёт на оплату, покупка ожидает оплаты;
- CANCELLED — покупка отменена покупателем;
- PROCESSING — запущена оплата;
- REJECTED — покупка отклонена (например, ввиду недостатка средств);
- EXPIRED — истекло время на оплату покупки;
- PAID — только для двухстадийной оплаты, промежуточный статус, средства на счёте покупателя захолдированы, покупка ожидает подтверждения от разработчика;
- CONFIRMED — покупка успешно оплачена;
- REFUNDING — инициирован возврат, запрос отправлен в эквайер;
- REFUNDED — запрос на возврат средств за покупку совершён успешно;
- REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 6 часов, холдирование средств отменено.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации
sandbox — флаг тестового платежа. Значение true — тестовый платёж, false— реальный платёж.

Проверка наличия RuStore на устройстве

Метод isRuStoreInstalled применяется для проверки, установлен ли RuStore на устройстве пользователя. Эта проверка нужна для реализации корректной логики работы с товарами и покупками. Приведённые ниже методы SDK платежей требуют авторизации пользователя:

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

Если на устройстве пользователя не установлен RuStore, всякий раз будет отображаться шторка веб-авторизаци, что может негативно сказаться на пользовательском опыте. Таким образом, если проверка показывает, что приложение RuStore устройстве пользователя не установлено, имеет смысл сократить количество запросов, которые требуют авторизации (подробнее см. в разделе Приём платежей без установки RuStore).

Kotlin
Java

public fun isRuStoreInstalled(context: Context): Boolean

RuStoreUtils.INSTANCE.isRuStoreInstalled(context);

Определение наличия авторизации у пользователя

Для проверки статуса авторизации пользователя, вызовите метод getUserAuthorizationStatus у UserInteractor. Результатом выполнения метода является класс UserAuthorizationStatus. Доступно 2 значения:

AUTHORIZED - пользователь авторизован в RuStore
UNAUTHORIZED - пользователь неавторизован в RuStore. Данное значение также вернется если у пользователя нет установленного RuStore на девайсе.

Kotlin
Java

RuStorePayClient.instance.getUserInteractor().getUserAuthorizationStatus()
    .addOnSuccessListener { result ->
        when (result) {
            UserAuthorizationStatus.AUTHORIZED -> {
                 // Логика когда пользователь авторизован в RuStore
            }
 
            UserAuthorizationStatus.UNAUTHORIZED -> {
                // Логика когда пользователь НЕ авторизован в RuStore
            }
        }
    }.addOnFailureListener { throwable ->
        // Обработка ошибки
    }

UserInteractor userInteractor = RuStorePayClient.Companion.getInstance().getUserInteractor();
userInteractor.getUserAuthorizationStatus()
    .addOnSuccessListener(status -> {
        switch (status) {
            case AUTHORIZED:
                // Логика когда пользователь авторизован в RuStore
                break;
            case UNAUTHORIZED:
                // Логика когда пользователь НЕ авторизован в RuStore
                break;
            }
    })
    .addOnFailureListener(throwable -> {
        // Обработка ошибки
    });

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

Для проверки доступности платежей, вызовите метод getPurchaseAvailability у PurchaseInteractor. При его вызове проверяются следующие условия.

У компании подключена монетизация через консоль разработчика RuStore.
Приложение не должно быть заблокировано в RuStore.
Пользователь не должен быть заблокирован в RuStore.

Если все условия выполняются, возвращается PurchaseAvailabilityResult.Available. Иначе, возвращается PurchaseAvailabilityResult.Unavailable(val cause: Throwable), где cause - это ошибка о невыполненном условии. Для проверки причины возвращения такого результата нужно проверить тип ошибки на RuStoreException (данные ошибки описаны в разделе Обработка ошибок).

Kotlin
Java

Вызов метода getPurchaseAvailability
RuStorePayClient.instance.getPurchaseInteractor().getPurchaseAvailability()
    .addOnSuccessListener { result ->
        when (result) {
            is PurchaseAvailabilityResult.Available -> {
                 // Process purchases available 
            }
 
            is PurchaseAvailabilityResult.Unavailable -> {
                // Process purchases unavailable
            }
        }
    }
    .addOnFailureListener { throwable ->
        // Process failure error
    }

Вызов метода getPurchaseAvailability
PurchaseInteractor purchaseInteractor = RuStorePayClient.Companion.getInstance().getPurchaseInteractor();

purchaseInteractor.getPurchaseAvailability()
    .addOnSuccessListener(result -> {
        if (result instanceof PurchaseAvailabilityResult.Available) {
            // Process purchases available
        } else if (result instanceof PurchaseAvailabilityResult.Unavailable) {
            RuStoreException exception = ((PurchaseAvailabilityResult.Unavailable) result).getCause();
            // Process purchases unavailable
    })
    .addOnFailureListener(throwable -> {
        // Process errors
    });

Статусная модель покупки

Статусная модель одностадийного платежа.

Статусная модель двухстадийного платежа.

Структура результата покупки

ProductPurchaseResult - результат успешной оплаты цифрового товара (для одностадийной оплаты) или успешного холдирования средств (для двухстадийной оплаты).

Kotlin
Java

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 quantity: Quantity,
public val sandbox: Boolean,
)

public class ProductPurchaseResult {
private final OrderId orderId;
private final PurchaseId purchaseId;
private final ProductId productId;
private final InvoiceId invoiceId;
private final PurchaseType purchaseType;
private final Quantity quantity;
private final boolean sandbox;

public ProductPurchaseResult(OrderId orderId,
                             PurchaseId purchaseId,
                             ProductId productId,
                             InvoiceId invoiceId,
                             PurchaseType purchaseType,
                             Quantity quantity,
                             boolean sandbox) {
    this.orderId = orderId;
    this.purchaseId = purchaseId;
    this.productId = productId;
    this.invoiceId = invoiceId;
    this.purchaseType = purchaseType;
    this.quantity = quantity;
    this.sandbox = sandbox;
}

public OrderId getOrderId() {
    return orderId;
}

public PurchaseId getPurchaseId() {
    return purchaseId;
}

public ProductId getProductId() {
    return productId;
}

public InvoiceId getInvoiceId() {
    return invoiceId;
}

public PurchaseType getPurchaseType() {
    return purchaseType;
}

public Quantity getQuantity() {
    return quantity;
}

public boolean isSandbox() {
    return sandbox;
}
}

ProductPurchaseResult — результат успешной оплаты цифрового товара (для одностадийной оплаты) или успешного холдирования средств (для двухстадийной оплаты).
- purchaseId - идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке.
- productId - идентификатор приобретенного продукта, указанный при создании в консоли разработчика RuStore.
- invoiceId - идентификатор счета. Используется для серверной валидации платежа, поиска платежей в консоли разработчика, а также отображается покупателю в истории платежей в мобильном приложении RuStore.
- orderId - уникальный идентификатор оплаты, указанный разработчиком или сформированный автоматически (uuid).
- purchaseType - тип покупки (ONE_STEP/TWO_STEP - одностадийная/двухстадийная).
- quantity - количество продуктов - опционально. Если не указывать, то будет подставлено значение 1. Применимо только для покупки потребляемых товаров.
- sandbox - флаг, указывающий признак тестового платежа в песочнице. Если TRUE - покупка совершена в режиме тестирования.

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

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

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

Структура ошибки и отмены покупки:

Kotlin
Java

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 sandbox: Boolean?,
    public override val cause: Throwable,
) : RustorePaymentException(message = "Error purchase product", cause = cause)
 
public class ProductPurchaseCancelled internal constructor(
    public val purchaseId: PurchaseId?,
    public val purchaseType: PurchaseType?,
)

public class ProductPurchaseException extends RuStorePaymentException {
    private final OrderId orderId;
    private final PurchaseId purchaseId;
    private final ProductId productId;
    private final InvoiceId invoiceId;
    private final Quantity quantity;
    private final PurchaseType purchaseType;
    private final Boolean sandbox;
 
    public ProductPurchaseException(OrderId orderId,
                                    PurchaseId purchaseId,
                                    ProductId productId,
                                    InvoiceId invoiceId,
                                    Quantity quantity,
                                    PurchaseType purchaseType,
                                    Boolean sandbox,
                                    Throwable cause) {
        super("Error purchase product", cause);
        this.orderId = orderId;
        this.purchaseId = purchaseId;
        this.productId = productId;
        this.invoiceId = invoiceId;
        this.quantity = quantity;
        this.purchaseType = purchaseType;
        this.sandbox = sandbox;
    }
 
    public OrderId getOrderId() {
        return orderId;
    }
 
    public PurchaseId getPurchaseId() {
        return purchaseId;
    }
 
    public ProductId getProductId() {
        return productId;
    }
 
    public InvoiceId getInvoiceId() {
        return invoiceId;
    }
 
    public Quantity getQuantity() {
        return quantity;
    }
 
    public PurchaseType getPurchaseType() {
        return purchaseType;
    }
 
    public Boolean getSandbox() {
        return sandbox;
    }
}
 
 
public class ProductPurchaseCancelled {
    private final PurchaseId purchaseId;
    private final PurchaseType purchaseType;
 
    public ProductPurchaseCancelled(PurchaseId purchaseId, PurchaseType purchaseType) {
        this.purchaseId = purchaseId;
        this.purchaseType = purchaseType;
    }
 
    public PurchaseId getPurchaseId() {
        return purchaseId;
    }
 
    public PurchaseType getPurchaseType() {
        return purchaseType;
    }
}

purchaseId — идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке.
productId — идентификатор приобретённого продукта, указанный при создании в консоли разработчика RuStore.
invoiceId — идентификатор счёта. Используется для серверной валидации платежа, поиска платежей в консоли разработчика, а также отображается покупателю в истории платежей в мобильном приложении RuStore.
orderId — уникальный идентификатор оплаты, указанный разработчиком или сформированный автоматически (uuid).
purchaseType — тип покупки (ONE_STEP/TWO_STEP — одностадийная/двухстадийная).
quantity — количество продуктов - опционально. Если не указывать, то будет подставлено значение 1. Применимо только для покупки потребляемых товаров.

ProductPurchaseCancelled — отмена покупки цифрового товара. Платёжный диалог был закрыт до получения результата покупки, поэтому состояние покупки неизвестно. Рекомендуется запросить статус покупки отдельно методом получения информации о покупке.

Kotlin
Java

public class ProductPurchaseCancelled internal constructor(
    public val purchaseId: PurchaseId?,
    public val purchaseType: PurchaseType?,
) : RuStorePaymentException(message = "Purchase product is cancelled")

public class ProductPurchaseCancelled extends RuStorePaymentException {
    private final PurchaseId purchaseId;
    private final PurchaseType purchaseType;
 
    public ProductPurchaseCancelled(PurchaseId purchaseId, PurchaseType purchaseType) {
        super("Purchase product is cancelled");
        this.purchaseId = purchaseId;
        this.purchaseType = purchaseType;
    }
 
    public PurchaseId getPurchaseId() {
        return purchaseId;
    }
 
    public PurchaseType getPurchaseType() {
        return purchaseType;
    }
}

purchaseId — идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке.
purchaseType — тип покупки (ONE_STEP/TWO_STEP — одностадийная/двухстадийная).

Валидация покупки на сервере

Kotlin
Java

Если вам необходимо произвести валидацию успешной покупки на сервере RuStore, вы можете использовать invoiceId из модели ProductPurchaseResult, возвращаемой при успешной покупке продукта.

Получение invoiceId из результата покупки
val params = ProductPurchaseParams(ProductId("productId"))
 
RuStorePayClient.instance.getPurchaseInteractor()
    .purchase(params = params, preferredPurchaseType = PreferredPurchaseType.TWO_STEP)
    .addOnSuccessListener { result ->
        val invoceId = result.invoceId.value
        yourApi.validate(invoceId)
    }

Также можно получить invoiceId в модели Purchase. Модель Purchase можно получить используя метод getPurchases() или метод getPurchase.

Получение subscriptionToken из результата покупки
RuStorePayClient.instance.getPurchaseInteractor().getPurchases()
    .addOnSuccessListener { purchases ->
        purchases.forEach { purchase ->
            yourApi.validate(purchase.invoiceId.value)
        }
    }

Получение subscriptionToken из результата покупки
ProductInteractor productInteractor = RuStorePayClient.Companion.getInstance().getProductInteractor();
ProductPurchaseParams params = new ProductPurchaseParams(new ProductId("productId"), null, null, null);
 
productInteractor.purchase(params, PreferredPurchaseType.TWO_STEP)
    .addOnSuccessListener(result -> {
        String invoceId = successResult.getInvoceId().getValue();
        yourApi.validate(invoceId);
    });

Получение subscriptionToken из результата покупки
PurchaseInteractor purchaseInteractor = RuStorePayClient.Companion.getInstance().getPurchaseInteractor();
 
purchaseInteractor.getPurchases()
    .addOnSuccessListener(purchases -> {
        for (Purchase purchase : purchases) {
            yourApi.validate(purchase.getInvoceId().getValue());
        }
    })
    .addOnFailureListener(error -> {
        // Process error
    });

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

Kotlin
Java

Вызов метода подтверждения
RuStorePayClient.instance.getPurchaseInteractor().confirmTwoStepPurchase(
    purchaseId = PurchaseId("purchaseId"),
    developerPayload = null,
    )
    .addOnSuccessListener {
        // Process success
    }.addOnFailureListener { throwable: Throwable ->
        // Process error
    }

purchaseId — идентификатор покупки.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимум 250 символов. Если передан, заменяет значение, записанное при старте покупки методом purchase/purchaseTwoStep.

Вызов метода подтверждения
PurchaseInteractor purchaseInteractor = RuStorePayClient.Companion.getInstance().getPurchaseInteractor();
 
purchaseInteractor.confirmTwoStepPurchase(
    new PurchaseId("purchaseId"),
    null
).addOnSuccessListener( success -> {
    // Process success
}).addOnFailureListener(throwable -> {
    // Process error
});

purchaseId — идентификатор покупки.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимум 250 символов. Если передан, заменяет значение, записанное при старте покупки методом purchase/purchaseTwoStep.

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

提示

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

Kotlin
Java

RuStorePayClient.instance.getPurchaseInteractor().cancelTwoStepPurchase(
    purchaseId = PurchaseId("purchaseId"),
    )
    .addOnSuccessListener {
        // Process success
    }.addOnFailureListener { throwable: Throwable ->
        // Process error
    }

purchaseId — идентификатор покупки.

PurchaseInteractor purchaseInteractor = RuStorePayClient.Companion.getInstance().getPurchaseInteractor();
 
purchaseInteractor.cancelTwoStepPurchase(
    new PurchaseId("purchaseId")
).addOnSuccessListener(success -> {
    // Process success
}).addOnFailureListener(throwable -> {
    // Process error
});

purchaseId — идентификатор покупки.

Список ошибок

RuStorePaymentNetworkException - ошибка сетевого взаимодействия SDK. В модели ошибки возвращается код ошибки (поле code), по которому можно определить причину ошибки. Таблица с кодами ошибок доступна в разделе коды ошибок.

Поле message содержит описание причины ошибки.

Kotlin
Java

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)  

public class RuStorePaymentNetworkException extends RuStorePaymentException {  
    private final String code;  
    private final String id;

    public RuStorePaymentNetworkException(  
            String code,  
            String id,  
            String message,  
            Throwable cause  
    ) {  
        super(message, cause);  
        this.code \= code;  
        this.id \= id;  
    }

    public String getCode() {  
        return code;  
    }

    public String getId() {  
        return id;  
    }  
}

RuStorePaymentNetworkException — ошибка сетевого взаимодействия SDK;
RuStorePaymentCommonException — общая ошибка SDK;
RuStorePayClientAlreadyExist — ошибка повторной инициализации SDK;
RuStorePayClientNotCreated — попытка обратиться к публичным интерфейсам SDK до момента её инициализации;
RuStorePayInvalidActivePurchase — запущен процесс оплаты неизвестного типа продукта;
RuStorePayInvalidConsoleAppId — не задан обязательный параметр console_application_id для инициализации SDK;
RuStorePaySignatureException — неверная сигнатура ответа. Возникает при попытке совершить мошеннические действия;
EmptyPaymentTokenException — ошибка получения платёжного токена;
InvalidCardBindingIdException — ошибка оплаты сохранённой картой;
ApplicationSchemeWasNotProvided — не указана схема для обратного диплинка;
ProductPurchaseException - ошибка покупки продукта. Структура модели представлена в разделе структура результата покупки;
ProductPurchaseCancelled - произошла отмена покупки продукта (пользователь закрыл платёжную шторку). Структура модели представлена в разделе структура результата покупки;
ProductPurchaseException — ошибка покупки продукта;
RuStoreNotInstalledException — на устройстве пользователя не установлен RuStore;
RuStoreOutdatedException — установленная на устройстве версия RuStore не поддерживает платежи;
RuStoreUserUnauthorizedException — пользователь не авторизован в RuStore;
RuStoreApplicationBannedException — приложение заблокировано в RuStore;
RuStoreUserBannedException — пользователь заблокирован в RuStore.

Коды ошибок

Код ошибки	Описание
`4000001`	Запрос сформирован некорректно: отсутствует или неверно заполнен обязательный параметр, неверный формат данных.
`4000002`, `4000016`, `4040005`	Приложение не найдено.
`4000003`	Приложение заблокировано.
`4000004`	Подпись приложения не совпадает с зарегистрированной.
`4000005`	Компания не найдена.
`4000006`	Компания заблокирована.
`4000007`	Монетизация компании отключена или неактивна.
`4000014`	Продукт не найден.
`4000015`	Продукт не опубликован.
`4000017`	Некорректный параметр `quantity`.
`4000018`	Превышен лимит покупок.
`4000020`	Продукт уже приобретен.
`4000021`	Незавершенная покупка продукта.
`4000022`	Покупка не найдена.
`4000025`	Не найден подходящий способ оплаты.
`4000026`	Неверный тип покупки для подтверждения (должна быть двухстадийная оплата).
`4000027`	Неверный статус покупки для подтверждения.
`4000028`	Неверный тип покупки для отмены (должна быть двухстадийная оплата).
`4000029`	Неверный статус покупки для отмены.
`4000030`	Выписанный токен не соответствует покупаемому товару.
`4010001`	Доступ к запрашиваему ресурсу запрещен (неавторизовано).
`4010002`	Время жизни токена истекло.
`4010003`	Платежный токен невалиден.
`4030001`	Не передан платежный токен.
`4030002`	Пользователь заблокирован по требованиям безопасности.
`4040002`, `4040003`, `4040004`	Ошибка платежной системы.
`5000***`	Внутренняя ошибка.

SDK Платежи in-app для Kotlin/Java (версия 9.0.1)

Подготовка к работе​

Обработка deeplink​

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

Методы SDK​

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

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

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

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

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

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

Проверка наличия RuStore на устройстве​

Определение наличия авторизации у пользователя​

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

Статусная модель покупки​

Структура результата покупки​

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

Валидация покупки на сервере​

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

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

Список ошибок​

Коды ошибок​

Подготовка к работе

Обработка deeplink

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

Методы SDK

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

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

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

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

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

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

Проверка наличия RuStore на устройстве

Определение наличия авторизации у пользователя

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

Статусная модель покупки

Структура результата покупки

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

Валидация покупки на сервере

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

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

Список ошибок

Коды ошибок