Перейти к основному содержимому

SDK Платежи in-app и подписки для Defold (версия 9.1.0)

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

подсказка

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

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

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

  1. Скопируйте проекты плагина и приложения-примера из официального репозитория RuStore на GitFlic.
  2. Скопируйте папки billing_example/extension_rustore_billing и billing_example/extension_rustore_core в корень вашего проекта.

Для корректной работы оплаты через сторонние приложения (СБП, SberPay и др.) необходимо правильно реализовать обработку deeplink.

Плагин extension_rustore_billing содержит реализацию RuStoreIntentFilterActivity, которая обрабатывает входящие intent и возвращается в игровую активити com.dynamo.android.DefoldActivity.

Для включения в сборку добавьте RuStoreIntentFilterActivity в AndroidManifest.xml с указанием двух intent-filter.

AndroidManifest.xml
<activity android:name="ru.rustore.defold.billing.RuStoreIntentFilterActivity"
          android:theme="@android:style/Theme.NoDisplay"
          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" />
        <!-- Set your appscheme -->
        <data android:scheme="yourappscheme" />
    </intent-filter>
</activity>

Вместо yourappscheme из примера выше укажите название своей схемы. Например, ru.package.name.rustore.scheme.

к сведению

Схема, указанная в AndroidManifest файле должна совпадать со схемой, которую вы указываете в методе create RuStore SDK платежей.

К игровому активити добавьте атрибут android:launchMode="singleTask" и удалите intent-filter с android.intent.action.MAIN.

AndroidManifest.xml
<activity android:name="com.dynamo.android.DefoldActivity"
          android:label="{{project.title}}"
          android:configChanges="fontScale|keyboard|keyboardHidden|locale|mcc|mnc|navigation|orientation|screenLayout|screenSize|smallestScreenSize|touchscreen|uiMode"
          android:theme="@android:style/Theme.NoTitleBar.Fullscreen"
          android:screenOrientation="{{orientation-support}}"
          android:exported="true"
          android:launchMode="singleTask">
    <meta-data android:name="android.app.lib_name"
               android:value="{{exe-name}}" />
</activity>

Пример приложения содержит модифицированный манифест в файле billing_example/extension_rustore_billing/manifests/android/AndroidManifest.xml

Пример оформления манифеста
<?xml version="1.0" encoding="utf-8"?>
<?xml version="1.0" encoding="utf-8"?>
<!-- BEGIN_INCLUDE(manifest) -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        package="{{android.package}}"
        android:versionCode="{{android.version_code}}"
        android:versionName="{{project.version}}"
        android:installLocation="auto">

    <uses-feature android:required="true" android:glEsVersion="0x00020000" />
    <uses-sdk android:minSdkVersion="{{android.minimum_sdk_version}}" android:targetSdkVersion="{{android.target_sdk_version}}" />
    <application
        {{#has-icons?}}
        android:icon="@drawable/icon"
        {{/has-icons?}}
        android:label="{{project.title}}" android:hasCode="true"
        android:name="android.support.multidex.MultiDexApplication"
        android:enableOnBackInvokedCallback="true"
        android:debuggable="{{android.debuggable}}">

        <meta-data android:name="android.max_aspect" android:value="2.1" />
        <meta-data android:name="android.notch_support" android:value="true"/>

        <activity android:name="ru.rustore.defold.billing.RuStoreIntentFilterActivity"
                  android:theme="@android:style/Theme.NoDisplay"
                  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" />
                <!-- Set your appscheme -->
                <data android:scheme="example" />
            </intent-filter>
        </activity>

        <activity android:name="com.dynamo.android.DefoldActivity"
                android:label="{{project.title}}"
                android:configChanges="fontScale|keyboard|keyboardHidden|locale|mcc|mnc|navigation|orientation|screenLayout|screenSize|smallestScreenSize|touchscreen|uiMode"
                android:theme="@android:style/Theme.NoTitleBar.Fullscreen"
                android:screenOrientation="{{orientation-support}}"
                android:exported="true"
                android:launchMode="singleTask">
            <meta-data android:name="android.app.lib_name"
                    android:value="{{exe-name}}" />
        </activity>

    </application>

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

</manifest>
<!-- END_INCLUDE(manifest) -->
Реализация RuStoreIntentFilterActivity
package ru.rustore.defold.billing;

import android.app.Activity;
import android.content.Intent;
import android.os.Bundle;

public class RuStoreIntentFilterActivity extends Activity {
    
    private final String defoldActivityClassName = "com.dynamo.android.DefoldActivity";
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        if (savedInstanceState == null) {
            RuStoreBilling.onNewIntent(getIntent());
        }
        
        if (!isTaskRoot()) {
            finish();
            return;
        }
        
        startGameActivity(defoldActivityClassName);
        finish();
    }
    
    @Override
    public void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        
        RuStoreBilling.onNewIntent(intent);
    }
    
    private void startGameActivity(String gameActivityClassName) {
        Class<?> gameActivityClass = getActivityClass(gameActivityClassName);
        if (gameActivityClass != null) {
            Intent intent = new Intent(this, gameActivityClass);
            intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TASK);
            startActivity(intent);
        }
    }
    
    private Class<?> getActivityClass(String activityClassName) {
        try {
            return Class.forName(activityClassName);
        } catch(ClassNotFoundException ex) {
            return null;
        }
    }
}

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

