The following documentation was deprecated. Current version is available at developers.xsolla.com

Виртуальные товары

Виртуальные товары — модуль продажи внутриигрового контента за реальную или виртуальную валюту. Xsolla предлагает полноценный магазин для работы с товарами:

  • Цены в реальной и виртуальной валюте
  • Быстрая покупка товаров в один клик
  • Управление доступом к контенту (возможность покупки предмета только по достижении пользователем определенного уровня и т.д.)
  • Многоуровневый каталог с сортировкой и избранным
  • Пользовательская сортировка товаров по алфавиту или цене
  • Полное и краткое описание товаров
  • Список избранных и недавно приобретенных товаров

Руководство по интеграции

Для подключения модуля необходимо:

  1. Зарегистрироваться в Личном Кабинете Xsolla.
  2. Создать проект.
  3. Настроить модуль.
  4. Получить токен.
  5. Настроить открытие магазина.
  6. Настроить обработку оповещений.
  7. Протестировать процесс оплаты.
  8. Запустить модуль и подписать договор.

В процессе интеграции понадобятся следующие параметры:

  • ID мерчанта. Отображается в URL Личного Кабинета — https://publisher.xsolla.com/{merchant_id}/.
  • Ключ API. Генерируется в Личном Кабинете в разделе Настройки -> Компания.
  • ID проекта. Отображается в URL Личного Кабинета при переходе в настройки проекта — https://publisher.xsolla.com/{merchant_id}/projects/{project_id}/.
  • Секретный ключ проекта. Генерируется на странице настройки проекта.

Создание проекта

  1. Перейдите в раздел Проекты и нажмите кнопку Создать проект.
  2. В настройках проекта:
    a. Укажите URL оповещений.
    b. Сгенерируйте секретный ключ проекта для подписи оповещений.
    c. Включите модуль Товары.

Настройка модуля

  1. Перейдите в настройки модуля Товары и нажмите кнопку Создать группу товаров. Задайте настройки группы:
    • Место в каталоге. По умолчанию группа будет располагаться в корне.
    • Код.
    • Название и описание.
    • Если группа должна отображаться в магазине, необходимо установить флажок Показывать в магазине.
  2. Нажмите кнопку Создать.
  3. Нажмите ссылку Список товаров для возврата к основным настройкам модуля и создайте другие группы, необходимые для структуры вашего каталога.
  4. Нажмите кнопку Создать товар и укажите следующие параметры:
    • Одну или несколько групп, которым должен принадлежать товар. Товар, не принадлежащей ни одной из групп, в магазине не отображается.
    • SKU — уникальный идентификатор.
    • Название и краткое описание.
    • Стоимость в реальной валюте.
    • Изображение.
  5. Нажмите кнопку Создать.
  6. Нажмите ссылку Список товаров для возврата к основным настройкам модуля и создайте другие товары.

Получение токена магазина

Для интеграции магазина необходимо получить токен. Токен — это строка, в которой содержится информация об игре, пользователе и параметрах платежа. Xsolla API использует Basic HTTP-аутентификацию. Укажите свой ID мерчанта в качестве username и ключ API в качестве password.

Для получения доступа к sandbox-режиму используется параметр "mode" = "sandbox".

URL получения токена:

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

В HTTP POST запросе вы можете указать параметры, которые нужно передать на платежный интерфейс. Запрос и ответ передаются в JSON формате.

Ниже указан пример получения токена на PHP с использованием Xsolla PHP SDK. Если вы разрабатываете на другом языке, можно использовать CURL пример (нажмите на кнопку CURL).

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"
        }
    }'

Полный список параметров доступен в справочнике API.

Открытие магазина

Доступны следующие способы открытия магазина:

  • с помощью скрипта Pay Station Embed;
  • в новом окне;
  • в iframe.

Для открытия магазина в sandbox-режиме используйте URL https://sandbox-secure.xsolla.com/.

Pay Station Embed

Скрипт Pay Station Embed определяет тип устройства и открывает магазин в lightbox (для полноэкранной версии) или в новом окне (для мобильных устройств и планшетов). Рекомендуется использовать асинхронную загрузку скрипта.

Пример асинхронной загрузки

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

Полный список параметров инициализации скрипта доступен в справочнике API.

Новое окно

Для открытия магазина в новом окне используется ссылка https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN, где ACCESS_TOKEN — токен, полученный на предыдущем шаге.

Iframe

Чтобы открыть магазин в iframe, необходимо реализовать:

  • определение типа устройства (desktop или mobile) и передачу значения в токене в параметре settings.ui.version;
  • механизм postMessage для получения событий от платежного интерфейса.

Для открытия магазина в новом окне используется ссылка https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN, где ACCESS_TOKEN — токен, полученный на предыдущем шаге.

Настройка оповещений

Xsolla отправляет проекту следующие типы оповещений (webhooks):

  • Проверка существования пользователя
  • Успешный платеж
  • Отмена платежа

Чтобы подтвердить получение оповещения, ваш сервер должен вернуть 204 HTTP код без тела сообщения. Механизм работы оповещений с примерами обработки подробно описан в справочнике API.

Формирование подписи

Процесс формирования подписи включает следующие шаги:

  1. Данные, переданные в запросе от сервера Xsolla, и секретный ключ проекта (генерируется на странице настройки проекта) конкатенируются в строку.
  2. Полученная строка хешируется с помощью SHA1 хеш-алгоритма.
  3. Подпись передается в Signature заголовке.

