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

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

подсказка

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

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

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

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

Установка через .unitypackage
Установка через Package Manager

Для подключения скачайте файл RuStoreUnityPaySDK-version.unitypackage и импортируйте его в проект (Assets → Import Package → Custom Package). Зависимости подключаются автоматически с помощью **External Dependency Manager **(включен в .unitypackage).

подсказка

Если вы используете операционную систему MacOS, измените настройки утилиты архивации. В настройках Archive Utility снимите флажок Keep expanding if possible. В противном случае архив проекта будет скачан некорректно.

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

Для подключения скачайте со страницы upm_tgz пакеты:

ru.rustore.core-x.y.z.tgz
ru.rustore.pay-x.y.z.tgz

Импортируйте пакеты в проект через Package Manager (Window → Package Manager → + → Add package from tarball...).

Зависимости подключаются автоматически с помощью External Dependency Manager.

Откройте окно менеджера пакетов (Window → Package Manager → + → Add package from git URL...).
Используйте ссылку https://github.com/googlesamples/unity-jar-resolver.git?path=/upm для подключения пакета External Dependency Manager.
Для устранения ошибки Google.IOSResolver.dll will not be loaded установите модуль сборки iOS для вашей версии Unity (UnityHub → Installs → Ваша версия Unity → Add modules → iOS Build Support).

Ошибка Google.IOSResolver.dll
Assembly 'Packages/com.google.external-dependency-manager/ExternalDependencyManager/Editor/1.2.182/Google.IOSResolver.dll' will not be loaded due to errors:
Unable to resolve reference 'UnityEditor.iOS.Extensions.Xcode'. Is the assembly missing or incompatible with the current platform?
Reference validation can be disabled in the Plugin Inspector.

подсказка

Если вы используете операционную систему macOS, измените настройки утилиты архивации. В настройках Archive Utility снимите флажок Keep expanding if possible. В противном случае архив проекта будет скачан некорректно.

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

Откройте настройки проекта: Edit → Project Settings → Player → Android Settings.
В pазделе Publishing Settings включите следующие настройки.
- Custom Main Manifest.
- Custom Main Gradle Template.
- Custom Gradle Properties Template.
В разделе Other Settings настройте:
- package name.
- Minimum API Level = 24.
- Target API Level = 34.
Откройте настройки External Dependency Manager: Assets → External Dependency Manager → Android Resolver → Settings, включите следующие настройки.
- Use Jetifier.
- Patch mainTemplate.gradle.
- Patch gradleTemplate.properties.
Обновите зависимости проекта: Assets → External Dependency Manager → Android Resolver → Force Resolve.

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

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

<!-- 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" />

Оба значения должны располагаться внутри тега <application>

<?xml version="1.0" encoding="utf-8"?>
<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.unity3d.player"
    xmlns:tools="http://schemas.android.com/tools">
    <application>
        <activity android:name="com.unity3d.player.UnityPlayerActivity"
                  android:theme="@style/UnityThemeSelector">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
            <meta-data android:name="unityplayer.UnityActivity" android:value="true" />
        </activity>
       
        <!-- 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" />
       
    </application>
</manifest>

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

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

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

Важно

Package Name приложения, указанный в Edit → Project Settings... → Player > Android → Other Settings → Package Name, должен совпадать с Package Name APK-файла, который вы публиковали в системе RuStore Консоль.

warning

Подпись и package name различных типов сборок вашего приложения (debug, release и т.д.) могут отличаться друг от друга. В таком случае вы должны создать в разделе Push-уведомления > Проекты из Консоль RuStore проект под каждый тип сборки.

Значение console_app_id_value задается в файле PayClientSettings.assets. Чтобы создать файл PayClientSettings.assets, в меню редактора Unity выберите пункт: Window → RuStore SDK → Settings → PayClient.

Значение internal_config_key задается в файле PayClientSettings.assets автоматически.

Внимание!

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

Обработка deeplink

Deeplink в RuStore SDK платежей нужна для корректной работы со сторонними приложениями оплаты. Она помогает пользователям быстрее совершать покупки в стороннем приложении и возвращаться в ваше приложение.

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

AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.unity3d.player"
    xmlns:tools="http://schemas.android.com/tools">
    <application>
        <activity android:name="ru.rustore.unitysdk.RuStoreUnityPayActivity"
                  android:theme="@style/UnityThemeSelector"
                  android:exported="true">
            <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>
            <meta-data android:name="unityplayer.UnityActivity" android:value="true" />
        </activity>
        <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 -->
        <meta-data android:name="sdk_pay_scheme_value" android:value="@string/rustore_PayClientSettings_deeplinkScheme" />
    </application>
</manifest>