Перед вызовом методов библиотеки необходимо выполнить её инициализацию.

Для инициализации вызовите метод init().
Вызов метода init
local APPLICATION_ID = "123456"
local DEEPLINK_SCHEME = "yourappscheme"
local DEBUG_LOGS = true

rustorebilling.init(APPLICATION_ID, DEEPLINK_SCHEME, DEBUG_LOGS)
Где в RuStore Консоль отображаются идентификаторы приложений?
  1. Перейдите на вкладку Приложения и выберите нужное приложение.
  2. Скопируйте идентификатор из URL-адреса страницы приложения — это набор цифр между apps/ и /versions. Например, для URL-адреса https://console.rustore.ru/apps/123456/versions ID приложения — 123456.

  • DEEPLINK_SCHEME — схема deeplink, необходимая для возврата в ваше приложение после оплаты через стороннее приложение (например, SberPay или СБП). SDK генерирует свой хост к данной схеме.
  • DEBUG_LOGS — флаг, регулирующий ведение журнала событий. Укажите значение true, если хотите, чтобы события попадали в журнал. В ином случае укажите false.
примечание
Схема deeplink, передаваемая в DEEPLINK_SCHEME, должна совпадать со схемой, указанной в AndroidManifest.xml (подробнее см. Обработка deeplink).

Как работают платежи​

Приложение для оплаты RuStore Сервер RuStore_Billing_Client Ваш сервер Ваше приложение Покупатель Приложение для оплаты RuStore Сервер RuStore_Billing_Client Ваш сервер Ваше при�ложение ПокупательПроверка доступности работы платежей [Необязательно] Серверная валидация платежа [Обязательно] Покупка потребляемого товара [Обязательно] Обработка deeplink при оплате СБП, SberPay и т.д.Покупка продукта Входит в ваше приложение checkPurchasesAvailability Результат getProducts Список продуктов вашего приложения Показ списка доступных покупок Приобретение товара purchaseProduct Запрос способа оплаты Проведение платежа Способ оплаты Результат проведения платежа Информация о платеже Серверная валидация (public API) Достоверная информация о покупке Начисление товара покупателю Резул�ьтат валидации confirmPurchase Результат потребления purchaseProduct Запрос способа оплаты Указал СБП/SberPay/T-Pay Запуск процесса оплаты Сценарий оплаты Оплата покупки Возврат в приложение OnNewIntent Результат оплаты Отображение платёжной шторки с результатом оплаты

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

Устарело

Метод устарел и не рекомендуется к использованию.

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

к сведению

