Subscriptions

Subscriptions solution allows users to get access to a package of services under specified conditions. Key features:

  • Define subscription-based products.
  • Define plans. You can create and configure plans for each currency, set the trial period, configure the grace period, view subscribed users, and change subscription statuses for specific users.
  • Let users manage their subscriptions from a dashboard. They will be able to see detailed subscription information, view payment history, change the plan, and suspend/renew/cancel the subscription.
  • Manage user subscriptions from your Publisher Account: create and configure plans for each currency, set trial periods, configure grace periods, view subscribed users, and change subscription statuses for specific users.
  • Enable automatic renewal using a saved payment account.
  • Let users renew subscriptions manually.

Glossary

Subscription Plan

Subscription plan — billing conditions (billing amount, currency, and frequency) in terms of which a user gets their access to the service.

Subscription-Based Product

Subscription-based product — a service or a set of services provided to a user when they purchase the subscription.

Subscription

Subscription — a combination of the product and the chosen plan. A user gets the subscription when they choose the subscription plan and receive access to the service. The number of subscriptions a user can get at the same time depends on the number of products in the project.

EXAMPLE 1

Product: Access to the game

  • Subscription plan Silver: $10 per 1 month
  • Subscription plan Gold: $100 per 1 year

A user can select one of the following subscriptions:

  • Subscription 1: Access to the game with the $10/month plan
  • Subscription 2: Access to the game with the $100/year plan

EXAMPLE 2

Product 1: Access to the game1

Product 2: Access to the game2

  • Subscription plan: $10 per 1 month

A user can get two subscriptions simultaneously:

  • Subscription 1: Access to the game1 with the $10/month plan
  • Subscription 2: Access to the game2 with the $10/month plan

Note: If the subscription-based product is not set up, the user can get only one subscription at a time. To get several subscriptions simultaneously, you need to set up products.

Grace Period

A grace period is the period of time that defines the length of time the user can access the game after the subscription expires. Features:

  • A grace period is supported only by subscriptions with the one-time payment type. Payment for auto-renewing subscriptions is processed automatically.
  • You can change the length of the grace period in Publisher Account.
  • The system sends payment reminders every day until the user pays for the subscription or the grace period ends.
  • The user pays the full subscription price. The number of days the user spends in the grace period is removed from the main billing period, as these days are included in the main subscription.
  • If the value in the Grace period field in the plan settings is 0, the plan has no grace period.

Number of Billing Retries

Number of billing retries is a value that defines the number of attempts to withdraw money for the subscription. It’s supported only by the auto-renewing subscriptions with a saved payment account and is activated after the failed money withdrawal. Features:

  • The system tries to withdraw money from the payment account once a day.
  • The system will try to withdraw money until the subscription is renewed, canceled by a user, or canceled after the number of billing retries exceeds.
  • If this setting is active, the user will have access to the subscription until the number of billing retries exceeds.
  • If the subscription is renewed by a user, the number of days the system has spent on the billing attempts (one day per attempt) is removed from the main billing period, as these days are included in the main subscription.

How It Works

Step 1

Step 2

Step 3

User Flow

Subscription Statuses

A subscription can have one of the following statuses:

  • Active. Primary status. The subscription is created and activated after the first successful payment. Further charges are only possible for active subscriptions.

Notice: You cannot create a subscription manually using the API — this can only be done automatically upon making a purchase.

  • Canceled. The subscription has been canceled with immediate effect due to one of the following reasons:
    • Status changed via an API method or from the Xsolla Publisher Account.
    • Canceled by the user.
    • Expired, if an expiration date was set in the parameters.
    • Maximum number of charging attempts exceeded. This is three by default; please contact your Account Manager to change it.
    • User not found in the game.
    • User account deleted.

Note: When a subscription is canceled, the last payment can be refunded. This option is available for both the partner and the user.

  • Non renewing. Subscription renewal canceled. The subscription will last until the current billing cycle ends before the status changes to Canceled. A renewal can be canceled due to one of the following reasons:
    • Status changed via an API method or from Publisher Account.
    • Canceled by user via email link.
    • User account deleted.

Integration Flow

To integrate Subscriptions:

  1. Register an Xsolla Publisher Account.
  2. Create a project.
  3. Set up a plan.
  4. Set up Webhooks.
  5. Get a token.
  6. Configure the UI opening flow.
  7. Set up products.

Note: This guide describes the minimum settings required to quick-start the solution. If you have any questions, please contact your Account Manager.

Creating a Project

  1. Go to Projects and click Create new project.
  2. In setup mode:
    1. Specify the webhook URL.
    2. Generate a secret key to sign project webhooks.

