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

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

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

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

  • Инструкции

  • Расширения

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

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

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

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

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

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

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

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

    Чтобы найти эти данные:

    1. Зайдите в Личный кабинет и перейдите в Настройки компании.
    2. На вкладке Компания скопируйте ID продавца.
    3. На вкладке Ключ API скопируйте Kлюч API.

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

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

    В HTTP POST запросе вы можете указать параметры, которые нужно передать на платежный интерфейс. Передайте информацию о пользователе в параметрах user.id, user.name и user.email метода Получение токена.

    Примечание
    Для параметра 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"
                }
        }
    }'

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

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

    Примечание

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

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

    Pay Station Embed

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

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

    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 соответствует высоте платежного интерфейса.
    lightbox.height
    stringВысота lightbox. Значение по умолчанию 100%. Если установлено значение null, высота lightbox соответствует высоте платежного интерфейса.
    lightbox.zIndex
    integerСвойство, отвечающее за положение объекта, по умолчанию 1000.
    lightbox.overlayOpacity
    integerНепрозрачность верхнего слоя (от 0 до 1), по умолчанию .6.
    lightbox.overlayBackground
    stringФон для верхнего слоя, по умолчанию #000000.
    lightbox.modal
    booleanЕсли установлено значение true, lightbox нельзя закрыть. По умолчанию false.
    lightbox.closeByClick
    booleanЕсли установлено значение true, lightbox закрывается при нажатии на верхний слой. По умолчанию true.
    lightbox.closeByKeyboard
    booleanЕсли установлено значение true, 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.

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

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

    Внимание
    Параметр 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 код без тела сообщения.

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

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

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

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

    Примечание
    Тестирование платежей до подписания договора с Иксоллой доступно только в тестовом окружении.

    Используя тестовое окружение, вы можете тестировать процесс оплаты с помощью:

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

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

    Кроме реквизитов карты вам потребуется указать индекс, если выполняется хотя бы одно из условий:

    • Страна пользователя определена как США или Канада.
    • Идентификатор карты (БИН) указывает на то, что карта выпущена в США.

    Вы можете указать произвольное числовое значение в качестве индекса (например, 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.

    Внимание
    Изучите доступные сценарии тестирования разовой оплаты и сохраненных карт.

    Тестирование оплаты с помощью PayPal

    Внимание
    В настоящее время тестирование оплаты с помощью PayPal доступно только для сценария с успешным платежом.

    1. Создайте аккаунт для тестового окружения PayPal:
      1. Откройте сайт PayPal для разработчиков.
      2. Войдите в свой аккаунт или создайте новый.
      3. Перейдите на вкладку Sandbox > Accounts.
      4. В разделе Sandbox Account нажмите Create account.
      5. В модальном окне выберите тип аккаунта Personal и страну.
      6. Нажмите Create. Созданный аккаунт появится в списке тестовых аккаунтов.

    1. Откройте платежный интерфейс в тестовом окружении.
    2. Выберите способ оплаты PayPal.
    3. В окне ввода платежных данных введите необходимую информацию.
    4. Нажмите Pay Now. Вы будете перенаправлены на окно для входа в аккаунт PayPal.

    1. Для завершения тестового платежа введите данные вашего тестового аккаунта, созданного на шаге 1: Email ID в качестве email-адреса и System Generated Password в качестве пароля. Чтобы найти эти данные:
      1. Войдите в свой аккаунт на сайте PayPal для разработчиков.
      2. Перейдите на вкладку Sandbox > Accounts.
      3. В разделе Sandbox Account выберите тестовый аккаунт.
      4. Нажмите ••• и в раскрывающемся списке выберите View/edit account.
    2. Нажмите Pay Now.

    Вы также можете использовать данные уже созданных тестовых аккаунтов:

    Email IDSystem Generated Password
    sb-xmxij16980134@business.example.comoi9_m_KW
    sb-p7pju16979920@business.example.com7%%p8ioS

    Запуск

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

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

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

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

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