SDK Платежи in-app для Flutter (версия 11.1.0)

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

подсказка

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

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

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

flutter pub add flutter_rustore_pay

Обработка deeplink

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

Для настройки работы с deeplink в вашем приложении и Pay SDK, укажите deeplinkScheme с помощью sdk_pay_scheme_value в файле android/app/src/main/AndroidManifest.xml.

Внимание

При использовании deeplinks указание схемы является обязательным.
При попытке платежа без указания схемы будет возникать ошибка.
Допускаются только символы в кодировке ASCII. Формат должен соответствовать спецификации RFC-3986.

Указание deeplinkScheme:

android/app/src/main/AndroidManifest.xml
<activity
    android:name=".MainActivity"
    android:launchMode="singleTop"
    android:exported="true">

    <!-- ... -->

    <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/SDK_PAY_SCHEME" />
    </intent-filter>
</activity>

<meta-data
    android:name="sdk_pay_scheme_value"
    android:value="@string/SDK_PAY_SCHEME" />

подсказка

Не забудьте указать строку с вашей SDK_PAY_SCHEME в файле strings.xml.

Атрибут android:launchMode="singleTop" у главной Activity нужен для восстановления состояния приложения при возврате с deeplink.

Обработку возврата по deeplink (onNewIntent) плагин выполняет самостоятельно — писать нативный код не требуется.

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

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

AndroidManifest.xml
<meta-data
    android:name="console_app_id_value"
    android:value="@string/CONSOLE_APPLICATION_ID" />

В strings.xml замените строку с вашим app_id.

strings.xml
<string name="CONSOLE_APPLICATION_ID">your_app_id</string>

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

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

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

Важно

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

информация

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

Необходимые разрешения и параметры безопасности

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

Прочие разрешения

Также Pay SDK может потребовать другие стандартные разрешения, такие как:

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

Методы SDK

Доступ к методам осуществляется через синглтон RuStorePayClient.instance и его интеракторы: purchaseInteractor, productInteractor, userInteractor, а также блок утилит ruStoreUtils.

Публичные классы SDK импортируются по отдельным файлам пакета. Для работы примеров из этого раздела добавьте нужные импорты, например:

Импорт классов SDK
import 'package:flutter_rustore_pay/api/flutter_rustore_pay_client.dart';
import 'package:flutter_rustore_pay/api/purchase_event_listener.dart';
import 'package:flutter_rustore_pay/model/acknowledgement_state.dart';
import 'package:flutter_rustore_pay/model/preferred_purchase_type.dart';
import 'package:flutter_rustore_pay/model/product.dart';
import 'package:flutter_rustore_pay/model/product_type.dart';
import 'package:flutter_rustore_pay/model/purchase.dart';
import 'package:flutter_rustore_pay/model/purchase_availability.dart';
import 'package:flutter_rustore_pay/model/purchase_result.dart';
import 'package:flutter_rustore_pay/model/ru_store_exception.dart';
import 'package:flutter_rustore_pay/model/sdk_theme.dart';

purchaseInteractor — интерактор для работы с платежами:
- Future<Purchase> getPurchase(String purchaseId) — позволяет получить информацию о покупке по её ID.
- Future<List<Purchase>> getPurchases({ProductType? productType, PurchaseStatus? purchaseStatus, AcknowledgementState? acknowledgementState}) — позволяет получить покупки пользователя. Метод поддерживает опциональную фильтрацию по типу товаров (потребляемые, непотребляемые товары или подписки), по статусу покупки (поддерживаются статусы paid, confirmed, active, paused) и по состоянию выдачи товара (pending, acknowledged). По умолчанию фильтры отключены, и вернутся все покупки пользователя (независимо от типа товара) в статусах paid, confirmed, active, paused.
- Future<PurchaseAvailabilityResult> getPurchaseAvailability() — возвращает результат проверки доступности работы с платежами.
- Future<ProductPurchaseResult> purchase(String productId, {String? orderId, int? quantity, String? developerPayload, String? appUserId, String? appUserEmail, PreferredPurchaseType? preferredPurchaseType, SdkTheme? sdkTheme, PurchaseEventListener? purchaseEventListener}) — позволяет совершить покупку продукта с указанием желаемого типа оплаты — одностадийной (oneStep) или двухстадийной (twoStep). Для данного метода на платёжной шторке доступны все способы оплаты. Если параметр не задан, по умолчанию запускается оплата в одну стадию.
Важно!
Если указан тип оплаты twoStep, будет произведена попытка запустить двухстадийную оплату, но итоговый результат напрямую зависит от того, какой способ оплаты (карта, СБП и др.) выберет пользователь.
Обратите внимание, что тип оплаты twoStep недоступен:
- При выборе способа оплаты СБП.
- При покупке подписок.
Двухстадийная оплата доступна только для определённого набора способов оплаты (на текущий момент — только для карт и SberPay). Если выбран способ оплаты, который не поддерживает холдирование, покупка будет запущена по сценарию с одной стадией.
- Future<ProductPurchaseResult> purchaseTwoStep(String productId, {String? orderId, int? quantity, String? developerPayload, String? appUserId, String? appUserEmail, SdkTheme? sdkTheme, PurchaseEventListener? purchaseEventListener}) — запускает сценарий гарантированной двухстадийной покупки товара. При использовании данного метода пользователю на платёжной шторке доступен ограниченный набор способов оплаты — только те, которые поддерживают двухстадийную оплату. Сначала осуществляется холдирование денежных средств покупателя, которые списываются только после подтверждения покупки методом confirmTwoStepPurchase.
- Future<void> confirmTwoStepPurchase(String purchaseId, {String? developerPayload}) — подтверждение покупки, совершённой по двухстадийной оплате.
- Future<void> cancelTwoStepPurchase(String purchaseId) — отмена покупки, совершённой по двухстадийной оплате.
- Future<AcknowledgementState> updateAcknowledgementState(String purchaseId, AcknowledgementState acknowledgementState, {String? developerPayload}) — обновляет состояние выдачи товара по покупке. Метод возвращает фактическое состояние после выполнения операции.
- Future<List<BillingSubscription>> getBillingSubscriptions() — возвращает список подписок, оформленных в SDK Billing Client. Такие подписки не попадают в результат методов getPurchase и getPurchases.
productInteractor — интерактор для работы с продуктами:
- Future<List<Product>> getProducts(List<String> ids) — позволяет получить информацию по активным продуктам, опубликованным в консоли RuStore.
Важно
Данный метод возвращает не более 1000 продуктов и работает без авторизации и наличия установленного RuStore на устройстве пользователя.
userInteractor — интерактор для получения статуса авторизации пользователя UserAuthorizationStatus. У модели два состояния:
- Authorized — пользователь авторизован в RuStore.
- Unauthorized — пользователь не авторизован в RuStore.
блок ruStoreUtils — набор открытых методов:
- Future<bool> isRuStoreInstalled() — проверка наличия приложения RuStore на устройстве пользователя.
- Future<void> openRuStoreDownloadInstruction() — открывает веб-страницу для скачивания приложения RuStore.
- Future<void> openRuStore() — запускает приложение RuStore.
- Future<void> openRuStoreAuthorization() — запускает приложение RuStore для авторизации. После успешной авторизации приложение RuStore автоматически закроется.

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

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