Setting Up a Plan

  1. Go to Subscriptions settings: Project > Store > Subscriptions.
  2. Specify the following parameters:
    • Name
    • Billing cycle

Note: A plan can have one currency only. You must create a separate set of plans for each project currency.

Setting Up Webhooks

You need to implement the following webhooks for the Subscriptions:

Acknowledge the receipt of a webhook by responding with HTTP code 204 without a message body. You can read more about webhooks, including examples, in the API Reference.

To test the webhook handler, open Project settings > Webhooks section.

Getting a Token

You need to obtain a token to integrate with the subscriptions. A token is a string containing game/user data and payment settings.

Xsolla API uses basic access authentication. Specify your merchant ID as the username and the API key as the password.

URL to retrieve the token:

Copy
Full screen
Small screen
https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

Requesting a Token

You can alter the HTTP POST request by including the parameters you want to pass on to the Subscriptions UI. Both the request and the response are in JSON format. Below you can find sample code of how to get a token in PHP with the help of Xsolla PHP SDK. If you are using another programming language, please take a look at the CURL example by clicking on the CURL tab.
Copy
Full screen
Small screen
php
  • php
  • curl
<?php

use Xsolla\SDK\API\XsollaClient;
use Xsolla\SDK\API\PaymentUI\TokenRequest;

$tokenRequest = new TokenRequest($projectId, $userId);
$tokenRequest->setUserEmail('email@example.com')
    ->setExternalPaymentId('12345')
    ->setSandboxMode(true)
    ->setUserName('USER_NAME');

$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$token = $xsollaClient->createPaymentUITokenFromRequest($tokenRequest);
curl -v https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
-X POST \
-u your_merchant_id:merchant_api_key \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-d '
{
    "user": {
        "id": {
            "value": "1234567"
        },
        "email": {
            "value": "email@example.com"
        }
    },
    "settings": {
        "project_id": 14004,
        "mode": "sandbox"
    }
}'
You can find the full list of parameters in the API Reference.

Testing the Payment Process

To test the payment process, you can:
  • Use the Sandbox
  • Make a real payment and then initiate a refund via Publisher Account

Xsolla Sandbox is a standalone environment that supports all features of the live environment, except real payments. You can access the Sandbox by sending "mode":"sandbox" when getting the token.

To test a bank card payment:

  1. Open the Subscriptions UI in sandbox mode.
  2. Choose the item to purchase.
  3. Choose the Credit/debit cards group of payment methods.
  4. Enter the bank card details. Enter any values in the remaining fields. You can also specify incorrect details (card number, expiration date, or CVV) in order to generate an error.

List of bank cards to be used for testing

Note: Sandbox bank card payments can be made in the following currencies: USD, EUR, RUB, GBP, AED, ALL, AMD, ARS, AUD, AZN, BGN, BRL, BYN, CAD, CHF, CLP, CNY, COP, CZK, DKK, DZD, EGP, GEL, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KES, KGS, KRW, KZT, MAD, MDL, MKD, MNT, MXN, MYR, NGN, PEN, PHP, PKR, PLN, RON, RSD, SAR, SEK, SGD, THB, TRY, TWD, UAH, UYU, UZS, VEF, VND, ZAR.
Notice: To start receiving real payments, please remove "mode":"sandbox" first.

To test the payment process by making real payments, it is also recommended to use a bank card:

  1. Open the Subscriptions UI.
  2. Choose the item to purchase.
  3. Choose the Credit/Debit cards group of payment methods.
  4. Enter valid bank card details.
  5. After the payment is made, go to the Transaction search section in Publisher Account.
  6. Select your test transaction and click Refund (the transaction must be in the Completed status).

Info: To test the payment process for a subscription with a trial period, use a valid credit card and complete a real payment. Test bank cards are suitable only for testing subscription purchases without a trial period, since you can’t create a billing account in a test environment.
Note: It is recommended to use Visa and MasterCard cards to test the payment process.

Opening Subscriptions UI

To open the Subscriptions UI in a new window, use the following link: https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN, where ACCESS_TOKEN is the token obtained in the previous step. For testing purposes, use this URL: https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN.

Setting Up Product

API methods are used for managing subscription-based products.

Promotional Options

Coupons

The Coupon feature enables partners to create a coupon campaign which includes coupon codes that can either be uploaded by the partner or generated in Publisher Account. Coupons can grant a user virtual currency, virtual items, or trial days for a subscription plan. Customize the number of redemptions and the expiration date (if any).

See recipe

Bonuses

The Bonus feature lets users receive a bonus item when they buy a subscription.

See recipe

Recipes

Our Recipes will help you try out some of the advanced features of the Subscriptions: