Lootboxes

Lootboxes are sets of in-game items and/or virtual currencies that a user can buy or receive as a reward. The contents of a lootbox are generated randomly and are unknown to the user before the lootbox is opened.

The lootbox module has various integration options and allows game projects to configure the following:

  • Options to issue a lootbox: from the game’s request or through a store purchase
  • Options to buy a lootbox: via real or virtual currency
  • Options to open a lootbox: via real or virtual currency or by using a key purchased using real or virtual currency
  • Options to define how specific items or virtual currency packages spawn inside a lootbox
  • Ability to set the odds for any given item’s properties to appear in the lootbox
  • Lootbox opening animation

Integration Guide

The module supports the following features:

  • Adding a lootbox to the user’s inventory upon a purchase or an in-game event
  • Displaying an animated sequence when adding new items to the user’s inventory
  • Displaying an animated sequence when opening the lootbox
  • Removal of a lootbox from the inventory after it is opened

To enable lootboxes:

  1. Register a Xsolla Publisher Account.
  2. Create a project.
  3. Set up the module.
  4. Set up the lootboxes.
  5. Get a token.
  6. Set up the opening of the store UI.
  7. Set up webhook handling.
  8. Test the payment process.
  9. Launch the module and sign the agreement.

The following parameters are required for the integration:

  • Merchant ID — shown in the Publisher Account URL: https://publisher.xsolla.com/{merchant_id}/.
  • API Key — generated in Publisher Account > Settings > Company.
  • Project ID — shown in the Publisher Account URL when viewing project settings: https://publisher.xsolla.com/{merchant_id}/projects/{project_id}/.
  • Project secret key — generated in project settings.

Creating a Project

  1. Go to Projects and click Create new project.
  2. In the project settings:
    a. Specify the webhook URL.
    b. Generate a secret key to sign project webhooks.
    c. Enable the Virtual Items module.
    d. Go to Users and set Store users’ data in Xsolla to On.

Setting Up the Module

To get started with lootboxes, first create a catalog of virtual items that can be stored inside a lootbox.

  1. To do this, go to the Virtual Items module settings and click Create group of items. Configure the group:
    a. Location in the catalog (root folder by default).
    b. Code.
    c. Name and description.
    d. Store appearance. If you want the group to appear in the store, check Show in the store.
  2. Click Create.
  3. Click Item list to return to basic module settings and create other groups as needed for your catalog.
  4. Click Create Item and set the following parameters:
    a. Number of groups the item belongs to (one or more). If no group is selected, the item will not be displayed in the store.
    b. SKU — a unique identifier.
    c. Name and short description.
    d. Price in real currency.
    e. Image.
  5. Click Create.
  6. Click Item list to return to basic module settings and create other items as needed.

Setting Up Lootboxes

A lootbox consists of several slots. When a lootbox is opened, each slot is filled with a random item. You must define the range of items and the odds of their appearance in advance.

To create and configure a lootbox, use the CREATE LOOTBOXES method, specifying the following parameters:

  • Number of lootbox slots.
  • Table of probabilities of each possible lootbox item appearing in each slot.
  • Table of probabilities of specific-property items appearing in each slot.
  • Probability of a slot remaining empty.
  • Whether duplicate items can be replaced by virtual currency (as a percentage of their price or a specific amount thereof).

You can find the full list of methods and parameters in the API Reference.

Get Token to Open Store

To integrate the store UI into your game, you will need an access token. An access token is a string that identifies the game, user and purchase parameters.

Xsolla API uses HTTP Basic Authentication. Provide your Merchant ID as the basic auth username and the API key as your password.

Set the value to "mode":"sandbox" to test the payment process.

Token endpoint URL:

https://api.xsolla.com/merchant/merchants/{merchant_id}/token

In an HTTP POST request, you can use parameters for store UI. Request and response payloads are formatted as JSON.

Example Request

Below you can find sample code of how to get a token in PHP with the help of Xsolla PHP SDK. If you're using another programming language, please take a look at the CURL example by clicking on the CURL tab.

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')
    ->setCustomParameters(array('key1' => 'value1', 'key2' => 'value2'));

$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$token = $xsollaClient->createPaymentUITokenFromRequest($tokenRequest);
    curl -v https://api.xsolla.com/merchant/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.

Opening the Store UI

There are three ways of opening a store:

  • Use the Pay Station Embed script.
  • New window.
  • Iframe.

To open the store in sandbox mode, use the following URL: https://sandbox-secure.xsolla.com/.

