6.1.0 (Beta)

With RuStore you can integrate payments in your mobile app.

tip

If you are in doubt read the instruction in the usage scenarios.

Implementation example

Look at the example app to learn how to integrate our SDK.

Prerequisites

In-app purchases for the app are enabled in RuStore Console.
The app must not be banned in RuStore.
The current version of RuStore is installed on the user's device.
User is authorized in RuStore.
The user must is not banned in RuStore.

Connect to project

Installation with .unitypackage
Installation with Package Manager

Download the files below:

Import files to your project with Package Manager (Window > Package Manager > + > Add package from tarball...).

The dependencies are connected automatically with External Dependency Manager.

Open package manager window (Window > Package Manager > + > Add package from git URL...).
Use the https://github.com/googlesamples/unity-jar-resolver.git?path=/upm link to connect the External Dependency Manager package.
To cure the Google.IOSResolver.dll will not be loaded error, install the iOS build module for your version of Unity (UnityHub > Installs > Your version of Unity > Add modules > iOS Build Support).

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

tip

If you use macOS, change Archive Utility settings. Uncheck Keep expanding if possible. Otherwise, the project archive will not be downloaded correctly.

Download RuStoreUnityPaySDK-version.unitypackage and import it to your project (Assets > Import Package > Custom Package). The dependencies are connected automatically with External Dependency Manager (included in .unitypackage).

tip

If you use macOS, change Archive Utility settings. Uncheck Keep expanding if possible. Otherwise, the project archive will not be downloaded correctly.

For proper SDK dependencies processing set the following settings.

Opt project settings: Edit > Project Settings > Player > Android Settings.
In the Publishing Settings section enable to following settings.
- Custom Main Manifest.
- Custom Main Gradle Template.
- Custom Gradle Properties Template.
In the Other Settings section configure:
- package name.
- Minimum API Level = 24.
- Target API Level = 34.
Open the External Dependency Manager settings: Assets > External Dependency Manager > Android Resolver > Settings and enable the following settings.
- Use Jetifier.
- Patch mainTemplate.gradle.
- Patch gradleTemplate.properties.
Update project dependencies: Assets > External Dependency Manager > Android Resolver > Force Resolve.

Initialization

Initialize the library before calling its methods. The initialization itself is done automatically, however, for your SDK to work, in your Manifest.xml file define console_app_id_key and 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" />

Both values must be inside the <application> tag

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

Where are app IDs in the RuStore Console?

Navigate to the Applications tab and selected the needed app.
Copy the ID from the URL address of the app page — it is a set of numbers between apps/ and /versions. FOr example, for URL address https://console.rustore.ru/apps/123456/versions the app ID is 123456.

Important

Package Name of the app specified in Edit > Project Settings... > Player > Android > Other Settings > Package Name must match Package Name of the APK file you published in the RuStore Console.

warning

Test build signature (for example: debug) of the app must match the signature of the app build that was uploaded to the console and passed moderation (for example, release)

The console_app_id_key value is set in the PayClientSettings.assets file. To create the PayClientSettings.assets file, in the Unity editor select Window > RuStore SDK > Settings > PayClient.

The internal_config_key value is set in the PayClientSettings.assets automatically.

Attention!

Do not specify console_app_id_key and internal_config_key in the manifest directly. The strings must be placed in a resource file that is generated automatically based on PayClientSettings.assets data.

Working with SDK

Payments availability check

To check purchase availability, call the GetPurchaseAvailability method. On calling, the following conditions are checked.

The current version of RuStore is installed on the user's device.
RuStore app supports payments.
User is authorized in RuStore.
The user and the app are not banned in RuStore.
In-app purchases for the app are enabled in RuStore Console.

If all above conditions are met, PurchaseAvailabilityResult.Available is returned.

Otherwise, PurchaseAvailabilityResult.Unavailable(val cause: Throwable) is returned, where cause is an error of a failed condition. To check what caused such result, check error type for RuStoreException (error data is described in Errors).

Calling GetPurchaseAvailability
RuStorePayClient.Instance.GetPurchaseAvailability(
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        if (result.isAvailable) {
            // Process success
        }
        else {
            // Process result.cause
        }
    });

Check whether RuStore is installed

To check whether the RuStore app is installe don the user's device, call the IsRuStoreInstalled method.

bool isRuStoreInstalled = RuStorePayClient.Instance.IsRuStoreInstalled();

true – RuStore is installed.
false – RuStore is not installed.

Retrieving products list

You checked that payments are available and the users are able to make purchases. Now you can request products list. Use the getProducts method to request the information about products added to your app in RuStore Console.

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

ProductId[] productIds — the list of product IDs that are set when products are created in the RuStore Console. The list is limited by 1000 items.

Where are product IDs in the RuStore Console?

Navigate to the Applications tab and selected the needed app.
Select Monetization in the left menu.
Select product type: Subscriptions or In-App purchases.
Copy the IDs of the required products.

The method returns products list. Below is the product pattern.