Значение sdk_pay_scheme_value задается в файле PayClientSettings.assets. Чтобы создать файл PayClientSettings.assets, в меню редактора Unity выберите пункт: Window → RuStore SDK → Settings → PayClient.

Далее расширьте класс UnityPlayerActivity и добавьте обработку входящего intent в onNewIntent.

Пример RuStoreUnityPayActivity.java
package ru.rustore.unitysdk;

import android.os.Bundle;
import android.content.Intent;
import ru.rustore.unitysdk.payclient.RuStoreUnityPayClient;
import com.unity3d.player.UnityPlayerActivity;

public class RuStoreUnityPayActivity extends UnityPlayerActivity {

    @Override protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        if (savedInstanceState == null) {
            RuStoreUnityPayClient.INSTANCE.proceedIntent(getIntent());
        }
    }

    @Override protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        RuStoreUnityPayClient.INSTANCE.proceedIntent(intent);
    }
}

Разместите Java-файл с кодом расширения UnityPlayerActivity в папке проекта Assets. Если у вас уже есть своё расширение UnityPlayerActivity, перенесите в него код функций onCreate и onNewIntent.

Работа с SDK

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

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

Важно!

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

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

Важно

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

блок RuStoreCoreClient.Intstance — набор открытых методов, таких как:
- IsRuStoreInstalled — проверки наличия приложения RuStore на устройстве пользователя.
- OpenRuStoreDownloadInstruction — открывает веб-страницу для скачивания приложения RuStore.
- OpenRuStore — запускает приложение RuStore.
- OpenRuStoreAuthorization — запускает приложение RuStore для авторизации. После успешной авторизации пользователя приложение RuStore автоматически закроется.

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

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

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

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

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

Вызов метода GetPurchaseAvailability
RuStorePayClient.Instance.GetPurchaseAvailability(
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        if (result.isAvailable) {
            // Process success
        }
        else {
            // Process result.cause
        }
    });

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

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

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

Вызов метода GetUserAuthorizationStatus
RuStorePayClient.Instance.GetUserAuthorizationStatus(
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        if (result == UserAuthorizationStatus.AUTHORIZED) {
            // Process success
        }
    });

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

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

Вызов метода GetProducts
ProductId[] ids = ...
 
RuStorePayClient.Instance.GetProducts(
    productIds: ids,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        // Process success
    });

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

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

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

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

Структура продукта
public class Product : BaseFields {

    public ProductId productId { get; }
    public ProductType type { get; }
    public AmountLabel amountLabel { get; }
    public Price? price { get; }
    public Currency currency { get; }
    public Title title { get; }
    public Description? description { get; }
    public Url imageUrl { get; }

    ...
}

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

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

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

Вызов метода получения списка покупок пользователя
RuStorePayClient.Instance.GetPurchases(
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        // Process success
    });

Метод поддерживает опциональную фильтрацию по типу товаров (потребляемые или непотреблямые товары) и по статусу покупки (поддерживаются статусы PAID и CONFIRMED).

Вызов метода получения списка покупок пользователя
RuStorePayClient.Instance.GetPurchases(
    productType: ProductType.CONSUMABLE_PRODUCT,
    purchaseStatus: PurchaseStatus.CONFIRMED,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        // Process success
    });

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

Структура с информацией о покупке
public class Purchase : BaseFields {

    public PurchaseId purchaseId { get; }
    public ProductId productId { get; }
    public InvoiceId invoiceId { get; }
    public OrderId? orderId { get; }
    public PurchaseType purchaseType { get; }
    public ProductType productType { get; }
    public Description description { get; }
    public DateTime? purchaseTime { get; }
    public Price price { get; }
    public AmountLabel amountLabel { get; }
    public Currency currency { get; }
    public Quantity quantity { get; }
    public PurchaseStatus status { get; }
    public DeveloperPayload? developerPayload { get; }
    public bool sandbox { get; }
 
    ...
}

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 — покупка успешно оплачена;
- REFUNDED — запрос на возврат средств за покупку совершён успешно;
- REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 6 часов, холдирование средств отменено.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки
sandbox — флаг тестового платежа. Значение true — тестовый платёж, false— реальный платёж.

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

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

Вызов метода получения списка покупок пользователя
RuStorePayClient.Instance.GetPurchase(
    purchaseId: purchase.purchaseId,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (response) => {
        // Process success
    });

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

Структура с информацией о покупке
public class Purchase : BaseFields {

    public PurchaseId purchaseId { get; }
    public ProductId productId { get; }
    public InvoiceId invoiceId { get; }
    public OrderId? orderId { get; }
    public PurchaseType purchaseType { get; }
    public ProductType productType { get; }
    public Description description { get; }
    public DateTime? purchaseTime { get; }
    public Price price { get; }
    public AmountLabel amountLabel { get; }
    public Currency currency { get; }
    public Quantity quantity { get; }
    public PurchaseStatus status { get; }
    public DeveloperPayload? developerPayload { get; }
    public bool sandbox { get; }
 
