3.1.0
RuStore allows you to integrate payments into your mobile app.
Implementation example
See the example app to learn how to integrate rating and feedback SDK correctly.
Prerequisites
- The current version of RuStore is installed on the user's device.
- The user is authorized in RuStore.
- The user and the app should not be blocked in RuStore.
- In-app purchases should be enabled for the app in RuStore Console.
The service has some restrictions to work outside of Russia.
Getting started
Run the command below to add the application package to your project:
// HTTPS
npm install git+https://git@gitflic.ru/project/rustore/react-native-rustore-billing-sdk.git
// SSH
npm install git+ssh://git@gitflic.ru/project/rustore/react-native-rustore-billing-sdk.git
Deeplink processing
To redirect a user to your app after payment via third-party apps (the Faster Payments System (SBP), SberPay and others), you need to properly implement deep linking in your app. Specify the intent-filter
in AndroidManifest.xml
with scheme
of your project (see below).
<activity
android:name=".sample.MainActivity">
<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"/>
<data android:scheme="yourappscheme"/>
</intent-filter>
</activity>
where yourappscheme
— your deeplink scheme, it can be changed to another one.
This scheme must match the deeplinkSheme value specified during the billing client library initialization.
Initialization
Initialize the library before calling its methods.
For initialisation, call theRustoreBillingClient.init()
method.
try {
RustoreBillingClient.init({
consoleApplicationId: 'appId' ,
deeplinkScheme: 'scheme' ,
});
console.log(initialize success: ${result});
} catch (err) {
console.log(initialize err: ${err});
}
-
consoleApplicationId
— application code from RuStore Console (example:https://console.rustore.ru/apps/123456
). -
deeplinkScheme
— deeplink scheme required to return to your app upon payment via a third-party application (for example, SberPay or SBP). SDK generates its host for this scheme.
deeplinkScheme
must match the one specified in AndroidManifest.xml
(see Deeplinks handling).How payments work
Checking purchases availability
Please ensure compliance with the conditions below to check whether your app supports payment functions.
- The current version of RuStore is installed on the user's device.
- RuStore app supports payment functionality.
- The user is authorized in RuStore.
- The user and the app should not be blocked in RuStore.
- In-app purchases should be enabled for the app in RuStore Console.
To check whether your app supports payment functions, call the RustoreBillingClient.checkPurchasesAvailability()
method.If all conditions are met, the method returns true
.
try {
const isAvailable = await RustoreBillingClient.checkPurchasesAvailability();
console.log(available success ${isAvailable});
} catch (err) {
console.log(available error ${err});
}
Working with SDK
Getting products list
Use the RustoreBillingClient.getProducts(productIds)
method to get a list of products.
try {
const products = await RustoreBillingClient.getProducts(productIds);
for (const product of products) {
console.log(product?.productId);
}
} catch (err) {
console.log(products err: ${err});
}
productIds
— list of products IDs.
This method returns Product[]
. Below is the product pattern:
interface Product {
productId: string;
productType?: ProductType;
productStatus: ProductStatus;
priceLabel?: string;
price?: number;
currency?: string;
language?: string;
title?: string;
description?: string;
imageUrl?: string;
promoImageUrl?: string;
subscription?: ProductSubscription;
}
productId
— product ID..productType
— product type..productStatus
— product status..priceLabel
— formatted purchase price, including the currency symbol inlanguage
.price
— price in minor units (in kopecks)..currency
— ISO 4217 currency code.language
— language specified with the BCP 47 encoding..title
— product name inlanguage
.description
— product description inlanguage
.imageUrl
— link to an image..promoImageUrl
— promotional picture link..subscription
— subscription description, returned only for products withsubscription
.
Subscription Structure Subscription
interface ProductSubscription {
subscriptionPeriod?: SubscriptionPeriod;
freeTrialPeriod?: SubscriptionPeriod;
gracePeriod?: SubscriptionPeriod;
introductoryPrice?: string;
introductoryPriceAmount?: string;
introductoryPricePeriod?: SubscriptionPeriod;
}
subscriptionPeriod
— subscription period..freeTrialPeriod
— trial subscription period..gracePeriod
— grace period..introductoryPrice
— formatted introductory subscription price, including the currency symbol, inproduct:language
.introductoryPriceAmount
— introductory price in minor units of currency (in kopecks).introductoryPricePeriod
— calculated period of the introductory price..
>Subscription Period structure SubscriptionPeriod
interface SubscriptionPeriod {
years: number;
months: number;
days: number;
}
years
— number of years..months
— number of days..days
— number of days..
Purchasing product
Use theRustoreBillingClient.purchaseProduct({...})
method to call a product purchase.
try {
const response = await RustoreBillingClient.purchaseProduct({
productId: 'productId' ,
orderId: 'orderId' ,
quantity: 0,
developerPayload: 'developerPayload'
});
console.log(purchase success: ${response});
} catch (err) {
console.log(purchase err: ${err});
}
productId
— product ID..orderId
— unique payment identifier generated by the application (uuid);.quantity
— product quantity..developerPayload
— уline specified by the developer that contains additional information about the order..
The purchase result can be represented as one of the following interfaces:SuccessPayment
, CancelledPayment
or FailurePayment
.
enum PaymentResult {
SUCCESS = 'SUCCESS' ,
CANCELLED = 'CANCELLED' ,
FAILURE = 'FAILURE' ,
}
interface SuccessPaymentResult {
orderId?: string;
purchaseId: string;
productId: string;
invoiceId: string;
subscriptionToken?: string;
}
interface SuccessPayment {
type: PaymentResult.SUCCESS;
result: SuccessPaymentResult;
}
interface CancelledPaymentResult {
purchaseId: string;
}
interface CancelledPayment {
type: PaymentResult.CANCELLED;
result: CancelledPaymentResult;
}
interface FailurePaymentResult {
purchaseId?: string;
invoiceId?: string;
orderId?: string;
quantity?: number;
productId?: string;
errorCode?: number;
}
interface FailurePayment {
type: PaymentResult.FAILURE;
result: FailurePaymentResult;
}
SuccessPayment
- successful purchase result..FailurePayment
- error occurred when sending a payment request or receiving a payment status, it is not possible to set the purchase status..CancelledPayment
— a purchase request has been sent, but the user has closed the "payment window" on their device, so the payment result is unknown..
Getting purchases list
Метод возвращает только покупки со статусами из таблицы ниже.
Тип/Статус | INVOICE_CREATED | CONFIRMED | PAID |
---|---|---|---|
CONSUMABLE | + | + | |
NON-CONSUMABLE | + | + | |
SUBSCRIPTION | + | + |
Метод возвращает незавершённые состояния покупки и покупки потребляемых товаров, требующих обработки. Помимо этого, он показывает подтверждённые покупки для подписок и непотребляемых товаров — тех, которые нельзя купить повторно.
Use theRustoreBillingClient.getPurchases()
method to get the user's list of purchases.
try {
const purchases = await RustoreBillingClient.getPurchases();
for (const purchase of purchases) {
console.log(purchase?.purchaseId);
}
} catch (err) {
console.log(purchase err: ${err});
}
Метод возвращает список покупок Purchase[]
. Ниже представлена модель покупки.
interface Purchase {
purchaseId?: string;
productId: string;
productType?: ProductType;
invoiceId?: string;
description?: string;
language?: string;
purchaseTime?: string;
orderId?: string;
amountLabel?: string;
amount?: number;
currency?: string;
quantity?: number;
purchaseState?: PurchaseState;
developerPayload?: string;
subscriptionToken?: string;
}
purchaseId
— purchase ID..productId
— product ID..productType
— product type..invoiceId
— invoice ID..description
— product description inlanguage
.language
— language specified with the BCP 47 encoding..
.purchaseTime
— time of purchase.orderId
— unique payment identifier generated by the application (uuid);.amountLable
— formatted purchase price, including the currency symbol inlanguage
.amount
— price in minor units of currency..currency
— ISO 4217 currency code.quantity
— product quantity..purchaseState
— purchase state.:developerPayload
— уline specified by the developer that contains additional information about the order..subscriptionToken
— token for server validation..
Confirming purchase
Products that require confirmation
The RuStore application consists of the following types of products:
SUBSCRIPTION
— subscription (can be purchased for a period of time, such as a streaming service subscription)..NON_CONSUMABLE
— non-consumables (one-time purchases, such as disabling ads in an app).
.CONSUMABLE
— consumables (multiple-time purchases, such as crystals in the app);
Only CONSUMABLE
type products require confirmation if they are in PurchaseState.PAID
state.
Calling confirmation method
Canceling purchase
Use theRustoreBillingClient.deletePurchase(purchaseId)
method to cancel a purchase.
try {
const isDeleted = await RustoreBillingClient.deletePurchase(purchaseId)
console.log(delete success: ${isDeleted});
} catch (err) {
console.log(delete err: ${err});
}
purchaseId
— purchase ID..
Provided that all conditions are met, the RustoreBillingClient.deletePurchase()
method returns true
.
Note. Use this method if your app logic is related to purchase cancellation. The purchase is canceled automatically after a 20-min timeout, or upon a second purchase from the same customer.
Processing unfinished payments
Обработка незавершённых платежей производится разработчиком.
Чтобы подтвердить покупку типа CONSUMABLE
и в статусе PAID
вызовите метод подтверждения покупки.
В случае с отменой покупки при использовании методов обработки платежей учитывайте свой внутренний процесс. У некоторых разработчиков он предусматривает проверки перед потреблением или отменой покупки. В этом случае запросите отдельно статус такой покупки.
Например, если пользователь оплатил товар, который вы по каким-то причинам не можете ему поставить, вызовите метод отмены покупки в статусе PAID
, чтобы отменить покупку.
В случаях, когда метод получения списка покупок возвращает покупку со статусом INVOICE_CREATED
вы можете использовать метод отмены покупки. Например, если не хотите видеть покупку с такими статусами в списке покупок. Делать это самим не обязательно, поскольку RuStore обрабатывает отмену таких покупок на своей стороне.
Иногда после оплаты через приложение банка (СБП, SberPay, Tinkoff Pay и др.) и при последующем возврате обратно в приложение статус покупки остаётся INVOICE_CREATED
, при этом статус платежа — неуспешная покупка. Это связано с временем обработки покупки на стороне банка. Поэтому разработчику необходимо правильно связать логику получения списка покупок с жизненным циклом экрана.
Альтернативное решение — отмена покупки в статусе INVOICE_CREATED
только через взаимодействие пользователя с приложением. Например, вы можете вынести эту логику в отдельную кнопку.
Errors processing
Possible errors
RuStoreNotInstalledException
— RuStore not installed on user's device;RuStoreOutdatedException
— RuStore, installed on the user's device, does not support payment processing functions.;RuStoreUserUnauthorizedException
— user not authorized on RuStore;RuStoreRequestLimitReached
— not enough time has passed since the process was last shown.;RuStoreReviewExists
— this user has already rated your app.;RuStoreInvalidReviewInfo
— problems withReviewInfo
;RuStoreException
— basic RuStore error, from which all other errors are inherited..