Xsolla Documentation - Платежи

Платежи Иксолла (Xsolla Pay Station) позволяют партнерам монетизировать игру, предоставляя пользователям удобный интерфейс для оплаты покупок во внутриигровом магазине. Основные возможности:

Более 700 способов оплаты в более чем 200 странах, в том числе банковские карты, электронные кошельки, мобильная оплата, оплата через платежные терминалы, подарочные карты, спецпредложения, криптовалюта
Более 130 валют
Локализация пользовательского интерфейса на 20 языков
Поддержка версий для настольных и мобильных браузеров, Смарт ТВ
Учет акций, купонов, налоговых сборов и комиссий платежных систем при расчете стоимости покупки
Автоматический подбор наиболее релевантных для пользователя способов оплаты с использованием алгоритма PayRank
Защита от мошеннических транзакций
Управление через Личный кабинет Иксолла: настройка прямых аккаунтов, изменение порядка отображения способов оплаты, просмотр истории транзакций и другой статистики, проведение сверок, выгрузка отчетов, просмотр обращений в поддержку, отмена платежей и т.д.

Note: Если вы подключаете продукт Магазин, отдельная интеграция платежного интерфейса Иксоллы не требуется — решение подключается автоматически.

Как это работает

Шаг 1

Шаг 2

Шаг 3

Глоссарий

PayRank

PayRank — алгоритм сортировки, который предлагает пользователям наиболее релевантные способы оплаты с учетом различных параметров — местоположение, история платежей, размер платежа и т.д. Используется при формировании списка популярных способов оплаты и полного списка способов оплаты в платежном интерфейсе. Гибкая настройка PayRank доступна в Личном кабинете.

Прямые аккаунты

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

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

Чтобы прямой аккаунт отображался в платежном интерфейсе, необходимо настроить его в Личном кабинете и подписать договор с Иксоллой.

Спецпредложения

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

Подарочная карта

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

Сценарий пользователя

Сценарий интеграции

Чтобы подключить продукт Платежи:

Зарегистрируйтесь в Личном кабинете Иксолла.
Создайте проект.
Получите токен.
Настройте открытие платежного интерфейса.
Настройте обработку оповещений.

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

ID продавца. Параметр отображается в разделе Настройки проекта > Оповещения.
Ключ API. Параметр генерируется в разделе Настройки компании > Ключ API.
ID проекта. Параметр отображается в разделе Настройки проекта > Оповещения.
Секретный ключ проекта. Параметр генерируется в разделе Настройки проекта > Оповещения.

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

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

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

Получение токена

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

API Иксоллы использует Basic HTTP-аутентификацию. Укажите свой ID продавца в качестве username и ключ API в качестве password.

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

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

Запрос на получение токена

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

Ниже указан пример получения токена на PHP с использованием PHP SDK. Если вы разрабатываете на другом языке, можно использовать CURL пример (нажмите на кнопку 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')
    ->setPurchase(9.99, 'USD');

$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"
    },
    "purchase": {
            "checkout": {
                "amount": 9.99,
                "currency": "USD"
            }
    }
}'

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

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

Для тестирования процесса оплаты вы можете:

использовать тестовое окружение;
провести реальный платеж, а затем сделать возврат через Личный кабинет.

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

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

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

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

Note: Платежи банковской картой в тестовом окружении могут проводиться в следующих валютах: USD, EUR, RUB, GBP, AED, ALL, AMD, ARS, AUD, AZN, BGN, BRL, BYN, CAD, CHF, CLP, CNY, COP, CZK, DKK, DZD, EGP, GEL, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KES, KGS, KRW, KZT, MAD, MDL, MKD, MNT, MXN, MYR, NGN, PEN, PHP, PKR, PLN, RON, RSD, SAR, SEK, SGD, THB, TRY, TWD, UAH, UYU, UZS, VEF, VND, ZAR.

Notice: Удалите "mode":"sandbox" перед тем, как начать принимать реальные платежи.

Для тестирования оплаты на реальных платежах рекомендуется также использовать банковскую карту:

Откройте платежный интерфейс.
Выберите группу способов оплаты Банковские карты.
Введите реквизиты действующей карты.
После оплаты перейдите в Личный кабинет в раздел Поиск транзакций.
Выберите тестовую транзакцию и нажмите Возврат (транзакция должна находиться в статусе Выполнена).

Note: Для тестирования оплаты рекомендуется использовать карты Visa и MasterCard.

Открытие платежного интерфейса

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

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

Note: Для открытия платежного интерфейса в тестовом окружении используйте 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 — токен, полученный на предыдущем шаге. Для тестирования используйте URL https://sandbox-secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN.

Iframe

Чтобы открыть платежный интерфейс в iframe, необходимо реализовать:

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

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

Для подключения продукта Платежи необходимо реализовать обработку следующих типов оповещений:

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

Чтобы протестировать оповещения, перейдите в раздел Оповещения в настройках проекта.

Note: После реализации оповещений откройте настройки продукта Платежи и установите переключатель Чекаут в положение Вкл.

Рецепты

Изучите наши рецепты, чтобы попробовать расширенные возможности продукта Платежи: