How to use Pay Station in combination with PlayFab authentication

If you have already implemented user authentication in your application using PlayFab, you can generate a payment token on PlayFab side and then pass it to the client side of the application to open the payment UI.

Using this integration option, you need to independently implement the logic for determining the user’s country and currency to pay for the purchase.

Integration flow:

1. Create a project.

1. Sign up to Publisher Account and create a new project. You will need the ID of the created project in further steps.

2. Set up a catalog:
   • Create an item catalog on Xsolla side. You can add items manually or import them from Google Play or PlayFab.
   • Implement getting and displaying the catalog on the client side of the application using the SDK.

3. Set up an item purchase:
   • Create an order with user and item data on the client side of the application using the PlayFab cloud script.
   • Implement opening of the payment UI on the client side of your application using the SDK.

4. Set up an order status tracking.

Create project

Sign up to Publisher Account

Publisher Account is the main tool to configure Xsolla features, as well as to work with analytics and transactions.

The data about the company and your application specified during registration will be used to create a draft licensing agreement with Xsolla and to generate recommendations on solutions that are suitable for you. You can change the data later, but providing the correct data when you sign up will speed up the process of signing the licensing agreement.

To sign up, go to Publisher Account and create an account.

Create project in Publisher Account

If you have multiple applications, we recommend creating a separate project for each application. Based on the data specified during project creation, Xsolla generates recommendations on solutions that are suitable for you.

To create a new project:

1. Open Publisher Account.
2. In the side menu, click Create project.

3. Enter your project name in English (required).

4. Select one or several release platforms of your game (required).
5. Add a link to your game. If your game doesn’t have a website yet, add a link to the source that includes information about the game (required).
6. Select the game engine.
7. Select the monetization options you use or plan to use.
8. Specify if the game is already released. If the game hasn’t been released yet, specify the planned release date.
9. Click Create project. You will see a page with the Xsolla products recommended for you.

During the integration process, you need to provide the project ID that can be found in your Publisher Account next to the project name.

Set up catalog

Create items in Publisher Account

To add a virtual item with basic settings to the catalog:

1. Open your project in Publisher Account.
2. Click Store in the side menu.
3. In the Virtual Items pane, click Connect.
4. In the drop-down menu, select Create item.

5. Set the basic settings of the item in the following fields:
   • Image (optional)
   • SKU (item unique ID)
   • Item name
   • Description (optional)

6. Specify item price:
   1. Set the Price in real currency toggle to On.
   2. In the Default currency field, change the currency (optional) and specify the item price.
   3. If you changed the currency in the Default currency field, select the same currency in the Price in real currency field.

7. Change the item status to Available.

8. Click Create item.

Install and set up SDK

1. Download the Epic Games Launcher.
2. Create a new Unreal Engine project.

3. Download and install the SDK:
   1. To download and install the SDK from the Unreal Engine Marketplace:
      1. Go to the SDK page on the Unreal Engine Marketplace.
      2. Click Open in Launcher.

1. 1. 3. Go to Epic Games Launcher.

1. 1. 4. Click Install to Engine.
      5. Open your Unreal Engine project in Unreal Editor.
      6. Go to the Settings > Plugins > Installed > Xsolla SDK section. Check the Enabled box and click Restart Now to save settings and reload the Unreal Editor.

1. 2. To download and install the SDK from GitHub:
      1. Download the package with the SDK for your version of the engine.
      2. Unzip the package.
      3. Move the SDK folder to the plugins directory in the root of your Unreal Engine project.

4. Go to Settings > Project Settings > Plugins > Xsolla Settings > General.
5. In the Project ID field, specify the project ID that can be found in Publisher Account next to the name of your project.

Display catalog on client side of application

Create class for catalog item

1. In Content Browser, go to the Content directory.
2. Call the context menu and select Blueprint Class.

3. In the All Classes section, select Object and click Select.

4. Specify StoreItemData as the class name.
5. Open the blueprint of the created class.
6. In the My Blueprint panel, click Add New and select Variable.
7. In the Details panel:

1. 1. Specify StoreItem in the Variable Type field.
   2. Check the Instance Editable and Expose on Spawn boxes.

8. Save and close the StoreItemData blueprint.

Create widget of catalog item

1. In Content Browser, go to Content directory. Call the context menu and select User Interface > Widget Blueprint.
2. Specify StoreItem as the blueprint name.
3. Open the created blueprint.
4. In the Hierarchy panel, call the context menu for the CanvasPanel element. Select Replace With > Overlay.

5. Place the UI primitives from the Palette panel as shown below. For an item's image, title, and description, check the Is Variable box in the Details panel.

6. Open the Graph view.
7. Click Class settings.
8. In the Details panel, go to Interfaces > Implemented Interfaces.
9. Click Add and select UserObjectListEntry. This is a standard UE interface that allows the UI primitive to implement a behavior normal for the element of the list.

10. Add logic for the OnListItemObjectSet event:
    1. In the My Blueprint panel, call the context menu for the Interfaces section and select Implement event.

1. 2. Add nodes as shown below:

11. Save and close the StoreItem blueprint.

Create widget for catalog page

1. In Content Browser, go to the Content directory and select User Interface > Widget Blueprint from the context menu.
2. Specify WBP_Store as the name of the blueprint.
3. Open the created blueprint.
4. In the item display area, add the List View element and name it StoreListView.

5. In the Details panel, in the Entry Widget Class field, select the previously created class for the item (StoreItem).
6. Go to the Graph view.
7. Bind the GetVirtualItems SDK method call to the EventConstruct node, as shown in the figure below.

8. In the My Blueprint panel, click Add New and select Variable.
9. In the Details panel:
   1. In the Variable Type field, select String.
   2. Check the Instance Editable and Expose on Spawn boxes.
   3. Specify PlayFabId as the name.

10. Save and close the WBP_Store widget.
11. Add directory display logic. Below is an example of implementation of directory display after successful user authentication.

Set up item purchase

To create an order with user and item data on Xsolla side, add a cloud function to the project that uses the Create payment token for purchase API call. This call will return a payment token, which is required to open the payment UI and make a purchase.

Limitations:

• You need to pass either the user country or the user’s IP address when requesting the payment token.
• If you don’t pass the currency in the token, it is determined by the country.
• If you pass the currency in the token, the user pays in this currency.

Add cloud script to your project

1. Open Visual Studio Code and go to the Azure tab.
2. In the Workspace section, click the + icon and select Create Function.

3. Select the new project directory. A menu for creating a new project will appear with a choice of settings.

4. Specify the new project settings:
   1. Select a language for your function project — JavaScript.
   2. Select a JavaScript programming model — model V4.
   3. Select a template for your project's first function — HTTP trigger.
   4. Enter a function name — getXsollaPaymentToken.
   5. Select how you would like to open your project — Open in current window.

1. As a result, Visual Studio Code will generate a JS project and open the generated getXsollaPaymentToken.js file.

5. Modify the getXsollaPaymentToken.js file:

const { app } = require('@azure/functions');

const projectId = ""; //your xsolla project id from publisher account
const apiKey = ""; your api key from publisher account

app.http('getXsollaPaymentToken', {
    methods: ['POST'],
    authLevel: 'anonymous',
    handler: async (request, context) => {

      var body = await request.json();

      const userId = body.uid;
      const email = body.email;
      const sku = body.sku;
      const returnUrl = body.returnUrl;

        if (!userId) {
          return {status: 400, body: 'Request body is missing' };
        }

        const payload = {
            user: {
              id: {value: userId},
              name: {
                value: email
              },
              email: {
                value: email
              },
              country: {
                value: 'US',
                allow_modify: false
              }
            },
            purchase: {
              items: [
                {
                  sku: sku,
                  quantity: 1
                }
              ]
            },
            sandbox: true,
            settings: {
              language: 'en',
              currency: 'USD',
              return_url: returnUrl,
              ui: {
                theme: '63295aab2e47fab76f7708e3'
              }
            }
          }

        let url = "https://store.xsolla.com/api/v2/project/" + projectId.toString() + "/admin/payment/token";

        return fetch(
            url,
            {
                method: "POST",
                headers: {
                'Content-Type': 'application/json',
                Authorization: 'Basic ' + btoa(`${projectId}:${apiKey}`)
                },
                body: JSON.stringify(payload)
            },
            )
            .then(xsollaRes => {
            // Handle the response data
                if (xsollaRes.ok) {
                    return xsollaRes.json();
                } else {
                    return { status: 400, body: `HTTP request failed with error: ${xsollaRes.statusText}` };
                }
            })
            .then(data => {
                return { status: 200, body: JSON.stringify(data) };
            })
            .catch(error => {
                return { status: 501, body: `Error = ${error}` };
            });
        }
});

