10.3.1 (актуальная версия)

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

подсказка

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

Пример реализации

Ознакомьтесь с проектом-примером, чтобы узнать, как правильно интегрировать SDK платежей.

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

Установка плагинов

Перейдите в раздел Релизы репозитория проекта на GitFlic.
Скачайте из выбранного релиза артефакт:
- ru.rustore.pay.zip
Распакуйте скачанный архив.

Для сборки Android-приложения и работы с нативными функциями ОС Construct использует фреймворк Cordova.

Убедитесь, что у вас установлен фреймворк Cordova версии не ниже 12.0.0.

cordova -v

Перейдите в корневую папку вашего Cordova-проекта и выполните команду:

cordova plugin add /путь_к_папке_плагина/ru.rustore.pay

После установки проверьте наличие плагина с помощью команды:

cordova plugin list

В списке должен появиться плагин ru.rustore.pay.

Плагин требует, чтобы вы разместили свои данные для инициализации в файле rustore_pay_strings.xml расположенном в папке ru.rustore.pay / src / android / res / values.

Создайте или отредактируйте этот файл, поместив туда необходимые параметры инициализации плагина.

После установки плагин автоматически добавит теги <meta-data> и дополнительную активити RuStoreIntentFilterActivity в AndroidManifest.xml в папке *your_cordova_project* / platforms / android / app / src / main.

Пример готового манифеста:

<?xml version='1.0' encoding='utf-8'?>
<manifest android:hardwareAccelerated="true" android:versionCode="10000" android:versionName="1.0.0" xmlns:android="http://schemas.android.com/apk/res/android">
    <supports-screens android:anyDensity="true" android:largeScreens="true" android:normalScreens="true" android:resizeable="true" android:smallScreens="true" android:xlargeScreens="true" />
    <uses-permission android:name="android.permission.INTERNET" />
    <application android:hardwareAccelerated="true" android:icon="@mipmap/ic_launcher" android:label="@string/app_name" android:supportsRtl="true">
        
        <!-- Game activity -->
        <activity android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation" android:exported="true" android:label="@string/activity_name" android:launchMode="singleTop" android:name="MainActivity" android:theme="@style/Theme.App.SplashScreen" android:windowSoftInputMode="adjustResize">
            <intent-filter android:label="@string/launcher_name">
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <provider android:authorities="${applicationId}.cdv.core.file.provider" android:exported="false" android:grantUriPermissions="true" android:name="androidx.core.content.FileProvider">
            <meta-data android:name="android.support.FILE_PROVIDER_PATHS" android:resource="@xml/cdv_core_file_provider_paths" />
        </provider>

        <!-- Deeplink Scheme -->
        <meta-data android:name="sdk_pay_scheme_value" android:value="@string/rustore_PayClientSettings_deeplinkScheme" />
        
        <!-- Initializing SDK -->
        <meta-data android:name="console_app_id_value" android:value="@string/rustore_PayClientSettings_consoleApplicationId" />
        <meta-data android:name="internal_config_key" android:value="@string/rustore_PayClientSettings_internalConfigKey" />
        
        <!-- Deeplink Activity -->
        <activity android:exported="true" android:name="ru.rustore.paybridge.RuStoreIntentFilterActivity" android:theme="@android:style/Theme.NoDisplay">
            <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="@string/rustore_PayClientSettings_deeplinkScheme" />
            </intent-filter>
        </activity>

    </application>
    <queries>
        <intent>
            <action android:name="android.media.action.IMAGE_CAPTURE" />
        </intent>
    </queries>
</manifest>

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

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

<!-- Initializing sdk -->
<meta-data android:name="console_app_id_value" android:value="@string/rustore_PayClientSettings_consoleApplicationId" />
<meta-data android:name="internal_config_key" android:value="@string/rustore_PayClientSettings_internalConfigKey" />

<!-- Deeplink Scheme -->
<meta-data android:name="sdk_pay_scheme_value" android:value="@string/rustore_PayClientSettings_deeplinkScheme" />

Значения тегов задаюся в файле rustore_pay_strings.xml расположенном в папке ru.rustore.pay / src / android / res / values.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="rustore_PayClientSettings_consoleApplicationId" translatable="false">1234567890</string>
    <string name="rustore_PayClientSettings_internalConfigKey" translatable="false">construct</string>
    <string name="rustore_PayClientSettings_deeplinkScheme" translatable="false">yourappscheme</string>
</resources>

consoleApplicationId — идентификатор приложения из RuStore консоли.

internalConfigKey — всегда должно иметь значение construct.

deeplinkScheme — уникальная схема deeplink.

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

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

Важно

Package Name и подпись Cordova-приложения, должены совпадать с Package Name и подписью приложения, которое вы публиковали в системе RuStore Консоль.

Внимание!

Не задавайте значения console_app_id_value и internal_config_key напрямую в манифесте. Строки должны располагаться в файле ресурсов.

Работа с SDK

Доступные публичные методы:

getPurchase — позволяет получить информацию о покупке по ее ID.
getPurchases — позволяет получить покупки пользователя. Данный метод поддерживает опциональную фильтрацию по типу товаров (потребляемые или непотребляемые товары), а также по статусу покупки (поддерживаются статусы PAID и CONFIRMED). По умолчанию фильтры отключены, и вернутся все покупки пользователя (независимо от типа товара) в статусах PAID и CONFIRMED.
getPurchaseAvailability — возвращает результат доступности работы с платежами.
purchase — позволяет совершить покупку продукта с указанием желаемого типа оплаты - одностадийной (ONE_STEP) или двухстадийной (TWO_STEP). Для данного метода оплаты на платежной шторке доступны все способы оплаты. Если параметр не задан, по умолчанию запускается с оплатой в одну стадию.

Важно!

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

purchaseTwoStep — запускает сценарий гарантированной двухстадийной покупки товара. При использовании данного метода пользователю на платежной шторке доступен ограниченный набор способов оплаты — только те, которые поддерживают двухстадийную оплату. В процессе платежа сначала осуществляется холдирование денежных средств покупателя, которые списываются только после подтверждения покупки методом confirmTwoStepPurchase.
confirmTwoStepPurchase — подтверждение покупки, совершенной по двухстадийной оплате.
cancelTwoStepPurchase — отмена покупки, совершенной по двухстадийной оплате.
getProducts — позволяет получить информацию по активным продуктам, опубликованным в RuStore консоль.

Важно

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

getUserAuthorizationStatus — проверяет статус авторизации пользователя.
isRuStoreInstalled — проверки наличия приложения RuStore на устройстве пользователя.
openRuStoreDownloadInstruction — открывает веб-страницу для скачивания приложения RuStore.
openRuStore — запускает приложение RuStore.
openRuStoreAuthorization — запускает приложение RuStore для авторизации. После успешной авторизации пользователя приложение RuStore автоматически закроется.

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

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

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

Если все указанные выше условия выполняются, возвращается PurchaseAvailabilityResult.isAvailable == true.

В противном случае возвращается PurchaseAvailabilityResult.isAvailable == false и PurchaseAvailabilityResult.cause, где cause — это ошибка о невыполненном условии (возможные ошибки описаны в разделе Список ошибок).

Вызов метода getPurchaseAvailability
cordova.plugins.RuStorePay.getPurchaseAvailability(
    function(result) {
        var data = JSON.parse(result);
        if (data.isAvailable === true) {
            // Process success
        } else {
            // Process data.cause
        }
    },
    function(error) {
        var data = JSON.parse(error);
        // Process error
    }
);

Проверка статуса авторизации пользователя

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

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

Вызов метода getUserAuthorizationStatus
cordova.plugins.RuStorePay.getUserAuthorizationStatus(
    function(result) {
        var data = JSON.parse(result);
        if (data.userAuthorizationStatus == cordova.plugins.RuStorePay.UserAuthorizationStatus.AUTHORIZED) {
            // Process AUTHORIZED
        } else {
            // Process UNAUTHORIZED
        }
    },
    function(error) {
        var data = JSON.parse(error);
        // Process error
    }
);

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

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

Вызов метода getProducts
var productIds = ["product_id1", "product_id2"];

cordova.plugins.RuStorePay.getProducts(
    productIds,
    function(result) {
        var data = JSON.parse(result);
        // Process success
    },
    function(error) {
        var data = JSON.parse(error);
        // Process error
    }
);

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

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

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

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

