Store

Store is a comprehensive e-store solution for partners that supports:

Note: If you are already using Xsolla products and want to integrate Store, please contact your Account Manager.

How It Works

Step 1

Step 2

Step 3

User Flow

Integration Flow

To integrate Store:

  1. Register an Xsolla Publisher Account.
  2. Create a project.
  3. Choose your monetization option(s).
  4. Get a token.
  5. Configure the store opening flow.
  6. Customize Store parameters.
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:
    • Specify the webhook URL.
    • Generate a secret key to sign project webhooks.

Monetization Options

Virtual Currency

The Virtual Currency option allows game developers to sell in-game currencies. Key features:

  • Sell packages of in-game currency
  • Run promotional campaigns
  • Manage in-game currency user balances
  • Auto-detect user currency and country

Setting up

  1. Go to Virtual Currency settings and configure the following parameters:
    • Name
    • Price per unit
    • Image
  2. Create as many virtual currency packages as you need and set the following parameters for each of them:
    • Price
    • Image
  3. Turn on package display in Store.

Setting up Webhooks

You need to implement the following webhooks for the Virtual Currency:

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.

Recipes

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

Virtual Items

The Virtual Items option allows you to sell in-game content for real or virtual currencies. Key features:

  • Set prices in real and virtual currencies
  • Set up catalogs with one or several levels
  • Manage content access. For example, you can make a certain item available only to users who have reached a certain level, etc.
  • Configure brief and detailed item cards
  • Run promotional campaigns
  • Manage in-game currency user balances
  • Auto-detect user currency and country

Setting up

  1. Go to Virtual Items settings.
  2. Fill the store catalog:
    • Create item groups
    • Create items, specifying the following for each of them:
      • One or more groups that the item should belong to
      • SKU
      • Name and short description
      • Prices in real and virtual currencies
      • Image
  3. Turn on group display in Store.

Setting up Webhooks

You need to implement the following webhooks for the Virtual Items:

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.

Recipes

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

Subscriptions

The Subscriptions option allows developers to provide limited-time access to their services. Key features:

  • Define products to offer to users including access levels.
  • Define plans. You can create and configure plans for each currency, set trial periods, configure grace periods, 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.
  • Renew a subscription manually.

Product. Service to give access to.

Group. Sets of plans to provide access to products.

Plan. Purchase parameters: price, currency, payment period, grace & trial period.

Subscription. Combination of a product and plan chosen by the user.

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 the Publisher Account.
    • Canceled by user via email link.
    • User account deleted.

Setting up

  1. Go to Subscriptions settings.
  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.

Recipes

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

Game Keys

The Game Keys option allows game developers to sell keys and distribution packages right from the game’s website. Users can access the store using the Game Keys widget. Key features:

  • Choose DRM platforms via which to distribute keys and distribution packages
  • Choose the operating systems/game console versions for each DRM platform
  • Set different prices for different DRM platforms
  • Configure widget size and color theme
  • Give tips to the developer
  • Pre-orders

You can integrate the option in either basic or advanced mode.

Basic Integration

Basic integration:

  • Is quick to implement,
  • Does not require token generation or server implementation, and
  • Works well for games not requiring user pre-authorization.

You will need the Project ID parameter for the integration. You can find it in the Project settings > Webhooks section.

Setting up the module:

  1. Go to the Game Keys settings and press New package.
  2. Configure package parameters:
    • SKU - a unique identifier
    • Game title
    • A brief summary of your game
  3. Choose DRM and platforms.
  4. Configure prices for the selected DRMs.
  5. Upload keys for the selected DRMs.
  6. Implement widget code to the landing page.

You can find the full list of widget parameters for the basic integration in the API Reference.

Advanced Integration

Advanced integration:

You will need the following parameters for the integration:

  • Merchant ID, shown in Project settings > Webhooks
  • API key. Parameter is generated in the Company settings > API key section
  • Project ID, shown in Project settings > Webhooks
  • Secret key. Parameter is generated in the Project settings > Webhooks section

Setting up the module:

  1. Go to the Game Keys settings and press New package.
  2. Configure package parameters:
    • SKU - a unique identifier
    • Game title
    • A brief summary of your game
  3. Choose DRM and platforms.
  4. Configure prices for the selected DRMs.
  5. Upload keys for the selected DRMs.
  6. Implement widget code to the landing page.

You can find the full list of widget parameters for the advanced integration in the API Reference.

Setting up Webhooks

You need to implement the following webhooks for the Game Keys advanced integration:

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.

Recipes

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

Getting a Token

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

Xsolla API uses Basic HTTP authentication. Specify your merchant ID as the username and the API key as the password.

URL to retrieve the token:

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 store 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
  • 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

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 store 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

Notice: Sandbox bank card payments can only be made in USD, EUR, RUB, or GBP.
Note: Remove “mode”:“sandbox” to start accepting real payments.

Opening Store

Use the following link to open the store UI in a new window: https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN, where ACCESS_TOKEN is the token obtained in the previous step.

Use the following URL for testing purposes: https://sandbox-secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN.

Customizing Store

Customization is done on Xsolla’s side. Store allows customizing the following parameters for UI elements:

  • Location on the screen
  • Size
  • Shape
  • Styles
  • Fonts
  • Background

To customize Store, send the UI Kit or design assets to your Account Manager.

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 the 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

Labels

The Labels feature lets partners affix Labels to virtual items and virtual currency package promotions. For example, “Best Value”.

See recipe

Bonuses

The Bonus feature lets users receive a bonus item when they make a purchase. A bonus can be any of the following:

  • Virtual currency
  • Trial days for a subscription
  • Virtual item(s)
  • Game(s)
  • Physical goods (e.g. merchandise)

See recipe

Recipes

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