7.0.0 (Beta)

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

подсказка

• Если не знаете с чего начать, прочтите инструкцию в сценариях использования.

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

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

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

Условия работы платежей

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

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

1. Скопируйте проекты плагина и приложения-примера из официального репозитория RuStore на GitFlic.
2. Скопируйте содержимое папки godot_example/android/plugins в папку your_project/android/plugins.
3. В пресете сборки Android в списке Плагины отметьте плагины Ru Store Godot Pay и Ru Store Godot Core.

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

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

<!-- Initializing sdk -->
<meta-data
    android:name="console_app_id_key"
    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"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.godot.game"
    android:versionCode="1"
    android:versionName="1.0"
    android:installLocation="auto" >
 
    <supports-screens
        android:smallScreens="true"
        android:normalScreens="true"
        android:largeScreens="true"
        android:xlargeScreens="true" />
 
    <uses-feature
        android:glEsVersion="0x00030000"
        android:required="true" />
 
    <application
        android:label="@string/godot_project_name_string"
        android:allowBackup="false"
        android:icon="@mipmap/icon"
        android:appCategory="game"
        android:isGame="true"
        android:hasFragileUserData="false"
        android:requestLegacyExternalStorage="false"
        tools:ignore="GoogleAppIndexingWarning" >
        <meta-data
            android:name="org.godotengine.editor.version"
            android:value="${godotEditorVersion}" />
        <activity
            android:name=".GodotApp"
            android:label="@string/godot_project_name_string"
            android:theme="@style/GodotAppSplashTheme"
            android:launchMode="singleInstancePerTask"
            android:excludeFromRecents="false"
            android:exported="true"
            android:screenOrientation="landscape"
            android:configChanges="orientation|keyboardHidden|screenSize|smallestScreenSize|density|keyboard|navigation|screenLayout|uiMode"
            android:resizeableActivity="false"
            tools:ignore="UnusedAttribute" >
 
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
 
        <!-- Initializing sdk -->
        <meta-data
            android:name="console_app_id_key"
            android:value="@string/rustore_PayClientSettings_consoleApplicationId" />
        <meta-data
            android:name="internal_config_key"
            android:value="@string/rustore_PayClientSettings_internalConfigKey" />
    </application>
</manifest>

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

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

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

примечание

Application Id приложения, указанный в Проект > Экспорт... > Android > Параметры > Уникальное Имя, должен совпадать с Application Id APK-файла, который вы публиковали в системе RuStore Консоль.

warning

Подпись тестируемой сборки (например, debug) приложения должна совпадать с подписью сборки приложения, которая была загружена в консоль и прошла модерацию ранее (например, release)

warning

Не задавайте значения console_app_id_key и internal_config_key напрямую в манифесте. Строки должны располагаться в файле ресурсов, например: your_project/android/build/res/values/rustore_values.xml. При этом значение internal_config_key всегда должно быть godot.

Пример rustore_values.xml

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="rustore_PayClientSettings_consoleApplicationId" translatable="false">198332</string>
    <string name="rustore_PayClientSettings_internalConfigKey" translatable="false">godot</string>
</resources>

Работа с SDK

Перед использованием всех методов плагина должен быть создан экземпляр объекта RuStoreGodotPayClient.

Создание инстанса RuStoreGodotPayClient

var _pay_client: RuStoreGodotPayClient = RuStoreGodotPayClient.get_instance()

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

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

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

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

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

• on_get_purchases_availability_success;
• on_get_purchases_availability_failure.

Подписка на события

func _ready():
   # Инициализация _pay_client
     
   _pay_client.on_get_purchase_availability_success.connect(_on_get_purchase_availability_success)
   _pay_client.on_get_purchase_availability_failure.connect(_on_get_purchase_availability_failure)
 
func _on_get_purchase_availability_success(result: RuStorePayGetPurchaseAvailabilityResult):
    pass
	
func _on_get_purchase_availability_failure(error: RuStoreError):
   pass

Вызов метода get_purchase_availability

_pay_client.get_purchase_availability()

Проверка установки приложения RuStore

Чтобы проверить установлен ли на устройстве пользователя RuStore необходимо вызвать метод is_rustore_installed.

var is_rustore_installed: bool = _pay_client.is_rustore_installed()

• true – RuStore установлен.
• false – RuStore не установлен.

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