Product structure
public class Product : BaseFields {
    public ProductId productId { get; }
    public ProductType type { get; }
    public AmountLabel amountLabel { get; }
    public Price? price { get; }
    public Currency currency { get; }
    public Url? imageUrl { get; }
    public Title title { get; }
    public Description? description { get; }
 
    ...
}

productId — product ID assigned to product in RuStore Console (mandatory).
type — product type: CONSUMABLE/NON-CONSUMABE.
amountLabel — formatted purchase price, including currency symbol
price — price in minimum currency units.
currency — ISO 4217 currency code.
title — product name in language.
description — descriptions in language.
imageUrl — image URL.

Getting products list

Go get the user's purchases list, use the getPurchases method.

RuStorePayClient.Instance.GetPurchases(
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        // Process success
    });

This method returns the purchases list in the CONFIRMED status for non-consumable products and PAID for consumable products. Below is the purchase pattern:

Purchase information structure
public class Purchase : BaseFields {
    public PurchaseId purchaseId { get; }
    public ProductId productId { get; }
    public InvoiceId invoiceId { get; }
    public OrderId? orderId { get; }
    public PurchaseType type { get; }
    public Description description { get; }
    public DateTime? purchaseTime { get; }
    public Price price { get; }
    public AmountLabel amountLabel { get; }
    public Currency currency { get; }
    public Quantity quantity { get; }
    public PurchaseStatus status { get; }
    public SubscriptionToken? subscriptionToken { get; }
    public DeveloperPayload? developerPayload { get; }
 
    ...
}

purchaseId — product ID.
productId — product ID assigned to product in RuStore Console (mandatory).
invoiceId — invoice ID.
orderId — payment ID generated by the app (optional). If you specify this parameter in your system, you will receive it via our API. If not specified, will be generated automatically (uuid). 150 characters max.
type — purchase type:
- APPLICATION
- NON_CONSUMABLE_PRODUCT
- CONSUMABLE_PRODUCT
- SUBSCRIPTION
description — descriptions in language
purchaseTime — purchase time:
price — price in minimum currency units
amountLable — formatted purchase price, including currency symbol.
currency — ISO 4217 currency code.
quantity — product amount (optional, value 1 will be used if not specified).
status — purchase state:
- INVOICE_CREATED — purchase invoice is created and awaiting payment
- CANCELLED — purchase canceled by the user
- PROCESSING — payment initiated
- REJECTED — purchase rejected (for example: due to insufficient funds)
- PAID — only for two-stage payments, intermediate status, funds are put on hold on the user's account, the purchase is awaiting confirmation from the developer
- CONFIRMED — purchase successfully paid for
- REFUNDED — purchase successfully refunded
- REVERSED — only for two-stage payment: wither the purchase was canceled by the developer or there was no payment within 72 hours, the funds on the user's account are put off hold
developerPayload — string with additional order information, that you can specify on purchase initialization
subscriptionToken — purchase token for server validation

Getting purchase information

Go get purchase information, use the getPurchase method.

RuStorePayClient.Instance.GetPurchase(
    purchaseId: purchase.purchaseId,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (response) => {
        // Process success
    });

This method returns information about a specific purchase in any status. Below is the purchase pattern:

Purchase information structure
public class Purchase : BaseFields {
    public PurchaseId purchaseId { get; }
    public ProductId productId { get; }
    public InvoiceId invoiceId { get; }
    public OrderId? orderId { get; }
    public PurchaseType type { get; }
    public Description description { get; }
    public DateTime? purchaseTime { get; }
    public Price price { get; }
    public AmountLabel amountLabel { get; }
    public Currency currency { get; }
    public Quantity quantity { get; }
    public PurchaseStatus status { get; }
    public SubscriptionToken? subscriptionToken { get; }
    public DeveloperPayload? developerPayload { get; }
 
    ...
}

purchaseId — product ID.
productId — product ID assigned to product in RuStore Console (mandatory).
invoiceId — invoice ID.
orderId — payment ID generated by the app (optional). If you specify this parameter in your system, you will receive it via our API. If not specified, will be generated automatically (uuid). 150 characters max.
type — purchase type:
- APPLICATION
- NON_CONSUMABLE_PRODUCT
- CONSUMABLE_PRODUCT
- SUBSCRIPTION
description — descriptions in language
purchaseTime — purchase time:
price — price in minimum currency units
amountLable — formatted purchase price, including currency symbol.
currency — ISO 4217 currency code.
quantity — product amount (optional, value 1 will be used if not specified).
status — purchase state:
- INVOICE_CREATED — purchase invoice is created and awaiting payment
- CANCELLED — purchase canceled by the user
- PROCESSING — payment initiated
- REJECTED — purchase rejected (for example: due to insufficient funds)
- PAID — only for two-stage payments, intermediate status, funds are put on hold on the user's account, the purchase is awaiting confirmation from the developer
- CONFIRMED — purchase successfully paid for
- REFUNDED — purchase successfully refunded
- REVERSED — only for two-stage payment: wither the purchase was canceled by the developer or there was no payment within 72 hours, the funds on the user's account are put off hold
developerPayload — string with additional order information, that you can specify on purchase initialization
subscriptionToken — purchase token for server validation

Purchasing product

To purchase product, use the purchase method.

var parameters = new ProductPurchaseParams(
      productId: new ProductId("product_id"),
      quantity: new Quantity(1),
      orderId: null,
      developerPayload: null);
 
RuStorePayClient.Instance.Purchase(
    parameters: parameters,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        // Process success
    });

Purchase parameters structure.

Purchase parameters structure
public class ProductPurchaseParams : BaseFields {
    public ProductId productId { get; }
    public Quantity? quantity { get; }
    public OrderId? orderId { get; }
    public DeveloperPayload? developerPayload { get; }
 
    ...
}

productId — product ID assigned to product in RuStore Console (mandatory).
quantity — product amount (optional, value 1 will be used if not specified).
orderId — payment ID generated by the app (optional). If you specify this parameter in your system, you will receive it via our API. If not specified, will be generated automatically (uuid). 150 characters max.
developerPayload — string with additional order information, that you can specify on purchase initialization. 250 characters max.

Purchase result structure.

public interface IProductPurchaseResult {
}
 
public sealed class SuccessProductPurchaseResult : BaseFields, IProductPurchaseResult {
    public OrderId? orderId { get; }
    public PurchaseId purchaseId { get; }
    public ProductId productId { get; }
    public InvoiceId invoiceId { get; }
    public SubscriptionToken? subscriptionToken { get; }
 
    ...
}
 
public sealed class CancelProductPurchaseResult : BaseFields, IProductPurchaseResult {
    public PurchaseId? purchaseId { get; }
 
    ...
}
 
public sealed class FailureProductPurchaseResult : BaseFields, IProductPurchaseResult {
    public OrderId? orderId { get; }
    public PurchaseId? purchaseId { get; }
    public ProductId? productId { get; }
    public InvoiceId? invoiceId { get; }
    public Quantity? quantity { get; }
    public SubscriptionToken? subscriptionToken { get; }
    public RuStoreError cause { get; }
 
    ...
}

SuccessProductPurchaseResult - successful purchase result.
FailureProductPurchaseResult - there was a problem during sending payment request or receiving payment status, purchase status unknown.
CancelProductPurchaseResult — payment request sent, although, the user closed the payment screen on their app, thus, the payment result is unknown.

Server validation

If you need to validate a purchase on the RuStore server, you can use subscriptionToken in SuccessProductPurchaseResult, that is returned on successful purchase.

Retrieving subscriptionToken from purchase result
var parameters = new ProductPurchaseParams(
      productId: new ProductId("product_id"),
      quantity: new Quantity(1),
      orderId: null,
      developerPayload: null);
 
RuStorePayClient.Instance.Purchase(
    parameters: parameters,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        if (result is SuccessProductPurchaseResult success) {
            var subscriptionToken = success.subscriptionToken;
            yourApi.validate(subscriptionToken);
        }
    });

You can also get a subscriptionToken from the Purchase entity. The Purchase entity can be retrieved using the GetPurchases method.

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

Consume (confirm) purchase

The RuStore application consists of the following types of products:

CONSUMABLE — consumables (multiple-time purchases, such as crystals in the app).
NON_CONSUMABLE — non-consumables (one-time purchases, such as disabling in-app ads).

Only CONSUMABLE products need confirmation when they are in the PurchaseState.PAID status.

Us the ConsumePurchase method to confirm a purchase. Purchase confirmation request must be accompanied by the delivery of the product. After calling the confirmation method the purchase changes its state to CONSUMED.

Calling confirmation method
PurchaseId id = ...
DeveloperPayload payload = ...
 
RuStorePayClient.Instance.ConsumePurchase(
    purchaseId: id,
    developerPayload: payload,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: () => {
        // Process success
    });

purchaseId — product ID.
developerPayload — string with additional order information, that you can specify on purchase initialization

Error handling

RuStorePaymentNetworkException — SDK network communication error;
RuStorePaymentCommonException — general SDK error;
RuStorePayClientAlreadyExist — duplicate initialization error SDK;
RuStorePayClientNotCreated — attempt to access public SDK interface before initialisation;
RuStorePayInvalidActivePurchase — payment initiated for unknown product type;
RuStorePayInvalidConsoleAppId — mandatory parameter сonsole_application_id for SDK initialisation not set;
RuStorePaySignatureException — invalid signature (occurs because of fraud actions);
EmptyPaymentTokenException — error receiving payment token;
RuStoreNotInstalledException — RuStore is not installed on the user's device;
RuStoreOutdatedException — RuStore version installed on the user's device does not support this SDK;
RuStoreUserUnauthorizedException — user is not authorized in RuStore;
RuStoreApplicationBannedException — app is banned in RuStore RuStore;
RuStoreUserBannedException — user is blocked in RuStore;
RuStoreException — basic RuStore error from which other errors are inherited.

6.1.0 (Beta)

Implementation example​

Prerequisites​

Connect to project​

Initialization​

Working with SDK​

Payments availability check​

Check whether RuStore is installed​

Retrieving products list​

Getting products list​

Getting purchase information​

Purchasing product​

Server validation​

Consume (confirm) purchase​

Error handling​