Начиная с версии 6.0.0 процедура и результат проверки доступности платежей зависит от наличия RuStore на устройстве пользователя.

Подробнее см. ниже.

Наличие RuStoreПроцедура и результат проверки
Не установлен

Метод вернёт isAvailable == false — статус платежей неизвестен (приём платежей без установки RuStore).

Установлен

Выполняется проверка следующих условий.

  • На устройстве пользователя установлена актуальная версия RuStore.
  • Приложение RuStore поддерживает функциональность платежей.
  • Пользователь авторизован в RuStore.

  • Пользователь и приложение не должны быть заблокированы в RuStore

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

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

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

предупреждение

Таким образом, положительный ответ вернётся в двух случаях:

  • если RuStore не установлен;
  • если RuStore установлен и установленный экземпляр RuStore на устройстве пользователя соответствует проверяемым условиям.

Сам по себе ответ метода check_purchases_availability не показывает, установлен ли RuStore на устройстве пользователя. Вы можете проверить наличие RuStore на устройстве пользователя с помощью метода isRuStoreInstalled.

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

  • rustore_check_purchases_available_success;
  • rustore_check_purchases_available_failure.
Подписка на события
function init(self)
    # Инициализация rustorebilling
 
    rustorecore.connect("rustore_check_purchases_available_success", _check_purchases_available_success)
    rustorecore.connect("rustore_check_purchases_available_failure", _check_purchases_available_failure)
end
  
function _check_purchases_availability_success(self, channel, value)
    local data = json.decode(value)
end
  
function _check_purchases_availability_failure(self, channel, value)
    local data = json.decode(value)
end
Вызов метода check_purchases_availability
rustorebilling.check_purchases_availability()

Обратный вызов (callback) rustore_check_purchases_availability_success возвращает строку JSON с информацией о доступности сервиса.

  • isAvailable — выполнение условий выполнения платежей (true/false).
  • cause — информация об ошибке.

Структура ошибки описана в разделе Обработка ошибок.

Обратный вызов (callback) rustore_check_purchases_availability_failure возвращает строку JSON с информацией об ошибке. Структура ошибки описана в разделе Обработка ошибок.

Методы SDK​

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

В rustorebilling есть возможность определить, является ли пользователь авторизованным. Для определения наличия авторизации у пользователя требуется вызвать метод get_authorization_status.

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

  • rustore_on_get_authorization_status_success;
  • rustore_on_get_authorization_status_failure.
Подписка на события
function init(self)
    # Инициализация rustorebilling
	
    rustorecore.connect("rustore_on_get_authorization_status_success", _on_get_authorization_status_success)
    rustorecore.connect("rustore_on_get_authorization_status_failure", _on_get_authorization_status_failure)
end

function _on_get_authorization_status_success(self, channel, value)
    local isAuthorized = value -- boolean
end
  
function _on_get_authorization_status_failure(self, channel, value)
    local data = json.decode(value)
end
Вызов метода get_authorization_status
rustorebilling.get_authorization_status()
Важно

В случае использования SDK вне RuStore результат true также может вернуться, если в процессе оплаты пользователь авторизовался через VK ID и с момента авторизации прошло менее 15 минут.

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

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

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

  • rustore_on_get_products_success;
  • rustore_on_get_products_failure.
Подписка на события
function init(self)
    # Инициализация rustorebilling
 
    rustorecore.connect("rustore_on_get_products_success", _on_get_products_success)
    rustorecore.connect("rustore_on_get_products_failure", _on_get_products_failure)
end
 
function _on_get_products_success(self, channel, value)
    local data = json.decode(value)
end
 
function _on_get_products_failure(self, channel, value)
    local data = json.decode(value)
end
Вызов метода get_products
local PRODUCT_IDS = {
    "non_con2",
    "non_con1",
    "con2",
    "con1",
    "sub2",
    "sub1"}
 
rustorebilling.get_products(PRODUCT_IDS)

PRODUCT_IDS — список идентификаторов продуктов. В нём не должно быть более 100 позиций.