Модель продукта
{
    productId,       // string
    type,            // string cordova.plugins.RuStorePay.ProductType
    amountLabel,     // string
    price,           // number (optional)
    currency,        // string
    title,           // string
    description,     // string (optional)
    imageUrl,        // string
    subscriptionInfo // object (optional)
}

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

Модель информации о подписке
{
    periods // array
}

periods — cписок периодов подписки.

Модель периода подписки
{
    simpleName, // string
    duration,   // string
    currency,   // string (optional)
    price       // number (optional)
}

simpleName — тип периода (TrialPeriod/PromoPeriod/MainPeriod/GracePeriod/HoldPeriod).
duration — длительность периода в формате ISO 8601.
currency — код валюты ISO 4217.
price — Цена в минимальных единицах валюты.

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

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

Вызов метода получения списка покупок пользователя
var productType = null;	   // cordova.plugins.RuStorePay.ProductType
var purchaseStatus = null; // cordova.plugins.RuStorePay.ProductPurchaseStatus
                           // or cordova.plugins.RuStorePay.SubscriptionPurchaseStatus

cordova.plugins.RuStorePay.getPurchases(
    productType,
    purchaseStatus,
    function(result) {
        var data = JSON.parse(result);
        // Process success
    },
    function(error) {
        var data = JSON.parse(error);
        // Process error
    }
);

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

productType — типы товаров:

Потребляемые товары — ProductType.CONSUMABLE_PRODUCT
Непотребляемые товары — ProductType.NON_CONSUMABLE_PRODUCT
Подписки — ProductType.SUBSCRIPTION

purchaseStatus — статусы покупок:

Для продуктов:
- PAID: Успешное холдирование средств, покупка ожидает подтверждения со стороны разработчика.
- CONFIRMED: Покупка подтверждена, средства списаны.
Для подписок:
- ACTIVE: Подписка активна.
- PAUSED: Подписка в Hold периоде (например, из-за недостатка средств на карте), продолжаются попытки списания в соответствии с настройками тарифа подписки.

По умолчанию фильтры выключены, если значения не заданы, метод вернет все покупки пользователя в статусах PAID, CONFIRMED, ACTIVE и PAUSED, независимо от типа товара.

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

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

Вызов метода получения списка покупок пользователя
var purchaseId = ...

cordova.plugins.RuStorePay.getPurchase(
    purchaseId,
    function(result) {
        var data = JSON.parse(result);
        // Process success
    },
    function(error) {
        var data = JSON.parse(error);
        // Process error
    }
);

Типы покупок

В SDK предусмотрено две реализации типов покупок.

ProductPurchase: для потребляемых и непотребляемых покупок.
SubscriptionPurchase: для подписок.

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

Модель разовой покупки ProductPurchase

Модель ProductPurchase
{
    amountLabel,      // string
    currency,         // string
    description,      // string
    developerPayload, // string (optional)
    invoiceId,        // string
    orderId,          // string (optional)
    price,            // number
    productId,        // string
    productType,      // string cordova.plugins.RuStorePay.ProductType
    purchaseId,       // string
    purchaseTime,     // string (optional)
    purchaseType,     // string cordova.plugins.RuStorePay.PurchaseType
    quantity,         // number
    status,           // string cordova.plugins.RuStorePay.ProductPurchaseStatus
    sandbox           // boolean
}

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

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

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

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

Модель подписки

Модель SubscriptionPurchase
{
    purchaseId,         // string
    invoiceId,          // string
    orderId,            // string (optional)
    purchaseType,       // string cordova.plugins.RuStorePay.PurchaseType
    status,             // string cordova.plugins.RuStorePay.SubscriptionPurchaseStatus
    description,        // string
    purchaseTime,       // string (optional)
    price,              // number
    amountLabel,        // string
    currency,           // string
    developerPayload,   // string (optional)
    sandbox,            // boolean
    productId,          // string
    expirationDate,     // string
    gracePeriodEnabled, // boolean
}

