Unreal Engine SDKs

Overview

Use Unreal Engine SDKs to integrate Xsolla products with your UE4 projects.

System Requirements

  • 64-bit OS
  • Windows 7 and higher
  • macOS 10.13.6 and higher
  • XCode 10.1 and higher (for macOS)
  • Visual Studio 2017 and higher
  • Unreal Engine 4.24 and higher

Target OS

  • iOS
  • Android
  • Linux
  • macOS
  • Windows 32-bit
  • Windows 64-bit

Integration Options

The following integration options are available:

  • Integration with Xsolla servers is suitable for partners who want to use a ready-made server solution for monetization and in-game items management.
  • Integration with your server side is suitable for partners who want to use Xsolla Pay Station with their own authentication method, in-game store, and player’s inventory.
  • Integration with third-party service servers is suitable for partners who already use third-party solutions to implement the server side, but want to use Xsolla Pay Station. Currently, Xsolla provides integration with PlayFab services.
  • Serverless or simplified integration is suitable for partners who want to use Xsolla Pay Station for in-game purchases, but their games have no server part and game logic is implemented on the client side.

Integrating with Xsolla servers is suitable for partners who want a ready-made server solution for monetization and in-game items management.

After integration of Xsolla SDKs, you can use:

With this integration, all operations are processed on the Xsolla side and you do not have to configure your own server side for these tasks.

To integrate the Xsolla products mentioned above, installing and configuring the Store SDK is enough because it contains all the necessary methods. The Login SDK can be downloaded and used separately from the Store SDK to implement only Xsolla Login functions in your application.

Privacy Policy

If you use the SDK, add the Xsolla Privacy Policy Agreement link to your application. You can see the example of this link in the demo project on the sign up page.

Note: Note that the Xsolla Privacy Policy Agreement doesn’t mean user data will be used. If you plan to collect and process this kind of data, make sure that your actions comply with the law. You should ask users for their permission to collect and process their data or inform them about the Privacy Policy Agreement.

Charge Policy

Xsolla offers the necessary tools to help you build and grow your gaming business, including personalized support at every stage. The terms of payment are determined by the contract that can be signed via Publisher Account.

The cost of using all Xsolla products is 5% of the amount you receive for the sale of the game and in-game goods via the Xsolla Pay Station. If you do not use the Xsolla Pay Station in your application, but use other products, contact your Account Manager to clarify the terms and conditions.

Prerequisites

Before integrating Unreal Engine SDKs, follow these steps:

  1. Install the plugin.
  2. Set up the project in your Publisher Account.

Install the Plugin

  1. Download the Epic Games Launcher.
  2. Create a new UE4 project.
  3. Download the plugin from the Unreal Engine Marketplace or GitHub.

After installing the plugin, launch the Demo_Login, Demo_Store and Demo demo maps, that show how SDKs features work.

Set Up the Project in Your Publisher Account

  1. Register an Xsolla Publisher Account.
  2. Configure a Publisher Account project that is automatically created after the previous step:
    1. Click My game in the Projects block and go to Project settings.
    2. In setup mode, specify a Project name and click Save.

    1. Go to Integration settings and check that the Integrate new Store management methods toggle is set to On.

During the integration process, you will need the following parameters:

  • Project ID found in Project settings > Project ID.

  • Login ID found in Login settings > Login ID. It has the UUID format.

Login UE4 SDK

The Login UE4 SDK is used to integrate Xsolla Login API methods with apps based on Unreal Engine. Main features:

  • authenticating via username and password
  • signup
  • email confirmation
  • password reset
  • authenticating via Steam session_ticket
  • authenticating via Steam account by opening a login form in the in-game browser
  • managing user attributes
  • cross-platform account linking

Note: To enable cross-platform account linking, email the Xsolla integration team (integration@xsolla.com). Follow the instructions below to try account linking in the demo.

The solution works for:

  • user data storing at Xsolla’s side
  • authentication via email or username and password
  • authentication via Steam

Demo

The integration demo is available in the Content Browser > Content > Maps folder. Use it as an example.

By default, the demo uses the Xsolla Login ID of a preset Publisher Account project.

Default values for the Demo_Login map:

  • Login ID: e6dfaac6-78a8-11e9-9244-42010aa80004
  • Username: xsolla
  • Email: support@xsolla.com
  • Password: xsolla

Integration

To integrate the Login UE4 SDK:

  1. Set up Login in your Publisher Account. You will need a Login ID, found in Login settings > Login ID. It has the UUID format.
  2. Set up the plugin for your UE4 project.

Set Up Login in Publisher Account

  1. Go to your project and click Connect in the Login block. You can go to the Login settings from any section of Publisher Account by clicking the Login button in the left-hand-side menu.

  1. Go to Login projects and click Set up Login.

  1. Specify a Login name and click Create.

  1. Go to General settings > URL block and specify the Callback URL that the user is redirected to after the email confirmation or password reset.
  2. Select the Xsolla storage in the User data storage block.

Set Up the Plugin for Your UE4 Project

  1. Open your UE project in Unreal Editor.
  2. For Blueprint projects only:
    1. Compile your UE project.
    2. Go to the Content Browser and add a New C++ Class with the None parent node.
  3. Go to Settings > Plugins > Installed > Xsolla Store SDK, check the Enabled box and click the Restart Now button to save settings and reload the Unreal Editor.
  4. Go to Settings > Project Settings > Plugins > Xsolla Login and fill in the Project ID found in Publisher Account > Project settings > Project ID, and the Login ID found in Publisher Account > Login settings > Login ID which has the UUID format.

  1. Go to Content Browser > View Options and check the Show Engine Content and Show Plugin Content boxes.

  1. Go to Content Browser > Content > Maps and launch the Demo_Login map of the game.

  1. Create a new user and check for the confirmation email.

  1. Log in as a new user and change the password if necessary.

You can customize the integration demo settings if needed:

Info: To modify the SDK for your application specifics, follow the SDK modification instruction.

Store UE4 SDK

The Xsolla Store UE4 SDK is used to integrate Xsolla Store API methods with apps based on Unreal Engine.

The solution works for:

  • selling virtual items
  • managing your in-game store
  • managing user inventory
  • managing virtual currencies

Before using the plugin, you need to set up Store and Login modules in your Publisher Account.