Чтобы указать id продуктов, которые нужны для работы метода, выполните следующие действия.

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

Обратный вызов (callback) rustore_on_get_products_success возвращает строку JSON с информацией о продуктах (см. ниже).

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

Доступные поля объекта subscription (см. ниже).

  • subscriptionPeriod — период подписки.
  • freeTrialPeriod — пробный период подписки.
  • gracePeriod — льготный период подписки.
  • introductoryPrice — отформатированная вступительная цена подписки, включая знак валюты, на языке product:language.
  • introductoryPriceAmount — вступительная цена в минимальных единицах валюты (в копейках).
  • introductoryPricePeriod — расчётный период вступительной цены.

Доступные поля объекта «период» (см. ниже).

  • years — количество лет.
  • months — количество месяцев.
  • days — количество дней.

Обратный вызов (callback) rustore_on_get_products_failure возвращает строку JSON с информацией об ошибке. Структура ошибки описана в разделе Обработка ошибок.

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

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

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

  • rustore_on_purchase_product_success;
  • rustore_on_purchase_product_failure.
Подписка на события
function init(self)
    # Инициализация rustorebilling
 
    rustorecore.connect("rustore_on_purchase_product_success", _on_purchase_product_success)
    rustorecore.connect("rustore_on_purchase_product_failure", _on_purchase_product_failure)
end
 
function _on_purchase_product_success(self, channel, value)
    local data = json.decode(value)
end
  
function _on_purchase_product_failure(self, channel, value)
    local data = json.decode(value)
end
Вызов метода purchase_product
local PRODUCT_ID = "example_id"
local PARAMS = "{" ..
	"\"orderId\":\"example\"," ..
	"\"quantity\":1," ..
	"\"payload\":\"example\"" ..
	"}"

rustorebilling.purchase_product(PRODUCT_ID, PARAMS)
  • PRODUCT_ID — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр);
  • PARAMS — опциональные параметры:
    • orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов;
    • quantity — количество продукта. Необязательный параметр со стандартным значением 1. Применим только к покупке потребляемых товаров;
    • payload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации.

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

  • type — тип результата запроса

    • Success — результат успешного завершения покупки цифрового товара;
    • Failure — при отправке запроса на оплату или получения статуса оплаты возникла проблема, невозможно установить статус покупки;
    • Cancelled — запрос на покупку отправлен, при этом пользователь закрыл «платёжную шторку» на своём устройстве, и результат оплаты неизвестен;
    • InvalidPaymentState — ошибка работы SDK платежей. Может возникнуть, в случае некорректного обратного deeplink.

  • data — строка JSON с опциональными полями.

Объект типа Success возвращается в случае удачного выполнения запроса. Доступны следующие поля.

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

  • sandbox — флаг тестового платежа. Значение true — тестовый платёж, false— реальный платёж.

    .
  • subscriptionToken — токен для валидации покупки на сервере.

Объект типа Failure возвращается в случае ошибки при выполнения запроса. Доступны следующие поля.

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

  • sandbox — флаг тестового платежа. Значение true — тестовый платёж, false— реальный платёж.

    .
  • errorCode — код ошибки.

Коды ошибок описаны в разделе Коды ошибок.

Объект типа Cancelled возвращается в случае отмены покупки пользователем. Доступны следующие поля.

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

  • sandbox — флаг тестового платежа. Значение true — тестовый платёж, false— реальный платёж.

    .

Объект типа InvalidPaymentState возвращается в случае ошибки работы SDK платежей. Например в случае некорректного обратного deeplink.

Обратный вызов (callback) rustore_on_purchase_product_failure возвращает строку JSON с информацией об ошибке. Структура ошибки описана в разделе Обработка ошибок.

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

Метод возвращает только покупки со статусами из таблицы ниже. Подробнее о других возможных состояниях покупки смотрите в разделе Получение сведений о покупке.