purchaseId — идентификатор покупки. Идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке.
invoiceId — идентификатор счета. Идентификатор счета. Используется для серверной валидации платежа, поиска платежей в консоли разработчика, а также отображается покупателю в истории платежей.
orderId - уникальный идентификатор оплаты, указанный разработчиком или сформированный автоматически (uuid).
purchaseType — тип покупки:
- ONE_STEP - одностадийная покупка;
- TWO_STEP - двухстадийная покупка;
- UNDEFINED - стадийность не определена.
status — состояние подписки:
- INVOICE_CREATED — создан счет на оплату, подписка ожидает оплаты.
- CANCELLED — счет на оплату подписки отменен.
- EXPIRED — срок действия оплаты счета истек.
- PROCESSING — первый платеж по подписке в обработке.
- REJECTED — первый платеж по подписке отклонен. Подписка не оформлена.
- ACTIVE — подписка активна.
- PAUSED — подписка приостановлена из-за проблем с оплатой.
- TERMINATED — закончились попытки списания по подписке (все были неуспешными). Подписка закрыта автоматически из-за проблем с оплатой.
- CLOSED — подписка была отменена пользователем или разработчиком. Истек срок оплаченного периода, подписка закрыта.
description — описание покупки.
purchaseTime — время покупки.
price — цена в минимальных единицах (в копейках).
amountLabel — отформатированная цена покупки, включая валютный знак.
currency — код валюты ISO 4217.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимальная длина 250 символов. Символы не экранируются (при использовании кавычек требуется экранирование)
sandbox — флаг тестового платежа. Значение true — тестовый платеж, false— реальный платеж.
productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр). Идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
expirationDate — дата окончания действия подписки.
gracePeriodEnabled — флаг, указывающий, активен ли Grace-период для подписки.

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

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

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

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

Важно

Двухстадийная оплата доступна только для определенного набора способов оплаты (на текущий момент — только для карт и SberPay). Технологии СБП не поддерживают двухстадийную оплату. Если выбран способ оплаты, который не поддерживает холдирование, то покупка будет запущена по сценарию с одной стадией.

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

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

Вызов метода покупки продукта
const params = {
    productId: "productId"
    //quantity: 1,                      // optional
    //orderId: "order_456",             // optional
    //developerPayload: "payload_data", // optional
    //appUserId: "user123",             // optional
    //appUserEmail: "user@example.com", // optional
}
const json_params = JSON.stringify(params);
const preferred_purchase_type = cordova.plugins.RuStorePay.PreferredPurchaseType.ONE_STEP;
const sdk_theme = cordova.plugins.RuStorePay.SdkTheme.DARK;
const purchase_event_listener = null;

cordova.plugins.RuStorePay.purchase(
    json_params,
    preferred_purchase_type,
    sdk_theme,
    function(result) {
        var data = JSON.parse(result);
        // Process success
    },
    function(error) {
        var data = JSON.parse(result);
        switch(error.simpleName) {
            case "ProductPurchaseCancelled":
                // Process error
                break;
            case "ProductPurchaseException":
                // Process error
                break;
        }
    },
    purchase_event_listener
);

json_params — json параметров покупки продукта.
purchase_event_listener — желаемый тип покупки: одностадийная (ONE_STEP) или двухстадийная (TWO_STEP), по умолчанию ONE_STEP — опционально.
sdk_theme — цветовая тема платежной шторки. Доступны два варианта LIGHT и DARK (светлая и темная тема соотвественно), по умолчанию LIGHT — опционально.
purchase_event_listener — набор callback функций, позволяющий получать данные об invoiceId и purchaseId на разных этапах покупки — опционально.

Важно

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

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

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

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

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

к сведению

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

Вызов метода покупки продукта
const params = {
    productId: "productId"
    //quantity: 1,                      // optional
    //orderId: "order_456",             // optional
    //developerPayload: "payload_data", // optional
    //appUserId: "user123",             // optional
    //appUserEmail: "user@example.com", // optional
}
const json_params = JSON.stringify(params);
const sdk_theme = cordova.plugins.RuStorePay.SdkTheme.DARK;
const purchase_event_listener = null;

cordova.plugins.RuStorePay.purchaseTwoStep(
    json_params,
    sdk_theme,
    function(result) {
        var data = JSON.parse(result);
        // Process success
    },
    function(error) {
        var data = JSON.parse(result);
        switch(error.simpleName) {
            case "ProductPurchaseCancelled":
                // Process error
                break;
            case "ProductPurchaseException":
                // Process error
                break;
        }
    },
    purchase_event_listener
);