Demo

The integration demo is available in the Content Browser > Content > Maps folder. Use it as an example.

By default, the demo uses the Xsolla Project ID and Login ID of a preset Publisher Account project that has a fully configured store.

Default values for the Demo_Store map:

  • Login ID: e6dfaac6-78a8-11e9-9244-42010aa80004
  • Username: xsolla
  • Email: support@xsolla.com
  • Password: xsolla
  • Project ID: 44056

Integration

To integrate the Store UE4 SDK:

  1. Set up Login in your Publisher Account or implement your own authorization system using the Pay Station Access Token.
  2. Set up the Virtual Currency module in Publisher Account (optional).
  3. Set up the Virtual Items module in your Publisher Account.
  4. Set up the plugin for your UE4 project.

After the integration is complete, test the payment process.

Set Up the Virtual Currency Module in Publisher Account

Note: The SDK supports purchasing of virtual items for virtual currency. Also, the users are able to use virtual currency according to in-game logics (getting access to a location, getting progression levels, etc.). Users spend virtual currency when calling a Consume Item API method.

To set up the Virtual Currency module in Publisher Account:

  1. Open your project and click Connect in the Store block. You can go to the Store settings from any section of Publisher Account by clicking the Store button in the left-hand-side menu.

  1. Click Connect in the Virtual Currency block.

  1. Create virtual currency:
    1. Click Create virtual currency.

    1. Specify the following information:
      • SKU
      • currency name
      • price of one unit of virtual currency
      • default currency
      • features of hard virtual currency (optional)
      • image (optional)
    2. Click Create currency.

  1. Create packages of virtual currency:
    1. Go to Packages.
    2. Click Create package.

    1. Specify the following information:
      • SKU
      • package name
      • short description
      • virtual currency
      • quantity of currency units in a package
      • price
      • default currency
      • image (optional)

  1. Set the Show in Store toggle to On.
  2. Click Create package.

Set Up the Virtual Items Module in Your Publisher Account

The SDK supports the following types of items:

  • Consumable item – an item in the inventory that can be accrued or purchased repeatedly and decreases in its number once used. The item stock can be replenished. Example: grenades and bullets to attack the opponents, first aid kits, etc.
  • Nonconsumable – an item in the inventory that can be accrued or purchased only once and does not disappear from the inventory. Example: access to a location, status, etc.
  • Non-renewing subscription – a nonconsumable item that is available for a limited period of time and disappears from the inventory when it expires. For example: premium access or season access. See the non-renewing subscriptions recipe for more details.

To set up the Virtual Items module in your Publisher Account:

  1. Open your project and click Open in the Store block. If you haven’t connected Store yet, click Connect in the Store block.

  1. Click Connect in the Virtual Items block.

  1. Click Create a group.

  1. Specify Group code and Group name, turn on the group display in Store. Click Create group.

  1. Create items:
    1. Specify the following info for each of them:
      • one or more groups that the item should belong to
      • SKU
      • name and a short description
      • prices in real and virtual currencies
      • image (optional)

    1. In the Item property field of the Preferences section, select one of the following properties depending on the type of item:
      • consumable
      • nonconsumable
      • non-renewing subscription

  1. Make sure that the group status is Enabled.

Set Up the Plugin for Your UE4 Project

  1. Open your UE project in Unreal Editor.
  2. For Blueprint projects only:
    1. Compile your UE project.
    2. Go to the Content Browser and add a New C++ Class with the None parent node.
  3. Go to Settings > Plugins > Installed > Xsolla Store SDK, check the Enabled box and click the Restart Now button to save settings and reload the Unreal Editor.
  4. Go to Settings > Project Settings > Plugins > Xsolla Login and fill in the Login ID and to Settings > Project Settings > Plugins > Xsolla Store and fill in the Project ID.

  1. Go to Content Browser > View Options and check the Show Engine Content and Show Plugin Content boxes.

  1. Go to Content Browser > Content > Maps and launch the Demo_Store map of the game.

  1. Create a new user. Check for the confirmation email.

  1. Log in as a new user and change the password if necessary.

You can customize the integration demo settings if needed:

Info: To modify the SDK for your application specifics, follow the SDK modification instruction.

Test the Payment Process

After successful configuring the plugin, test the payment process. By default, all payments are in sandbox mode for any users. Use a test bank card to simulate a successful payment process.

Test the payment process by making real payments:

  • Make sure that you have signed a contract with Xsolla.
  • In your UE project, uncheck the Sandbox box in Settings > Project Settings > Plugins > Xsolla Store.

Note: After the first real payment is made, a strict sandbox payment policy takes effect. A payment in the sandbox mode is available only to users who are specified in Publisher Account > Company settings > Users.

How to Try Account Linking in Demo

You can implement the following features by linking a player’s account on different platforms to the main account:

  • automatic player identification on different platforms
  • manage a single cross-platform inventory on different platforms

Use demo maps to check the linking of platform accounts to the main account for a preset Publisher Account project.

Info: You can link only one account of each platform to the main account.

To try account linking in a demo project:

  1. Go to your UE project in Unreal Editor.
  2. Set up the demo map to log in to the application via the platform account:
    1. Go to Settings > Project Settings > Plugins > Xsolla Login. Enable the Use Cross-Platform Account Linking option. Specify Platform and Platform Account ID.
    2. Go to Settings > Project Settings > Plugins > Xsolla Store. Enable the Use Cross-Platform Account Linking option. Select the same Platform as in Xsolla Login.

  1. Start the Demo demo map from the Content Browser > Xsolla Content > Maps folder. The demo simulates authentication via the platform account, so you automatically authenticate and proceed to the in-game store.

  1. Click Account linking in the demo map. The demo project will open in the default browser to simulate the start of the application on another platform.

  1. Click Create an account.

  1. Specify email and password. Click Accept and create.

  1. Select an item in the catalog and click Buy on Xsolla. Purchase the item using one of the test bank cards. Close the receipt.

  1. Click on the email at the top of the screen to open the menu. Click Inventory. Make sure that the purchased item is available in the inventory.

  1. Click Get code. Click Request the code in the opened window. Write down the received account linking code.

  1. Go to the UE demo map.
  2. Enter the received account linking code (see step 9) and click Confirm.
  3. Now the platform account is linked to the main account. Make sure that the purchased item is available in the inventory of the demo map.

  1. Since this account is already linked to the main account, you can get the account linking code from it. Click Get linking code. Write down the received code.

  1. Set up the demo map to log in to the application via another platform account (see step 2). The Publishing platform should be different from the one selected in step 2.
  2. Start the Demo demo map from the Content Browser > Xsolla Content > Maps folder.

  1. Make sure the player’s inventory is empty.
  2. Click Account linking. Stay in the UE demo map.

  1. Enter the received account linking code (see step 13) and click Confirm.

  1. Now the account from the new platform is also linked to the main account. Make sure that the purchased item is available in the inventory of the UE demo map.

