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

Pay2Play

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

  • Выбор платформы для каждой DRM
  • Разные цены для разных DRM
  • Выбор размера и цветовой темы виджета
  • Чаевые разработчику

Варианты интеграции

Возможны два варианта интеграции модуля — базовая и расширенная.

Базовая интеграция

Особенности базовой интеграции:

  • Быстрый запуск модуля
  • Не требует генерации токена и наличия серверной части
  • Подходит для продажи игры без предварительной авторизации пользователя

Расширенная интеграция

Особенности расширенной интеграции:

  • Позволяет безопасно передать данные пользователя для дальнейшей привязки покупки на стороне игры
  • Требует реализации серверной части

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

Для базовой интеграции модуля необходимо:

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

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

  • ID проекта. Отображается в URL Личного Кабинета при переходе в настройки проекта — https://publisher.xsolla.com/{merchant_id}/projects/{project_id}/.

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

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

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

  1. Перейдите в настройки модуля Pay2Play и задайте базовые настройки игры:
    • Название.
    • Описание.
    • Системные требования.
    • SKU - уникальный идентификатор.
    • Дата релиза.
    • Изображение.
    • DRM.
    • Платформы, которые поддерживаются выбранными DRM.
  2. Нажмите кнопку Далее.
  3. Настройте цены для выбранных DRM. Нажмите кнопку Далее.
  4. Установите переключатель Загруженные коды в положение Вкл.
  5. Загрузите пин-коды для выбранных DRM.

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

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

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

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

HTML
 <script>
     var access_data = {"settings":{"project_id":14004},"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.

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

Для расширенной интеграции модуля необходимо:

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

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

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

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

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

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

  1. Перейдите в настройки модуля Pay2Play и задайте базовые настройки игры:
    • Название.
    • Описание.
    • Системные требования.
    • SKU - уникальный идентификатор.
    • Дата релиза.
    • Изображение.
    • DRM.
    • Платформы, которые поддерживаются выбранными DRM.
  2. Нажмите кнопку Далее.
  3. Настройте цены для выбранных DRM. Нажмите кнопку Далее.
  4. Установите переключатель Загруженные коды в положение Вкл.
  5. Загрузите пин-коды для выбранных DRM.

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

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

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

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

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

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

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

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

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

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

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

HTML
 <script>
     var access_data = {"settings":{"project_id":14004},"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.

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

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

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

Доставка пин-кодов пользователю по API

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

  • реализовать обработку оповещения Получение пин-кода;
  • в настройках аддона на вкладке Загрузка кодов установить переключатель По требованию в положение Вкл., переключатель Загруженные коды — в положение Выкл.

Ограничение продаж пин-кодов

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

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

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

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

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

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

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

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

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