json_params — json параметров покупки продукта.
sdk_theme — цветовая тема платежной шторки. Доступны два варианта LIGHT и DARK (светлая и темная тема соотвественно), по умолчанию LIGHT — опционально.
purchase_event_listener — набор callback функций, позволяющий получать данные об invoiceId и purchaseId на разных этапах покупки — опционально.

Модель параметров покупки

Модель параметров покупки
{
    productId,        // string
    quantity,         // number (optional)
    orderId,          // string (optional)
    developerPayload, // string (optional)
    appUserId,        // string (optional)
    appUserEmail      // string (optional)
}

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

Работа с PurchaseEventListener

Данный интерфейс представляет из себя набор callback функций событий покупки, которые вызываются в процессе покупки.

Нативный интерфейс PurchaseEventListener
public class PurchaseEventListener {
    public Action<PurchaseId, InvoiceId> onPurchaseCreated;
    public Action<PurchaseId, InvoiceId> onPaymentStarted;
    public Action<PurchaseId, InvoiceId> onPayment;
    public Action<PurchaseId?, InvoiceId?> onPaymentFailed;
    public Action<PurchaseId?, InvoiceId?> onPurchaseCancelled;
}

onPurchaseCreated — событие создания покупки.
onPaymentStarted — событие старта покупки.
onPayment — событие успешного завершения покупки.
onPaymentFailed — событие неуспешного завершения покупки.
onPurchaseCancelled — событие отмены покупки.

Реализация передается в методы purchase и purchaseTwoStep. Благодаря данным уведомлениям можно получать данные о purchaseId и invoiceId на разных этапах покупки, чтобы взаимодействовать с этой информацией. Например, передать значение в аналитику или сделать запись в базу данных.

Пример использования PurchaseEventListener
const params = {
    productId: "productId"
}
const json_params = JSON.stringify(params);
const purchase_type = cordova.plugins.RuStorePay.PreferredPurchaseType.ONE_STEP;
const sdk_theme = cordova.plugins.RuStorePay.SdkTheme.LIGHT;
const purchaseEventListener = {
    onPurchaseCreated: (data) => {
        const obj = JSON.parse(data);
        const purchaseId = obj.purchaseId // string
        const invoiceId  = obj.invoiceId  // string
    },
    onPaymentStarted: (data) => {
        const obj = JSON.parse(data);
        const purchaseId = obj.purchaseId // string
        const invoiceId  = obj.invoiceId  // string
    },
    onPaymentCompleted: (data) => {
        const obj = JSON.parse(data);
        const purchaseId = obj.purchaseId // string
        const invoiceId  = obj.invoiceId  // string
    },
    onPaymentFailed: (data) => {
        const obj = JSON.parse(data);
        const purchaseId = obj.purchaseId ?? null;
        const invoiceId  = obj.invoiceId  ?? null;
    },
    onPurchaseCancelled: (data) => {
        const obj = JSON.parse(data);
        const purchaseId = obj.purchaseId ?? null;
        const invoiceId  = obj.invoiceId  ?? null;
    },
};

cordova.plugins.RuStorePay.purchase(
    json_params,
    purchase_type,
    sdk_theme,
    function(result) { },
    function(error) { },
    purchaseEventListener
);

productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
purchaseId — идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке. Параметр опциональный, может отсутствовать в событиях:
- onPaymentFailed.
- onPurchaseCancelled.
invoiceId — идентификатор счета. Используется для серверной валидации платежа, поиска платежей в консоли разработчика, а также отображается покупателю в истории платежей в мобильном приложении RuStore. Параметр опциональный, может отсутствовать в событиях:
- onPaymentFailed.
- onPurchaseCancelled.

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

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

{
    invoiceId,    // string
    orderId,      // string (optional)
    productId,    // string
    productType,  // string cordova.plugins.RuStorePay.ProductType
    purchaseId,   // string
    purchaseType, // string cordova.plugins.RuStorePay.PurchaseType
    quantity,     // number
    sandbox       // boolean
}

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

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

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

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

Модель ошибки оплаты

{
    simpleName,   // string
    invoiceId,    // string (optional)
    orderId,      // string (optional)
    productId,    // string (optional)
    productType,  // string cordova.plugins.RuStorePay.ProductType (optional)
    purchaseId,   // string (optional)
    purchaseType, // string cordova.plugins.RuStorePay.PurchaseType (optional)
    quantity,     // number (optional)
    sandbox       // boolean (optional)
}

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

