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

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

• С помощью метода создания токена, если в вашем приложении используется собственная система авторизации.
• С помощью клиентских методов API, если в вашем проекте настроена Авторизация Иксолла.

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

1. Реализуйте получение токена, чтобы открыть платежный интерфейс одним из способов:
   • на странице выбора платежного метода;
   • на странице ввода платежных данных;
   • на странице управления подпиской и платежным аккаунтом.
2. Реализуйте способ открытия платежного интерфейса:
   • с помощью скрипта Pay Station Embed;
   • в iframe;
   • в новом окне.

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

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

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 с идентификатором выбранного плана.
• settings.payment_method с идентификатором платежного метода. Список идентификаторов вы можете найти в вашем проекте в Личном кабинете, в разделе Платежи > Способы оплаты или запросить у аккаунт-менеджера проекта.

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

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"
    }
  }
}'

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

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

Чтобы платежный интерфейс при открытии отображал страницу управления подписками и платежным аккаунтом, передайте в метод Создание токена параметр settings.ui.mode = user_account.

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
        }
    },
    "settings": {
      "project_id": 146026,
      "language": "en",
      "currency": "USD",
      "ui": {
          "mode": "user_account",
          "theme": "default_dark",
          "desktop": {
             "subscription_list": {
               "layout": "grid"
             }
           }
         }
    }
  }

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

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

1. Реализуйте клиентские методы для открытия платежного интерфейса одним из способов:
   • на странице выбора платежного метода или ввода платежных данных;
   • на странице управления подпиской и платежным аккаунтом.
2. Реализуйте открытие платежного интерфейса одним из способов:
   • с помощью скрипта Pay Station Embed;
   • в iframe;
   • в новом окне.

Открытие платежного интерфейса на странице выбора платежного метода или ввода платежных данных

В клиентской части вашего приложения реализуйте получение ссылки на открытие платежного интерфейса с использованием 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 и settings.payment_method для открытия платежного интерфейса на странице ввода платежных данных.

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

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

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

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
        }
      },
      "license_url": "string",
      "mode": "user_account",
      "user_account": {
        "history": {
          "enable": true,
          "order": 1
        },
        "payment_accounts": {
          "enable": true,
          "order": 1
        },
        "info": {
          "enable": true,
          "order": 1
        },
        "subscriptions": {
          "enable": true,
          "order": 1
        }
      }
    },
    "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"
    }
  }
}

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

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

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

Запрос к методу должен содержать заголовок 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-адресу пользователя.

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

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

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

curl -X 'POST' \
'https://subscriptions.xsolla.com​/api/user/v1/projects/{project_id}/subscriptions/manage?country=RU  ' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer client_user_jwt'
{
  "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
        }
      },
      "license_url": "string",
      "mode": "user_account",
      "user_account": {
        "history": {
          "enable": true,
          "order": 1
        },
        "payment_accounts": {
          "enable": true,
          "order": 1
        },
        "info": {
          "enable": true,
          "order": 1
        },
        "subscriptions": {
          "enable": true,
          "order": 1
        }
      }
    },
    "currency": "str",
    "locale": "st",
    "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"
    }
  }
}

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

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

Кастомизация

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

• Изменить стандартную светлую тему интерфейса на темную, передав в метод Создание токена или клиентский метод для открытия платежного интерфейса параметр settings.ui.theme = default_dark. Если параметр не передается, по умолчанию используется светлая тема.

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

Пример запроса на получение токена для темной темы:

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"
    "ui": {
       "theme": "default_dark"
    }
  }
}
'

• Разместить собственное описание раздела планов. Для этого передайте текст описания в метод Создание токена в параметре ui.desktop.subscription_list.description.

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

Пример запроса на получение токена для светлой темы с разделом управления подписками и описанием раздела планов:

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",
    "ui": {
       "desktop": {
         "subscription_list": {
           "description": "Your Description"
         }
       },
        "user_account": {
          "subscriptions": {
              "order": 1,
              "enable": true
          }
        }
      }
    }
}
'

• Изменить стандартное отображение списка подписок на альтернативное в виде блоков. Для этого передайте в метод Создание токена параметр settings.ui.desktop.subscription_list.layout = grid. По умолчанию параметр принимает значение list.

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

Пример запроса на получение токена для альтернативного отображения списка подписок:

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": 111111,
    "currency": "USD",
    "ui": {
       "desktop": {
         "subscription_list": {
           "layout": "grid"
         }
       }
    }
  }
}
'

Больше информации о кастомизации и используемых для этого параметрах вы можете прочитать в инструкции Как кастомизировать платежный интерфейс.

С помощью Pay Station Embed

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

<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.

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

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

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

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

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

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

В 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.