При обработке оповещения необходимо проверить, что полученная подпись и подпись, переданная в Signature заголовке, совпадают.

Проверка существования пользователя

Сервер Xsolla посылает запрос на URL оповещений проекта, чтобы проверить существование персонажа в игре.

Пример запроса

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"
    }
}'

Полный список параметров доступен в справочнике API.

Успешный платеж

Когда пользователь завершает процесс оплаты, сервер Xsolla отправляет проекту оповещение с информацией о платеже.

Пример запроса

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
        }
    }
}'

Полный список параметров доступен в справочнике API.

Отмена платежа

Если пользователь отменяет платеж, сервер Xsolla отправляет проекту оповещение с информацией о платеже.

Пример запроса

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"
        }
    }
}'

Полный список параметров доступен в справочнике API.

Тестирование оповещений

Чтобы протестировать обработчик оповещений:

  1. Откройте настройки модуля в Личном Кабинете.
  2. Перейдите на вкладку Тестирование.
  3. Введите тестовые данные и нажмите кнопку Запустить тесты: сервер Xsolla отправит все типы оповещений.
  4. Если скрипт вернул корректный ответ, тест помечается зеленым цветом, в случае ошибки — красным.

Тестирование процесса оплаты

Xsolla Sandbox ("песочница") — это автономная рабочая среда, в которой доступны все функции Live режима, кроме проведения реальных платежей. Вы можете получить доступ к Sandbox, отправив параметр "mode = "sandbox" при получении токена.

Тестирование оплаты банковской картой:

  1. Откройте магазин в sandbox-режиме.
  2. Выберите предмет покупки.
  3. Выберите группу способов оплаты Банковские карты.
  4. Введите реквизиты карты из таблицы ниже. Остальные поля могут быть заполнены любыми данными. Вы также можете указать неверные реквизиты (номер карты, срок действия или CVV) для генерации ошибки.

Список банковских карт для тестирования

Обратите внимание! Платежи банковской картой в sandbox-режиме могут быть проведены только в валюте USD, EUR, RUB, GBP, SGD, HKD или THB.

Запуск

Чтобы запустить модуль после успешно пройденного тестирования, откройте настройки модуля в Личном Кабинете, перейдите на вкладку Запуск и установите переключатель в положение Вкл.

Обратите внимание! Чтобы начать принимать реальные платежи, необходимо:

  1. Удалить "sandbox" режим.
  2. Подписать договор.

Предотвращение фрода при помощи игровых параметров

Объект custom_parameters, переданный в токене, может использоваться для отправки игровых данных пользователя и обнаружения подозрительной активности. Так, игрок с низким количеством игрового времени и высоким игровым уровнем может быть мошенником, который создал аккаунт для продажи и "прокачал" его при помощи украденных банковских карт.

Список доступных параметров

Сообщите вашему аккаунт-менеджеру, какие параметры вы планируете передавать, и значения каждого из них. Эта информация будет использована для настройки антифрод-фильтров.

Оплата выбранным способом

При открытии магазина вы можете передавать id способа оплаты в параметре settings.payment_method. В этом случае пользователь сразу перенаправляется на платежную форму выбранного способа оплаты.

Пример запроса

CURL
    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"
            },
        },
        "settings": {
            "project_id": 14004,
            "payment_method": 24
        }
    }'

Список id способов оплаты можно получить в Личном Кабинете в разделе Платежные системы или с помощью метода Список платежных систем.

Покупка выбранного товара

При открытии магазина вы можете передавать ID товара в параметре purchase.virtual_items.items.sku. В этом случае пользователь сразу перенаправляется в платежный интерфейс.

Пример запроса

CURL
    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"
            },
        },
        "settings": {
            "project_id": 14004
        },
        "purchase": {
            "virtual_items": {
                "items": {
                  "sku": "item"
                },
          },
      }  
    }'

Оплата товара внутриигровой валютой

Если у вас подключен модуль Виртуальная валюта, вы можете продавать товар во внутриигровой валюте вашего проекта. Стоимость товара указывается в настройках товара в поле Стоимость товара в виртуальной валюте.

Построение каталога по атрибутам пользователя

Атрибуты пользователей предназначены для фильтрации товаров в магазине. Каталог товаров строится в реальном времени и отображается только для определенной группы игроков. Вы можете управлять видимостью и доступом к товарам в зависимости от переданных значений атрибутов пользователей.

Создание списка атрибутов

  1. Откройте в настройках модуля вкладку Правила фильтрации и нажмите кнопку Создать новый атрибут.
  2. Заполните следующие параметры:
    • Название.
    • Ключ.
    • Тип ключа.
  3. Нажмите кнопку Создать.

Создание правил

  1. Нажмите ссылку Установить правила фильтрации виртуальных товаров.
  2. Нажмите кнопку Создать новое правило.
  3. Заполните следующие параметры:
    • Название.
    • Условие.
    • Действие.
    • Товары, к которым применяется правило.
  4. Нажмите кнопку Создать.

После настройки атрибутов в токене необходимо передать параметр user.attributes с данными об атрибутах пользователя, необходимых для фильтрации списка товаров.

Пример запроса

CURL
    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"
            },
            "attributes": {
                "attribute1": "level80",
                "attribute2": "assassin"
            },
        },
        "settings": {
            "project_id": 14004
        }
    }'