Pay Station Embed

The Pay Station Embed script determines the type of device and opens the store UI in a lightbox (on desktop screens) or in a new window (on mobile and tablet screens). We recommend using asynchronous script loading.

Asynchronous script loading example:

 <script>
     var options = {
         access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
         sandbox: true //TODO please do not forget to remove this setting when going live
     };
     var s = document.createElement('script');
     s.type = "text/javascript";
     s.async = true;
     s.src = "https://static.xsolla.com/embed/paystation/1.0.7/widget.min.js";
     s.addEventListener('load', function (e) {
         XPayStationWidget.init(options);
     }, false);
     var head = document.getElementsByTagName('head')[0];
     head.appendChild(s);
 </script>

<button data-xpaystation-widget-open>Buy Credits</button>

You can find the full list of parameters in the API Reference.

New Window

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

Iframe

To open the store UI in an iframe, you must implement the following mechanisms on your side:

  • Specify the device type (desktop vs mobile) and send it within the token’s settings.ui.version parameter;
  • Receiving events from the payment UI via postMessage.

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

Setting Up Webhooks

Xsolla sends the following webhooks to your project:

  • User Validation
  • Payment
  • Inventory Content Changed
  • Refund

To acknowledge that you received webhook notifications without any problem, your server should return a 204 HTTP status code without body. The full description of webhook mechanism with samples is described in detail in the API Reference.

Creating a Signature

To create a signature:

  1. Concatenate the data sent in the Xsolla server’s request and the project’s secret key (generated in project settings).
  2. Hash the string using the SHA1 algorithm.
  3. Send the signature in the Signature header.

When handling a webhook, make sure that the signature received matches the one set in the Signature header.

User Validation

The Xsolla server sends a request to the project’s webhook URL to verify that a user exists in the game.

Request example

PHP
CURL
$request = array(
    'notification_type' => 'user_validation',
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email'=> 'email@example.com',
        'id'=> '1234567',
        'country' => 'US'
    )
)
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "notification_type": "user_validation",
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "country": "US"
    }
}'

You can find the full list of parameters in the API Reference.

Payment

The Xsolla server sends a webhook including payment details whenever a user completes a payment.

Request example

PHP
CURL
$request = array(
    'notification_type' => 'payment',
    'purchase' => array(
        'virtual_items' => array(
            'items' => array(
                0 => array(
                    'sku' => 'test_item1',
                    'amount' => 1,
                    ),
                1 => array(
                    'sku' => 'test_item2',
                    'amount' => 1,
                    ),
                2 => array(
                    'sku' => 'test_item3',
                    'amount' => 1,
                    ),
            )
        ),
        'total' => array(
            'currency' => 'USD',
            'amount' => 9.99
        )
    ),
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email' => 'email@example.com',
        'id' => '1234567',
        'country' => 'US'
    ),
    'transaction' => array(
        'id' => 87654321,
        'payment_date' => '2014-09-23T19:25:25+04:00',
        'payment_method' => 1380,
        'dry_run' => 1
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'payout_currency_rate' => 1,
        'payout' => array(
            'currency' => 'USD',
            'amount' => 9.49
        ),
        'xsolla_fee' => array(
            'currency' => 'USD',
            'amount' => 0.19
        ),
        'payment_method_fee' => array(
            'currency' => 'USD',
            'amount' => 0.31
        )
    )
)
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "notification_type": "payment",
    "purchase": {
        "virtual_items": {
            "items": [
                {
                    "sku": "test_item1",
                    "amount": 1
                },
                {
                    "sku": "test_item2",
                    "amount": 1
                },
                {
                    "sku": "test_item3",
                    "amount": 2
                },
            ]
        },
        "total": {
            "currency": "USD",
            "amount": 9.99
        }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "country": "US"
    },
    "transaction": {
        "id": 87654321,
        "payment_date": "2014-09-23T19:25:25+04:00",
        "payment_method": 1380,
        "dry_run": 1
    },
    "payment_details": {
        "payment": {
            "currency": "USD",
            "amount": 9.99
        },
        "vat": {
            "currency": "USD",
            "amount": 0
        },
        "payout_currency_rate": 1,
        "payout": {
            "currency": "USD",
            "amount": 9.49
        },
        "xsolla_fee": {
            "currency": "USD",
            "amount": 0.19
        },
        "payment_method_fee": {
            "currency": "USD",
            "amount": 0.31
        }
    }
}'

You can find the full list of parameters in the API Reference.

Inventory Content Changed