Модель отмены оплаты

{
    simpleName,   // string
    productType,  // string cordova.plugins.RuStorePay.ProductType (optional)
    purchaseId,   // string (optional)
    purchaseType, // string cordova.plugins.RuStorePay.PurchaseType (optional)
}

simpleName — имя класса, содержит значение "ProductPurchaseCancelled".
purchaseId — идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке.
purchaseType — тип покупки (ONE_STEP/TWO_STEP/UNDEFINED — одностадийная/двухстадийная/стадийность не определена).
productType — тип продукта (NON_CONSUMABLE_PRODUCT - непотребляемый товар, CONSUMABLE_PRODUCT - потребляемый товар, SUBSCRIPTION - подписка).

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

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

Получение invoiceId из результата покупки
const params = {
    productId: product.productId
    //quantity: 1,                      // optional
    //orderId: "order_456",             // optional
    //developerPayload: "payload_data", // optional
    //appUserId: "user123",             // optional
    //appUserEmail: "user@example.com", // optional
}
const json_params = JSON.stringify(params);
const preferred_purchase_type = cordova.plugins.RuStorePay.PreferredPurchaseType.TWO_STEP;

cordova.plugins.RuStorePay.purchase(
    json_params,
    preferred_purchase_type,
    function(result) {
        var data = JSON.parse(result);
        var invoiceId = data.invoiceId;
        yourApi.validate(invoiceId);
    },
    function(error) {
        var data = JSON.parse(error);
        // Process error
    }
);

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

cordova.plugins.RuStorePay.getPurchases(
    null,
    null,
    function(result) {
        var data = JSON.parse(result);
        numbers.forEach((num) => {
            const invoiceId = item.invoiceId;
            yourApi.validate(invoiceId);
        });
    },
    function(error) {
        var data = JSON.parse(error);
        // Process error
    }
);

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

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

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

Вызов метода подтверждения покупки
var purchaseId = ...
var developerPayload = "";

cordova.plugins.RuStorePay.confirmTwoStepPurchase(
    purchaseId,
    function() {
        // Process success
    },
    function(error) {
        var data = JSON.parse(error);
        // Process error
    }
);

purchaseId — идентификатор покупки.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимальная длина 250 символов. Символы не экранируются (при использовании кавычек требуется экранирование) (опционально). Максимум 250 символов (символы не экранируются). Если передан, заменяет значение, записанное при старте покупки методом Purchase/PurchaseTwoStep.

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

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

подсказка

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

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

Вызов метода отмены покупки
var purchaseId = ...

cordova.plugins.RuStorePay.cancelTwoStepPurchase(
    purchaseId,
    function() {
        // Process success
    },
    function(error) {
        var data = JSON.parse(error);
        // Process error
    }
);

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

RuStoreUtils

RuStoreUtils — это блок в нативном SDK, содержащий набор публичных методов, предназначенных для взаимодействия с приложением RuStore на устройстве пользователя.

Для доступа к методам блока в среде Construct используется синглтон класса RuStoreCoreClient.

Метод isRuStoreInstalled проверяет наличие приложения RuStore на устройстве пользователя.

Вызов метода isRuStoreInstalled
cordova.plugins.RuStorePay.isRuStoreInstalled(
    function(result) {
        var data = JSON.parse(result);
        if (data.isRuStoreInstalled === true) {
            // Process RuStore is installed
        } else {
            // Process RuStore is not installed
        }
    }
);

Метод openRuStoreDownloadInstruction открывает веб-страницу для скачивания мобильного приложения RuStore.

Вызов метода openRuStoreDownloadInstruction
cordova.plugins.RuStorePay.openRuStoreDownloadInstruction()

Метод openRuStore запускает мобильное приложение RuStore. При вызове данного метода, в случае отсутствия установленного приложения RuStore, будет отображено Toast уведомление с сообщением "Не удалось открыть приложение".

Вызов метода openRuStore
cordova.plugins.RuStorePay.openRuStore()

Метод openRuStoreAuthorization запускает мобильное приложение RuStore для авторизации. После успешной авторизации пользователя приложение RuStore автоматически закрывается. При вызове данного метода, в случае отсутствия установленного приложения RuStore, будет отображено Toast уведомление с сообщением "Не удалось открыть приложение".

