Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

7.0.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.

  • If you migrate to Pay SDK from billingClient SDK, please review the migration instructions. For more details, see here.

Implementation example​

Look at the example app to learn how to integrate the 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.

Getting started​

  1. Copy the plugin and the sample app projects from the official RuStore repository on GitFlic.
  2. Copy the contents of godot_example/android/plugins to your_project/android/plugins.
  3. In the Plug-ins list of the Android build preset select Ru Store Godot Pay and Ru Store Godot Core.

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"
    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 — product ID form the RuStore Console.

Where are app IDs in the RuStore Console?
  1. Navigate to the Applications tab and selected the needed app.
  2. 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.

note

Application Id specified in Project > Export... > Android > Settings > Unique Name, must match the Application Id 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)
warning

Do not specify console_app_id_key and internal_config_key in the manifest directly. The strings must be placed in a resource file, for example: your_project/android/build/res/values/rustore_values.xml. The internal_config_key value must always be godot.

rustore_values.xml example
<?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>

Working with SDK​

Create a RuStoreGodotPayClient instance before using the plugin methods.

Creating RuStoreGodotPayClient instance
var _pay_client: RuStoreGodotPayClient = RuStoreGodotPayClient.get_instance()

Payments availability check​

To check purchase availability, call the get_purchase_availability 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, isAvailable == true is returned. Otherwise, isAvailable == false 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).

You must subscribe to events once before using this method:

  • on_get_purchases_availability_success;
  • on_get_purchases_availability_failure.
Subscription to events
func _ready():
   # _pay_client initialization
     
   _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
Calling get_purchase_availability
_pay_client.get_purchase_availability()

Check whether RuStore is installed​

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

var is_rustore_installed: bool = _pay_client.is_rustore_installed()
  • 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 get_products method to request the information about products added to your app in RuStore Console.

You must subscribe to events once before using this method:

  • on_get_products_success;
  • on_get_products_failure.
Subscription to events
func _ready():
    # _pay_client initialization
     
    _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
Calling get_products
var PRODUCT_IDS: Array[RuStorePayProductId] = [
    RuStorePayProductId.new("con_1"),
    RuStorePayProductId.new("non_con_1"),
]
 
_pay_client.get_products(PRODUCT_IDS)

product_ids — 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?
  1. Navigate to the Applications tab and selected the needed app.
  2. Select Monetization in the left menu.
  3. Select product type: Subscriptions or In-App purchases.
  4. Copy the IDs of the required products.

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

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 — 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.

Purchasing product​

One-stage payment (without hold)

To purchase product, use the purchase_one_step method.

You must subscribe to events once before using this method:

  • on_purchase_one_step_success;
  • on_purchase_one_step_failure.
Subscription to events
func _ready():
    # _pay_client initialization
 
    _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)

Two-stage payment (with hold)

To purchase product, use the purchase_two_step method.

You must subscribe to events once before using this method:

  • on_purchase_two_step_success;
  • on_purchase_two_step_failure.
Subscription to events
func _ready():
    # _pay_client initialization
 
    _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)

Purchase parameters structure.

Purchase parameters structure
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 — 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.

Purchase result structure
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 - 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.

Getting purchase information​

Go get purchase information, use the get_purchase method.
Subscription to events
func _ready:
    # _pay_client initialization
   
    _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
Calling get_purchase method
var purchase_id: RuStorePayPurchaseId = ...
 
_pay_client.get_purchase(purchase_id)

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

Purchase information structure
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 — formatted purchase price, including currency symbol.
  • currency — ISO 4217 currency code.
  • description — descriptions in language.
  • developerPayload — string with additional order information, that you can specify on purchase initialization
  • 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.
  • price — price in minimum currency units.
  • productId — product ID assigned to product in RuStore Console (mandatory).
  • productType — product type.
  • purchaseId — product ID.
  • purchaseTime — purchase time.
  • PurchaseType — purchase type:
    • ONE_PHASE - one-stage payment;
    • TWO_PHASE - two-stage payment.
  • 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.

Purchase status model​

One-stage payment status model.

Two-stage payment status model.

Getting products list​

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

Subscription to events
func _ready:
   # _pay_client initialization
   
   _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 initialization

_pay_client.get_purchases()

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

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 — formatted purchase price, including currency symbol.
  • currency — ISO 4217 currency code.
  • description — descriptions in language.
  • developerPayload — string with additional order information, that you can specify on purchase initialization
  • 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.
  • price — price in minimum currency units.
  • productId — product ID assigned to product in RuStore Console (mandatory).
  • productType — product type.
  • purchaseId — product ID.
  • purchaseTime — purchase time.
  • PurchaseType — purchase type:
    • ONE_PHASE - one-stage payment;
    • TWO_PHASE - two-stage payment.
  • 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.

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
func _on_purchase_two_step_success(result: RuStorePayProductPurchaseResult):
   if result is RuStorePayProductPurchaseResult.SuccessProductPurchaseResult:
      yourApi.validate(result.subscriptionToken);

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

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

Consume (confirm) purchase​

Consume (confirm) purchase​

Us the consume_purchase 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.

You must subscribe to events once before using this method:

  • on_confirm_two_step_purchase_success;
  • on_confirm_two_step_purchase_failure.
Subscription to events
func _ready:
    # _pay_client initialization
   
    _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
Calling confirmation method
var id: RuStorePayPurchaseId = ...
var payload: RuStorePayDeveloperPayload = ...
 
_pay_client.confirm_two_step_purchase(id, payload)
  • id — product ID.
  • payload — string with additional order information, that you can specify on purchase initialization

Purchase cancellation​

To cancel a purchase, use the cancel_two_step_purchase method.

You must subscribe to events once before using this method:

  • on_cancel_two_step_purchase_success;
  • on_cancel_two_step_purchase_failure.
Subscription to events
func _ready:
    # _pay_client initialization
  
    _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 method
# Your purchase cancellation UI implementation
func _on_cancel_two_step_purchase_pressed(purchaseId: RuStorePayPurchaseId):
    _pay_client.cancel_two_step_purchase(purchaseId)
purchaseId — product ID

  • The on_cancel_two_step_purchase_success callback returns purchase ID.
  • The on_cancel_two_step_purchase_failure callback returns purchase ID of the String type and the RuStoreError object with error information. The error structure is described in Error Handling.

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.