Тип/СтатусINVOICE_CREATEDCONFIRMEDPAID
CONSUMABLE++
NON-CONSUMABLE++
SUBSCRIPTION++
примечание

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

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

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

  • rustore_on_get_purchases_success;
  • rustore_on_get_purchases_failure.
Подписка на события
function init(self)
    # Инициализация rustorebilling
 
    rustorecore.connect("rustore_on_get_purchases_success", _on_get_purchases_success)
    rustorecore.connect("rustore_on_get_purchases_failure", _on_get_purchases_failure)
end
 
function _on_get_purchases_success(self, channel, value)
    local data = json.decode(value)
 
    for key, value in pairs(data) do
        -- value.amount
    end
end
  
function _on_get_purchases_failure(self, channel, value)
    local data = json.decode(value)
end
Вызов метода get_purchases
rustorebilling.get_purchases()

Обратный вызов (callback) rustore_on_get_purchases_success возвращает массив объектов с информацией о покупках. Доступны следующие поля.

  • amount — цена в минимальных единицах валюты.
  • amountLable — отформатированная цена покупки, включая валютный знак.
  • currency — код валюты ISO 4217.
  • developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации.
  • invoiceId — идентификатор счёта.
  • language — язык, указанный с помощью BCP 47 кодирования.
  • orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
  • productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
  • productType — тип продукта (потребляемый / непотребляемый / подписка): CONSUMABLE/NON-CONSUMABE/SUBSCRIPTION.
  • purchaseId — идентификатор покупки.
  • purchaseState — состояние покупки:
  • purchaseTime — время покупки.
  • quantity — количество продукта. Необязательный параметр со стандартным значением 1. Применим только к покупке потребляемых товаров.
  • subscriptionToken — токен для валидации покупки на сервере.

Обратный вызов (callback) rustore_on_get_purchases_failure возвращает строку JSON с информацией об ошибке. Структура ошибки описана в разделе Обработка ошибок.

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

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

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

  • rustore_on_get_purchase_info_success;
  • rustore_on_get_purchase_info_failure.
Подписка на события
function init(self)
    # Инициализация rustorebilling
 
    rustorecore.connect("rustore_on_get_purchase_info_success", _on_get_purchase_info_success)
    rustorecore.connect("rustore_on_get_purchase_info_failure", _on_get_purchase_info_failure)
end
 
function _on_get_purchase_info_success(self, channel, value)
    local data = json.decode(value)
end
  
function _on_get_purchase_info_failure(self, channel, value)
    local data = json.decode(value)
end
Вызов метода get_purchase_info
# Ваша реализация UI запроса информации о покупке
function _on_get_purchase_info_pressed(purchaseId):
    rustorebilling.get_purchase_info(purchaseId)
end

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

Обратный вызов (callback) rustore_on_get_purchase_info_success возвращает строку JSON с информацией о покуп

  • amount — цена в минимальных единицах валюты.
  • amountLable — отформатированная цена покупки, включая валютный знак.
  • currency — код валюты ISO 4217.
  • developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации.
  • invoiceId — идентификатор счёта.
  • language — язык, указанный с помощью BCP 47 кодирования.
  • orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
  • productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
  • productType — тип продукта (потребляемый / непотребляемый / подписка): CONSUMABLE/NON-CONSUMABE/SUBSCRIPTION.
  • purchaseId — идентификатор покупки.
  • purchaseState — состояние покупки:
  • purchaseTime — время покупки.
  • quantity — количество продукта. Необязательный параметр со стандартным значением 1. Применим только к покупке потребляемых товаров.
  • subscriptionToken — токен для валидации покупки на сервере.

Обратный вызов (callback) rustore_on_get_purchase_info_failure возвращает строку JSON с информацией об ошибке. Структура ошибки описана в разделе Обработка ошибок.

Статусная модель (purchaseState)

Статусная модель покупки потребляемых продуктов (CONSUMABLES)

img

Статусная модель покупки непотребляемых продуктов (NON-CONSUMABLES)

img

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

img

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