Follow the recipe to configure account linking for your project.

How to Set Up OAuth 2.0 Authentication

OAuth 2.0 uses short-lived tokens with long-term authorization (refresh tokens) instead of long-lived tokens. A refresh token allows users to stay in your application for an extended period of time without needing to re-enter their username and password. This eliminates the risk of compromising user authentication data.

Set up OAuth 2.0 for authorization:

  • via username or email and password
  • via social networks
  • via Steam

If the option is enabled, user registration and authentication is carried out by calling the Register a New User and JWT Auth by Username and Password API methods. The Login UE4 SDK provides the same methods for OAuth 2.0 authorization as for JWT token authorization. In the FXsollaAuthToken structure, the refresh token is specified in the RefreshToken field.

Note: Enabling this setting doesn’t change the authentication process in your application for the user.

To configure OAuth 2.0 authorization:

  1. Set up OAuth 2.0 authentication for Login project in your Publisher Account.
  2. Set up plugin in your UE4 project.

Set Up OAuth 2.0 Authentication for Login Project in Your Publisher Account

  1. Go to your Publisher Account.
  2. Click Open in the Login block and go to Login projects.
  3. Click Open and set up in the Login project block.
  4. Go to General settings > Authorization.
  5. Click Connect in the OAuth 2.0 authentication block.
  6. Specify OAuth 2.0 redirect URIs and click Connect.
  7. Copy and save the Client ID.

Set Up Plugin in Your UE4 Project

  1. Open your UE project in Unreal Editor.
  2. Go to Settings > Project Settings > Plugins > Xsolla Login.
  3. Enable Use OAuth 2.0 option.
  4. In the Client ID field, specify Client ID received when setting up OAuth 2.0 in Publisher Account.

The following methods are implemented in Login UE4 SDK to work with refresh tokens:

  • RefreshToken — refreshes the token if it has expired.
  • ExchangeAuthenticationCodeToToken — exchanges the user's authentication code for a valid JWT.

The State parameter found in the RegisterUser, GetSocialAuthenticationUrl, and AuthenticateWithSessionTicket methods is used for additional user verification during OAuth 2.0 authentication. This parameter is used to mitigate possible CSRF attacks.

How to Set Up Native Authentication via Steam

Native authentication allows players to enter your application via the installed Steam application.

To set up native authentication:

  1. Configure your UE4 project.
  2. Configure the processing of events.
  3. Ensure authentication via Steam.

Configure Your UE4 Project

  1. Go to the Config catalog of your UE4 project.
  2. Add the lines below to the DefaultEngine.ini file and specify your app ID in Steam for the SteamDevAppId parameter.

Copy
Full screen
Small screen
[/Script/Engine.GameEngine]
+NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="OnlineSubsystemSteam.SteamNetDriver",DriverClassNameFallback="OnlineSubsystemUtils.IpNetDriver")

[OnlineSubsystem]
DefaultPlatformService=Steam

[OnlineSubsystemSteam]
bEnabled=true
SteamDevAppId=480

[/Script/OnlineSubsystemSteam.SteamNetDriver]
NetConnectionClassName="OnlineSubsystemSteam.SteamNetConnection"

  1. Open the project in the Unreal Editor.
  2. Go to Settings > Plugins > Online Platform.
  3. In the Online Subsystem Steam module, check the Enabled box and click the Restart Now button to save settings and reload the Unreal Editor.

Configure the Processing of Events

  1. The image below shows how to add nodes to the project:

    To authenticate users via Steam, you should get a session ticket via the GetSessionTicket method. Pass the received value when calling the AuthenticateWithSessionTicket method. As a result, you get the token that is used when calling the API methods.

  1. For additional token validation, add the ValidateToken method callback (optional).

Ensure Authentication via Steam

  1. Create the build of your UE4 project for a stand-alone platform.
  2. Launch Steam and log in.
  3. Launch your application. If everything is correct, the Steam pop-up window appears.

How to Set Up Token Invalidation

Token invalidation allows for improved security of user authentication data in your application. If the option is enabled, a new token replaces the old one that becomes invalid every time the user authenticates.

Info: You can configure token invalidation for authentication that uses a JWT token. For OAuth 2.0 authentication, token invalidation is provided by the protocol itself and does not need to be configured separately.

When using the Login UE4 SDK, invalidation of the existing token and generation of a new one is made by calling Auth by Username and Password and Auth via Social Network API methods, if the with_logout parameter has the 1 value.

To enable token invalidation in your UE4 project:

  1. Go to Settings > Project Settings > Plugins > Xsolla Login.
  2. Enable the Invalidate Existing Sessions option.

How to Work With User Attributes

You can use attributes to manage additional information about the users of your application. The user attribute is a key-value pair. The Login SDK supports the following types of attributes:

  • User-editable attributes. The values for this type of attributes are entered by a user or specified according to the in-game logics on the client side. For example: the name and character stats, game difficulty level, etc.

  • Read-only attributes. The values for this type of attributes are entered and edited on the server side of your application. We recommend you use them for configuration of game character stats or user parameters that shouldn’t be changed a lot. For example: use them for the chance to get a bonus, game character key parameters, user categories, etc.

You can manage user attributes via user attributes management API methods.

To work with the API methods for server attributes, you need to add an additional Authorization header to the request and use a Publisher Account token for authentication. To get the token:

  1. Enter your Publisher Account.
  2. Go to the cookie files viewpage via the developers’ tools in your browser.
  3. Copy the value from the pa-v4-token parameter and paste it to the Authorization header.

