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

Предзаказы

Предзаказы — решение Xsolla на базе модуля Pay2Play, которое позволяет продавать игру до официального релиза. При оплате предзаказа пользователь получает уникальный номер, являющийся подтверждением факта покупки. Пин-коды доступа к игре автоматически доставляются пользователям в день релиза.

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

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

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

  1. Перейдите в настройки модуля Pay2Play и задайте базовые настройки игры:
    a. Название.
    b. Описание.
    c. Системные требования.
    d. SKU — уникальный идентификатор.
    e. Дата релиза.
    f. Изображение.
    g. DRM.
    h. Платформы, которые поддерживаются выбранными DRM.
  2. Нажмите Далее.
  3. Настройте цены для выбранных DRM.

Интеграция виджета Pay2Play

Виджет Pay2Play открывает магазин в lightbox (для полноэкранной версии) или в новом окне (для мобильных устройств и планшетов). Тип устройства определяется автоматически.

Для получения кода виджета откройте настройки модуля в Личном Кабинете и перейдите на вкладку Опубликовать. Скопируйте код нужного виджета и добавьте его на сайт игры. Рекомендуется использовать асинхронную загрузку.

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

 <script>
         var access_data = {"settings":{"project_id":14004,"mode":"sandbox"},"purchase":{"pin_codes":{"codes":[{"digital_content":"game_sku"}]}}};
         var target_element = "#widget-example-element";
         var s = document.createElement('script');
         s.type = "text/javascript";
         s.async = true;
         s.src = "//static.xsolla.com/embed/pay2play/2.1.0/widget.min.js";
         s.addEventListener('load', function (e) {
                 var widgetInstance = XPay2PlayWidget.create(access_data,target_element);
         }, false);
         var head = document.getElementsByTagName('head')[0];
         head.appendChild(s);
 </script>

Полный список параметров инициализации виджета доступен в справочнике API, инструкция по добавлению виджета — в проекте GitHub.

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

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

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

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

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

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

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

Загрузка пин-кодов

В день релиза игры откройте настройки модуля Pay2Play и загрузите пин-коды для выбранных DRM на вкладке Загрузка пин-кодов.

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

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

  1. Настроить проект.
  2. Получить токен.
  3. Настроить обработку оповещений.

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

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

Настройка проекта

При настройке проекта:

  1. Установите переключатель HTTP оповещения в положение Вкл.
  2. Укажите URL оповещений.
  3. Сгенерируйте секретный ключ проекта для подписи оповещений.
  4. Установите переключатель Бессерверная интеграция в положение Выкл.

Получение токена платежного интерфейса

Для интеграции платежного интерфейса в вашей игре необходимо получить токен. Токен — это строка, в которой содержится информация об игре, пользователе и параметрах платежа. 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.

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

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. Если скрипт вернул корректный ответ, тест помечается зеленым цветом, в случае ошибки — красным.

Чаевые разработчику

Проект может получать чаевые с каждой покупки. Для включения опции откройте настройки цен аддона и установите переключатель Использовать чаевые в виджете Pay2Play в положение Вкл. Для каждой добавленной валюты доступны три предустановленные суммы чаевых.

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

Ограничение продаж на предзаказ игры

Проект может ограничить количество доступных к продаже предзаказов. По мере продажи предзаказов вы будете получать уведомления по электронной почте. Первое уведомление будет отправлено, когда в продаже останется не более 100 предзаказов, второе — когда все предзаказы будут проданы. При попытке приобрести предзаказы сверх лимита проведение платежа блокируется.

Региональные ограничения продаж

Модуль Предзаказы позволяет настроить региональные ограничения продажи предзаказов:

  • задать различную стоимость для отдельных стран или групп стран;
  • запретить продажу в определенных странах.

После выполнения необходимых настроек при покупке предзаказа пользователь увидит предупреждение (если страна пользователя попадает под заданные ограничения). В странах, для которых продажа предзаказов запрещена, проведение платежа блокируется.

Для подключения опции обратитесь к аккаунт-менеджеру проекта. По каждой платформе, для которой необходимо настроить региональные ограничения, вам потребуется следующая информация:

  • Тип ограничения:
    • на активацию — пин-код может быть активирован только в определенных странах;
    • на запуск — пин-код может быть активирован в любой стране, игра может быть запущена только в определенных странах;
    • на активацию и на запуск — активация пин-кода и запуск игры могут быть выполнены только в определенных странах.
  • Список групп стран, для которых стоимость предзаказов будет отличаться от базовых настроек модуля.
  • Настройки для каждой группы стран:
    • Название группы.
    • SKU — уникальный идентификатор группы.
    • Список цен в разных валютах. Обязательно укажите цену в валюте, выбранной в настройках модуля по умолчанию.
    • Список стран, входящих в группу.
  • Список стран, для которых продажа предзаказов должна быть запрещена (при необходимости).

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

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