RuStorePayClient.instance.productInteractor.getProducts(ids).then((products) {
  for (final product in products) {
    print(product.productId);
  }
}, onError: (err) {
  print("products err: $err");
});

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

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

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

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

final class Product {
  final String productId;
  final ProductType type;
  final String amountLabel;
  final int? price;
  final String currency;
  final String imageUrl;
  final String title;
  final String? description;
  final SubscriptionInfo? subscriptionInfo;
}

Экземпляры модели создаёт сам SDK — публичного конструктора у класса нет. Ниже представлена сама модель.

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

Структура ProductType

enum ProductType {
  consumable,
  nonConsumable,
  subscription,
  undefined
}

Cтруктура информации о подписке

final class SubscriptionInfo {
  final List<SubscriptionPeriod> periods;
}

Cтруктура информации о периоде подписки (sealed class)

sealed class SubscriptionPeriod {
  String get duration;
}

final class TrialPeriod implements SubscriptionPeriod {
  final String duration;
  final String currency;
  final int price;
}

final class PromoPeriod implements SubscriptionPeriod {
  final String duration;
  final String currency;
  final int price;
}

final class MainPeriod implements SubscriptionPeriod {
  final String duration;
  final String currency;
  final int price;
}

final class GracePeriod implements SubscriptionPeriod {
  final String duration;
}

final class HoldPeriod implements SubscriptionPeriod {
  final String duration;
}

Типы периодов подписки

TrialPeriod (бесплатный пробный период)

String duration - длительность периода в формате ISO 8601 (например, “P7D” - 7 дней, “P1M” - 1 месяц)
String currency - код валюты ISO 4217
int price - цена в минимальных единицах валюты

PromoPeriod (промо-период)

String duration - длительность периода в формате ISO 8601
String currency - код валюты ISO 4217
int price - цена в минимальных единицах валюты

MainPeriod (основной период)

String duration - длительность периода в формате ISO 8601
String currency - код валюты ISO 4217
int price - цена в минимальных единицах валюты

GracePeriod (период отсрочки)

String duration - длительность периода в формате ISO 8601

HoldPeriod (период приостановки)

String duration - длительность периода в формате ISO 8601

Пример обработки периодов подписки

final products = await RuStorePayClient.instance.productInteractor.getProducts(ids);

for (final product in products) {
  if (product.type == ProductType.subscription && product.subscriptionInfo != null) {
    final subscriptionInfo = product.subscriptionInfo!;

    for (final period in subscriptionInfo.periods) {
      switch (period) {
        case TrialPeriod trial:
          print('Бесплатный пробный период: ${trial.duration}');
          break;
        case PromoPeriod promo:
          print('Промо-период: ${promo.duration} за ${promo.price} ${promo.currency}');
          break;
        case MainPeriod main:
          print('Основной период: ${main.duration} за ${main.price} ${main.currency}');
          break;
        case GracePeriod grace:
          print('Период отсрочки: ${grace.duration}');
          break;
        case HoldPeriod hold:
          print('Период приостановки: ${hold.duration}');
          break;
      }
    }
  }
}

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