Продукты, требующие подтверждения (потребления)​

Учитывайте тип покупки. Метод подтверждения (потребления) необходим, только если у вас потребляемый товар (CONSUMABLE), который можно купить много раз.

Чтобы такие товары начислились пользователям без ошибок, подтвердите подтверждение (потребление) продукта с помощью метода confirmPurchase. При начислении товара в вашем приложении используйте серверную валидацию платежей. Начисляйте товар только когда платёж (счёт) перейдет в финальный статус CONFIRMED. Начисление продуктов пользователям надо делать в callback addOnSuccessListener метода confirmPurchase.

Обратите внимание!

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

Исключение — платежи через СБП или со счёта телефона: при этих способах оплаты используется одностадийный платёж, но модель счёта остаётся двухстадийной. Подробнее см. пояснения ниже.

При оплате потребляемых (CONSUMABLE) товаров через СБП или со счета телефона используется одностадийный платёж, при этом модель счёта остаётся двухстадийной. Это значит, что при переходе счёта в статус PAID при оплате через СБП или со счета мобильного телефона деньги уже списаны со счёта покупателя, а с разработчика удержана комиссия. В этом случае при отмене покупки в состоянии PAID происходит возврат средств (refund), а не отмена холдирования — reverse. Удержанная комиссия разработчику не возвращается. При этом для завершения покупки всё равно нужно выполнить метод подтверждения (потребления) — см. также таблицу ниже.

Платёжный методТип платежаПлатёж в статусе PAID
  • банковские карты;
  • Сбер ID;
  • SberPay;
  • T-Pay;
  • VK Pay.
Двухстадийный
  • Средства захолдированы на счёте покупателя.
  • Комиссия с разработчика не удержана.
  • Возможна отмена платежа.
  • СБП;
  • оплата со счета мобильного телефона.
Одностадийный
  • Средства списаны со счёта покупателя.
  • Удержана комиссия с разработчика.
  • При отмене покупки в состоянии PAID происходит возврат средств (refund), а не отмена холдирования — reverse. Удержанная комиссия разработчику не возвращается.

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

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

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

  • rustore_on_confirm_purchase_success;
  • rustore_on_confirm_purchase_failure.
Подписка на события
function init(self)
    # Инициализация rustorebilling
     
    rustorecore.connect("rustore_on_confirm_purchase_success", _on_confirm_purchase_success)
    rustorecore.connect("rustore_on_confirm_purchase_failure", _on_confirm_purchase_failure)
end
 
function _on_confirm_purchase_success(self, channel, value)
    local data = json.decode(value)
end
  
function _on_confirm_purchase_failure(self, channel, value)
    local data = json.decode(value)
end
Вызов метода confirm_purchase
# Ваша реализация UI подтверждения (потребления) покупки
function _on_confirm_purchase_pressed(purchaseId):
    rustorebilling.confirm_purchase(purchaseId)
end
  • purchaseId — идентификатор покупки.

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

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

SubscriptionToken состоит из invoiceId покупки и userId, записанных через точку: $invoiceId.$userId.

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

function _on_purchase_product_success(self, channel, value)
    local data = json.decode(value)
 
    if data.type == "Success" then
        local subscriptionToken = data.data.subscriptionToken
        yourApi.validate(subscriptionToken)
    end
end

Также можно получить subscriptionToken из объектов списка покупок.

function _on_get_purchases_success(self, channel, value)
    local data = json.decode(value)

    for key, value in pairs(data) do
        yourApi.validate(value.subscriptionToken)
    end
end

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

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

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

  • rustore_on_delete_purchase_success;
  • rustore_on_delete_purchase_failure.

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

Подписка на события
function init(self)
    # Инициализация rustorebilling
     
    rustorecore.connect("rustore_on_delete_purchase_success", _on_delete_purchase_success)
    rustorecore.connect("rustore_on_delete_purchase_failure", _on_delete_purchase_failure)
end
 
function _on_delete_purchase_success(self, channel, value)
    local data = json.decode(value)