How to Modify the SDK

The SDK is a flexible solution that you can customize to fit your specific application.

To modify the SDK code downloaded from the Unreal Engine Marketplace, follow these steps:

  1. Open the catalog <UE4 Root>/Engine/Plugins/Marketplace/<Plugin name>, where:
    • <UE4 Root> — path to the root directory where Unreal Engine is installed.
    • <Plugin name> — plugin name.

  1. Move the directory with the plugin files to <Project root>/Plugins/, where <Project root> is the path to your UE4 project.
  2. Make changes to the plugin code and restart the project. You need to confirm the rebuild of the plugin module.
  3. Delete the Binaries and Intermediate folders.

You don't need to do any preliminary steps to make changes to the SDK you downloaded from GitHub.

How to Work With User Account in Your Application

Users can configure the following data from a user account:

  • public profile data:
    • avatar
    • nickname

  • personal user data:
    • name and surname
    • birthdate
    • gender
    • phone number
    • email

Info: To set some additional user parameters or set the parameters of a game character, use the instruction on how to work with user attributes. You can add the friend list management functionality in the user account if the friend system is implemented in the application.

You can manage the user account via the API methods. The Login UE4 SDK has the following methods implemented:

  • UpdateUserDetails — updates locally cached user data.

Note: The user can set their birthdate only once. The entered value can’t be changed in the future.

  • ModifyUserDetails — changes the specified user data.
  • UpdateUserEmail — updates the locally cached user email.
  • UpdateUserPhoneNumber — updates the locally cached user phone number.
  • ModifyUserPhoneNumber — changes the user’s phone number.
  • RemoveUserPhoneNumber — deletes the user’s phone number.
  • ModifyUserProfilePicture — changes the user’s avatar.
  • RemoveProfilePicture — deletes the user’s avatar.

How to Work With Friend System in Your Application

The friend system allows your users to find each other and set up social connections. The SDK supports the following functionality:

  • search by nickname
  • get the list of friends from social networks
  • manage the friend list, send invitations, add and remove friends, block users, etc.
  • manage personal data via the user account

To implement the friend system, you should have the user account functionality in your application. Methods of working with this system use the following parameters from the user account:

  • user ID
  • avatar
  • nickname

Users should specify the nickname to ensure the friend system works correctly. Implement the following nickname specification logics:

  • Use the name that was used for registration via login and password as a nickname.
  • Implement the nickname request during social authentication or platform accounts.

To let users interact with friends from their social networks in your application, configure the storage of friend data on the Xsolla side:

  1. Go to your Publisher Account.
  2. Click Open in the Login block and go to Login projects.
  3. Click Open and set up in the Login project block.
  4. Go to General settings > Authentication.
  5. Set the Store friends from social networks toggle to On.
  6. Save changes.

The Login UE4 SDK has the following methods of working with the friend system:

  • UpdateFriends — updates the locally cached user friends data. The Get Friends API method is used alongside the SDK method.

  • ModifyFriends — updates the status of the user’s social connections. The Update Friends API method is used alongside the SDK method. The social connections status is affected by the following actions:
    • send or cancel a friend request
    • accept or decline a friend request
    • delete the user from the friend list
    • block unblock the user

  • UpdateSocialFriends — updates the locally cached data of user’s friends from a social network. The Get User’s Friends API method is used alongside the SDK method.

How to Work With Coupons

To get new clients to your application and increase sales, you can implement coupon promotions. When redeeming a coupon, the user may receive one of the following rewards:

  • virtual currency package
  • game key
  • virtual item

For details on the features and limitations of coupon promotions, see the In-Game Store guide.

To work with coupon promotions:

  1. Complete the settings in Publisher Account following to the instructions for setting up promotional campaigns with coupons.
  2. Implement in-game logic using the following Store UE4 SDK methods:

    • GetCouponRewards — gets a list of items that can be credited to the user when the coupon is redeemed. The Get Coupon Rewards API method is used alongside the SDK method.
    • RedeemCoupon — redeems the coupon code and rewards the user. The Redeem Coupon Code API method is used alongside the SDK method.

This type of integration is suitable for partners who have already implemented the game logic for authorization, in-game store, and player’s inventory on their servers and they want to use Xsolla Pay Station. In this case, you will need to receive an access token and configure the handling of webhooks.

Charge Policy

Xsolla offers the necessary tools to help you build and grow your gaming business, including personalized support at every stage. The terms of payment are determined by the contract that can be signed via Publisher Account.

The cost of using all Xsolla products is 5% of the amount you receive for the sale of the game and in-game goods via the Xsolla Pay Station. If you do not use the Xsolla Pay Station in your application, but use other products, contact your Account Manager to clarify the terms and conditions.

Prerequisites

Before integration Payments UE4 SDK, follow these steps:

  1. Install the plugin for your UE project.
  2. Set up a project in your Publisher Account.

Install the Plugin

  1. Download the Epic Games Launcher.
  2. Create a new UE4 project.
  3. Download the plugin from Unreal Engine Marketplace or GitHub.

Set Up the Project in Your Publisher Account

  1. Register an Xsolla Publisher Account.
  2. Configure a Publisher Account project that is automatically created after the previous step:
    1. Click My game in the Projects block and go to Project settings.
    2. In setup mode, specify a Project name and click Save.

    1. Go to Integration settings and check that the Integrate new Store management methods toggle is set to Off.

You will need the following parameters for the integration:

  • Merchant ID found in Project settings > Webhooks.

  • API key found in Company settings > API key section.

  • Project ID found in Project settings > Project ID.

  • Secret key found in Project settings > Webhooks section.

Integration

To integrate the Payments UE4 SDK:

  1. Set up the Virtual Items module in your Publisher Account.
  2. Set up the plugin for your UE project.
  3. Get a token.
  4. Open the payment UI.
  5. Set up webhook handling.

  1. In Publisher Account, turn on virtual items display in Store:
    1. Click Store in the left-hand-side menu.
    2. Set the Show in Store toggle to On in the Virtual Items block.

After the integration is complete, test the payment process.

Note: This guide describes the minimum settings required to quick-start the module. For questions, contact your Account Manager.

Set Up the Virtual Items Module in Your Publisher Account

  1. Go to your project and click Connect in the Store block. You can go to the Store settings from any section of Publisher Account by clicking the Store button in the left-hand-side menu.

  1. Click Connect in the Virtual Items block.

  1. Click Create a group.

  1. Specify Group code, Group name, and Description and turn on the group display in Store. Click Create group.

  1. Create items, specifying the following info for each of them:
    • one or more groups that the item should belong to
    • SKU
    • name and a short description
    • prices in real and virtual currencies
    • image (optional)

  1. Make sure that the group status is Enabled.

Set Up the Plugin for Your UE4 Project

  1. Open your UE4 project in Unreal Editor.
  2. For Blueprint projects only:
    1. Compile your UE4 project.
    2. Go to the Content Browser and add a New C++ Class with the None parent node.
  3. Go to Settings > Plugins > Installed > Xsolla Payments SDK, check the Enabled box and click the Restart Now button to save settings and reload the Unreal Editor.
  4. Go to Content Browser > View Options and enable the Show Engine Content and Show Plugin Content options.

  1. Follow UMG UI documentation to customize the user interface.
  2. Set up events processing.

Info: To modify the SDK for your application specifics, follow the SDK modification instruction.

Get a Token

You need a token to integrate with the payment UI. An access token is a string that identifies game, user, and purchase parameters.

Xsolla API uses basic access authentication. Specify your Merchant ID as the username and the API key as the password.

URL to retrieve the token:

Copy
Full screen
Small screen
https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

Learn more about getting a token in the Pay Station guide.

Open the Payment UI

To open the payment UI, use LaunchPaymentConsoleWithAccessToken method, and use the token obtained in the previous step.

Set Up Webhooks

  1. Go to your project in Publisher Account.
  2. Go to Project settings > Webhooks, specify the Webhook URL, and generate a Secret key to sign project webhooks.

  1. Save settings.
  2. Implement the following webhooks for Pay Station:
  3. Test the webhook handler.

Note: Acknowledge the receipt of a webhook by responding with HTTP code 204 without a message body. You can read more about webhooks, including examples, in the API reference.

Test the Payment Process

After successful configuring the plugin, test the payment process. By default, all payments are in the sandbox mode and you can use a test bank card to simulate a successful payment process.

To test the payment process with real payments:

  • Make sure that you have signed a contract with Xsolla.
  • In your UE project, uncheck the Sandbox box in Settings > Project Settings > Plugins > Xsolla Payments.

How to Modify the SDK

The SDK is a flexible solution that you can customize to fit your specific application.

To modify the SDK code downloaded from the Unreal Engine Marketplace, follow these steps:

  1. Open the catalog <UE4 Root>/Engine/Plugins/Marketplace/<Plugin name>, where:
    • <UE4 Root> — path to the root directory where Unreal Engine is installed.
    • <Plugin name> — plugin name.

  1. Move the directory with the plugin files to <Project root>/Plugins/, where <Project root> is the path to your UE4 project.
  2. Make changes to the plugin code and restart the project. You need to confirm the rebuild of the plugin module.
  3. Delete the Binaries and Intermediate folders.

You don't need to do any preliminary steps to make changes to the SDK you downloaded from GitHub.

This integration option allows you to take advantage of Xsolla Pay Station if you use a third-party backend solution.

After integrating Xsolla SDKs, you can use Xsolla Pay Station for processing in-game purchases in combination with other BaaS providers responsible for game logic.

Currently, Xsolla provides integration with PlayFab services.

Charge Policy

Xsolla offers the necessary tools to help you build and grow your gaming business, including personalized support at every stage. The terms of payment are determined by the contract that can be signed via Publisher Account.

The cost of using all Xsolla products is 5% of the amount you receive for the sale of the game and in-game goods via the Xsolla Pay Station. If you do not use the Xsolla Pay Station in your application, but use other products, contact your Account Manager to clarify the terms and conditions.

Prerequisites

Before integrating the Payments UE4 SDK with the PlayFab service, follow these steps:

  1. Install the plugin.
  2. Install the demo project of integration of the Payments UE4 SDK with PlayFab service.
  3. Set up the project in your Publisher Account.
  4. Set up a project in PlayFab.

Install the Plugin

  1. Download the Epic Games Launcher.
  2. Create a new UE4 project.
  3. Download the plugin from Unreal Engine Marketplace or GitHub.

Install the Demo Project

To install a demo project, download it from GitHub.

After installing the demo project, launch the demo map showing the joint use of the Payments UE4 SDK with the PlayFab service.

Set up the Project in Your Publisher Account

  1. Register an Xsolla Publisher Account.
  2. Configure a Publisher Account project that is automatically created after the previous step:
    1. Click My game in the Projects block and go to Project settings.
    2. In setup mode, specify a Project name and click Save.

    1. Go to Integration settings and check that the Integrate new Store management methods toggle is set to Off.

    1. Select the PlayFab integration option.
    2. Click Save.

During the integration process, you will need the following parameters:

  • Merchant ID found in Publisher Account > Project settings > Webhooks.

  • API key found in Publisher Account > Company settings > API key.

  • Project ID found in Publisher Account > Project settings > Project ID.

Set Up the Project in PlayFab

  1. Create a PlayFab account.
  2. Set up a project created automatically after registration:
    1. Click the ⚙ icon to the right of the My Game project to open the menu. Click Edit title info.
    2. Specify Name and click Save title.

  1. Go to the project settings and click Add-ons.
  2. Select the Xsolla add-on in the Monetization section.
  3. Click Install Xsolla.
  4. Specify an email to receive notifications, Merchant ID, Project ID, and API key and enable the I agree to the Xsolla Terms and Conditions option.
  5. Indicate whether you want to use the sandbox mode when processing payments (this setting can be changed later).
  6. Click Install Xsolla.

PlayFab must approve a new add-on. The PlayFab team will send you a message to the specified email when it happens.

During the integration process you will need a Title ID. You can find it in the project settings in Title Settings > API Features section or in the address bar of the browser when navigating to the project settings.

Demo

We provide Demo_Login demo map to demonstrate the integration of the Payments UE4 SDK with the PlayFab service. It is available in the Content Browser > Content > Maps folder. Use it as an example.

By default, the demo uses parameters of preset PlayFab and Publisher Account projects.