Иллюстрация структуры моделей в ответе — вывод toString() (экземпляры моделей создаёт сам SDK).

Пример модели Потребляемого продукта
Product(
    productId: conProduct1,
    type: ProductType.consumable,
    amountLabel: 100.00 руб.,
    price: 10000,
    currency: RUB,
    imageUrl: https://your_image_consumable_product.png,
    title: Название Потребляемого продукта,
    description: Описание потребляемого продукта,
    subscriptionInfo: null
)

Пример модели Непотребляемого продукта
Product(
    productId: nonConProduct1,
    type: ProductType.nonConsumable,
    amountLabel: 200.00 руб.,
    price: 20000,
    currency: RUB,
    imageUrl: https://your_image_non_consumable_product.png,
    title: Название Непотребляемого продукта,
    description: Описание Непотребляемого продукта,
    subscriptionInfo: null
)

Пример модели Подписки
Product(
    productId: sub_1,
    type: ProductType.subscription,
    amountLabel: 300.00 руб.,
    price: 30000,
    currency: RUB,
    imageUrl: https://your_image_subscription.png,
    title: Название вашей подписки,
    description: Описание вашей подписки,
    subscriptionInfo: SubscriptionInfo(periods: [
        TrialPeriod(duration: P1M, currency: RUB, price: 0),
        PromoPeriod(duration: P5D, currency: RUB, price: 149),
        MainPeriod(duration: P1Y, currency: RUB, price: 299),
        GracePeriod(duration: P3D),
        HoldPeriod(duration: P5D)
    ])
)

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

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

Authorized - пользователь авторизован в RuStore или через VK ID на платежной шторке.
Unauthorized - пользователь не авторизован в RuStore. Данное значение также вернется если у пользователя нет установленного RuStore на устройстве.

RuStorePayClient.instance.userInteractor.getUserAuthorizationStatus().then((value) {
  if (value case Authorized _) {
      // Process authorized
  } else if (value case Unauthorized _) {
      // Process unauthorized
  }
});

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

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

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

Если все указанные выше условия выполняются, возвращается Available. В противном случае возвращается Unavailable, где errorMessage — это ошибка о невыполненном условии.

Вызов метода getPurchaseAvailability
RuStorePayClient.instance.purchaseInteractor.getPurchaseAvailability().then((value) {
  if (value case Available _) {
    // Process purchases available
  } else if (value case Unavailable unavailable) {
    // Process purchases unavailable
  }
});

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

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

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

Ограничения по типам платежей для подписок

На данный момент покупка подписки (SubscriptionPurchase) может быть совершена только с использованием одностадийного платежа (PurchaseType.oneStep).

Важно

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

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

Для вызова покупки продукта с выбором стадийности оплаты используйте метод purchase. Первым аргументом передаётся productId, остальные параметры — именованные и опциональные.

Вызов метода покупки продукта
Future<void> purchaseProduct() async {
  try {
    final result = await RuStorePayClient.instance.purchaseInteractor.purchase(
      'productId',
      quantity: 1,
      orderId: null,
      developerPayload: null,
      appUserId: null,
      appUserEmail: null,
      preferredPurchaseType: PreferredPurchaseType.oneStep,
      sdkTheme: SdkTheme.light, // или SdkTheme.dark
      purchaseEventListener: null,
    );
    // Логика обработки успешного результата покупки
  } on RuStoreProductPurchaseException {
    // Обработка ошибки покупки продукта
  } on RuStorePurchaseCancelledException {
    // Обработка отмены покупки продукта
  } catch (_) {
    // Обработка ошибки
  }
}

preferredPurchaseType — желаемый тип покупки: одностадийная (ONE_STEP) или двухстадийная (TWO_STEP);
purchaseEventListener — набор callback-функций, вызываемых в процессе покупки. Параметр опциональный. По умолчанию передается null.

Важно

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

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

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

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

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

к сведению

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

Ограничения по типам платежей для подписок

Вызов метода двухстадийной покупки продукта
Future<void> purchaseTwoStep() async {
  try {
    final result = await RuStorePayClient.instance.purchaseInteractor.purchaseTwoStep(
      'productId',
      quantity: 1,
      orderId: null,
      developerPayload: null,
      appUserId: null,
      appUserEmail: null,
      sdkTheme: SdkTheme.light, // или SdkTheme.dark
      purchaseEventListener: null,
    );
    // Логика обработки успешного результата покупки
  } on RuStoreProductPurchaseException {
    // Обработка ошибки покупки продукта
  } on RuStorePurchaseCancelledException {
    // Обработка отмены покупки продукта
  } catch (_) {
    // Обработка ошибки
  }
}

Работа с PurchaseEventListener

PurchaseEventListener — это интерфейс с набором callback-ов, которые вызываются в процессе покупки.

Реализация передается в методы purchase() и purchaseTwoStep(). С помощью этих callback-ов можно получать данные о purchaseId и invoiceId на разных этапах покупки.

Работа с PurchaseEventListener
abstract class PurchaseEventListener {
  void onPurchaseCreated(String purchaseId, String invoiceId);
  void onPaymentStarted(String purchaseId, String invoiceId);
  void onPaymentCompleted(String purchaseId, String invoiceId);
  void onPaymentFailed(String purchaseId, String invoiceId);
  void onPurchaseCancelled(String purchaseId, String invoiceId);
}

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