end
  
function _on_delete_purchase_failure(self, channel, value)
    local data = json.decode(value)
end
Вызов метода delete_purchase
# Ваша реализация UI отмены покупки
function _on_delete_purchase_pressed(purchaseId):
    rustorebilling.delete_purchase(purchaseId)
end
  • purchaseId — идентификатор покупки.

Обратный вызов rustore_on_delete_purchase_success возвращает идентификатор покупки:

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

Обратный вызов rustore_on_delete_purchase_failure возвращает строку JSON с информацией об ошибке. Доступны следующие поля.

  • purchaseId — идентификатор покупки.
  • cause — информация об ошибке.

Структура ошибки описана в разделе Обработка ошибок.

к сведению

Используйте метод отмены покупки с осторожностью и только в исключительных случаях, только если покупка осталась в статусе PAID, а вы не можете выдать товар пользователю. В остальных случаях не рекомендуется вручную отменять покупки, так как RuStore автоматически обрабатывает незавершённые покупки (например, таймаут в 20 минут или повторная покупка от того же клиента).

При оплате покупки через СБП или со счета мобильного телефона отмена покупки в статусе PAID не отменяет холдирование, а приводит к возврату средств (refund). При этом с разработчика удерживается комиссия, которая не возвращается.

Обработка незавершённых платежей​

Обработка незавершённых платежей производится разработчиком.

Чтобы подтвердить покупку продукта типа CONSUMABLE и в статусе PAID (см. Получение сведений о покупке), вызовите метод подтверждения (потребления) покупки. Без подтверждения RuStore не перечислит средства на счёт разработчика. Это действие необходимо для финализации процесса покупки и начисления товара пользователю.

Если вы по каким-либо причинам не можете предоставить оплаченный товар, рекомендуется отменить покупку самостоятельно. Если вы этого не сделаете, RuStore автоматически отменит покупку по истечении определённого времени.

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

Особое внимание при оплате через СБП или со счета мобильного телефона:

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

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

Также вы можете подтверждать или отменять покупки через API RuStore:

подсказка

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

Ведение журнала событий​

Если необходимо логировать события библиотеки платежей, добавьте необязательный параметр debugLogs в вызов init и единожды выполните подписку на события:

  • rustore_on_payment_logger_debug;
  • rustore_on_payment_logger_error;
  • rustore_on_payment_logger_info;
  • rustore_on_payment_logger_verbose;
  • rustore_on_payment_logger_warning.
local APPLICATION_ID = "123456"
local DEEPLINK_SCHEME = "yourappscheme"
local DEBUG_LOGS = true
local LOG_TAG = "yourtag"

function init(self)
    rustorecore.connect("rustore_on_payment_logger_debug", _on_payment_logger_debug)
    rustorecore.connect("rustore_on_payment_logger_error", _on_payment_logger_error)
    rustorecore.connect("rustore_on_payment_logger_info", _on_payment_logger_info)
    rustorecore.connect("rustore_on_payment_logger_verbose", _on_payment_logger_verbose)
    rustorecore.connect("rustore_on_payment_logger_warning", _on_payment_logger_warning)
	
    rustorebilling.init(APPLICATION_ID, DEEPLINK_SCHEME, DEBUG_LOGS)
end

function _on_payment_logger_debug(self, channel, value)
    rustorecore.log_debug(LOG_TAG, value)
end

function _on_payment_logger_error(self, channel, value)
    rustorecore.log_error(LOG_TAG, value)
end

function _on_payment_logger_info(self, channel, value)
    rustorecore.log_info(LOG_TAG, value)
end		

function _on_payment_logger_verbose(self, channel, value)
    rustorecore.log_verbose(LOG_TAG, value)
end

function _on_payment_logger_warning(self, channel, value)
    rustorecore.log_warning(LOG_TAG, value)
end

Параметр для включения логирования:

  • DEBUG_LOGS — включить логи (логи будут автоматически отключены для Release-сборок).

Все обратные вызовы (callbacks) логирования возвращают строку JSON. Доступны следующие поля:

  • e — информация об ошибке или null. Структура ошибки описана в разделе Обработка ошибок;
  • message – описание ошибки.

Смена темы интерфейса​

Для динамической смены темы необходимо использовать метод set_theme.

Пример использования setTheme

rustorebilling.set_theme(0)
  • 0 - тёмная тема;
  • 1 - светлая тема.

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

Структура ошибки

Обработка json ошибки
function _on_failure(self, channel, value)
    local data = json.decode(value)
	
    local name = data.simpleName
    local message = data.detailMessage
end
  • simpleName – имя ошибки.
  • detailMessage – описание ошибки.

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

  • RuStoreNotInstalledException — на устройстве пользователя не установлен RuStore;
  • RuStoreOutdatedException — версия RuStore, установленная на устройстве пользователя, не поддерживает данный SDK;
  • RuStoreUserUnauthorizedException — пользователь не авторизован в RuStore;
  • RuStoreRequestLimitReached — с момента последнего отображения процесса прошло слишком мало времени;
  • RuStoreReviewExists — этот пользователь уже оценил ваше приложение;
  • RuStoreInvalidReviewInfo — проблемы с ReviewInfo;
  • RuStoreException — базовая ошибка RuStore, от которой наследуются остальные ошибки.
При вызове метода purchase_product ошибки обрабатываются автоматически.

Для показа диалога с ошибкой пользователю используйте метод set_error_handling.

Устарело

Метод устарел и не рекомендуется к использованию.

function init(self)
    rustorebilling.set_error_handling(true)
	
    # Инициализация rustorebilling
end
  • true — показывать диалог;
  • false — не показывать диалог.

Коды ошибок​

Ниже представлено описание возможных ошибок в поле errorCode.

HTTP-кодКод ошибкиОписание
40040001Параметры запроса неверны — не заполнены обязательные параметры/неверный формат параметров.
40040003Приложение не найдено.
40040004Статус приложения inactive.
40040005Продукт не найден.
40040006Статус продукта inactive.
40040007Недопустимый тип продукта. Поддерживаемые типы: consumable, non-consumable, subscription.
40040008Покупка с таким order_id уже существует.
40040009У текущего клиента найдена покупка этого продукта со статусом invoice_created. Необходимо предложить клиенту оплатить/отменить покупку.
40040010Для типа продукта consumable. У текущего клиента найдена покупка этого продукта со статусом paid. Сначала требуется подтвердить потребление покупки на устройстве, а затем можно отправлять следующий запрос на покупку этого продукта.
40040011Для типа продукта non-consumable. У текущего клиента найдена покупка этого продукта со статусом pre_confirmed/confirmed. Такой продукт уже приобретён. Более одного раза продукт не продаётся.
40040012Для типа продукта subscription. У текущего клиента найдена покупка этого продукта со статусом pre_confirmed/confirmed. Такой продукт уже приобретён. Более одного раза продукт не продаётся.
40040013Для типа продукта subscription. При обращении в сервис подписок за списком продуктов GET/products (serviceId, user_id) данные не были получены.
40040014Обязательный атрибут(-ы) не пришел в запросе.
40040015Не удалось изменить статус при обновлении покупки (переход запрещён).
40040016При покупке подписки непотребляемого продукта указано значение quantity > 1.
40040017Продукт удалён, новые покупки не доступны.
40040018Нельзя подтверждать продукт с типом тип продукта.
40140101Невалидный токен.
40140102Время жизни токена истекло.
40340301Доступ к запрашиваемому ресурсу запрещён (неавторизованно).
40340302Для текущего токена текущий вызов не авторизован (метод запрещён).
40340303Идентификатор приложения в запросе и токен не совпадают.
40340305Неверный тип токена.
40440401Не найдено.
40840801Истекло время ожидания уведомления, указанное в запросе.
50050***Внутренняя ошибка платежного сервиса.