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

Xsolla Smart TV

Xsolla Smart TV — решение для платформы Smart TV, которое позволяет оплачивать покупки в магазине приложения Smart TV с помощью платежного интерфейса Pay Station. Выбор предмета покупки и расчет стоимости покупки выполняются на стороне приложения Smart TV. Данные о покупке передаются на платежный интерфейс.

Основные возможности:

  • Открытие платежного интерфейса по QR-коду или короткой ссылке
  • Проведение оплаты в мобильной или полной версии Pay Station
  • Оплата по сохраненному платежному аккаунту

Посмотреть демо

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

Для подключения модуля необходимо:

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

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

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

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

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

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

В зависимости от вида покупки необходимо включить и настроить один или несколько модулей:

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

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

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

Для открытия платежного интерфейса на платформе Smart TV используется ссылка https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN&smart_tv=1, где ACCESS_TOKEN — токен, полученный на предыдущем шаге.

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

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.

Запуск

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

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

  1. Удалить "sandbox" режим.
  2. Подписать договор.