Модуль Pay2Play позволяет разработчикам игр продавать пин-коды напрямую с сайта игры. Для перехода в магазин используется виджет Pay2Play. Модуль имеет несколько вариантов интеграции и предлагает следующие возможности:
Возможны два варианта интеграции модуля — базовая и расширенная.
Особенности базовой интеграции:
Особенности расширенной интеграции:
Для базовой интеграции модуля необходимо:
В процессе интеграции понадобятся следующие параметры:
Xsolla Sandbox (“песочница”) — это автономная рабочая среда, в которой доступны все функции Live режима, кроме проведения реальных платежей. Вы можете получить доступ к Sandbox, отправив параметр "settings.mode" = "sandbox" в объекте access_data. Параметры и структура JSON внутри объекта access_data идентичны JSON в запросе на получение токена.
Тестирование оплаты банковской картой:
Список банковских карт для тестирования
Обратите внимание! Платежи банковской картой в sandbox-режиме могут быть проведены только в валюте USD, EUR, RUB, GBP, SGD, HKD или THB.
Виджет Pay2Play открывает магазин в lightbox (для полноэкранной версии) или в новом окне (для мобильных устройств и планшетов). Тип устройства определяется автоматически. Для получения кода виджета откройте настройки модуля в Личном Кабинете и перейдите на вкладку Опубликовать. Скопируйте код нужного виджета и добавьте его на сайт игры. Рекомендуется использовать асинхронную загрузку.
Пример асинхронной загрузки
<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.
Для расширенной интеграции модуля необходимо:
В процессе интеграции понадобятся следующие параметры:
Для интеграции магазина необходимо получить токен. Токен — это строка, в которой содержится информация об игре, пользователе и параметрах платежа. 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
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.
Процесс формирования подписи включает следующие шаги:
При обработке оповещения необходимо проверить, что полученная подпись и подпись, переданная в Signature заголовке, совпадают.
Сервер Xsolla посылает запрос на URL оповещений проекта, чтобы проверить существование персонажа в игре.
Пример запроса
$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 отправляет проекту оповещение с информацией о платеже.
Пример запроса
$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 отправляет проекту оповещение с информацией о платеже.
Пример запроса
$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.
Чтобы протестировать обработчик оповещений:
Xsolla Sandbox ("песочница") — это автономная рабочая среда, в которой доступны все функции Live режима, кроме проведения реальных платежей. Вы можете получить доступ к Sandbox, отправив параметр "mode" = "sandbox" при получении токена.
Тестирование оплаты банковской картой:
Список банковских карт для тестирования
Обратите внимание! Платежи банковской картой в sandbox-режиме могут быть проведены только в валюте USD, EUR, RUB, GBP, SGD, HKD или THB.
Виджет Pay2Play открывает магазин в lightbox (для полноэкранной версии) или в новом окне (для мобильных устройств и планшетов). Тип устройства определяется автоматически. Для получения кода виджета откройте настройки модуля в Личном Кабинете и перейдите на вкладку Опубликовать. Скопируйте код нужного виджета и добавьте его на сайт игры. Рекомендуется использовать асинхронную загрузку.
Пример асинхронной загрузки
<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 в положение Вкл. Для каждой добавленной валюты доступны три предустановленные суммы чаевых.
Пользователь сможет выбрать сумму чаевых перед переходом в магазин, чаевые будут добавлены к стоимости покупки.
Вы можете отправлять пин-коды при каждой покупке игры вместо загрузки файла с пин-кодами. Для включения опции необходимо:
Проект может ограничить количество доступных к продаже пин-кодов. По мере продажи пин-кодов вы будете получать уведомления по электронной почте. Первое уведомление будет отправлено, когда в продаже останется не более 100 пин-кодов, второе — когда все пин-коды будут проданы. При попытке приобрести пин-коды сверх лимита проведение платежа блокируется.
Модуль Pay2Play позволяет настроить региональные ограничения продажи пин-кодов:
После выполнения необходимых настроек при покупке пин-кода пользователь увидит предупреждение (если страна пользователя попадает под заданные ограничения). В странах, для которых продажа пин-кодов запрещена, проведение платежа блокируется.
Для подключения опции обратитесь к аккаунт-менеджеру проекта. По каждой платформе, для которой необходимо настроить региональные ограничения, вам потребуется следующая информация:
В рамках одной платформы страна может входить только в одну из групп с настройками цен или в список стран с запретом продажи. В странах, не вошедших ни в один из списков, продажа пин-кодов будет осуществляться без каких-либо ограничений и по ценам, указанным в базовых настройках модуля.
Обратите внимание! Если активация пин-кодов и запуск игры выполняются на вашей стороне или на стороне платформы, в день релиза игры необходимо загружать пин-коды с уже настроенными региональными ограничениями.