class PurchaseEventListenerExample implements PurchaseEventListener {

  @override
  void onPurchaseCreated(String purchaseId, String invoiceId) {
    // Реализация метода при создании покупки
  }

  @override
  void onPaymentStarted(String purchaseId, String invoiceId) {
    // Реализация метода при старте покупки
  }

  @override
  void onPaymentCompleted(String purchaseId, String invoiceId) {
    // Реализация метода при успешном завершении покупки
  }

  @override
  void onPaymentFailed(String purchaseId, String invoiceId) {
    // Реализация метода при неуспешном завершении покупки
  }

  @override
  void onPurchaseCancelled(String purchaseId, String invoiceId) {
    // Реализация метода при отмене покупки
  }
}

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

sdkTheme — тема платёжного интерфейса: SdkTheme.light (светлая) или SdkTheme.dark (тёмная). Необязательный параметр, по умолчанию — светлая тема.
purchaseEventListener — слушатель событий процесса покупки (см. пример выше). Необязательный параметр.

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

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

final class ProductPurchaseResult {
  final String? orderId;
  final String purchaseId;
  final String productId;
  final String invoiceId;
  final PurchaseType purchaseType;
  final ProductType productType;
  final int quantity;
  final bool sandbox;
}

Экземпляры модели создаёт сам SDK — публичного конструктора у класса нет.

ProductPurchaseResult — результат успешной оплаты цифрового товара (для одностадийной оплаты) или успешного холдирования средств (для двухстадийной оплаты).
- purchaseId - идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке и серверной валидации подписки.
- productId - идентификатор приобретенного продукта, указанный при создании в консоли разработчика RuStore.
- invoiceId - идентификатор счета. Используется для серверной валидации платежа, поиска платежей в консоли разработчика, а также отображается покупателю в истории платежей в мобильном приложении RuStore.
- orderId - уникальный идентификатор оплаты, указанный разработчиком или сформированный автоматически (uuid).
- purchaseType - тип покупки (PurchaseType.oneStep/PurchaseType.twoStep/PurchaseType.undefined - одностадийная/двухстадийная/стадийность не определена).
- productType - тип продукта (ProductType.nonConsumable - непотребляемый товар, ProductType.consumable - потребляемый товар, ProductType.subscription - подписка).
- quantity - количество товара, заданное при старте покупки.
- sandbox - флаг, указывающий признак тестового платежа в песочнице. Если true - покупка совершена в режиме тестирования.

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

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

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

RuStorePayClient.instance.purchaseInteractor
    .confirmTwoStepPurchase(id)
    .then((_) {
      // Логика обработки успешного подтверждения покупки
    })
    .catchError((error) {
      // Обработка ошибки
    });

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

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

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

подсказка

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

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

void cancelTwoStepPurchaseExample() {
  RuStorePayClient.instance.purchaseInteractor
      .cancelTwoStepPurchase('purchaseId')
      .then((_) {
        // Логика обработки успешной отмены покупки
      })
      .catchError((error) {
        // Обработка ошибки
      });
}

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

Работа с подтверждением выдачи товара

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

Подтверждение выдачи товара по покупке
RuStorePayClient.instance.purchaseInteractor.updateAcknowledgementState(
  "PURCHASE_ID",
  AcknowledgementState.acknowledged,
  developerPayload: "DEVELOPER_PAYLOAD",
).then((state) {
  // state — состояние выдачи товара после выполнения операции
}).catchError((error) {
  // Обработка ошибок
});

Логика не является обязательной и не влияет на проведение платежей. Она позволяет хранить на стороне RuStore состояние обработки покупки, чтобы затем при получении списка покупок с отдельной фильтрацией выбирать только необработанные покупки и выполнять по ним выдачу товара.

После успешного проведения платежа статус выдачи товара по умолчанию имеет значение pending.

Для платежей, совершённых в более ранних версиях SDK, где эта логика ещё не поддерживалась, используется статус unknown. При необходимости такой статус можно изменить на любой другой.

Статус обработки можно изменять в обе стороны: например, переводить покупку из pending в acknowledged, а также возвращать её в предыдущий статус, если требуется отозвать ранее выданный товар, например после возврата платежа.

При вызове этого метода значение developerPayload можно обновить. Если параметр передан, текущее значение будет перезаписано. Если параметр не передан, сохранится текущее значение developerPayload.

Метод возвращает фактическое состояние выдачи товара после выполнения операции — оно может отличаться от запрошенного.

purchaseId — идентификатор покупки.
acknowledgementState — новое состояние подтверждения покупки. Доступные значения: AcknowledgementState.pending, AcknowledgementState.acknowledged, AcknowledgementState.unknown.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимальная длина 250 символов. Символы не экранируются (при использовании кавычек требуется экранирование) (опционально).

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

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

