Create catalog UI

There are three ways to create catalog UI:

Using own interface

When creating a directory in your own interface, you can use:

  • Own data storage and any authorization option. In this case, implement the catalog UI on your side.
  • Your own authorization and the Get Plans server method. Implement the catalog UI on your side after getting the list of plans.
  • Xsolla Login and client-side API calls.
Note
You can also use the SDK libraries to implement a catalog in your own interface. Ready-made libraries facilitate integrating Xsolla products into your project by providing out-of-the-box data structures and methods for working with Xsolla API.

Xsolla Login and client-side API calls

To implement a catalog:

  1. Get a list of subscription plans using client methods:
  2. Implement the display of the received list of plans in the interface.

Client-side method to get the subscription plans by products

On the client side of your application, use an HTTP get request to implement getting the list of plans: https://subscriptions.xsolla.com​/api/user/v1/projects/{project_id}/products/{​​productId}/plans.

The request must contain an Authorization: Bearer <client_user_jwt> header, where <client_user_jwt> is user’s JSON Web Token (JWT) — a unique, Base64-encoded token encoded according to the Base64 standard. To get the token:

Specify as the path parameters:

  • projectId — project ID. You can find this parameter in your Publisher Account next to the name of the project.
  • productID — subscription-based product ID. To get it, contact your Account Manager.

Specify as query parameters:

ParameterTypeDescription
plan_id
array of integersPlan ID.
plan_external_id
array of stringsPlan external ID. Can be found in Publisher Account in the Subscriptions > Subscription plans > your plan section or via the Get Plans API call.
limit
integerLimit for the number of elements on the page. 15 items are displayed by default.
offset
integerNumber of the element from which the list is generated. The count starts from 0 by default.
locale
stringInterface language in two-letter lowercase. Accepts ISO 639-1 values. If this parameter is not passed, the language is determined by the user’s IP address.
country
stringThe two-letter ISO 3166-1 alpha-2 designation is used to identify the user’s country. This parameter affects the choice of locale and currency. If this parameter is not passed, the country is determined by the user’s IP address.
Copy
Full screen
Small screen
    Request Example:
    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
    Response Example:
    {
      "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
    }
    

    Client-side method for getting the list of plans

    On the client side of your application, use an HTTP GET request to implement getting the list of plans: https://subscriptions.xsolla.com​/api/user/v1/projects/{project_id}/plans.

    The request must contain an Authorization: Bearer <client_user_jwt> header, where <client_user_jwt> is user’s JSON Web Token (JWT) — a unique, Base64-encoded token encoded according to the Base64 standard. To get the token:

    Specify the project ID as the projectId path parameter. You can find this parameter in your Publisher Account next to the name of the project.

    Specify as query parameters:

    ParameterTypeDescription
    plan_id
    array of integersPlan ID.
    plan_external_id
    array of stringsPlan external ID. Can be found in Publisher Account in the Subscriptions > Subscription plans > your plan section or via the Get Plans API call.
    limit
    integerLimit for the number of elements on the page. 15 items are displayed by default.
    offset
    integerNumber of the element from which the list is generated. The count starts from 0 by default.
    locale
    stringInterface language in two-letter lowercase. Accepts ISO 639-1 values. If this parameter is not passed, the language is determined by the user’s IP address.
    country
    stringThe two-letter ISO 3166-1 alpha-2 designation is used to identify the user’s country. This parameter affects the choice of locale and currency. If this parameter is not passed, the country is determined by the user’s IP address.
    Copy
    Full screen
    Small screen
      Request Example:
      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
      Response Example:
      {
        "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
      }
      

      Using Xsolla Pay Station

      The way a catalog is created in the payment UI depends on the authorization settings of your project:

      Own authorization system

      If your application uses your own authorization system:

      1. Implement getting of the token via the server Create token API call. In the request, pass the user information in the user.id and user.email parameters.
      2. Implement opening the payment UI in Pay Station Embed, iframe or new window.
      Copy
      Full screen
      Small screen
      Request Example:
      {
          "user": {
              "id": {
                  "value": "1234567",
                  "hidden": true
              }
          },
          "settings": {
              "project_id": 123456,
              "language": "en",
              "currency": "USD"
          }
      }
      

      Xsolla Login

      If Xsolla Login is set up in your project:

      On the client side of your application, use an HTTP POST request to implement opening the payment UI: https://subscriptions.xsolla.com​/api/user/v1/projects/{project_id}/subscriptions/buy.

      The request must contain an Authorization: Bearer <client_user_jwt> header, where <client_user_jwt> is user’s JSON Web Token (JWT) — a unique, Base64-encoded token encoded according to the Base64 standard. To get the token:

      Specify the project ID as the projectId path parameter. You can find this parameter in your Publisher Account next to the name of the project.

      Specify country as the query parameter — the two-letter designation of the user’s country according to the ISO 3166-1 alpha-2 standard. Affects the choice of locale and currency. If this parameter is not passed, the country is determined by the user’s IP address.

      Request body parameters:

      ParameterTypeDescription
      plan_external_id
      stringRequired. The external ID of the subscription plan. You can find it in Publisher Account > Subscriptions > Subscription Plans section.
      settings
      objectCustom project settings (object).
      settings.ui
      objectInterface settings (object).
      settings.ui.size
      stringPayment UI size. Can be:
      • small: the least possible size of the payment UI. Use this value when the window size is strictly limited (dimensions: 620 x 630 px)
      • medium: recommended size. Use this value to display the payment UI in a lightbox (dimensions: 740 x 760 px)
      • large: the optimal size for displaying the payment UI in a new window or tab (dimensions: 820 x 840 px)
      settings.ui.theme
      stringPayment UI theme. Can be default or default_dark.
      settings.ui.version
      stringDevice type. Can be desktop (default) or mobile.
      settings.ui.desktop
      objectInterface settings for the desktop version (object).
      settings.ui.desktop.header
      objectHeader settings (object).
      settings.ui.desktop.header.close_button
      booleanWhether to show a Close button in Pay Station desktop. The button closes Pay Station and redirects the user to the URL specified in the settings.return_url parameter. false by default.
      settings.ui.desktop.header.is_visible
      booleanWhether to show the header in the payment UI.
      settings.ui.desktop.header.is_visible.type
      stringHeader appearance. Can be compact (in which case the game name and user ID will not be shown in the header) or normal.
      booleanIf true, the header will show your logo (first provide the image to your account manager).
      settings.ui.desktop.header.visible_name
      booleanWhether to show the project name in the header.
      settings.ui.desktop.header.type
      stringHow to show the header. Can be compact (hides project name and user ID) or normal (default).
      settings.ui.mobile.mode
      stringA user can only pay using their saved payment methods. Can be saved_accounts.
      booleanWhether to hide the footer in the mobile version of the payment UI.
      settings.ui.mobile.header.close_button
      booleanWhether to show a Close button in Pay Station mobile. The button closes Pay Station and redirects the user to the URL specified in the settings.return_url parameter. false by default.
      settings.ui.license_url
      stringLink to the EULA.
      settings.ui.mode
      stringInterface mode in Pay Station. Can be user_account only: The header contains only the account navigation menu, and the user cannot select a product or make a payment. This mode is only available on the desktop.
      settings.ui.user_account
      objectUser account details (object).
      settings.ui.user_account.history
      objectHistory submenu.
      settings.ui.user_account.history.enable
      integerWhether the section should be displayed in the drop-down menu in the payment UI. Can be true or false. If the parameter is not passed, the section is not displayed.
      settings.ui.user_account.history.order
      integerThe location of the section in the drop-down menu in the payment interface.
      settings.ui.user_account.info
      objectPage My account.
      settings.ui.user_account.info.order
      integerThe location of the section in the drop-down menu in the payment UI.
      settings.ui.user_account.info.enable
      booleanWhether the section should be displayed in the drop-down menu in the payment UI. Can be true or false. If the parameter is not passed, the section is not displayed.
      settings.ui.user_account.payment_accounts
      objectMy payment accounts submenu.
      settings.ui.user_account.payment_accounts.order
      integerThe location of the section in the drop-down menu in the payment UI.
      settings.ui.user_account.payment_accounts.enable
      booleanWhether to show the submenu. Can be true or false. If the parameter is not passed, the section will be displayed.
      settings.ui.user_account.subscriptions
      objectManage subscriptions submenu.
      settings.ui.user_account.subscriptions.enable
      booleanWhether to show the submenu. Can be true or false. If the parameter is not passed, the section will be displayed.
      settings.ui.user_account.subscriptions.order
      integerThe location of the section in the drop-down menu in the payment UI.
      settings.currency
      stringPreferred payment currency. Three-letter currency code per ISO 4217.
      settings.external_id
      stringTransaction ID in the game. Has to be unique for each user payment.
      settings.payment_method
      integerPayment method ID. You can get the list of payment method IDs in Publisher Account or using the Get payment methods API call.
      settings.return_url
      stringPage to redirect the user to after payment. Parameters user_id, foreigninvoice, invoice_id and status will be automatically added to the link.
      settings.redirect_policy
      objectRedirect policy settings (object).
      settings.redirect_policy.redirect_conditions
      stringA payment status that redirects the user to a return URL after making a payment. Can be none, successful, successful_or_canceled, or any.
      settings.redirect_policy.delay
      integerDelay (in seconds) after which a user is automatically redirected to the return URL.
      settings.redirect_policy.status_for_manual_redirection
      stringA payment status that redirects the user to a return URL after making a payment. Can be none, successful, successful_or_canceled, or any.
      settings.redirect_policy.redirect_button_caption
      stringText on the button for manual redirection.

      Pass the additional parameters for customization if needed.

      Copy
      Full screen
      Small screen
        Request Example:
        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
          Response Example:
          {
            "link_to_ps": "https://secure.xsolla.com/paystation2/?access_token=<access_token>"
          }

          An example of displaying the subscription catalog in the Xsolla Pay Station:

          Using Xsolla Site Builder

          Xsolla Site Builder allows you to create and set up your site for subscription sales. To do this, use the Web Shop template to create a site. You can read more about setting up roles in the Web Shop with user authentication instructions.

          Your progress
          Thank you for your feedback!
          Last updated: October 13, 2022

          Found a typo or other text error? Select the text and press Ctrl+Enter.

          Report a problem
          We always review our content. Your feedback helps us improve it.
          Provide an email so we can follow up
          Thank you for your feedback!