Set up opening of the payment UI

Depending on project authentication settings, you can use one of the following to open the payment UI:

• server-side Create token API call if:
  • you use your own authorization system in your application.
  • subscription plans are set up with a subscription fee associated with the first payment in your project.
• client-side method for getting a link to open a payment UI if you use Xsolla Login in your project.

Via server-side Create token API call

1. Implement getting a token to open the payment UI in one of the following ways:
   • on payment method selection page
   • on entering payment data page
2. Implement how the payment UI is opened:
   • Pay Station Embed script
   • Iframe
   • New window

With the display of the payment method selection page

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

Example of payment method selection page:

With the display of payment data entry page

• purchase.subscription.plan_id with the ID of the selected plan.
• settings.payment_method with the payment method ID. To find the list of identifiers, in your project in Publisher Account, go to the Pay Station > Payment methods section, or request it from your Customer Success Manager.

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

Example of payment data entry page:

Via client API method

1. Implement getting a link to open the payment UI using the client API method.
2. Implement opening the payment UI in one of the following ways:
   • Pay Station Embed script
   • Iframe
   • New window

Client method for getting a link to open a payment UI

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:

• Use the Register new user and Auth by username and password API calls if your application uses login and password authorization.

• Use the Auth via social network API call if your application uses authorization through social networks.

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.

Pass the following parameters in the request:

• plan_external_id to open the payment interface on the payment method selection page.

• plan_external_id and settings.payment_method to open the payment interface on the page for entering payment data.

Request body parameters:

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

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

With Pay Station Embed

Add a script to your website page to open the payment UI widget. A full description of the script is available in the GitHub repository.

EXAMPLE: ASYNCHRONOUS SCRIPT LOADING

<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 allows getting events from the payment UI via postMessage. You can send these events to analytics systems. To set up events processing in your analytics system, contact your Customer Success Manager or email to csm@xsolla.com.

Script initialization parameters:

In an Iframe

You need to implement the following mechanisms on your side:

• Check the device type (desktop vs. mobile) and send it within the token’s settings.ui.version parameter.
• Get events from the payment UI via postMessage. You can send these events to analytics systems. To set up events processing in your analytics system, contact your Customer Success Manager or email to csm@xsolla.com.

To open the payment UI in an iframe, use the following link: https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, where ACCESS_TOKEN is the token obtained with the Create token method. You can also get a ready-made link with a token when implementing the client method for opening the payment interface.

For testing purposes, use this URL: https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN.

In a new window

To open the payment UI in a new window, use the following link: https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, where ACCESS_TOKEN is the token obtained with the Create token method. You can also get a ready-made link with a token when implementing the client method for opening the payment interface.

For testing purposes, use this URL: https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN.