Non-renewing Subscription

How It Works

Non-renewing subscription is a premium bonus which is a one-time purchase. Therefore, the user needs to buy it again when it expires.

Main features:

  • The subscription can be sold for an unlimited number of times.
  • When the user purchases the subscription again, the number of items in the inventory does not change, but the time before the subscription expires increases.
  • You can configure the subscription expiration time in your Publisher Account.

Restrictions:

  • You can manage the non-renewing subscription from the game served side only.

Who Can Use It

  • Partners who have integrated In-Game Store and want to set up a new item type — subscriptions.
  • Partners who want to sell Season Pass, Battle Pass, or different types of items which give users advantage or additional content (e.g. in-game items or tasks) for a limited period of time.

How to Get It

Prerequisites

If you have not integrated Xsolla Store yet, do the following:

  1. Create your Xsolla Publisher Account.
  2. Go to Projects and click on the Create project button.
  3. Add Project name and click Create.
  4. Go to Project settings > Integration settings and check that Integrate new Store management methods toggler is enabled.

  1. Connect Store to your project.
  2. Connect the Virtual Items module.

Integration Flow

  1. Create a group of items.
  2. Create items:
    1. When creating a new item, choose Non-renewing subscription in the Item property menu.
    2. Specify the expiration time.

  1. Implement getting subscriptions in a catalog.
  2. Implement getting subscriptions in an inventory.
  3. Implement methods for purchasing a subscription.

Getting Subscriptions in Catalog

Implement the Get virtual items list API method to show the full list of virtual items added to your store.

Example

var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/items/virtual_items?locale=en");

xhr.send(data);

//RESPONSE

"items": [
    {
      "attributes": [],
      "description": "Conquer your foes with vindication using the Basic Blaster! ",
      "groups": [
        "all",
        "featured",
        "Xsolla",
        "weapons"
      ],
      "image_url": "https://cdn.xsolla.net/img/misc/images/0c59a7698d4f66c1008b27ee752089b7.png",
      "is_free": false,
      "name": "Xsolla Basic Blaster 1",
      "order": 1,
      "price": {
        "amount": "0.9950000000000000",
        "amount_without_discount": "1.9900000000000000",
        "currency": "USD"
      },
      "sku": "gun_1",
      "type": "virtual_good"

Getting Subscriptions in Inventory

Implement the Get the current user's subscriptions method in the user inventory to give them access to additional features.

Purchasing Subscription

After the first purchase the subscription is added to the inventory.

After the second and future purchases:

  1. If the subscription is active, the subscription expiration time sums with the remaining time.
  2. If the subscription is not active, the subscription expiration time is default.

Implement the following methods to purchase a subscription.

Get Cart

Implement the Get cart by ID or Get current user’s cart API method for purchasing virtual items. Cart ID will be used to add/remove items.

Example

var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/cart/custom_id?locale=en&currency=USD");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");

xhr.send(data);

//RESPONSE

{
  "cart_id": "custom_id",
  "is_free": true,
  "items": [],
  "price": null
}

Note: To enable the quick items purchase (without creating a cart), use the Create order with specified item API method.

Create Order with All Items

  1. Implement one of the API methods:
    1. Create order with all items from particular cart if you got the cart by ID.
    2. Create order with all items from current cart if you got the current cart.

The created order will receive a New order status.

  1. To open the payment UI in a new window, use the following link: https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN, where ACCESS_TOKEN is the token received when the order was created.
  2. To test the payment process:
    1. Use the following URL: https://sandbox-secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN.
    2. Set the sandbox parameter to true in the request.
    3. Use the list of bank cards for testing.

Example

var data = JSON.stringify({
  "currency": "USD",
  "locale": "en",
  "sandbox": false
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://store.xsolla.com/api/v2/project/44056/payment/cart/custom_id");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");

xhr.send(data);

//RESPONSE  

{
  "order_id": 641,
  "token": "f4puMEFFDZcx9nv5HoNHIkPe9qghvBQo"
}

Get Order

Implement the Get order API method to determine if the purchase has already been processed. The following order statuses are possible:

  • New — order is created but not paid
  • Paid — order is paid
  • Cancelled — order is cancelled
  • Done — order is paid and the item is added to the inventory

Note: The status check should be carried out with a certain frequency, since a one-time check can occur earlier than the order is given the new status.

Example

var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/order/656");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");

xhr.send(data);

//RESPONSE

{
  "content": {
    "is_free": false,
    "items": [
      {
        "is_free": false,
        "price": {
          "amount": "0.9950",
          "amount_without_discount": "1.9900",
          "currency": "USD"
        },
        "quantity": 123,
        "sku": "gun_1"
      }
    ],
    "price": {
      "amount": "122.3850",
      "amount_without_discount": "122.3850",
      "currency": "USD"
    }
  },
  "order_id": 656,
  "status": "new"
}

Server-side Subscription Management

Granting

The game server can grant the subscription item to users via the granting method.

The subscription expiration time will be calculated in the same way as during the subscription purchase.

Revoking

The game server can revoke the item from the user via the revoking method. Revoking the item means that it will be completely deleted from the user inventory.