Subscriptions / Настройка открытия платежного интерфейса

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

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

Внимание
Так как клиентский метод получения ссылки на открытие платежного интерфейса не позволяет управлять ценами на своей стороне и устанавливать стоимость подписки для конкретного пользователя, не используйте его для продажи подписки с ценой, равной сумме первого платежа.
Примечание
Если вы хотите разрешить пользователю смену плана в проекте, для настройки корректной работы платежного интерфейса обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.

С помощью серверного метода создания токена

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

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

Чтобы платежный интерфейс при открытии отображал страницу выбора платежного метода, передайте в метод Создание токена параметр purchase.subscription.plan_id с ID плана подписки, выбранного пользователем. При необходимости передайте дополнительные параметры для кастомизации платежного интерфейса.
Примечание
Если в проекте настроены планы с ценой, равной сумме первого платежа, дополнительно передайте параметры:
  • purchase.checkout.amount со значением стоимости плана подписки;
  • purchase.checkout.currency со значением валюты.
Copy
Full screen
Small screen
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",
      "hidden": true
    },
    "email": {
      "value": "user1234@game1234.com"
    },
    "name": {
      "value": "UserName",
      "hidden": false
    }
  },
  "settings": {
    "project_id": 12345,
    "currency": "USD"
  },
  "purchase": {
    "subscription": {
      "plan_id": "54321"
    }
  }
}'

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

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

Для того чтобы платежный интерфейс при открытии отображал страницу ввода платежных данных, передайте в метод Создание токена параметры:
  • purchase.subscription.plan_id с ID выбранного плана.
  • settings.payment_method с ID платежного метода. Список ID вы можете найти в проекте в Личном кабинете, в разделе Pay Station > Способы оплаты или запросить у персональному менеджеру проекта.
Примечание
Если в проекте настроены планы с ценой, равной сумме первого платежа, дополнительно передайте параметры:
  • purchase.checkout.amount со значением стоимости плана подписки;
  • purchase.checkout.currency со значением валюты.
При необходимости передайте дополнительные параметры для кастомизации платежного интерфейса.
Copy
Full screen
Small screen
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",
      "hidden": true
    },
    "email": {
      "value": "user1234@game1234.com"
    },
    "name": {
      "value": "UserName",
      "hidden": false
    }
  },
  "settings": {
    "project_id": 12345,
    "payment_method": 1380,
    "currency": "USD"
  },
  "purchase": {
    "subscription": {
      "plan_id": "54321"
    }
  }
}'

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

С помощью клиентского метода API

  1. Реализуйте получение ссылки на открытие платежного интерфейса с помощью клиентского метода API.
  2. Реализуйте открытие платежного интерфейса одним из способов:

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

В клиентской части вашего приложения реализуйте получение ссылки на открытие платежного интерфейса с использованием HTTP POST-запроса https://subscriptions.xsolla.com​/api/user/v1/projects/{project_id}/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
stringОбязательный. Внешний ID плана подписки. Вы можете найти этот параметр в Личном кабинете в разделе Subscriptions > Планы подписки.
settings
objectОбъект, содержащий настройки проекта.
settings.ui
objectОбъект с настройками интерфейса.
settings.ui.theme
stringВнешний вид интерфейса оплаты. Может принимать значения default (по умолчанию), default_dark или значение ID кастомизированной темы.
settings.ui.version
stringТип устройства. Может принимать значения desktop (по умолчанию) или mobile.
settings.ui.desktop
objectОбъект с данными настроек для desktop-версии.
settings.ui.desktop.header
objectОбъект с настройками header.
settings.ui.desktop.header.close_button
booleanПоказывать ли кнопку Закрыть в настольной версии платежного интерфейса. Нажатие на кнопку закрывает платежный интерфейс и перенаправляет пользователя на адрес, указанный в параметре settings.return_url. false по умолчанию.
settings.ui.desktop.header.is_visible
booleanДолжен ли хедер отображаться на странице оплаты.
settings.ui.desktop.header.type
stringВнешний вид хедера. Может принимать значения compact (в этом случае название игры и ID пользователя не будут показываться в хедере) или normal.
booleanЕсли значение true, то логотип будет отображаться в header (необходимо сначала прислать файл с логотипом вашему персональному менеджеру).
settings.ui.desktop.header.visible_name
booleanДолжно ли название игры отображаться в хедере.
settings.ui.desktop.header.type
stringВнешний вид хедера. Может принимать значения compact (в этом случае название игры и ID пользователя не будут показываться в хедере) или normal.
settings.ui.mobile.header.close_button
booleanПоказывать ли кнопку Закрыть в мобильной версии платежного интерфейса. Нажатие на кнопку закрывает платежный интерфейс и перенаправляет пользователя на адрес, указанный в параметре settings.return_url. false по умолчанию.
settings.ui.mode
stringПлатежный интерфейс в режиме Личного кабинета. Принимает значение user_account. Хедер содержит только навигационное меню Личного кабинета; исключается возможность выбора предмета и оплата покупки; режим Личного кабинета доступен только в desktop-режиме.
settings.currency
stringПредпочтительная валюта платежа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
settings.external_id
stringID транзакции в игре. Должен быть уникальным для каждого платежа пользователя.
settings.payment_method
integerID способа оплаты. Список ID способов оплаты можно получить в Личном кабинете.
settings.return_url
stringПользователь будет перенаправлен на данную страницу после совершения платежа. Параметры user_id, foreigninvoice, invoice_id и status будут автоматически добавлены к ссылке.
settings.redirect_policy
objectНастройки политики редиректа (объект).
settings.redirect_policy.redirect_conditions
stringСтатус платежа, при котором пользователь перенаправляется на URL-адрес возврата после совершения платежа. Принимает значение none, successful, successful_or_canceled или any.
settings.redirect_policy.delay
integerЗадержка (в секундах), после которой пользователь автоматически перенаправляется на return URL.
settings.redirect_policy.status_for_manual_redirection
stringСтатус платежа, при котором пользователь перенаправляется на URL-адрес возврата после совершения платежа. Принимает значение none, successful, successful_or_canceled или any.
settings.redirect_policy.redirect_button_caption
stringТекст кнопки для ручного перенаправления.
При необходимости передайте дополнительные параметры для кастомизации платежного интерфейса.
Copy
Full screen
Small screen
curl -X 'POST' \
'https://subscriptions.xsolla.com/api/user/v1/projects/{project_id}/subscriptions/buy?country=RU  ' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer client_user_jwt'

  {
    "plan_external_id": "PlanExternalId",
    "settings": {
      "ui": {
        "size": "large",
        "theme": "string",
        "version": "desktop",
        "desktop": {
          "header": {
            "is_visible": true,
            "visible_logo": true,
            "visible_name": true,
            "type": "compact",
            "close_button": true
          }
        },
        "mobile": {
          "mode": "saved_accounts",
          "footer": {
            "is_visible": true
          },
          "header": {
            "close_button": true
          }
        },
        "mode": "user_account"
        }
      },
      "currency": "string",
      "locale": "string",
      "external_id": "string",
      "payment_method": 1,
      "return_url": "string",
      "redirect_policy": {
        "redirect_conditions": "none",
        "delay": 0,
        "status_for_manual_redirection": "none",
        "redirect_button_caption": "string"
      }
    }
Copy
Full screen
Small screen
    {
      "link_to_ps": "https://secure.xsolla.com/paystation2/?access_token=<access_token>"
    }
    

    С помощью Pay Station Embed

    На страницу вашего сайта добавьте скрипт для открытия виджета платежного интерфейса. Полное описание скрипта доступно в проекте на GitHub.

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

    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 события платежного интерфейса, которые вы можете отправлять в систему аналитики. Чтобы узнать, как настроить обработку событий в вашей системе аналитики, обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.

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

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

    В Iframe

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

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

    Для открытия платежного интерфейса в iframe используйте ссылку https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, где ACCESS_TOKEN — токен, полученный с помощью метода Создание токена. Готовую ссылку с токеном вы также можете получить при реализации клиентского метода для открытия платежного интерфейса.

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

    В новом окне

    Для открытия платежного интерфейса в новом окне используйте ссылку https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, где ACCESS_TOKEN — токен, полученный с помощью метода Создание токена. Готовую ссылку с токеном вы также можете получить при реализации клиентского метода для открытия платежного интерфейса.

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

    Была ли статья полезна?
    Спасибо!
    Что может сделать страницу еще лучше? Сообщение
    Жаль, что так произошло
    Расскажите, почему статья не была полезна. Сообщение
    Спасибо за обратную связь!
    Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.
    Последнее обновление: 30 сентября 2024

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

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