The Xsolla server will send a webhook to the project server whenever a user’s inventory is changed (items are added or removed).

Request example

PHP
CURL
$request = array(
    'virtual_currency_balance' => (
            'old_value' => '0',
            'new_value' => '200',
            'diff' => '200'
    ),
    'user' => (
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'inGamePurchase',
    'notification_type' => 'user_balance_operation',
    'items_operation_type' =>  'add',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
    'id_operation' => '66989'
);
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "virtual_currency_balance":{
        "old_value":"0",
        "new_value":"200",
        "diff":"200"
    },
    "user":{
        "name":"Xsolla User",
        "id":"1234567",
        "email":"semail@example.com
    },
    "operation_type":"inGamePurchase",
    "notification_type":"user_balance_operation",
    "items_operation_type": "add",
         "items": [{
         "sku": "1468",
         "amount": "2"
         }],
    "id_operation":"66989"
}'

You can find the full list of parameters in the API Reference.

Refund

If the user cancels the payment, the Xsolla server sends a webhook notification with information about the payment.

Request example

PHP
CURL
$request = array(
    'notification_type' => 'refund',
    'purchase' => array(
        'virtual_currency' => array(
            'name' => 'Coins',
            'quantity' => 100,
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'total' => array(
            'currency' => 'USD',
            'amount' => 9.99
        )
    ),
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email' => 'email@example.com',
        'id' => '1234567',
        'country' => 'US'
    ),
    'transaction' => array(
        'id' => 87654321,
        'payment_date' => '2014-09-23T19:25:25+04:00',
        'payment_method' => 1380,
        'dry_run' => 1
    ),
    'refund_details' => (
            'code' => 1,
            'reason' => 'Fraud'
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'payout_currency_rate' => 1,
        'payout' => array(
            'currency' => 'USD',
            'amount' => 9.49
        ),
        'xsolla_fee' => array(
            'currency' => 'USD',
            'amount' => 0.19
        ),
        'payment_method_fee' => array(
            'currency' => 'USD',
            'amount' => 0.31
        )
    )
);
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "notification_type":"refund",
    "purchase":{
        "virtual_currency":{
            "name": "Coins",
            "quantity":10,
            "currency":"USD",
            "amount":100
        },
        "subscription":{
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "date_create": "2014-09-22T19:25:25+04:00",
            "currency": "USD",
            "amount": 9.99
        },
        "checkout":{
            "currency":"USD",
            "amount":50
        },
        "virtual_items":{
            "items":[
                {
                    "sku": "test_item1",
                    "amount":1
                }
            ],
            "currency":"USD",
            "amount":50
        },
        "total":{
            "currency":"USD",
            "amount":200
        }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    },
    "transaction":{
        "id":1,
        "external_id":1,
        "dry_run":1,
        "agreement":1
    },
    "refund_details":{
        "code":1,
        "reason":"Fraud"
    },
    "payment_details":{
        "xsolla_fee":{
            "currency":"USD",
            "amount":"10"
        },
        "payout":{
            "currency":"USD",
            "amount":"200"
        },
        "payment_method_fee":{
            "currency":"USD",
            "amount":"20"
        },
        "payment":{
            "currency":"USD",
           "amount":"230"
        }
    }
}'

You can find the full list of parameters in the API Reference.

Testing Webhooks

To test the webhook handler:

  1. In the Publisher Account, open the module settings.
  2. Go to the Testing tab.
  3. Enter the test data and click Test. The Xsolla server will send all possible webhooks.
  4. The test is marked green in case of a valid response and red in case of an error.

Testing 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. Click Credit/debit cards.
  4. Enter the bank card details and 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

Important! Sandbox bank card payments can only be made in USD, EUR, RUB, GBP, SGD, HKD, or THB.

Launching the Module

To launch the module after its successful testing, open its settings in the Publisher Account, go to the Launch tab, and click On.

Important! Before you can accept real payments, you must:

  1. Remove "mode" = "sandbox".
  2. Sign the agreement.

Opening a Lootbox on the Game-Server Side

When a lootbox is opened on the game-server side, you can:

  • Check if a lootbox exists in a user's inventory.
  • Get the list of dropped items.
  • Add new items to a user’s inventory.
  • Remove a lootbox from the inventory after it is opened.

To enable the feature, please contact your account manager.

Lootbox Opening Animation

If a lootbox is opened on the Xsolla-server side, you can add an animated sequence depending on the outcome of the opening. To enable this feature, please contact your account manager.