Вызов метода получения покупки пользователя
RuStorePayClient.instance.purchaseInteractor.getPurchase("PURCHASE_ID").then((purchase) {
    // Для получения информации о покупке определенного типа
    if (purchase is ProductPurchase) {
      print('Product ID: ${purchase.productId}, Status: ${purchase.status}');
    } else if (purchase is SubscriptionPurchase) {
      print('Product ID: ${purchase.productId}, Status: ${purchase.status}');
    }
}).catchError((error) {
  // Обработка ошибок
});

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

Детали моделей покупки ProductPurchase и SubscriptionPurchase представлены в соответствующих разделах.

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

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

Вызов метода получения списка покупок пользователя
RuStorePayClient.instance.purchaseInteractor.getPurchases().then((purchases) {
  for (final purchase in purchases) {
    // Для получения покупки определенного типа
    if (purchase is ProductPurchase) {
      print('Product ID: ${purchase.productId}, Status: ${purchase.status}');
    } else if (purchase is SubscriptionPurchase) {
      print('Product ID: ${purchase.productId}, Status: ${purchase.status}');
    }
  }
}).catchError((error) {
  // Обработка ошибок
});

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

Типы товаров:

Потребляемые товары - ProductType.consumable
Непотребляемые товары - ProductType.nonConsumable
Подписки - ProductType.subscription

Статусы покупок:

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

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

AcknowledgementState.pending: Товар оплачен, но выдача ещё не подтверждена.
AcknowledgementState.acknowledged: Выдача товара подтверждена.

Передача значения AcknowledgementState.unknown равнозначна отсутствию фильтра — отобрать покупки именно в состоянии unknown нельзя.

По умолчанию фильтры выключены, если значения не заданы, метод вернет все покупки пользователя в статусах paid, confirmed, active и paused, независимо от типа товара.

Вызов метода получения списка покупок пользователя с фильтрацией
RuStorePayClient.instance.purchaseInteractor.getPurchases(
  productType: ProductType.consumable,
  purchaseStatus: ProductPurchaseStatus.paid,
  acknowledgementState: AcknowledgementState.pending,
).then((purchases) {
  // Для получения покупки определенного типа
  for (final purchase in purchases) {
    if (purchase is ProductPurchase) {
      print('Product ID: ${purchase.productId}, Status: ${purchase.status}');
    } else if (purchase is SubscriptionPurchase) {
      print('Product ID: ${purchase.productId}, Status: ${purchase.status}');
    }
  }
}).catchError((error) {
  // Обработка ошибок
});

Типы покупок

В SDK предусмотрен базовый интерфейс Purchase, который объединяет общие поля всех типов покупок. На его основе созданы две реализации:

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

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

Интерфейс Purchase
sealed class Purchase {
  String get purchaseId;
  String get invoiceId;
  String? get orderId;
  PurchaseType get purchaseType;
  PurchaseStatus get status;
  String get description;
  String? get purchaseTime;
  int get price;
  String get amountLabel;
  String get currency;
  String? get developerPayload;
  bool get sandbox;
  AcknowledgementState get acknowledgementState;
}

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

Модель разовой покупки
final class ProductPurchase implements Purchase {
  final String purchaseId;
  final String invoiceId;
  final String? orderId;
  final PurchaseType purchaseType;
  final ProductPurchaseStatus status;
  final String description;
  final String? purchaseTime;
  final int price;
  final String amountLabel;
  final String currency;
  final String? developerPayload;
  final bool sandbox;
  final AcknowledgementState acknowledgementState;
  final String productId;
  final int quantity;
  final ProductType productType;
}

Экземпляры модели создаёт сам SDK — публичного конструктора у класса нет.

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

purchaseId — идентификатор покупки.
invoiceId — идентификатор счета.
orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
PurchaseType — тип покупки:
- oneStep - одностадийная покупка;
- twoStep - двухстадийная покупка;
- undefined - стадийность не определена.
description — описание на языке language.
purchaseTime — время покупки.
price — цена в минимальных единицах (в копейках).
amountLabel — отформатированная цена покупки, включая валютный знак.
currency — код валюты ISO 4217.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимальная длина 250 символов. Символы не экранируются (при использовании кавычек требуется экранирование)
sandbox — флаг тестового платежа. Значение true — тестовый платеж, false— реальный платеж.
acknowledgementState — состояние выдачи товара:
- pending — товар оплачен, выдача ещё не подтверждена разработчиком;
- acknowledged — выдача товара подтверждена;
- unknown — логика подтверждения к платежу не применима.

Уникальные поля:

productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
productType — тип продукта.
- nonConsumable — непотребляемый товар;
- consumable — потребляемый товар.
quantity — количество продукта. Необязательный параметр со стандартным значением 1. Применим только к покупке потребляемых товаров.
status — состояние покупки:
- invoiceCreated — создан счет на оплату, покупка ожидает оплаты;
- cancelled — покупка отменена покупателем;
- processing — запущена оплата;
- rejected — покупка отклонена (например, ввиду недостатка средств);
- confirmed — покупка успешно оплачена;
- refunded — запрос на возврат средств за покупку совершен успешно. Деньги будут возвращены пользователю в течение 10 рабочих дней;
- refunding — инициирован возврат средств, запрос отправлен в эквайер;
- executing — покупка находится в процессе выполнения;
- expired — истекло время на оплату покупки;
- paid — только для двухстадийной оплаты, промежуточный статус, средства на счете покупателя захолдированы, покупка ожидает подтверждения от разработчика;
- reversed — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 6 часов, холдирование средств отменено.

Пример ответа — вывод toString() полученной модели (иллюстрация структуры, не компилируемый код).

Пример модели покупки потребляемого продукта
ProductPurchase(
    purchaseId: purchaseId,
    invoiceId: invoiceId,
    orderId: orderId,
    purchaseType: PurchaseType.oneStep,
    status: ProductPurchaseStatus.confirmed,
    description: Описание покупки,
    purchaseTime: 2026-07-01T12:00:00+03:00,
    price: 14100,
    amountLabel: 141,00 ₽,
    currency: RUB,
    developerPayload: developerPayload,
    sandbox: false,
    acknowledgementState: AcknowledgementState.pending,
    productId: game_coins_1000,
    quantity: 1,
    productType: ProductType.consumable
)

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

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

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

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

Модель подписки SubscriptionPurchase
final class SubscriptionPurchase implements Purchase {
    final String purchaseId;
    final String invoiceId;
    final String? orderId;
    final PurchaseType purchaseType;
    final PurchaseStatus status;
    final String description;
    final String? purchaseTime; // ISO-8601
    final int price;
    final String amountLabel;
    final String currency;
    final String? developerPayload;
    final bool sandbox;
    final AcknowledgementState acknowledgementState;
    final String productId;
    final String expirationDate; // ISO-8601
    final bool gracePeriodEnabled;
}

Экземпляры модели создаёт сам SDK — публичного конструктора у класса нет.

Поле status объявлено с типом PurchaseStatus — фактически SDK возвращает в нём значение SubscriptionPurchaseStatus.

purchaseId — идентификатор покупки. Идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке.
invoiceId — идентификатор счета. Идентификатор счета. Используется для серверной валидации платежа, поиска платежей в консоли разработчика, а также отображается покупателю в истории платежей.
orderId - уникальный идентификатор оплаты, указанный разработчиком или сформированный автоматически (uuid).
PurchaseType — тип покупки:
- oneStep - одностадийная покупка;
- twoStep - двухстадийная покупка;
- undefined - стадийность не определена.
status - состояние подписки:
- invoiceCreated - создан счет на оплату, подписка ожидает оплаты.
- cancelled - счет на оплату подписки отменен.
- expired - срок действия оплаты счета истек.
- processing - первый платеж по подписке в обработке.
- rejected - первый платеж по подписке отклонен. Подписка не оформлена.
- active - подписка активна.
- paused - подписка приостановлена из-за проблем с оплатой.
- terminated - закончились попытки списания по подписке (все были неуспешными). Подписка закрыта автоматически из-за проблем с оплатой.
- closed - подписка была отменена пользователем или разработчиком. Истек срок оплаченного периода, подписка закрыта.
description - описание покупки.
purchaseTime — время покупки.
price — цена в минимальных единицах (в копейках).
amountLabel — отформатированная цена покупки, включая валютный знак.
currency — код валюты ISO 4217.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимальная длина 250 символов. Символы не экранируются (при использовании кавычек требуется экранирование)
sandbox — флаг тестового платежа. Значение true — тестовый платеж, false— реальный платеж.
acknowledgementState - состояние выдачи товара:
- pending - товар оплачен, выдача ещё не подтверждена разработчиком.
- acknowledged - выдача товара подтверждена.
- unknown - логика подтверждения к платежу не применима.
productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр). Идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
expirationDate - дата окончания действия подписки.
gracePeriodEnabled - флаг, указывающий, активен ли Grace-период для подписки.

Пример ответа — вывод toString() полученной модели (иллюстрация структуры, не компилируемый код).

Пример модели покупки подписки
SubscriptionPurchase(
    purchaseId: sub_purchase_12345,
    invoiceId: inv_sub_67890,
    orderId: order_sub_abcde,
    purchaseType: PurchaseType.oneStep,
    status: SubscriptionPurchaseStatus.active,
    description: Ежемесячная подписка на «Премиум»,
    purchaseTime: 2026-07-01T12:00:00+03:00,
    price: 29900,
    amountLabel: 299 ₽,
    currency: RUB,
    developerPayload: user_id:123;source:profile,
    sandbox: false,
    acknowledgementState: AcknowledgementState.acknowledged,
    productId: premium_monthly_v1,
    expirationDate: 2026-08-01T12:00:00+03:00,
    gracePeriodEnabled: true
)

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

Получение списка подписок, оформленных в SDK Billing Client

Получение списка подписок, оформленных в SDK Billing Client
RuStorePayClient.instance.purchaseInteractor.getBillingSubscriptions().then((subscriptions) {
  for (final subscription in subscriptions) {
    print('Product ID: ${subscription.productId}, Status: ${subscription.status}');
  }
}).catchError((error) {
  // Обработка ошибок
});

Метод возвращает список подписок, оформленных в SDK Billing Client.

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

SDK предоставляет только сам метод: когда и при каких условиях его вызывать, определяет бизнес-логика вашего приложения.

Модель покупки подписки, оформленной в SDK Billing Client