Default values for the demo:

  • Title ID: 2915B
  • Username: xsolla
  • Password: xsolla
  • Merchant ID: 136551
  • Project ID: 58866

Limitations:

  • Demo supports the purchase of individual items only. Shopping cart is not available.
  • A nonconsumable item may exist in more than one instance in the inventory.

Integration

To integrate the Payments UE4 SDK with PlayFab:

  1. Set up a product catalog in PlayFab, add items to the catalog. For the next steps of integration, you will need the Item ID of the created goods.
  2. Add a script to receive a payment token.
  3. Go to Publisher Account > Project settings > Webhooks and set https://<title_ID>.playfabapi.com/ThirdPartyPayments/XsollaConfirm as a Webhook URL where <title_ID> is the Title ID of your PlayFab project.

  1. Set up the Virtual Items module in your Publisher Account.
  2. Set up virtual currency packages in your in-game store (optional).
  3. Set up the plugin for your UE4 project.
  4. Set up events processing.

After the integration is complete, test the payment process.

Add a Script to Receive a Payment Token

Due to the integration peculiarities, you must use the CreatePaystationToken script instead of the standard PlayFab REST API GetPaymentToken method to create a payment token.

To add CreatePaystationToken script:

  1. Create a file with the JavaScript code containing the following parameters:
    • <title_ID>Title ID of your PlayFab project. You can find it in the project settings in Title Settings > API Features section or in the address bar of the browser when navigating to the project settings.
    • <project_ID>Project ID from your Publisher Account. You can find it in Project settings > Project ID.
    • <your_authorization_basic_key> – the Merchant ID:API key pair encoded according to the Base64 standard. You can find Merchant ID in your Publisher Account > Project settings > Webhooks. You can find API key in your Publisher Account > Company settings > API key.
    • <merchant_ID>Merchant ID from your Publisher Account.

Copy
Full screen
Small screen
handlers.CreatePaystationToken = function (args) {

  let playFabProjectId = "<title_ID>"; // replace with your PlayFab Project ID
  let merchantId = "<merchant_ID>"; // replace with your Xsolla Merchant ID
  let authToken = "<your_authorization_basic_key>"; // base64(merchantId:merchantApiKey)
  let projectId = <project_ID>; // replace with your Xsolla Project ID

  let headers = {
    "Authorization": "Basic " + authToken
  };

  let body = {
    user: {
      id: {
        hidden: true,
        value: currentPlayerId
      },
      name: {
        value: server.GetUserAccountInfo({"PlayFabId": currentPlayerId}).UserInfo.Username
      }
    },
    settings: {
      project_id: projectId,
      xsolla_product_tag: (args.sdkTag === null || args.sdkTag === "") ? "SDK-payments_ver-0_integr-playfab_engine-0_enginever-0" : args.sdkTag,
      ui: {
        theme: (args.theme === null || args.theme === "") ? "default_dark" : args.theme,
      }
    },
    purchase: {
      virtual_items: {
        items: [
          {
            sku: args.sku,
            amount: args.amount
          }
        ]
      }
    },
    custom_parameters: {
      TitleId: playFabProjectId,
      PfId: currentPlayerId,
      PfOrderId: args.orderId
    }
  };

  if (args.sandbox) body.settings.mode = "sandbox"

  let url = "https://api.xsolla.com/merchant/v2/merchants/" + merchantId + "/token";
  let content = JSON.stringify(body);
  let httpMethod = "post";
  let contentType = "application/json";

  let response = http.request(url, httpMethod, content, contentType, headers);
  return JSON.parse(response);
}

  1. Go to PlayFab project settings.
  2. Click Automation in the side menu.
  3. Go to the Revisions tab.
  4. Click Upload new revision.
  5. Select the created file and save the script revision.

Set up the Virtual Items Module in Your Publisher Account

  1. Go to your project and click Connect in the Store block. You can go to the Store settings from any section of Publisher Account by clicking the Store button in the left-hand-side menu.

  1. Click Connect in the Virtual Items block.

  1. Click Create a group.

  1. Specify Group code, Group name, and Description and turn on the group display in Store. Click Create group.

  1. Create items previously added to the PlayFab catalog specifying the following info for each one of them:
    • group that the item should belong to
    • SKU
    • name and a short description
    • prices in real currency
    • image (optional)

Notice: The virtual item SKU must be the same as the Item ID specified in the product catalog in PlayFab, otherwise PlayFab will not be able to register purchases made via Xsolla Pay Station.

  1. Make sure that the group status is Enabled.

  1. Click Store in the left-hand-side menu and set the Show in Store toggle to On in the Virtual Items block.

Set Up Virtual Currency Packages in the In-Game Store

In addition to virtual items you can configure the purchase of virtual currency packages in the in-game store.

Limitations:

  • Currency packages must be added in the PlayFab catalog and in Publisher Account as items.
  • You need to create items only in one primary PlayFab catalog, otherwise after purchase for real money, items will not be credited.

To add a virtual currency package to an in-game store:

  1. Configure the virtual currency package in the PlayFab catalog as an item:
    1. In the catalog, go to Bundles and click New Bundle.
    2. Set the Item ID and specify Display name in accordance with the amount of currency in the package (for example, “500 crystals pack”).
    3. Enable the Consumable option and set auto-consumption after 3-5 seconds.
    4. In the Bundle Contents section, click Add to Bundle.
    5. Click Currencies and select the type of virtual currency. Click Close.
    6. In the Bundle Contents section, specify the Quantity for the game currency.
    7. In the Prices section, set RM as a Currency and in the Amount field specify the price in US cents. For example: 1 USD = 100 RM, 0.99 USD = 99 RM, 1.5 USD = 150 RM.
    8. Click Save bundle.
  2. Go to your Publisher Account and create an item in the Virtual Items module with the same parameters as previously created in the PlayFab catalog. Please note that the item SKU must be the same as the Item ID specified in the product catalog in PlayFab.

After purchasing this item, the player will automatically be credited with the appropriate amount of virtual currency.

