Партнерская сеть / Интеграция платежного решения
 На главную

Партнерская сеть

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

  • Возможности

  • Инструкции

  • Расширения

  • Справочники

  • Интеграция платежного решения

    Чтобы отслеживать рефералов и совершать выплаты партнерам, необходимо выполнить интеграцию с Платежами Иксоллы. Требования:

    1. Платежный интерфейс подключен на оптимизированном сайте.
    2. Платежи Иксоллы являются единственным способом оплаты на сайте игры, в которую будет привлекаться трафик по программе Партнерской сети.

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

    Note
    Реализуйте получение токена, если на вашем сайте покупку будут осуществлять авторизованные пользователи. Если вы планируете продажи неавторизованным пользователям, подключите продукт Buy Button.

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

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

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

    Copy
    Full screen
    Small screen
    https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

    В HTTP POST запросе вы можете указать параметры, которые нужно передать на платежный интерфейс. Передайте информацию о пользователе в параметрах user.id, user.name и user.email метода Получение токена.
    Note
    Для параметра user.id используйте идентификатор, который пользователь сможет запомнить и в дальнейшем использовать самостоятельно вне игры (например, при пополнении игрового баланса с помощью push-платежей).
    Справочник API
    Посмотреть полный список параметров.

    Запрос и ответ передаются в формате JSON.

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

    Copy
    Full screen
    Small screen
    php
    • 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')
        ->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"
                }
        }
    }'

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

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

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

    Pay Station Embed

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

    ПРИМЕР АСИНХРОННОЙ ЗАГРУЗКИ СКРИПТА

    Copy
    Full screen
    Small screen
    <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>

    Pay Station Embed позволяет обрабатывать через механизм postMessage события платежного интерфейса, которые вы можете отправлять в систему аналитики. Чтобы узнать, как настроить обработку событий в вашей системе аналитики, обратитесь к аккаунт-менеджеру проекта или напишите на адрес am@xsolla.com.

    Команда Иксоллы создала виджет для упрощения интеграции платежного интерфейса на вашем сайте. Скрипт виджета доступен по ссылке. Используйте этот URL для загрузки скрипта на вашу страницу. Более подробная информация доступна в нашем проекте на Github.

    Список параметров для инициализации виджета:

    ПараметрТипОписание
    access_token
    stringТокен, полученный по API. Обязательный.
    sandbox
    booleanПередайте true для тестирования. Будет использоваться URL sandbox-secure.xsolla.com вместо secure.xsolla.com.
    lightbox
    objectОбъект со списком настроек, доступных в случае открытия в lightbox (для полноэкранной версии).
    lightbox.width
    stringШирина lightbox. При значении null соответствует ширине платежного интерфейса. Значение по умолчанию null.
    lightbox.height
    stringВысота lightbox. Значение по умолчанию 100%. Если значение null, высота lightbox соответствует высоте платежного интерфейса.
    lightbox.zIndex
    integerСвойство, отвечающее за положение объекта, по умолчанию 1000.
    lightbox.overlayOpacity
    integerНепрозрачность верхнего слоя (от 0 до 1), по умолчанию .6.
    lightbox.overlayBackground
    stringФон для верхнего слоя, по умолчанию #000000.
    lightbox.modal
    booleanМожно ли закрыть lightbox, по умолчанию false.
    lightbox.closeByClick
    booleanДолжен ли закрываться lightbox при клике на верхний слой, по умолчанию true.
    lightbox.closeByKeyboard
    booleanДолжен ли закрываться lightbox при нажатии ESC, по умолчанию true.
    lightbox.contentBackground
    stringФон фрейма, по умолчанию #ffffff. Обратите внимание, что настройка влияет только на фон фрейма lightbox и не меняет фон окна платежного интерфейса.
    lightbox.contentMargin
    stringОтступ вокруг фрейма, по умолчанию 10px.
    lightbox.spinner
    stringТип прелоадера, может принимать значение xsolla или round, по умолчанию xsolla.
    lightbox.spinnerColor
    stringЦвет прелоадера.
    childWindow
    objectНастройки дочернего окна, в котором открывается платежный интерфейс. Работает для мобильной версии.
    childWindow.target
    stringСвойство, определяющее, где должно быть открыто дочернее окно, может принимать значения _blank, _self, _parent, по умолчанию _blank.

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

    Список событий:

    ПараметрОписание
    initИнициализация виджета.
    openОткрытие виджета.
    loadСобытие после загрузки платежного интерфейса.
    closeСобытие после закрытия платежного интерфейса.
    statusСобытие, когда пользователь попадает на страницу статуса.
    status-invoiceСобытие, когда пользователь попадает на страницу статуса, но платеж еще не завершен.
    status-deliveringСобытие, когда пользователь попадает на страницу статуса, платеж завершен, мы прислали оповещение о платеже.
    status-doneСобытие, когда пользователь попадает на страницу статуса, платеж успешно зачислен.
    status-troubledСобытие, когда пользователь попадает на страницу статуса, но платеж не прошел.

    Если вы хотите самостоятельно открывать платежный интерфейс, используйте ссылку https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN.

    Note
    Для открытия платежного интерфейса необходимо использовать ссылку с префиксом https://.

    Для тестирования используйте URL https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN.

    Notice
    Параметр access_token содержит приватную информацию о пользователе. Убедитесь, что вы получаете этот параметр только при server-server взаимодействии.

    Iframe

    Необходимо реализовать:

    • Определение типа устройства (desktop или mobile) и передачу значения в токене в параметре settings.ui.version.
    • Механизм postMessage для получения событий от платежного интерфейса, которые вы можете отправлять в систему аналитики. Чтобы узнать, как настроить обработку событий в вашей системе аналитики, обратитесь к аккаунт-менеджеру проекта или напишите на адрес am@xsolla.com.

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

    Новое окно

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

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

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

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

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

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

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

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

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

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

    Тестирование оплаты банковской картой:
    1. Откройте платежный интерфейс в тестовом окружении.
    2. Выберите группу способов оплаты Банковские карты.
    3. Введите реквизиты карты. Остальные поля могут быть заполнены любыми данными. Вы также можете указать неверные реквизиты (номер карты, срок действия или CVV) для генерации ошибки.
    Список тестовых карт
    Посмотреть список тестовых банковских карт.
    Note

    Если страна пользователя определена как США или Канада, кроме реквизитов карты необходимо указать индекс. Вы можете указать любой подходящий индекс (например, 12345). Он используется для определения ставки налога на продажу и не влияет на прохождение тестового платежа.

    Платежи банковской картой в тестовом окружении могут проводиться в следующих валютах: 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" перед тем, как начать принимать реальные платежи.

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

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

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

    Запуск

    Чтобы начать обработку реальных платежей:

    1. Убедитесь, что вы подписали договор с Иксоллой.
    2. Откройте платежный интерфейс по ссылке secure.xsolla.com. Или измените sandbox-secure.xsolla.com на secure.xsolla.com в скрипте Pay Station Embed.
    3. Уберите параметр "mode":"sandbox" при получении токена.

    Прогресс интеграции
    Спасибо за обратную связь!
    Последнее обновление: 5 июля 2021

    Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.

    Сообщите о проблеме
    Мы постоянно улучшаем качество нашей документации. Ваш отзыв поможет нам в этом.
    Укажите email-адрес, чтобы мы могли связаться с вами
    Спасибо за обратную связь!