    ...
}

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 — покупка успешно оплачена;
- REFUNDED — запрос на возврат средств за покупку совершён успешно;
- REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 6 часов, холдирование средств отменено.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки
sandbox — флаг тестового платежа. Значение true — тестовый платёж, false— реальный платёж.

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

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

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

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

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

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

Важно

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

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

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

Вызов метода покупки продукта
var parameters = new ProductPurchaseParams(
        productId: new ProductId("product_id"),
        appUserEmail: null,
        appUserId: null,
        developerPayload: null,
        orderId: null,
        quantity: new Quantity(1)
    );

RuStorePayClient.Instance.Purchase(
    parameters: parameters,
    preferredPurchaseType: PreferredPurchaseType.ONE_STEP,
    onFailure: (error) => {
        switch (error) {
            case RuStorePaymentException.ProductPurchaseCancelled cancelled:
                // Handle cancelled purchase
                break;
            case RuStorePaymentException.ProductPurchaseException exception:
                // Handle failed purchase
                break;
            default:
                // Handle other error
                break;
            }
    },
    onSuccess: (result) => {
        // Process success
    });

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:

к сведению

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

Вызов метода покупки продукта
var parameters = new ProductPurchaseParams(
        productId: new ProductId("product_id"),
        appUserEmail: null,
        appUserId: null,
        developerPayload: null,
        orderId: null,
        quantity: new Quantity(1)
    );
 
RuStorePayClient.Instance.PurchaseTwoStep(
    parameters: parameters,
    onFailure: (error) => {
        switch (error) {
            case RuStorePaymentException.ProductPurchaseCancelled cancelled:
                // Handle cancelled purchase
                break;
            case RuStorePaymentException.ProductPurchaseException exception:
                // Handle failed purchase
                break;
            default:
                // Handle other error
                break;
            }
    },
    onSuccess: (result) => {
        // Process success
    });

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

Структура параметров покупки
public class ProductPurchaseParams : BaseFields {

    public ProductId productId { get; }
    public AppUserEmail? appUserEmail { get; }
    public AppUserId? appUserId { get; }
    public Quantity? quantity { get; }
    public OrderId? orderId { get; }
    public DeveloperPayload? developerPayload { get; }
	
    ...
}

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

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

public sealed class ProductPurchaseResult : BaseFields {

   public PurchaseId purchaseId { get; }
   public ProductId productId { get; }
   public InvoiceId invoiceId { get; }
   public OrderId? orderId { get; }
   public PurchaseType purchaseType { get; }
   public Quantity quantity { get; }
   public bool sandbox { get; }
 
   ...
}

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

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

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

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

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

public sealed class ProductPurchaseException : RuStorePaymentException {

    public InvoiceId? invoiceId { get; }
    public OrderId? orderId { get; }
    public ProductId? productId { get; }
    public PurchaseId? purchaseId { get; }
    public PurchaseType? purchaseType { get; }
    public Quantity? quantity { get; }
    public bool? sandbox { get; }

    ...
}

public sealed class ProductPurchaseCancelled : RuStorePaymentException {

    public PurchaseId? purchaseId { get; }
    public PurchaseType? purchaseType { get; }

    ...
}

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

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

Получение invoiceId из результата покупки
var parameters = new ProductPurchaseParams(
      productId: new ProductId("product_id"));
 
RuStorePayClient.Instance.Purchase(
    parameters: parameters,
    preferredPurchaseType: PreferredPurchaseType.TWO_STEP,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        var invoiceId = result.invoiceId.value;
        yourApi.validate(invoiceId);
    });

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

RuStorePayClient.Instance.GetPurchases(
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        result.ForEach(item => {
            yourApi.validate(item.subscriptionToken);
        });
    });

Подтверждение (потребление) покупки

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

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

Вызов метода подтверждения
PurchaseId id = ...
DeveloperPayload payload = ...
 
RuStorePayClient.Instance.ConfirmTwoStepPurchase(
    purchaseId: purchaseId,
    developerPayload: payload,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: () => {
        // Process success
    });

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

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

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

подсказка

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

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

Вызов метода CancelTwoStepPurchase
PurchaseId id = ...

RuStoreBillingClient.Instance.CancelTwoStepPurchase(
    purchaseId: id,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: () => {
        // Process success
    }
);

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

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

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

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

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

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

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

Обработка deeplink​

Работа с SDK​

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

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

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

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

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

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

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

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

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

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

Подтверждение (потребление) покупки​

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

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

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

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

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

Обработка deeplink

Работа с SDK

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

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

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

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

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

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

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

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

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

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

Подтверждение (потребление) покупки

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

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