Модель подписки, оформленной в SDK Billing Client
final class BillingSubscription {
  final String purchaseId;
  final String invoiceId;
  final String? orderId;
  final PurchaseType purchaseType;
  final String description;
  final String? purchaseTime; // ISO-8601
  final int price;
  final String amountLabel;
  final String currency;
  final SubscriptionPurchaseStatus status;
  final String? developerPayload;
  final bool sandbox;
  final String productId;
  final String expirationDate; // ISO-8601
  final bool gracePeriodEnabled;
  final String subscriptionToken;
}

Экземпляры модели создаёт сам SDK — публичного конструктора у класса нет.

В отличие от моделей ProductPurchase и SubscriptionPurchase, класс BillingSubscription не реализует интерфейс Purchase. Такие подписки не попадают в результат методов getPurchase и getPurchases — их возвращает только метод getBillingSubscriptions.

Поля модели:

purchaseId — идентификатор покупки.
invoiceId — идентификатор счета.
orderId — уникальный идентификатор оплаты, указанный разработчиком или сформированный автоматически (uuid).
purchaseType — тип покупки:
- oneStep — одностадийная покупка;
- twoStep — двухстадийная покупка;
- undefined — стадийность не определена.
description — описание на языке language.
purchaseTime — время покупки.
price — цена в минимальных единицах (в копейках).
amountLabel — отформатированная цена покупки, включая валютный знак.
currency — код валюты ISO 4217.
status — статус подписки типа SubscriptionPurchaseStatus.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимальная длина 250 символов. Символы не экранируются (при использовании кавычек требуется экранирование)
sandbox — флаг тестового платежа. Значение true — тестовый платеж, false— реальный платеж.
productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
expirationDate — дата окончания срока действия подписки.
gracePeriodEnabled — флаг, указывающий, активен ли льготный период для подписки.
subscriptionToken — токен для валидации покупки на сервере.

Статусы подписки SubscriptionPurchaseStatus:

invoiceCreated — создан счет на оплату, подписка ожидает оплаты;
cancelled — подписка отменена пользователем;
expired — срок действия подписки истек;
processing — платеж в обработке;
rejected — платеж отклонен;
active — подписка активна;
paused — подписка приостановлена из-за проблем с оплатой;
terminated — закончились попытки списания по подписке (все были неуспешными). Подписка закрыта автоматически из-за проблем с оплатой;
closed — подписка была отменена пользователем или разработчиком. Истек срок оплаченного периода, подписка закрыта;
unknown — статус неизвестен.

Пример ответа — вывод toString() полученной модели (иллюстрация структуры, не компилируемый код).

Пример модели подписки, оформленной в SDK Billing Client
BillingSubscription(
    purchaseId: sub_purchase_12345,
    invoiceId: inv_sub_67890,
    orderId: order_sub_abcde,
    purchaseType: PurchaseType.oneStep,
    description: Ежемесячная подписка на «Премиум»,
    purchaseTime: 2026-07-01T12:00:00+03:00,
    price: 29900,
    amountLabel: 299 ₽,
    currency: RUB,
    status: SubscriptionPurchaseStatus.active,
    developerPayload: user_id:123;source:profile,
    sandbox: false,
    productId: premium_monthly_v1,
    expirationDate: 2026-08-01T12:00:00+03:00,
    gracePeriodEnabled: true,
    subscriptionToken: special_validation_token
)

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

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

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

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

final class RuStoreProductPurchaseException extends RuStoreException {
  const RuStoreProductPurchaseException({
    this.orderId,
    this.purchaseId,
    this.productId,
    this.invoiceId,
    this.quantity,
    this.purchaseType,
    this.sandbox,
    this.productType,
    String? message,
  }) : super(message);

  final dynamic orderId;
  final dynamic purchaseId;
  final dynamic productId;
  final dynamic invoiceId;
  final dynamic quantity;
  final dynamic purchaseType;
  final dynamic sandbox;
  final dynamic productType;
}

final class RuStorePurchaseCancelledException extends RuStoreException {
  const RuStorePurchaseCancelledException({
    this.purchaseId,
    this.purchaseType,
    this.productType,
    String? message,
  }) : super(message ?? 'Purchase product is cancelled');

  final dynamic purchaseId;
  final dynamic purchaseType;
  final dynamic productType;
}

purchaseId — идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке.
productId — идентификатор приобретённого продукта, указанный при создании в консоли разработчика RuStore.
invoiceId — идентификатор счёта. Используется для серверной валидации платежа, поиска платежей в консоли разработчика, а также отображается покупателю в истории платежей в мобильном приложении RuStore.
orderId — уникальный идентификатор оплаты, указанный разработчиком или сформированный автоматически (uuid).
purchaseType — тип покупки (PurchaseType.oneStep/PurchaseType.twoStep/PurchaseType.undefined — одностадийная/двухстадийная/стадийность не определена).
productType — тип продукта (ProductType.nonConsumable — непотребляемый товар, ProductType.consumable — потребляемый товар, ProductType.subscription — подписка).
quantity — количество товара, заданное при старте покупки.

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

