Создание каталога

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

В собственном интерфейсе

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

Примечание
При реализации каталога в собственном интерфейсе вы можете также использовать библиотеки SDK. Применение готовых библиотек позволяет упросить интеграцию продуктов Иксоллы в ваш проект, предоставляя готовые структуры данных и методы для работы с API Иксоллы.

Авторизация Иксолла и клиентские методы

Для реализации каталога:

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

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

В клиентской части вашего приложения реализуйте получение списка планов по продукту с использованием HTTP GET-запроса https://subscriptions.xsolla.com​/api/user/v1/projects/{project_id}/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 продукта подписки. Для его получения обратитесь к аккаунт-менеджеру проекта.

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

ПараметрТипОписание
plan_id
array of integersID рекуррентного плана.
plan_external_id
array of stringsВнешний идентификатор плана. Вы можете найти этот параметр в вашем проекте в Личном кабинете в разделе Подписки > Планы подписки > ваш план или с помощью метода Список планов.
limit
integerЛимит количества элементов на странице. По умолчанию отображается 15 элементов.
offset
integerНомер элемента, с которого выполняется вывод на странице. По умолчанию нумерация начинается с 0.
locale
stringЯзык интерфейса в двухбуквенном обозначении согласно стандарту ISO 639-1. Если параметр не передается, язык определяется по IP-адресу пользователя.
country
stringСтрана пользователя в двухбуквенном обозначении согласно стандарту ISO 3166-1 alpha-2. Влияет на выбор языка интерфейса и валюты. Если параметр не передается, страна определяется по IP-адресу пользователя.
Copy
Full screen
Small screen

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

    Copy
    Full screen
    Small screen

    {
      "items": [
        {
          "plan_id": 54321,
          "plan_external_id": "PlanExternalId",
          "plan_group_id": "TestGroupId",
          "plan_type": "all",
          "plan_name": "Localized plan name",
          "plan_description": "Localized plan description",
          "plan_start_date": "2021-04-11T13:51:02+03:00",
          "plan_end_date": "2031-04-11T13:51:02+03:00",
          "trial_period": 7,
          "period": {
            "value": 1,
            "unit": "month"
          },
          "charge": {
            "amount": 4.99,
            "setup_fee": 0.99,
            "currency": "USD"
          },
          "promotion": {
            "promotion_charge_amount": 3.99,
            "promotion_remaining_charges": 3
          }
        }
      ],
      "has_more": false
    }
    

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

    В клиентской части вашего приложения реализуйте получение списка планов по продукту с использованием HTTP GET-запроса https://subscriptions.xsolla.com​/api/user/v1/projects/{project_id}/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 проекта. Вы можете найти этот параметр в Личном кабинете рядом с названием проекта.

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

    ПараметрТипОписание
    plan_id
    array of integersID рекуррентного плана.
    plan_external_id
    array of stringsВнешний идентификатор плана. Вы можете найти этот параметр в вашем проекте в Личном кабинете в разделе Подписки > Планы подписки > ваш план или с помощью метода Список планов.
    limit
    integerЛимит количества элементов на странице. По умолчанию отображается 15 элементов.
    offset
    integerНомер элемента, с которого выполняется вывод на странице. По умолчанию нумерация начинается с 0.
    locale
    stringЯзык интерфейса в двухбуквенном обозначении согласно стандарту ISO 639-1. Если параметр не передается, язык определяется по IP-адресу пользователя.
    country
    stringСтрана пользователя в двухбуквенном обозначении согласно стандарту ISO 3166-1 alpha-2. Влияет на выбор языка интерфейса и валюты. Если параметр не передается, страна определяется по IP-адресу пользователя.
    Copy
    Full screen
    Small screen

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

      Copy
      Full screen
      Small screen

      {
        "items": [
          {
            "plan_id": 54321,
            "plan_external_id": "PlanExternalId",
            "plan_group_id": "TestGroupId",
            "plan_type": "all",
            "plan_name": "Localized plan name",
            "plan_description": "Localized plan description",
            "plan_start_date": "2021-04-11T13:51:02+03:00",
            "plan_end_date": "2031-04-11T13:51:02+03:00",
            "trial_period": 7,
            "period": {
              "value": 1,
              "unit": "month"
            },
            "charge": {
              "amount": 4.99,
              "setup_fee": 0.99,
              "currency": "USD"
            },
            "promotion": {
              "promotion_charge_amount": 3.99,
              "promotion_remaining_charges": 3
            }
          }
        ],
        "has_more": false
      }
      

      В платежном интерфейсе Иксолла

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

      Собственная система авторизации

      Если в вашем приложении используется собственная система авторизации:

      1. Реализуйте получение токена с помощью серверного метода Создание токена. В запросе к методу передайте информацию о пользователе в параметрах user.id и user.email.
      2. Реализуйте открытие платежного интерфейса в Pay Station Embed, iframe или в новом окне.
      Copy
      Full screen
      Small screen

      {
          "user": {
              "id": {
                  "value": "1234567",
                  "hidden": true
              }
          },
          "settings": {
              "project_id": 123456,
              "language": "en",
              "currency": "USD"
          }
      }
      

      Авторизация Иксолла

      Если в вашем проекте настроена Авторизация Иксолла:

      В клиентской части вашего приложения реализуйте получение ссылки на открытие платежного интерфейса с использованием 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
      stringОбязательный. Внешний ID плана подписки. Вы можете найти этот параметр в Личном кабинете в разделе Подписки > Планы подписки.
      settings
      objectОбъект, содержащий настройки проекта.
      settings.ui
      objectОбъект с настройками интерфейса.
      settings.ui.size
      stringРазмер платежного интерфейса. В зависимости от требуемых размеров платежного интерфейса параметр может принимать следующие значения:
      • small: Наименьший размер платежного интерфейса. Используется в случаях, когда размеры окна строго ограничены (размер: 620 x 630 px).
      • medium: Рекомендуемый размер платежного интерфейса. Оптимален при открытии в lightbox (размер: 740 x 760 px).
      • large: Желательно открывать в новом окне/вкладке (размер: 820 x 840 px).
      settings.ui.theme
      stringВнешний вид интерфейса оплаты. Может принимать значения default (по умолчанию) или default_dark.
      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.is_visible.type
      stringВнешний вид хедера. Может принимать значения compact (в этом случае название игры и ID пользователя не будут показываться в хедере) или normal.
      booleanЕсли значение true, то логотип будет отображаться в хедере. Для добавления логотипа отправьте его аккаунт-менеджеру проекта.
      settings.ui.desktop.header.visible_name
      booleanДолжно ли название игры отображаться в хедере.
      settings.ui.desktop.header.type
      stringВнешний вид хедера. Может принимать значения compact (в этом случае название игры и ID пользователя не будут показываться в хедере) или normal.
      settings.ui.mobile.mode
      stringПользователь может совершить платеж только через сохраненные способы оплаты. Принимает значение saved_accounts.
      booleanСкрывать или нет footer в мобильной версии платежного интерфейса.
      settings.ui.mobile.header.close_button
      booleanПоказывать ли кнопку Закрыть в мобильной версии платежного интерфейса. Нажатие на кнопку закрывает платежный интерфейс и перенаправляет пользователя на адрес, указанный в параметре settings.return_url. false по умолчанию.
      settings.ui.license_url
      stringСсылка на лицензионное соглашение.
      settings.ui.mode
      stringПлатежный интерфейс в режиме Личного кабинета. Принимает значение user_account. Хедер содержит только навигационное меню Личного кабинета; исключается возможность выбора предмета и оплата покупки; режим Личного кабинета доступен только в desktop-режиме.
      settings.ui.user_account
      objectОбъект с данными об аккаунте пользователя.
      settings.ui.user_account.history
      objectРаздел История.
      settings.ui.user_account.history.enable
      integerДолжен ли раздел отображаться в раскрывающемся меню в платежном интерфейсе. Может принимать значения true или false. Если параметр не передается, раздел будет отображаться.
      settings.ui.user_account.history.order
      integerРасположение раздела в раскрывающемся меню в платежном интерфейсе.
      settings.ui.user_account.info
      objectСтраница Мой аккаунт.
      settings.ui.user_account.info.order
      integerРасположение раздела в раскрывающемся меню в платежном интерфейсе.
      settings.ui.user_account.info.enable
      booleanДолжен ли раздел отображаться в раскрывающемся меню в платежном интерфейсе. Может принимать значения true или false. Если параметр не передается, раздел будет отображаться.
      settings.ui.user_account.payment_accounts
      objectСтраница Мои платежные аккаунты.
      settings.ui.user_account.payment_accounts.order
      integerРасположение раздела в раскрывающемся меню в платежном интерфейсе.
      settings.ui.user_account.payment_accounts.enable
      booleanДолжен ли раздел отображаться в раскрывающемся меню в платежном интерфейсе. Может принимать значения true или false. Если параметр не передается, раздел будет отображаться.
      settings.ui.user_account.subscriptions
      objectСтраница Управление подписками.
      settings.ui.user_account.subscriptions.enable
      booleanДолжен ли раздел отображаться в раскрывающемся меню в платежном интерфейсе. Может принимать значения true или false. Если параметр не передается, раздел будет отображаться.
      settings.ui.user_account.subscriptions.order
      integerРасположение раздела в раскрывающемся меню в платежном интерфейсе.
      settings.currency
      stringПредпочтительная валюта платежа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
      settings.external_id
      stringИдентификатор транзакции в игре. Должен быть уникальным для каждого платежа пользователя.
      settings.payment_method
      integerID способа оплаты. Список идентификаторов способов оплаты можно получить в Личном кабинете или с помощью метода API Список способов оплаты.
      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
                }
              },
              "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"
            }
          }
        }

        Copy
        Full screen
        Small screen

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

          Пример отображения каталога подписок в платежном интерфейсе Иксолла:

          В Конструкторе сайтов Иксолла

          В Конструкторе сайтов вы можете создать и настроить свой сайт для продажи подписок. Для этого создайте сайт с помощью шаблона Веб-магазин. Подробнее о настройке вы можете прочитать в инструкции Веб-магазин с аутентификацией пользователя.

          Прогресс интеграции
          Спасибо за обратную связь!
          Последнее обновление: 14 февраля 2023

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

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