Вы проверили, что платежи доступны и пользователи могут совершать покупки. Теперь можно получить список продуктов. Используйте метод get_products, чтобы получить информацию о продуктах, добавленных в ваше приложение через RuStore Консоль.

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

• on_get_products_success;
• on_get_products_failure.

Подписка на события

func _ready():
    # Инициализация _pay_client
     
    _pay_client.on_get_products_success.connect(_on_get_products_success)
    _pay_client.on_get_products_failure.connect(_on_get_products_failure)
 
func _on_get_products_success(products: Array[RuStorePayProduct]):
    pass
 
func _on_get_products_failure(error: RuStoreError):
    pass

Вызов метода get_products

var PRODUCT_IDS: Array[RuStorePayProductId] = [
    RuStorePayProductId.new("con_1"),
    RuStorePayProductId.new("non_con_1"),
]
 
_pay_client.get_products(PRODUCT_IDS)

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

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

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

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

class_name RuStorePayProduct extends Object
 
var productId: RuStorePayProductId = null
var type: ERuStorePayProductType.Item = 0
var amountLabel: RuStorePayAmountLabel = null
var price: RuStorePayPrice = null
var currency: RuStorePayCurrency = null
var imageUrl: RuStorePayUrl = null
var title: RuStorePayTitle = null
var description: RuStorePayDescription = null

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

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

Одностадийна оплата (без холдирования средств)

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

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

• on_purchase_one_step_success;
• on_purchase_one_step_failure.

Подписка на события

func _ready():
    # Инициализация _pay_client
 
    _pay_client.on_purchase_one_step_success(_on_purchase_one_step_success)
    _pay_client.on_purchase_one_step_failure(_on_purchase_one_step_failure)
 
func _on_purchase_one_step_success(result: RuStorePayProductPurchaseResult):
    pass
   
func _on_purchase_one_step_failure(product_id: RuStorePayProductId, error: RuStoreError):
    pass

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

var parameters = RuStorePayProductPurchaseParams.new(
      RuStoreProductId.new("product_id"),
      null,
      null,
      RuStoreQuantity.new(1));
 
_pay_client.purchase_one_step(parameters)

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

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

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

• on_purchase_two_step_success;
• on_purchase_two_step_failure.

Подписка на события

func _ready():
    # Инициализация _pay_client
 
    _pay_client.on_purchase_two_step_success(_on_purchase_two_step_success)
    _pay_client.on_purchase_two_step_failure(_on_purchase_two_step_failure)
 
func _on_purchase_two_step_success(result: RuStorePayProductPurchaseResult):
    pass
   
func _on_purchase_two_step_failure(product_id: RuStorePayProductId, error: RuStoreError):
    pass

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

var parameters = RuStorePayProductPurchaseParams.new(
      RuStoreProductId.new("product_id"),
      null,
      null,
      RuStoreQuantity.new(1));
 
_pay_client.purchase_two_step(parameters)

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

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

class_name RuStorePayProductPurchaseParams extends Object

var productId: RuStorePayProductId = null
var developerPayload: RuStorePayDeveloperPayload = null
var orderId: RuStorePayOrderId = null
var quantity: RuStorePayQuantity = null

func _init(
   productId: RuStorePayProductId,
   developerPayload: RuStorePayDeveloperPayload = null,
   orderId: RuStorePayOrderId = null,
   quantity: RuStorePayQuantity = null
):
   self.productId = productId
   self.developerPayload = developerPayload
   self.orderId = orderId
   self.quantity = quantity

• productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
• quantity — количество продукта (необязательный параметр — если не указывать, будет подставлено значение 1).
• orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
• developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки. Максимальная длина 250 символов.

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

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

class_name RuStorePayProductPurchaseResult extends Object

class SuccessProductPurchaseResult extends RuStorePayProductPurchaseResult:

   var invoiceId: RuStorePayInvoiceId = null
   var orderId: RuStorePayOrderId = null
   var productId: RuStorePayProductId = null
   var purchaseId: RuStorePayPurchaseId = null
   var subscriptionToken: RuStorePaySubscriptionToken = null

class CancelProductPurchaseResult extends RuStorePayProductPurchaseResult:

   var purchaseId: RuStorePayPurchaseId = null

class FailureProductPurchaseResult extends RuStorePayProductPurchaseResult:

   var cause: RuStoreError = null
   var invoiceId: RuStorePayInvoiceId = null
   var orderId: RuStorePayOrderId = null
   var productId: RuStorePayProductId = null
   var purchaseId: RuStorePayPurchaseId = null
   var quantity: RuStorePayQuantity = null
   var subscriptionToken: RuStorePaySubscriptionToken = null