Вызов метода openRuStoreAuthorization
cordova.plugins.RuStorePay.openRuStoreAuthorization()

Использование RuStoreUtils для проверки платежных сценариев

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

В статье приведены:

Сценарии работы с покупками при отсутствии установленного RuStore;
Примеры последовательного вызова методов проверки установки и авторизации через RuStoreUtils;
Особенности поведения SDK в разных условиях (наличие/отсутствие RuStore, авторизация пользователя и др.).

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

Throwable — базовый класс ошибки.

Модель базовой ошибки
{
    simpleName,   // string
    detailMessage // string
}

simpleName – имя ошибки.
detailMessage – описание ошибки.

RuStorePaymentException — базовый класс ошибки платежного клиента.

Модель базовой ошибки платежного клиента
{
    cause // Throwable
}

cause – дополнительная информация об ошибке.

Унаследованные поля:

simpleName – имя ошибки.
detailMessage – описание ошибки.

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

Модель RuStorePaymentNetworkException
{
    code, // string (optional)
    id    // string
}

code — код ошибки.
id — уникальный идентификатор.

Унаследованные поля:

simpleName – имя ошибки.
detailMessage – описание ошибки.
cause – дополнительная информация об ошибке.

Пример метода обработчика ошибок
function failure(result)
    var data = JSON.parse(result);

    // Required field
    const simple_name = data.simpleName
    const detail_message = data.detailMessage

    switch (data.simpleName) {
        case "RuStorePaymentNetworkException":
            // Required field
            const id = data.id

            // Optional field
            const code = 'code' in data ? data.code : null;
            break;

        case "RuStorePaymentNetworkException":
            // Process error
            break;
			
        case "RuStorePaymentNetworkException":
            // Process error
            break;
end

Возможные ошибки

RuStorePaymentNetworkException — ошибка сетевого взаимодействия SDK;
RuStorePaymentException — базовый класс всех исключений SDK, наследуется от Exception;
RuStorePayClientAlreadyExist — ошибка повторной инициализации SDK;
RuStorePayClientNotCreated — попытка обратиться к публичным интерфейсам SDK до момента ее инициализации;
RuStorePayInvalidActivePurchase — запущен процесс оплаты неизвестного типа продукта;
RuStorePayInvalidConsoleAppId — не задан обязательный параметр console_application_id для инициализации SDK;
RuStorePaySignatureException — неверная сигнатура ответа. Возникает при попытке совершить мошеннические действия;
EmptyPaymentTokenException — ошибка получения платежного токена;
InvalidCardBindingIdException — ошибка оплаты сохраненной картой;
ApplicationSchemeWasNotProvided — не указана схема для обратного диплинка;
ProductPurchaseException - ошибка покупки продукта. Структура модели представлена в разделе структура результата покупки;
ProductPurchaseCancelled - произошла отмена покупки продукта (пользователь закрыл платежную шторку). Структура модели представлена в разделе структура результата покупки;
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`	Выписанный токен не соответствует покупаемому товару.
`4000041`	У пользователя уже есть активная подписка для данного кода продукта.
`4000045`	Превышено максимальное значение размера.
`4010001`	Доступ к запрашиваему ресурсу запрещен (неавторизовано).
`4010002`	Время жизни токена истекло.
`4010003`	Платежный токен невалиден.
`4030001`	Не передан платежный токен.
`4030002`	Пользователь заблокирован по требованиям безопасности.
`4040002`, `4040003`, `4040004`	Ошибка платежной системы.
`5000***`	Внутренняя ошибка.

Пример реализации​

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

Установка плагинов​

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

Работа с SDK​

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

Проверка статуса авторизации пользователя​

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

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

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

Типы покупок​

Модель разовой покупки ProductPurchase​

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

Модель подписки​

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

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

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

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

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

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

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

RuStoreUtils​

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

Коды ошибок​

Пример реализации

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

Установка плагинов

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

Работа с SDK

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

Проверка статуса авторизации пользователя

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

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

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

Типы покупок

Модель разовой покупки ProductPurchase

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

Модель подписки

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

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

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

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

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

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

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

RuStoreUtils

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

Коды ошибок