В этом сценарии вы реализуете отображение каталога подписок на своей стороне и управляете процессом покупки через собственный сервер. Все взаимодействия с Xsolla выполняются с помощью серверных методов Xsolla API.

Чтобы реализовать отображение каталога и открытие платежного интерфейса:

1. Реализуйте получение списка планов с помощью серверного метода Список планов (опционально).

2. Реализуйте отображение каталога на своей стороне.
3. Реализуйте получение токена, чтобы открыть платежный интерфейс для покупки подписки одним из способов:
   • на странице выбора платежного метода;
   • на странице ввода платежных данных.
4. Реализуйте открытие платежного интерфейса.

Получение токена для открытия платежного интерфейса на странице выбора платежного метода

Чтобы платежный интерфейс при открытии отображал страницу выбора платежного метода, передайте в метод Создание токена параметр purchase.subscription.plan_id с ID плана подписки, выбранного пользователем. При необходимости передайте дополнительные параметры для кастомизации платежного интерфейса.

 1curl -v https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
 2-X POST \
 3-u your_merchant_id:merchant_api_key \
 4-H 'Content-Type:application/json' \
 5-H 'Accept: application/json' \
 6-d '
 7{
 8  "user":{
 9    "id":{
10      "value": "1234567",
11      "hidden": true
12    },
13    "email": {
14      "value": "user1234@game1234.com"
15    },
16    "name": {
17      "value": "UserName",
18      "hidden": false
19    }
20  },
21  "settings": {
22    "project_id": 12345,
23    "currency": "USD"
24  },
25  "purchase": {
26    "subscription": {
27      "plan_id": "54321"
28    }
29  }
30}'

Пример страницы выбора платежного метода:

Получение токена для открытия платежного интерфейса на странице ввода платежных данных

Для того чтобы платежный интерфейс при открытии отображал страницу ввода платежных данных, передайте в метод Создание токена параметры:

• purchase.subscription.plan_id с ID выбранного плана.

• settings.payment_method с ID платежного метода. Список ID вы можете найти в проекте в Личном кабинете, в разделе Платежи > Способы оплаты или запросить у персональному менеджеру проекта.

При необходимости передайте дополнительные параметры для кастомизации платежного интерфейса.

 1curl -v https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
 2-X POST \
 3-u your_merchant_id:merchant_api_key \
 4-H 'Content-Type:application/json' \
 5-H 'Accept: application/json' \
 6-d '
 7{
 8  "user":{
 9    "id":{
10      "value": "1234567",
11      "hidden": true
12    },
13    "email": {
14      "value": "user1234@game1234.com"
15    },
16    "name": {
17      "value": "UserName",
18      "hidden": false
19    }
20  },
21  "settings": {
22    "project_id": 12345,
23    "payment_method": 1380,
24    "currency": "USD"
25  },
26  "purchase": {
27    "subscription": {
28      "plan_id": "54321"
29    }
30  }
31}'

Пример страницы ввода платежных данных:

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

 1<script>
 2   var options = {
 3       access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
 4       sandbox: true //TODO please do not forget to remove this setting when going live
 5   };
 6   var s = document.createElement('script');
 7   s.type = "text/javascript";
 8   s.async = true;
 9   s.src = "https://cdn.xsolla.net/payments-bucket-prod/embed/1.5.0/widget.min.js";
10   s.addEventListener('load', function (e) {
11       XPayStationWidget.init(options);
12   }, false);
13   var head = document.getElementsByTagName('head')[0];
14   head.appendChild(s);
15</script>
16
17<button data-xpaystation-widget-open>Buy Credits</button>

1<iframe
2  src="https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN"
3  width="800"
4  height="930"
5  allow="clipboard-read; clipboard-write; payment"
6></iframe>

В этом сценарии все операции с данными о планах подписок выполняются с помощью клиентских методов Xsolla API. Это позволяет получать список планов, отображать каталог и открывать платежный интерфейс напрямую из клиента приложения.

Чтобы реализовать отображение каталога и открытие платежного интерфейса:

1. Реализуйте получение списка планов с помощью клиентских методов (опционально):
   • если в проекте настроены продукты подписки, используйте метод получения списка планов по продукту;
   • если в проекте не настроены продукты подписки, используйте метод получения списка планов.

2. Реализуйте отображение каталога на своей стороне.
3. Реализуйте получение токена, чтобы открыть платежный интерфейс для покупки подписки. Для этого используйте клиентский метод получения ссылки на открытие платежного интерфейса.
4. Реализуйте открытие платежного интерфейса.

Клиентский метод получения списка планов по продукту

