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

通过 RuStore，您可以在移动应用中集成支付功能。

提示

如果不知道从哪里开始，请在使用场景中阅读指南。
如果您从 billingClient SDK 迁移到 Pay SDK，请查看迁移指南。关于 Pay SDK 的详细信息，请参见此处。

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

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

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

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

Репозиторий содержит исходный код плагина и демонстрационный проект, содержащий представление работы всех методов SDK.

警告

Не используйте кнопку "Код → Скачать" на сайте GitFlic – этот метод не загружает файлы из Git LFS.

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

Git.
Git LFS.

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

git lfs install

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

git clone https://gitflic.ru/project/rustore/construct-rustore-pay.git
cd construct-rustore-pay
git lfs pull

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

Для сборки 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 в папке ваш_cordova_проект / platforms / android / app / src / main.
В файле AndroidManifest.xml найдите активити MainActivity и удалите у неё тег <intent-filter> содержащий MAIN и LAUNCHER, чтобы она больше не запускалась как стартовая. Новая активити RuStoreIntentFilterActivity, добавленная плагином, обязательно должна быть основной.

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

<?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">
            <!-- Starting intent-filter
            <intent-filter>
                <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.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="@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 控制台哪里可以查看应用 ID？

进入 Applications 选项卡并选择需要的应用。
从该应用页面的 URL 中复制 ID——它是位于 apps/ 与 /versions 之间的一串数字。例如：在 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 控制台中哪里可以看到产品 ID？

转到 应用程序 选项卡并选择所需的应用程序。
从左侧菜单中选择 货币化。
选择产品类型：订阅或 一次性购买。
复制所需产品的 ID。

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

Модель продукта
{
    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 — 图片链接.

Модель информации о подписке
{
    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 — 包含订单附加信息的字符串，您可以在确认购买时设置。此字符串会覆盖初始化时设置的值
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 — 购买退款请求已成功完成;
- REVERSED — 仅适用于双阶段支付，购买被开发者取消或在 6 小时内未确认购买，资金冻结已取消.
sandbox — 测试支付标志。值为 true 表示测试支付，false 表示真实支付。

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

单阶段支付的状态模型。

双阶段支付的状态模型。

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

Модель 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 — подписка активна.
- EXPIRED — срок действия подписки истек. - тоже самое, не подписки, а время на оплату счета первого для оформления подписки истекло, никакой подписки ещё не было
- PAUSED — подписка приостановлена из-за проблем с оплатой.
- TERMINATED — закончились попытки списания по подписке (все были неуспешными). Подписка закрыта автоматически из-за проблем с оплатой.
- CLOSED — подписка была отменена пользователем или разработчиком. Истек срок оплаченного периода, подписка закрыта.
description — описание покупки.
purchaseTime — 购买时间.
price — 以最小单位表示的价格（例如，戈比）.
amountLabel — 格式化的购买价格，包括货币符号.
currency — ISO 4217 货币代码.
developerPayload — 包含订单附加信息的字符串，您可以在确认购买时设置。此字符串会覆盖初始化时设置的值
sandbox — 测试支付标志。值为 true 表示测试支付，false 表示真实支付。
productId — 在 RuStore 控制台中分配给产品的产品标识符（必填参数）. Идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
expirationDate — дата окончания действия подписки.
gracePeriodEnabled — флаг, указывающий, активен ли Grace-период для подписки.

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

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

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

使用单阶段支付时，购买不需要确认，资金会立即从买家的账户中扣除，并向开发者收取佣金。在这种情况下，如果需要向客户退款（例如，由于某种原因无法交付产品），只能通过 RuStore 控制台进行退款，资金将在几天后退还给买家。全额退款，但扣除的佣金不予退还给开发者。
使用双阶段支付时，首先在买家的账户上冻结资金。在这种情况下，不收取佣金。冻结后，购买需要确认或取消。确认购买时会向开发者收取佣金。取消购买意味着解除冻结——资金会立即再次可用于买家。

Важно

双阶段支付仅适用于特定的支付方式（目前仅限于银行卡）。SBP 技术不支持双阶段支付。如果选择了不支持冻结的支付方式，则购买将以单阶段方案进行。

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

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

Вызов метода покупки продукта
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.ONE_STEP;
const sdk_theme = cordova.plugins.RuStorePay.SdkTheme.DARK;

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;
        }
    }
);

productId — 在 RuStore 控制台中分配给产品的产品标识符（必填参数）.
quantity — 产品数量。可选参数，默认值为 1。仅适用于可消耗商品的购买.
orderId — 应用生成的唯一支付标识符（可选参数）。如果您在系统中指定此参数，您将在使用 API 时收到它的响应。如果未指定，它将自动生成（uuid）。最大长度为 150 个字符。.
developerPayload — 包含订单附加信息的字符串，您可以在确认购买时设置。此字符串会覆盖初始化时设置的值。最大长度为 250 个字符。
appUserId — 您的应用中的用户内部 ID（可选参数）。字符串的最大长度为 128 个字符。
提示
例如，该参数可用于识别应用中的欺诈行为，从而提高应用的安全性。
appUserEmail - 这是一个可选参数，允许在您的应用中指定用户的电子邮件地址。如果在应用注册时提供了买家的电子邮件地址，可以将其传递用于在发送收据时自动填充 email 字段——无论是 RuStore 外的支付，还是用户未在 RuStore 中授权的情况。这可以避免用户手动输入电子邮件，缩短购买流程，并有助于提高转化率。
preferredPurchaseType — 所需的购买类型：单阶段（ONE_STEP）或双阶段（TWO_STEP）。

sdk_theme — цветовая тема платежной шторки. Доступны два варианта LIGHT и DARK (светлая и темная тема соотвественно), по умолчанию LIGHT.

Важно

该方法默认以单阶段支付方案 (preferred_purchase_type = cordova.plugins.RuStorePay.PreferredPurchaseType.ONE_STEP) 启动，即不冻结资金。

对于双阶段支付，需要指定 preferred_purchase_type = cordova.plugins.RuStorePay.PreferredPurchaseType.TWO_STEP。该方法的双阶段支付（即冻结资金的支付）不保证，直接取决于用户选择的支付方式（如卡、SPB 等）。

在启动该方法时（使用 preferredPurchaseType = twoStep），在用户选择支付方式之前，购买的阶段性将为 UNDEFINED。在处理购买取消结果 (ProductPurchaseCancelled) 或购买错误 (ProductPurchaseException) 时，请考虑此行为。

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

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

信息

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

Вызов метода покупки продукта
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 sdk_theme = cordova.plugins.RuStorePay.SdkTheme.DARK;

cordova.plugins.RuStorePay.purchase_two_step(
    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;
        }
    }
);

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

Модель параметров покупки
{
    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 个字符。
appUserId — 您的应用中的用户内部 ID（可选参数）。字符串的最大长度为 128 个字符。
提示
例如，该参数可用于识别应用中的欺诈行为，从而提高应用的安全性。
appUserEmail — 这是一个可选参数，允许在您的应用中指定用户的电子邮件地址。如果在应用注册时提供了买家的电子邮件地址，可以将其传递用于在发送收据时自动填充 email 字段——无论是 RuStore 外的支付，还是用户未在 RuStore 中授权的情况。这可以避免用户手动输入电子邮件，缩短购买流程，并有助于提高转化率。

sdk_theme — цветовая тема платежной шторки. Доступны два варианта LIGHT и DARK (светлая и темная тема соотвественно), по умолчанию LIGHT.

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

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 символов (символы не экранируются). Если передан, заменяет значение, записанное при старте покупки методом 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 на устройстве пользователя.

Для доступа к методам блока в среде Unity используется синглтон класса 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 网络交互错误;
RuStorePaymentCommonException — 通用 SDK 错误;
RuStorePayClientAlreadyExist — SDK 重新初始化错误;
RuStorePayClientNotCreated — 在 SDK 初始化之前尝试访问公共接口;
RuStorePayInvalidActivePurchase — 发起了未知类型产品的支付过程;
RuStorePayInvalidConsoleAppId — 未设置 SDK 初始化所需的参数 console_application_id;
RuStorePaySignatureException — 响应签名无效。发生在尝试进行欺诈行为时;
EmptyPaymentTokenException — 获取支付令牌时出错;
InvalidCardBindingIdException — 使用已保存的卡支付时出错;
ApplicationSchemeWasNotProvided — 未指定返回 deeplink 的 scheme;
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***`	内部错误。

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

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

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

Клонирование репозитория​

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

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

Работа с SDK​

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

RuStoreUtils​

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

错误代码​

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

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

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

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

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

Работа с SDK

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

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

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

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

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

Типы покупок

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

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

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

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

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

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

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

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

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

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

RuStoreUtils

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

错误代码