• SuccessProductPurchaseResult — результат успешного завершения покупки цифрового товара.
• FailureProductPurchaseResult — при отправке запроса на оплату или получения статуса оплаты возникла проблема, невозможно установить статус покупки.
• CancelProductPurchaseResult — запрос на покупку отправлен, при этом пользователь закрыл «платёжную шторку» на своём устройстве, и результат оплаты неизвестен.

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

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

Подписка на события

func _ready:
    # Инициализация _pay_client
   
    _pay_client.on_get_purchase_success(_on_get_purchase_success)
    _pay_client.on_get_purchase_failure(_on_get_purchase_failure)
 
func _on_get_purchase_success(purchase: RuStorePayPurchase):
    pass
   
func _on_get_purchase_failure(purchase_id: RuStorePayPurchaseId, error: RuStoreError):
    pass

Вызов метода получения информации о покупке пользователя

var purchase_id: RuStorePayPurchaseId = ...
 
_pay_client.get_purchase(purchase_id)

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

Структура с информацией о покупке

class_name RuStorePayPurchase extends Object

var amountLabel: RuStorePayAmountLabel = null
var currency: RuStorePayCurrency = null
var description: RuStorePayDescription = null
var developerPayload: RuStorePayDeveloperPayload = null
var invoiceId: RuStorePayInvoiceId = null
var orderId: RuStorePayOrderId = null
var price: RuStorePayPrice = null
var productId: RuStorePayProductId = null
var productType: ERuStorePayProductType.Item = 0
var purchaseId: RuStorePayPurchaseId = null
var purchaseTime: RuStorePayTime = null
var purchaseType: ERuStorePayPurchaseType.Item = 0
var quantity: RuStorePayQuantity = null
var status: ERuStorePayPurchaseStatus.Item = 0
var subscriptionToken: RuStorePaySubscriptionToken = null

• amountLabel — отформатированная цена покупки, включая валютный знак.
• currency — код валюты ISO 4217.
• description — описание на языке language.
• developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки
• invoiceId — идентификатор счёта.
• orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
• price — цена в минимальных единицах (в копейках).
• productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
• productType — тип продукта.

• purchaseId — идентификатор покупки.
• purchaseTime — время покупки.
• PurchaseType — тип покупки:
  • ONE_PHASE - одностадийная покупка;
  • TWO_PHASE - двухстадийная покупка.
• quantity — количество продукта (необязательный параметр — если не указывать, будет подставлено значение 1).
• status — состояние покупки:
  • INVOICE_CREATED — создан счёт на оплату, покупка ожидает оплаты;
  • CANCELLED — покупка отменена покупателем;
  • PROCESSING — запущена оплата;
  • REJECTED — покупка отклонена (например, ввиду недостатка средств);
  • PAID — только для двухстадийной оплаты, промежуточный статус, средства на счёте покупателя захолдированы, покупка ожидает подтверждения от разработчика;
  • CONFIRMED — покупка успешно оплачена;
  • REFUNDED — запрос на возврат средств за покупку совершён успешно;
  • REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 72 часов, холдирование средств отменено.

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

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



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



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

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

Подписка на события

func _ready:
   # Инициализация _pay_client
   
   _pay_client.on_get_purchases_success.connect(_on_get_purchases_success)
   _pay_client.on_get_purchases_failure.connect(_on_get_purchases_failure)
 
func _on_get_purchases_success(purchases: Array[RuStorePayPurchase]):
   pass
   
func _on_get_purchases_failure(error: RuStoreError):
   pass

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

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

_pay_client.get_purchases()

Метод возвращает список покупок в статусах CONFIRMED (для непотребляемых товаров) и PAID (для потребляемых товаров). Ниже представлена модель покупки.

class_name RuStorePayPurchase extends Object

var amountLabel: RuStorePayAmountLabel = null
var currency: RuStorePayCurrency = null
var description: RuStorePayDescription = null
var developerPayload: RuStorePayDeveloperPayload = null
var invoiceId: RuStorePayInvoiceId = null
var orderId: RuStorePayOrderId = null
var price: RuStorePayPrice = null
var productId: RuStorePayProductId = null
var productType: ERuStorePayProductType.Item = 0
var purchaseId: RuStorePayPurchaseId = null
var purchaseTime: RuStorePayTime = null
var purchaseType: ERuStorePayPurchaseType.Item = 0
var quantity: RuStorePayQuantity = null
var status: ERuStorePayPurchaseStatus.Item = 0
var subscriptionToken: RuStorePaySubscriptionToken = null

• amountLabel — отформатированная цена покупки, включая валютный знак.
• currency — код валюты ISO 4217.
• description — описание на языке language.
• developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки
• invoiceId — идентификатор счёта.
• orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
• price — цена в минимальных единицах (в копейках).
• productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
• productType — тип продукта.

• purchaseId — идентификатор покупки.
• purchaseTime — время покупки.
• PurchaseType — тип покупки:
  • ONE_PHASE - одностадийная покупка;
  • TWO_PHASE - двухстадийная покупка.
• quantity — количество продукта (необязательный параметр — если не указывать, будет подставлено значение 1).
• status — состояние покупки:
  • INVOICE_CREATED — создан счёт на оплату, покупка ожидает оплаты;
  • CANCELLED — покупка отменена покупателем;
  • PROCESSING — запущена оплата;
  • REJECTED — покупка отклонена (например, ввиду недостатка средств);
  • PAID — только для двухстадийной оплаты, промежуточный статус, средства на счёте покупателя захолдированы, покупка ожидает подтверждения от разработчика;
  • CONFIRMED — покупка успешно оплачена;
  • REFUNDED — запрос на возврат средств за покупку совершён успешно;
  • REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 72 часов, холдирование средств отменено.

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

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

Получение subscriptionToken из результата покупки

func _on_purchase_two_step_success(result: RuStorePayProductPurchaseResult):
   if result is RuStorePayProductPurchaseResult.SuccessProductPurchaseResult:
      yourApi.validate(result.subscriptionToken);

Также можно получить subscriptionToken в сущности Purchase. Сущность Purchase можно получить используя метод get_purchases.

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

func _on_get_purchases_success(purchases: Array[RuStorePayPurchase]):
   for item in purchases:
      yourApi.validate(item.subscriptionToken);

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

Вызов метода потребления (подтверждения)

Для потребления (подтверждения) покупки используйте метод consume_purchase. Запрос на потребление (подтверждение) покупки должен сопровождаться выдачей товара. После вызова подтверждения покупка перейдёт в статус CONSUMED.

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

• on_confirm_two_step_purchase_success;
• on_confirm_two_step_purchase_failure.

Подписка на события

func _ready:
    # Инициализация _pay_client
   
    _pay_client.on_confirm_two_step_purchase_success(_on_confirm_two_step_purchase_success)
    _pay_client.on_confirm_two_step_purchase_failure(_on_confirm_two_step_purchase_failure)
 
func _on_confirm_two_step_purchase_success(purchase_id: RuStorePayPurchaseId):
    pass
 
func _on_confirm_two_step_purchase_failure(purchase_id: RuStorePayPurchaseId, error: RuStoreError):
    pass

Вызов метода подтверждения

var id: RuStorePayPurchaseId = ...
var payload: RuStorePayDeveloperPayload = ...
 
_pay_client.confirm_two_step_purchase(id, payload)

• id — идентификатор покупки.
• payload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки

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

Для отмены покупки используйте метод cancel_two_step_purchase.

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

• on_cancel_two_step_purchase_success;
• on_cancel_two_step_purchase_failure.

Подписка на события

func _ready:
    # Инициализация _pay_client
  
    _pay_client.on_cancel_two_step_purchase_success(_on_cancel_two_step_purchase_success)
    _pay_client.on_cancel_two_step_purchase_failure(_on_cancel_two_step_purchase_failure)
	
func _on_cancel_two_step_purchase_success(purchase_id: String):
    pass
  
func _on_cancel_two_step_purchase_failure(purchase_id: String, error: RuStoreError):
    pass

Вызов метода cancel_two_step_purchase

# Ваша реализация UI отмены покупки
func _on_cancel_two_step_purchase_pressed(purchaseId: RuStorePayPurchaseId):
    _pay_client.cancel_two_step_purchase(purchaseId)

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

• Обратный вызов (callback) on_cancel_two_step_purchase_success возвращает идентификатор покупки.
• Обратный вызов (callback) on_cancel_two_step_purchase_failure возвращает идентификатор покупки типа String и объект RuStoreError с информацией об ошибке. Структура ошибки описана в разделе Обработка ошибок.

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

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