Set Up the Plugin for Your UE4 Project

  1. Open your UE project in Unreal Editor.
  2. For Blueprint projects only:
    1. Compile your UE project.
    2. Go to the Content Browser and add a New C++ Class with the None parent node.
  3. Go to Settings > Plugins > Installed > Xsolla Payments SDK, check the Enabled box and click the Restart Now button to save settings and reload the Unreal Editor.
  4. Go to Content Browser > View Options, enable the Show Engine Content, and Show Plugin Content options.

  1. Go to Content Browser > Content > Maps and launch the Demo_Login demo map of the game.

  1. Create a new user.

  1. Log in as a new user and change the password if necessary.

You can customize the demo design using the following documentation.

Info: To modify the SDK for your application specifics, follow the SDK modification instruction.

Set Up Events Processing

Info: Events are key actions that a user performs during the payment process.

The processing of the events is already set up in the integration demo. You can use it and change the settings accordingly:

  • If the plugin is installed from Epic Games Launcher, open your UE project in Unreal Editor and go to Xsolla Content > Demo > W_PaymentsWidget.
  • If the plugin is installed from GitHub, open your UE project in Unreal Editor and go to Plugins > Xsolla > Content > Demo > W_PaymentsWidget.

If you could not find the files mentioned above in Unreal Editor, go to View Options, enable the Show Plugin Content option, and try again.

To set up your own project’s events:

  1. Open your UE project in Unreal Editor.
  2. Follow the UMG UI Designer documentation to add and design the interface.
  3. Open the interface in the Graph view.
  4. Set up Set Play Fab Settings node. For the Game Title Id input, specify Title ID from your PlayFab project. You can find it in the project settings in Title Settings > API Features section or in the address bar of the browser when navigating to the project settings.

  1. Add and set up another Xsolla UE4 SDK nodes if needed.
  2. Compile the Blueprint/C++ class and play the level.

Test the Payment Process

After successful configuring the plugin, test the payment process. By default, all payments are in the sandbox mode and you can use a test bank card to simulate a successful payment process.

After the purchase is completed, Xsolla sends a webhook to PlayFab. You can check the receipt of an item in PlayFab by going to Players > (Player_ID) > Inventory or by calling the GetUserInventory API method.

Test the payment process by making real payments:

  • Make sure that you have signed a contract with Xsolla.
  • In your UE project, uncheck the Sandbox box in Settings > Project Settings > Plugins > Xsolla Payments.

How to Modify the SDK

The SDK is a flexible solution that you can customize to fit your specific application.

To modify the SDK code downloaded from the Unreal Engine Marketplace, follow these steps:

  1. Open the catalog <UE4 Root>/Engine/Plugins/Marketplace/<Plugin name>, where:
    • <UE4 Root> — path to the root directory where Unreal Engine is installed.
    • <Plugin name> — plugin name.

  1. Move the directory with the plugin files to <Project root>/Plugins/, where <Project root> is the path to your UE4 project.
  2. Make changes to the plugin code and restart the project. You need to confirm the rebuild of the plugin module.
  3. Delete the Binaries and Intermediate folders.

You don't need to do any preliminary steps to make changes to the SDK you downloaded from GitHub.

Simplified integration allows you to use Xsolla Pay Station to process purchases in games where all the game logic is implemented on the client side and the server part is missing. With this integration, you do not need to configure webhooks.

Limitations:

  • A short list of payment systems that is optimal for this type of integration is used.
  • In the payment interface, inventory, payment history, and balance, working with saved billing accounts and subscriptions are not available.

Charge Policy

Xsolla offers the necessary tools to help you build and grow your gaming business, including personalized support at every stage. The terms of payment are determined by the contract that can be signed via Publisher Account.

The cost of using all Xsolla products is 5% of the amount you receive for the sale of the game and in-game goods via the Xsolla Pay Station. If you do not use the Xsolla Pay Station in your application, but use other products, contact your Account Manager to clarify the terms and conditions.

Prerequisites

Before integrating the Payments UE4 SDK, follow these steps:

  1. Install the plugin.
  2. Set up the project in your Publisher Account.

Install the Plugin

  1. Download the Epic Games Launcher.
  2. Create a new UE4 project.
  3. Download the plugin from Unreal Engine Marketplace or GitHub.

After installing the plugin, launch the demo map showing how Pay Station works with simplified integration.

Set Up the Project in Your Publisher Account

  1. Register an Xsolla Publisher Account.
  2. Configure a Publisher Account project that is automatically created after the previous step:
    1. Click My game in the Projects block and go to Project settings.
    2. In setup mode, specify a Project name and click Save.

    1. Go to Integration settings and check that the Integrate new Store management methods toggle is set to Off.

    1. Select the Simplified integration option.
    2. Click Save.

If you want to change the settings of a project that you already created earlier in your Publisher Account:

  1. Go to your project.
  2. Disable all modules except Virtual Items.
  3. Go to Project settings > Integration settings and check that the Integrate new Store management methods toggle is set to Off.
  4. Select the Simplified integration option.
  5. Click Save.

During the integration process you will need the Project ID found in Publisher Account > Project settings > Project ID.

Demo

To demonstrate the functionality of simplified integration, we provide the SimplifiedIntegrationDemo demo map. It is available in the Content Browser > XsollaPayments Content > Maps folder. Use it as an example.

By default, the demo uses the Project ID 68789 of a preset Publisher Account project.

Limitations:

  • User authentication is not available in the demo.
  • Demo supports the purchase of virtual items and currency packages for real money only.

Integration

To integrate the Payments UE4 SDK:

  1. Set up the Virtual Items module in your Publisher Account.
  2. Set up a JSON file with a list of in-game items.
  3. Set up the plugin for your UE4 project.

After the integration is complete, test the payment process.

Set Up the Virtual Items Module in Your Publisher Account

  1. Go to your project and click Connect in the Store block. You can go to the Store settings from any section of Publisher Account by clicking the Store button in the left-hand-side menu.

  1. Click Connect in the Virtual Items block.

  1. Click Create a group.

  1. Specify Group code, Group name, and Description and turn on the group display in Store. Click Create group.

  1. Create items from your in-game catalog, specifying the following info for each one of them:
    • one or more groups that the item should belong to
    • SKU
    • name and a short description
    • prices in real currency
    • image (optional)

Notice: The virtual item SKU must be the same as the identification of the item in your game catalog.

  1. Make sure that the group status is Enabled.

  1. Click Store in the left-hand-side menu and set the Show in Store toggle to On in the Virtual Items block.