1. In the script, specify the values of the constants:

1. • PROJECT_ID — project ID that you can find in your Publisher Account next to the project name.

1. • API_KEY — API key. It is shown in Publisher Account only once when it is created and must be stored on your side. You can create a new key in the following section:
     • Company settings > API keys
     • Project settings > API keys

After adding the cloud script, you can test the call of the getXsollaPaymentToken function locally.

Deploy cloud script

1. In Visual Studio Code go to Azure > Resources section and click the + icon.
2. Select Create Function App in Azure as a resource. A menu for creating a new application will appear with a choice of settings.
3. Set application settings:

1. 1. Enter the name for the new function app — XsollaFunctions.
   2. Select a runtime stack — .NET 8 Isolated.
   3. Select a location for new resources (you can choose any option).

1. Wait until the resource group is created.

4. In the list of resources, select the XsollaFunctions, call the context menu and select Deply to Function App.

After adding the cloud script, you can test the call of the getXsollaPaymentToken function remotely.

Test cloud script

To test the cloud script (locally or remotely), call the getXsollaPaymentToken function using Postman or another tool. To do this:

1. In Visual Studio Code, go to the Azure > Workspace > Local Project > Functions section and click Start debugging to update this list.
2. Call the context menu for the function and select Copy Function Url. When testing locally, the URL will look like this — http://localhost:7071/api/getXsollaPaymentToken. When testing remotely — https://xsollafunctions.azurewebsites.net/api/GetXsollaPaymentToken.

3. Use the copied URL to call the function with the specified parameters. To call a function from Postman:
   1. Create a new GET request.
   2. Provide the URL you copied in step 2.
   3. Go to the Body tab and specify the request parameters.

Example request body:

{

 "FunctionArgument": {

   "uid": "1D384D9EF12EAB8B",

   "sku": "booster_max_1",

   "returnUrl": "https://login.xsolla.com/api/blank"

 }

}

4. Click Send. In the response you should receive JSON with the following parameters:
   • token — payment token. Required to open the payment UI.
   • order_id — ID of the created order. Required to track order status.

Example response body:

{"token":"xsnpCF8tS4ox7quoibgTgPFVFxG9gTvS_lc_en_bg_2C2640_tb_6E7BF7","order_id":90288613}

Register function for getting payment token in PlayFab

1. Open your project in PlayFab.
2. In the side menu, click Automation.
3. In the Register New Cloud Script Function. section, click Register Function.
4. Enter the name of the function — GetXsollaPaymentToken.
5. Enter the function URL that you copied into Visual Code Studio (see steps 1-2 of Test cloud script).

Create order and open payment UI in Unreal Engine project

1. Open your Unreal Engine project.
2. Open the WBP_Store widget.
3. In the Hierarchy panel, select StoreListView.
4. In the Details panel, click the + icon next to the On Clicked event.

5. Go to the Graph view.
6. Add the logic for creating a PlayfabJsonObject object and passing data to it to create an order to the OnItemClicked node, as shown below:

7. Add a call to the ExecuteFunction method. Pass the functionName = getXsollaPaymentToken and FunctionParameter = PlayfabJsonObject parameters to it.

Set up order status tracking

Tracking the order status is required to ensure that the payment was successful and to grant items to the user.

Get order status on client side

To track changes of the order status, use the CheckPendingOrder SDK method in the client part of the application. Pass the following parameters to the method:

• AuthToken — user authorization token
• OrderId — order ID received from purchase via the shopping cart, one-click purchase, or purchase for virtual currency
• SuccessCallback — callback in case the order moves to the done status
• ErrorCallback — callback in case Xsolla server returns an error

For detailed information about how the method works, refer to the Track order status section.

Get order status on server side

To configure webhooks on Xsolla side:

1. Open your project in Publisher Account.
2. Click Project settings in the side menu and go to the Webhooks section.
3. In the Webhook server field, enter the URL to which Xsolla will send webhooks.

4. Copy and save the value from the Secret key field. This key is generated by default and is used to sign webhooks. If you want to change it, click the update icon.
5. Click Enable webhooks.