Если вам необходимо произвести валидацию успешной покупки в RuStore, вы можете использовать публичные API-интерфейсы валидации (https://www.rustore.ru/help/work-with-rustore-api/api-subscription-payment/v2-purchase-invoiceid). Для валидации продуктов и подписок используются разные методы:

Для валидации покупки продукта используйте invoiceId из модели ProductPurchaseResult, возвращаемой после завершения покупки.
Для валидации покупки подписки используйте purchaseId из модели ProductPurchaseResult, возвращаемой после завершения покупки.

Тип приобретенного продукта можно определить по данным, полученным в ответе ProductPurchaseResult.

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

Получение invoiceId из результата покупки
class ProductPurchaseParams {
  final String productId;
  const ProductPurchaseParams(this.productId);
}

Future<void> exampleInvoiceFromResult() async {
  final params = ProductPurchaseParams('productId');

  final result = await RuStorePayClient.instance.purchaseInteractor.purchase(
    params.productId,
    preferredPurchaseType: PreferredPurchaseType.twoStep,
  );

  switch (result.productType) {
    case ProductType.consumable:
    case ProductType.nonConsumable:
      final invoiceId = result.invoiceId;
      yourApi.validateProduct(invoiceId);
      break;
    case ProductType.subscription:
      final purchaseId = result.purchaseId;
      yourApi.validateSubscription(purchaseId);
      break;
    default:
      // необязательная обработка неопределенного типа
      break;
  }
}

Получение invoiceId/purchaseId из модели Purchase
Future<void> exampleSubscriptionTokenFromPurchases() async {
  final purchases =
      await RuStorePayClient.instance.purchaseInteractor.getPurchases();

  for (final purchase in purchases) {
    if (purchase is SubscriptionPurchase) {
      final purchaseId = purchase.purchaseId;
      yourApi.validateSubscription(purchaseId);
    } else {
      final invoiceId = purchase.invoiceId;
      yourApi.validateProduct(invoiceId);
    }
  }
}

RuStoreUtils

RuStoreUtils — набор публичных методов для взаимодействия с приложением RuStore на устройстве пользователя из Flutter-приложения. Доступ к утилитам осуществляется через RuStorePayClient.instance.ruStoreUtils.

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

Вызов метода IsRuStoreInstalled
RuStorePayClient.instance.ruStoreUtils.isRuStoreInstalled().then((isInstalled) {

});

Возвращает логическое значение isInstalled

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

Вызов метода openRuStoreDownloadInstruction
RuStorePayClient.instance.ruStoreUtils.openRuStoreDownloadInstruction();

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

Вызов метода openRuStore
RuStorePayClient.instance.ruStoreUtils.openRuStore();

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

Вызов метода openRuStoreAuthorization
RuStorePayClient.instance.ruStoreUtils.openRuStoreAuthorization();

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

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

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

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

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

RuStorePaymentNetworkException — ошибка сетевого взаимодействия SDK. Все исключения SDK наследуются от базового RuStoreException, у которого есть поле message с описанием причины ошибки.

sealed class RuStoreException implements Exception {
  const RuStoreException([this.message]);

  final String? message;
}

final class RuStorePaymentNetworkException extends RuStoreException {
  const RuStorePaymentNetworkException([super.message]);
}

Все исключения SDK наследуются от sealed-класса RuStoreException.

RuStoreException — базовый класс всех исключений SDK;
RuStorePaymentNetworkException — ошибка сетевого взаимодействия SDK;
RuStorePaymentCommonException — общая ошибка платежного SDK;
RuStorePayClientAlreadyExist — ошибка повторной инициализации SDK;
RuStorePayClientNotCreated — попытка обратиться к публичным интерфейсам SDK до момента ее инициализации;
RuStorePayInvalidActivePurchase — запущен процесс оплаты неизвестного типа продукта;
RuStorePayInvalidConsoleAppId — не задан обязательный параметр console_app_id_value для инициализации SDK;
RuStorePaySignatureException — неверная сигнатура ответа. Возникает при попытке совершить мошеннические действия;
EmptyPaymentTokenException — ошибка получения платежного токена;
InvalidCardBindingIdException — ошибка оплаты сохраненной картой;
ApplicationSchemeWasNotProvided — не указана схема для обратного диплинка;
RuStoreProductPurchaseException - ошибка покупки продукта. Структура модели представлена в разделе структура результата покупки;
RuStorePurchaseCancelledException - произошла отмена покупки продукта (пользователь закрыл платежную шторку). Структура модели представлена в разделе структура результата покупки;
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***`	Внутренняя ошибка.

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

Обработка deeplink​

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

Необходимые разрешения и параметры безопасности​

Методы SDK​

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

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

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

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

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

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

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

Работа с подтверждением выдачи товара​

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

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

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

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

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

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

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

Получение списка подписок, оформленных в SDK Billing Client​

Модель покупки подписки, оформленной в SDK Billing Client​

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

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

RuStoreUtils​

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

Коды ошибок​

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

Обработка deeplink

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

Необходимые разрешения и параметры безопасности

Методы SDK

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

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

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

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

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

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

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

Работа с подтверждением выдачи товара

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

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

Типы покупок

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

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

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

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

Получение списка подписок, оформленных в SDK Billing Client

Модель покупки подписки, оформленной в SDK Billing Client

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

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

RuStoreUtils

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

Коды ошибок