В клиентской части вашего приложения реализуйте получение списка планов по продукту с использованием HTTP GET-запроса https://subscriptions.xsolla.com​/api/user/v1/projects/{projectId}/products/{​​productId}/plans.

Запрос к методу должен содержать заголовок Authorization: Bearer <client_user_jwt>, где <client_user_jwt> — JSON Web Token (JWT) пользователя — уникальный токен, закодированный по стандарту Base64. Используйте для его получения:

• Методы API Register new user и Auth by username, если в вашем приложении используется авторизация по логину и паролю.

• Метод API Auth via social network, если в вашем приложении используется авторизация через социальные сети.

В качестве path-параметра укажите:

• projectId — ID проекта. Вы можете найти этот параметр в Личном кабинете рядом с названием проекта.

• productID — ID продукта подписки. Для его получения обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.

В качестве query-параметров укажите:

1curl -X 'GET' \
2'https://subscriptions.xsolla.com/api/user/v1/projects/{project_id}/products/{​​productId}/plans?country=RU  ' \
3  -H 'accept: application/json' \
4  -H 'Authorization: Bearer client_user_jwt'

 1{
 2  "items": [
 3    {
 4      "plan_id": 54321,
 5      "plan_external_id": "PlanExternalId",
 6      "plan_group_id": "TestGroupId",
 7      "plan_type": "all",
 8      "plan_name": "Localized plan name",
 9      "plan_description": "Localized plan description",
10      "plan_start_date": "2021-04-11T13:51:02+03:00",
11      "plan_end_date": "2031-04-11T13:51:02+03:00",
12      "trial_period": 7,
13      "period": {
14        "value": 1,
15        "unit": "month"
16      },
17      "charge": {
18        "amount": 4.99,
19        "setup_fee": 0.99,
20        "currency": "USD"
21      },
22      "promotion": {
23        "promotion_charge_amount": 3.99,
24        "promotion_remaining_charges": 3
25      }
26    }
27  ],
28  "has_more": false
29}

Клиентский метод получения списка планов

В клиентской части вашего приложения реализуйте получение списка планов по продукту с использованием HTTP GET-запроса .

Запрос к методу должен содержать заголовок Authorization: Bearer <client_user_jwt>, где <client_user_jwt> — JSON Web Token (JWT) пользователя — уникальный токен, закодированный по стандарту Base64. Используйте для его получения:

• Методы API Register new user и Auth by username, если в вашем приложении используется авторизация по логину и паролю.

• Метод API Auth via social network, если в вашем приложении используется авторизация через социальные сети.

В качестве path-параметра укажите projectId — ID проекта. Вы можете найти этот параметр в Личном кабинете рядом с названием проекта.

В качестве query-параметров укажите:

1curl -X 'GET' \
2'https://subscriptions.xsolla.com/api/user/v1/projects/{project_id}/plans?country=RU  ' \
3  -H 'accept: application/json' \
4  -H 'Authorization: Bearer client_user_jwt'

 1{
 2  "items": [
 3    {
 4      "plan_id": 54321,
 5      "plan_external_id": "PlanExternalId",
 6      "plan_group_id": "TestGroupId",
 7      "plan_type": "all",
 8      "plan_name": "Localized plan name",
 9      "plan_description": "Localized plan description",
10      "plan_start_date": "2021-04-11T13:51:02+03:00",
11      "plan_end_date": "2031-04-11T13:51:02+03:00",
12      "trial_period": 7,
13      "period": {
14        "value": 1,
15        "unit": "month"
16      },
17      "charge": {
18        "amount": 4.99,
19        "setup_fee": 0.99,
20        "currency": "USD"
21      },
22      "promotion": {
23        "promotion_charge_amount": 3.99,
24        "promotion_remaining_charges": 3
25      }
26    }
27  ],
28  "has_more": false
29}

Клиентский метод получения ссылки на открытие платежного интерфейса

В клиентской части вашего приложения реализуйте получение ссылки на открытие платежного интерфейса с использованием HTTP POST-запроса https://subscriptions.xsolla.com​/api/user/v1/projects/{projectId}/subscriptions/buy.

Запрос к методу должен содержать заголовок Authorization: Bearer <client_user_jwt>, где <client_user_jwt> — JSON Web Token (JWT) пользователя — уникальный токен, закодированный по стандарту Base64. Используйте для его получения:

• Методы API Register new user и Auth by username, если в вашем приложении используется авторизация по логину и паролю.

• Метод API Auth via social network, если в вашем приложении используется авторизация через социальные сети.

В качестве path-параметра укажите projectId — ID проекта. Вы можете найти этот параметр в Личном кабинете рядом с названием проекта.

В качестве query-параметра укажите country — страна пользователя в двухбуквенном обозначении согласно стандарту ISO 3166-1 alpha-2. Влияет на выбор локали и валюты. Если параметр не передается, страна определяется по IP-адресу пользователя.

В запросе передайте параметры:

• plan_external_id для открытия платежного интерфейса на странице выбора платежного метода.

Пример платежного интерфейса:

• plan_external_id и settings.payment_method для открытия платежного интерфейса на странице ввода платежных данных.

Пример платежного интерфейса:

Параметры тела запроса:

При необходимости передайте дополнительные параметры для кастомизации платежного интерфейса.

 1curl -X 'POST' \
 2'https://subscriptions.xsolla.com/api/user/v1/projects/{project_id}/subscriptions/buy?country=RU  ' \
 3  -H 'accept: application/json' \
 4  -H 'Authorization: Bearer client_user_jwt'
 5
 6  {
 7    "plan_external_id": "PlanExternalId",
 8    "settings": {
 9      "ui": {
10        "size": "large",
11        "theme": "string",
12        "version": "desktop",
13        "desktop": {
14          "header": {
15            "is_visible": true,
16            "visible_logo": true,
17            "visible_name": true,
18            "type": "compact",
19            "close_button": true
20          }
21        },
22        "mobile": {
23          "mode": "saved_accounts",
24          "footer": {
25            "is_visible": true
26          },
27          "header": {
28            "close_button": true
29          }
30        },
31        "mode": "user_account"
32        }
33      },
34      "currency": "string",
35      "locale": "string",
36      "external_id": "string",
37      "payment_method": 1,
38      "return_url": "string",
39      "redirect_policy": {
40        "redirect_conditions": "none",
41        "delay": 0,
42        "status_for_manual_redirection": "none",
43        "redirect_button_caption": "string"
44      }
45    }

1{
2  "link_to_ps": "https://secure.xsolla.com/paystation2/?access_token=<access_token>"
3}

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

 1<script>
 2   var options = {
 3       access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
 4       sandbox: true //TODO please do not forget to remove this setting when going live
 5   };
 6   var s = document.createElement('script');
 7   s.type = "text/javascript";
 8   s.async = true;
 9   s.src = "https://cdn.xsolla.net/payments-bucket-prod/embed/1.5.0/widget.min.js";
10   s.addEventListener('load', function (e) {
11       XPayStationWidget.init(options);
12   }, false);
13   var head = document.getElementsByTagName('head')[0];
14   head.appendChild(s);
15</script>
16
17<button data-xpaystation-widget-open>Buy Credits</button>

1<iframe
2  src="https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN"
3  width="800"
4  height="930"
5  allow="clipboard-read; clipboard-write; payment"
6></iframe>

Чтобы открыть платежный интерфейс в новом окне, используйте URL-адрес https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN, где TOKEN — это полученный токен.

Вы также можете открывать платежный интерфейс другими способами:

• С помощью скрипта Pay Station Embed. Ограничение: могут возникнуть проблемы с открытием во внутриигровом браузере (WebView).
• В iframe. Ограничение: могут возникнуть проблемы с открытием во внутриигровом браузере (WebView) и в мобильной версии приложения.

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

 1<script>
 2   var options = {
 3       access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
 4       sandbox: true //TODO please do not forget to remove this setting when going live
 5   };
 6   var s = document.createElement('script');
 7   s.type = "text/javascript";
 8   s.async = true;
 9   s.src = "https://cdn.xsolla.net/payments-bucket-prod/embed/1.5.0/widget.min.js";
10   s.addEventListener('load', function (e) {
11       XPayStationWidget.init(options);
12   }, false);
13   var head = document.getElementsByTagName('head')[0];
14   head.appendChild(s);
15</script>
16
17<button data-xpaystation-widget-open>Buy Credits</button>

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

Команда Xsolla создала виджет для упрощения интеграции платежного интерфейса на вашем сайте. Скрипт виджета доступен в нашем проекте на GitHub.

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

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

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

Чтобы открыть платежный интерфейс внутри iframe:

1. Реализуйте механизм postMessage для получения событий от платежного интерфейса.
2. Откройте платежный интерфейс, используя ссылку https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN, где TOKEN — это полученный токен.

Возможная проблема: Если при открытии платежного интерфейса в iframe не отображается кнопка копирования кода для подтверждения оплаты, который запрашивают некоторые платежные системы, передайте в iframe атрибут allow=“clipboard-read; clipboard-write; payment”.

Пример:

1<iframe
2  src="https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN"
3  width="800"
4  height="930"
5  allow="clipboard-read; clipboard-write; payment"
6></iframe>