In-game subscriptions

OK.ru support a feature of in-game subscriptions for game applications. Game subscriptions allow users to make subscription-based purchases instead of classic single time purchases.

If user has purchased a subscription he will be charged for set amount of OKs every subscription period.

How it looks

In-game subscriptions are implemented as a part of OK.ru’s UI. To offer a subscription to user developer can show a special subscription dialog which contains all required information: subscription’s name, description, it’s icon and price.
In this dialog user can either purchase or cancel subscription.

If user has successfully purchased a subscription, it will be displayed in a special game subscriptions dialog which shows what current game subscription user has purchased.

Features

We highly recommend to use a trial period feature of in-game subscriptions. According to our information if user is offered to purchase a subscription without trying it for free drastically larger amount of users will refuse to purchase it.

Amount of subscriptions for every game is not limited. Every game can have multiple active subscriptions and each of them can be configured differently.

Following configuration options are available for developers:

  • trial period duration - period during which user is provided with subscription’s service / bonuses but uses it for free and is not charged with OKs. Period can be set in days, hours and minutes.
  • period duration - OKs charging periodicity. Every set period of time user will be charged by amount of OKs equal to subscription price. Period can be set in days, hours and minutes.
  • subscription name, description and icon which help user to identify what service or bonuses he gets for purchasing this subscription.
  • subscription price - amount of OKs to be charged every subscription period duration. Should be set in OKs.

How it works

To enable subscriptions in your game you need to complete two following steps:

  • register a new subscription for a game;
  • implement game subscriptions in your app using our API.

Creating a new subscription

To add a subscription please write an e-mail to api-support@ok.ru with following data:

ParameterDescriptionUnit
Trial period durationDuration of a trial period. On trial period subscription is free for userDays, hours, minutes
Period durationSubscription period. Every set amount of time user is charged for selected amount of OKsDays, hours, minutes
PriceSingle period priceOKs
Subscription iconSubscription image URL. Image’s size must be 256x256 
Product idString identifier of a subscription 
NameSubscription name. Must have a size of 1 to 3 words 
DescriptionShort subscription description. It must describe what user is purchasing with corresponding subscription 

For example, subscription can be configured like this:

  • trial period - 3 days;
  • period - 1 day;
  • price - 50 OKs;
  • product id - apples;
  • name - “Three apples each day”;
  • description - “Get three bonus apples each day”.

For such subscription user will be charged for 50 OKs every day. First three days are going to be free for user. And the most important thing - user must really get three apples each day while subscription is active.

Subscription dialog

To offer user to purchase a subscription you need to show special dialog window where he can view subscription information.

To do so you need to use FAPI-method ui.showPaymentSubscription.

Subscription purchasing

If subscription is active and trial period is finished, user will be charged for set amount of OKs every subscription period.

All “purchases” are going to be displayed on game’s payment statistics page.

In it happened that user has no OKs subscription does not cancel automatically. In this case money will be charged directly from his card.

Cancelling a subscription

At any time user can cancel a subscription via UI.

If subscription is cancelled all payment are stopped and user must not be provided with subscription bonuses or services anymore.

Subscription status

To have a control over subscription status we user payment callbacks just as in ordinary game payments. Every action is followed by a HTTP GET request from our service to game’s callback url.

Our payment service is expecting a specific response from your callback service which should be similar to common game payment: callbacks.payment

Request should be validated and if everything is correct callback service must respond with 200 status code response and XML type content.

Callback request depends on what type of action that has happened:

  • new subscription (or first subscription payment) - user can be notified that he has purchased a new subscription. He must be provided with subscription bonuses or services;
  • subscription cancelling - user can be notified that his subscription has ended and he is no longer provided with any bonuses or services;
  • subscription payment - user must be provided with bonuses or services.

New payment or subscription request

if user has subscribed or a new payment was proceeded, following request will come to your callback service:

https://callback.url/
?transaction_id=transactionId
&sig=270c83248ac45232be85bbbe3be7613b
&uid=123456789012
&amount=10
&method=callbacks.payment
&transaction_time=2017-11-08+00:21:10
&product_code=productCode
&extra_attributes={“action”: “reg_subscription”}
&application_key=CBAKMLELABABABABE
&call_id=1510089670220

Trial payment request

If payment or subscription is proceed during trial period, another request will come. It will contain different parameter extra_attributes value:

https://callback.url/
?transaction_id=transactionId
&sig=270c83248ac45232be85bbbe3be7613b
&uid=123456789012
&amount=10
&method=callbacks.payment
&transaction_time=2017-11-08+00:21:10
&product_code=productCode
&extra_attributes={“action”: “trial_subscription”}
&application_key=CBAKMLELABABABABE
&call_id=1510089670220

Subscription cancellation request

If user has cancelled subscription following request will be made:

https://callback.url/
?transaction_id=transactionId
&sig=270c83248ac45232be85bbbe3be7613b
&uid=123456789012
&amount=0
&method=callbacks.payment
&transaction_time=2017-11-08+00:21:10
&product_code=productCode
&extra_attributes={“action”: “unsubscribe”}
&application_key=CBAKMLELABABABABE
&call_id=1510089670220