Note: Virtual currency packages are not currently supported. Therefore, they should be created as virtual items. Implement the in-game logic in the client part of the game, allowing to handle such virtual items as packages of virtual currency. After the purchase, players should automatically be credited with the appropriate amount of virtual currency.

Set Up an In-Game Items List

Manually create a JSON file with a list of in-game items.

Example:

Copy
Full screen
Small screen
[
   {
      "sku":"x_gun",
      "type":"virtual_good",
      "display_name":"Xsolla Blaster",
      "description":"That's quite a deadly blaster right here!",
      "image_url":"https://cdn.xsolla.net/img/misc/images/0c59a7698d4f66c1008b27ee752089b7.png",
      "price":{
            "currency": "USD",
            "amount": 12.000000
      },
      "bundle_content": null
   },
   {
      "sku":"CR1500",
      "type":"virtual_currency_package",
      "display_name":"1500 Crystals",
      "description":"Large Crystals Pack",
      "image_url":"https://cdn3.xsolla.com/img/misc/images/1d67a1d2f92d69e021a97effa692dff3.png",
      "price":{
            "currency": "USD",
            "amount": 19.990000
      },
      "bundle_content":{
            "currency": "Crystal",
            "quantity": 1500.000000
      }
   }
]

Set the bundle_content field to null for virtual items. For virtual currency packages, in the bundle_content field, specify the name of the virtual currency in the currency parameter and the amount of virtual currency in the package in the quantity parameter (see the example above).

Notice: For each item, the sku parameter value must be the same as the identifier of the item in your game catalog and SKU of the virtual item specified in Publisher Account.

Set Up the Plugin for Your UE4 Project

  1. Open your UE4 project in Unreal Editor.
  2. For Blueprint projects only:
    1. Compile your UE4 project.
    2. Go to the Content Browser and add a New C++ Class with the None parent node.
  3. Go to Settings > Plugins > Installed > Xsolla Payments SDK, check the Enabled box and click the Restart Now button to save settings and reload the Unreal Editor.
  4. Go to Content Browser > View Options and enable the Show Engine Content and Show Plugin Content options.

  1. Import a JSON file with in-game items list to your UE4 project:
    1. Go to Content Browser.
    2. In the right-click menu go to New Asset > Import to.
    3. Select the previously created JSON file. Unreal Editor will offer you to create a new DataTable asset.
    4. Choose XsollaItemFormat for row type and set import key field name sku.
    5. Click OK.

  1. When importing an asset, there might be some warnings for items with the bundle_content field set to null. They can be ignored. As a result, you should get a data table that looks like the image below.

  1. Connect the added asset:
    1. Go to Content Browser > XsollaPayments Content > UI folder and open W_StoreDemo_SI blueprint.
    2. Go to the Graph view.
    3. Click Class Defaults.
    4. In the Details panel, specify the asset created in the previous steps.

  1. Go to Settings > Project Settings > Plugins > Xsolla Payments and fill in the Project ID.

  1. Go to Content Browser > XsollaPayments Content > Maps and launch the SimplifiedIntegrationDemo demo map of the game.

  1. Customize the integration demo settings if needed:
    1. Follow UMG UI Designer documentation to customize the user interface.
    2. Set up events processing.

Info: To modify the SDK for your application specifics, follow the SDK modification instruction.

Test the Payment Process

After successful configuring the asset, test the payment process. By default, all payments are in the sandbox mode and you can use a test bank card to simulate a successful payment process.

Your application receives information about a completed purchase using an API request, without using webhooks. The purchase process consists of the following steps:

  1. When you open the Pay Station on the client, a UUID is generated for the transaction.
  2. The UUID is passed as part of access_data in the request to open Pay Station as the external identifier of the current transaction.
  3. The client application with the specified frequency requests the current transaction status by the UUID. The response to the request contains the current status of the transaction, the external transaction identifier, and the name and quantity of the purchased product.
  4. Once receipt of a successful transaction is received, purchased items can be credited to the player's inventory according to in-game logic.

Example:

Copy
Full screen
Small screen
GET https://api.xsolla.com/merchant/projects/<Publisher Project ID>/transactions/external/<generated UUID>/status
{
"id":558357638,
"external_id":"647e9698-8ab3-11ea-ab8f-38f9d30e0dd3",
"status":"created",
"purchase": {
"checkout": null,
"virtual_currency": {
"name": "Money",
"quantity": 2
},
"virtual_items": null
}
}



{
"id": 558357634,
"external_id": "647e9698-8ab3-11ea-ab8f-38f9d30e0dd3",
"status": "processing",
"purchase": {
"checkout": null,
"virtual_currency": {
"name": "Money",
"quantity": 2
},
"virtual_items": null
}
}



{
"id": 556094258,
"external_id": "647e9698-8ab3-11ea-ab8f-38f9d30e0dd3",
"status": "canceled",
"purchase": {
"checkout": null,
"virtual_currency": null,
"virtual_items": [
{
"sku": "1468",
"quantity": 1
}
]
}
}
{
"id": 498415945,
"external_id": "647e9698-8ab3-11ea-ab8f-38f9d30e0dd3",
"status": "done",
"purchase": {
"checkout": {
"amount": -0.4,
"currency": "USD"
},
"virtual_currency": null,
"virtual_items": null
}
}

Test the payment process by making real payments:

  • Make sure that you have signed a contract with Xsolla.
  • In your UE4 project, uncheck the Sandbox box in Settings > Project Settings > Plugins > Xsolla Payments.

How to Modify the SDK

The SDK is a flexible solution that you can customize to fit your specific application.

To modify the SDK code downloaded from the Unreal Engine Marketplace, follow these steps:

  1. Open the catalog <UE4 Root>/Engine/Plugins/Marketplace/<Plugin name>, where:
    • <UE4 Root> — path to the root directory where Unreal Engine is installed.
    • <Plugin name> — plugin name.

  1. Move the directory with the plugin files to <Project root>/Plugins/, where <Project root> is the path to your UE4 project.
  2. Make changes to the plugin code and restart the project. You need to confirm the rebuild of the plugin module.
  3. Delete the Binaries and Intermediate folders.

You don't need to do any preliminary steps to make changes to the SDK you downloaded from GitHub.