Unity SDKs

Overview

Use Unity SDKs to integrate Xsolla products with your Unity projects.

System Requirements

  • 64-bit OS
  • Windows 7 SP1 and higher
  • macOS 10.12 and higher
  • A compatible version of Unity:
    • 2018.3.0f2
    • 2019.3.4f1

Notice: We recommend you use the Mono compiler for creating a game build. You can use either Mono or IL2CPP compiler for creating APK.

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 Unity SDKs, follow these steps:

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

Install the Asset

  1. Download Unity.
  2. Pick a personal or professional Unity license based on your preferences.
  3. Create a new Unity project.
  4. Download the asset from the Unity Asset Store or GitHub.

  1. Add a Store demo scene in build settings:
    1. Go to Assets > Xsolla > Demo > StoreDemo > Scene and launch the Store scene.
    2. Open File > Build settings and click Add Open Scenes.

  1. Make sure that the Mono compiler is used for creating a game build (optional):
    1. Click Edit > Project Settings in the main menu.
    2. Go to Other Settings > Configuration block.
    3. Make sure that Mono is chosen in the Scripting Backend field.

After installing the asset, launch the Store demo scene that shows 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.

Demo

To demonstrate the functionality of integration with Xsolla servers, we provide the Store demo scene. It is available in the Assets > Xsolla > Demo > StoreDemo > Scene folder. Use it as an example.

For the demo scene, a project in Publisher Account is preset and an in-game store is fully configured. When you launch the Store demo scene, the sign-up/login page is displayed. If the authorization is successful, the main menu opens.

Default values for the Store demo scene:

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

Login Unity SDK

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

  • authenticating via username and password
  • authenticating via social networks
  • signup
  • email confirmation
  • password reset
  • authenticating via Steam session_ticket
  • 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:

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

Integration

To integrate the Login Unity 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 asset for your Unity 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 Asset for Your Unity Project

  1. Go to your Unity project.
  2. Click Window > Xsolla > Edit Settings in the main menu. In the Inspector window, fill in the Login ID.

  1. Go to Assets > Xsolla > Demo > StoreDemo > Scene and launch the Store scene.
  2. 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:

Store Unity SDK

The Xsolla Store Unity SDK is used to integrate Xsolla Store API methods with apps based on Unity.

The solution works for:

  • selling virtual items
  • managing your in-game store
  • managing user inventory
  • 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.

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

Integration

To integrate the Store Unity 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 asset for your Unity 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 Asset for Your Unity Project

  1. Click Window > Xsolla > Edit Settings in the main menu. In the Inspector window:
    1. Fill in the Login ID.
    2. Fill in the Project ID.
    3. Check the Enable sandbox box.

  1. Go to Assets > Xsolla > Demo > StoreDemo > Scene > Store and 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:

Test the Payment Process

After successful configuring the asset, test the payment process. By default, all payments are made 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 Unity project, uncheck the Enable sandbox box in the Inspector window.

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.

Tutorials

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 scenes 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 Unity project.
  2. Set up the demo scene to log in to the application via the platform account:
    1. In the main menu, go to Window > Xsolla > Edit Settings.
    2. Set the following parameters in the Inspector window:
      1. Specify Publishing platform. The selected value must be different from Xsolla and None.
      2. Change User name from console.

  1. Start the Login demo scene from the Assets > Xsolla > Demo > LoginDemo > Scenes folder. The demo simulates authentication via the platform account, so you automatically authenticate and proceed to the Store demo scene.

  1. Click Account linking in the demo scene. 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 demo scene in Unity.
  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 in the Unity demo scene.

  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 scene 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 Login demo scene from the Assets > Xsolla > Demo > LoginDemo > Scenes folder.

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

  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 Unity demo scene.

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 Unity SDK provides the same methods for OAuth 2.0 authorization as for JWT token authorization. When the engine first initializes an object on the scene, the Awake method is called. The method checks the expiration of the current refresh token.

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 asset in your Unity 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 Asset in Your Unity Project

  1. Go to your Unity project.
  2. Click Window > Xsolla > Edit Settings in the main menu.
  3. In Inspector window:
    1. In the Authorization method field, select OAuth2.0.
    2. In the OAuth2.0 client ID field, specify Client ID received when setting up OAuth 2.0 in Publisher Account.

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

  • IsOAuthTokenRefreshInProgress — returns true during refresh token process, false otherwise.
  • ExchangeCodeToToken — exchanges the user's authentication code for a valid JWT.

The oauthState argument found in the GetSocialNetworkAuthUrl method is used for additional user verification during OAuth 2.0 authentication. This argument is used to mitigate possible CSRF attacks.

How to Integrate SDKs in Projects for Android Applications

Recommendations

When developing projects for Android applications, follow these recommendations:

  1. Provide users with the most convenient authentication method in your application:
    1. Set up native authentication via social networks by following the Native authentication instruction.

Note: Currently, native authentication is supported by the following social providers:
  • Google
  • Facebook
Use the WebView tool to set up native authentication for other social networks.

    1. Set up deep links to return users to the application after they confirm registration via email.
    2. Follow the customization recipe to customize confirmation emails.

Note: You can disable sending of registration confirmation emails if your security principles allow it. Contact your Account Manager to set it up, or email am@xsolla.com.

  1. Choose and set up the most suitable method of working with an in-game store. If you wish, you don’t have to implement the cart feature in your game. Instead, you can implement the ability to make an in-game purchase by clicking the Buy button.
  2. Set up user redirection to your application after making a payment via an external browser.
  3. Follow the Unity customization instruction to customize the UI for errors and pop-ups. Errors and pop-ups in the demo are created for game developers. Therefore, we recommend making them more suitable for the end users of your application.

  1. Go to Xsolla Publisher Account.
  2. To set up returning users to the application after they confirm registration:
    1. Go to your project and click Open in the Login block.
    2. Go to Login projects.
    3. Click Open and set up.
    4. In the window that opens, go to the URL block, specify Callback URL, and click Save changes.

  1. To set up user redirection to your application after making a payment via an external browser:
    1. Go to your project and click Open in the Pay Station block.
    2. Go to Settings.
    3. Specify the required parameters in the Redirect policy section and click Save.

  1. Manually create the AndroidManifest.xml file with the code below. Specify:
    • Callback URL divided into 3 parts. The example for https://example.com/callback is below.
    • Return URL divided into 3 parts. The example for https://example.com/return is below.

Copy
Full screen
Small screen
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <application>
        <activity
            android:name="com.unity3d.player.UnityPlayerActivity"
            android:label="@string/app_name"
            android:launchMode="singleTask">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
            <intent-filter>
                <data android:scheme="https" />
                <data android:host="example.com" />
                <data android:pathPrefix="/callback" />

                <action android:name="android.intent.action.VIEW" />

                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
            </intent-filter>
            <intent-filter>
                <data android:scheme="https" />
                <data android:host="example.com" />
                <data android:pathPrefix="/return" />

                <action android:name="android.intent.action.VIEW" />

                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
            </intent-filter>
        </activity>
    </application>
</manifest>

Note: If you want to set up user redirection to your application for only one case, delete the intent-filter block with the corresponding parameters from the code.

  1. Place the created file in the Assets/Plugins/Android folder of your Unity project.

How to Set Up Native Authentication via Social Networks

Native authentication allows players to log in to your application via installed applications that use social network accounts. Currently, the Unity SDK has implemented native authentication via the following social networks:

  • Google
  • Facebook

Note: Native authentication via social networks is available in Unity SDK version 0.5.2.0 and higher.

To configure native authentication:

  1. Create your Unity project build for Android.
  2. For native authentication via Facebook, create your Facebook developer account and a new app.
  3. Set up the application page in your Facebook developer account.
  4. For native authentication via Google, set up the project in Google API Console.
  5. Set up social networks for the Login project in your Publisher Account.
  6. Set up the asset for your Unity project.

Create Unity Project Build for Android

  1. Go to your Unity project.
  2. Click File > Build settings in the main menu.
  3. Click Android in the Platform block.
  4. Click Build.
  5. Make sure the hash key is formed:
    1. Click Window > Xsolla > Edit Settings in the main menu.
    2. Make sure that the hash key appears in the Android debug hash key field.

For further native authentication configuration you will need:

  • Package Name found in the Inspectorwindow after selecting the Android platform in File > Build settings.
  • Android class name found in Window > Xsolla > Edit Settings > Inspector > Android class name.
  • Android debug hash key found in Window > Xsolla > Edit Settings > Inspector > Android debug hash key.

Set Up Application Page in Your Facebook Developer Account

  1. Go to project settings in the Facebook developer account.
  2. Go to Settings > Basic.
  3. Click Add Platform and select Android.
  4. Specify Package Name from your Unity project for the Google Play Package Name.
  5. Specify Android class name from your Unity project for Class Name.
  6. Specify Android debug hash key from your Unity project for Key Hashes.
  7. Click Save Changes.

For further native authentication configuration, you will need App ID and App Secret found in project settings in Settings > Basic section.

Set Up Project in Google API Console

  1. Go to Google API Console.
  2. Click New Project.
  3. Specify Project name and Location and click Save.
  4. Go to the created project and click OAuth consent screen in the side menu.
  5. Select External option and click Create.
  6. Specify the necessary parameters and click Save.
  7. Click Credentials in the side menu.
  8. Create an OAuth 2.0 client for your Unity application:
    1. Click Create credentials and select OAuth client ID.
    2. Specify Android as the Application type.
    3. Specify Name.
    4. Specify Package name as a Package Name from your Unity project.
    5. Specify SHA-1 certificate fingerprint as Android debug hash key from your Unity project.
    6. Click Create.
    7. Click OK.
  9. Create an OAuth 2.0 client for the web application:
    1. Click Create credentials and select OAuth client ID.
    2. Specify Web application as the Application type.
    3. Specify Name.
    4. Click Add URI in the Authorized redirect URIs section and specify https://login.xsolla.com/api/social/oauth2/callback URI.
    5. Click Create.
    6. Click OK.

For further native authentication configuration, you will need Client ID and Client Secret found in settings of the Client ID for the web application.

Set Up Social Networks for Login Project in Your Xsolla 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 Social connections.
  5. To set up authentication via Facebook:
    1. Click Edit in the Facebook block and change status to Disconnected.
    2. Specify App ID from the Facebook developer account as Application ID.
    3. Specify App Secret from the Facebook developer account as Application Secret.
    4. Click Connect.
  6. To set up authentication via Google:
    1. Click Edit in the Google block and change status to Disconnected.
    2. Specify the Client ID for a web application from the Google API Console as Application ID.
    3. Specify Client Secret for a web application from the Google API Console as Application Secret.
    4. Click Connect.

Set Up Asset for Your Unity Project

  1. Go to your Unity project.
  2. Click Window > Xsolla > Edit Settings in the main menu.
  3. Specify App ID from the Facebook developer account as Facebook App ID.
  4. Specify the Client ID for a web application from the Google API Console as Google server ID.

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 Unity project.
  2. Configure processing of events.
  3. Ensure authentication via Steam.

Configure Your Unity Project

  1. Manually create a steam_appid.txt file and type your application ID in Steam there. Then, place this file to the Assets catalog of your project.

Info: If you downloaded an asset from GitHub, you will find the steam_appid.txt file in the Assets catalog. This file includes the application ID in Steam for a demo project.

  1. Open your Unity project.
  2. In the main menu, go to Window > Xsolla > Edit Settings.
  3. In the Inspector window:
    1. Check the Use Steam authorization box.
    2. In the Steam App ID field, specify your application ID in Steam. The value should be the same as the value in the steam_appid.txt file.

Configure the Processing of Events

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

Ensure Authentication via Steam

  1. Create the build of your Unity 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 Unity 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 Unity project:

  1. In the main menu, go to Window > Xsolla > Edit Settings.
  2. In the Inspector window, check the Enable JWT invalidation box.

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.

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 integrating Payments Unity SDK, follow these steps:

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

Install the Asset

  1. Download Unity.
  2. Pick a personal or professional Unity license based on your preferences.
  3. Create a new Unity project.
  4. Download the asset from Unity Asset Store or GitHub.

  1. Make sure that the Mono compiler is used for creating a game build (optional):
    1. Click Edit > Project Settings in the main menu.
    2. Go to Other Settings > Configuration block.
    3. Make sure that Mono is chosen in the Scripting Backend field.

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 Unity SDK:

  1. Set up the Virtual Items module in your Publisher Account.
  2. Set up the asset for your Unity 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 any 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 Asset for Your Unity Project

  1. Click Window > Xsolla > Edit Settings in the main menu. In the Inspector window select the Enable sandbox option.

  1. Design the user interface following the Unity tutorials.
  2. Set up SDK methods.

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 OpenPurchaseByAccessToken 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 asset, test the payment process. By default, all payments are made in sandbox mode for any users. 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 Unity project, uncheck the Enable sandbox box in the Inspector window.

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 Unity SDK with the PlayFab service, follow these steps:

  1. Install the asset.
  2. Set up the project in your Publisher Account.
  3. Set up a project in PlayFab.

Install the Asset

  1. Download Unity.
  2. Pick a personal or professional Unity license based on your preferences.
  3. Create a new Unity project.
  4. Download the asset from Unity Asset Store or GitHub.

  1. Add a Login demo scene in build settings:
    1. Go to Assets > Xsolla > PlayfabIntegrationDemo > LoginDemo > Scenes and launch the Login scene.
    2. Open File > Build settings and click Add Open Scenes.
  2. Do the same for the Store demo scene found in Assets > Xsolla > PlayfabIntegrationDemo > StoreDemo > Scenes folder.
  3. Check that demo scenes are added in the following order:
    • 0 - Login
    • 1 - Store
  4. Make sure that only the Login scene remains open in the Hierarchy window.

  1. Make sure that the Mono compiler is used for creating a game build (optional):
    1. Click Edit > Project Settings in the main menu.
    2. Go to Other Settings > Configuration block.
    3. Make sure that Mono is chosen in the Scripting Backend field.

After installing the asset, launch the demo scene showing the joint use of the Payments Unity 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 scene to demonstrate the integration of the Payments Unity SDK with the PlayFab service. It is available in the Assets > Xsolla > PlayfabIntegrationDemo 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

To test the purchase process, launch the Login demo scene from the Assets > Xsolla > PlayfabIntegrationDemo > LoginDemo > Scenes folder. If authentication is successful, the Store demo scene will open for the default user and the user’s preset project.

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 Unity 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 asset for your Unity project.

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 Asset for Your Unity Project

  1. Click Window > Xsolla > Edit Settings in the main menu. In the Inspector window:
    1. In the PlayFab title Id specify Title ID from your PlayFab project. It can be found in the project settings in the Title Settings > API Features section or in the address bar of the browser when navigating to the project settings.
    2. Check the Enable sandbox box.

  1. Go to Assets > Xsolla > PlayfabIntegrationDemo > LoginDemo > Scenes > Login and create a new user.

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

  1. Go to Assets > Xsolla > PlayfabIntegrationDemo > LoginDemo > Scenes and launch the Login demo scene. If you launch the Store demo scene first, authorization as a different user will be unavailable.

  1. Customize the integration demo settings if needed:
    1. Follow the Unity tutorials to customize the user interface.
    2. Set up events processing.

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.

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 Unity project, uncheck the Enable sandbox box in the Inspector window.

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 Unity SDK, follow these steps:

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

Install the Asset

  1. Download Unity.
  2. Pick a personal or professional Unity license based on your preferences.
  3. Create a new Unity project.
  4. Download the asset from Unity Asset Store or GitHub.

  1. Add a SimplifiedStore demo scene in build settings:
    1. Go to Assets > Xsolla > Demo > SimlifiedIntegrationDemo > Scenes and launch the SimplifiedStore scene.
    2. Open File > Build settings and click Add Open Scenes.
  2. Make sure that the Mono compiler is used for creating a game build (optional):
    1. Click Edit > Project Settings in the main menu.
    2. Go to Other Settings > Configuration block.
    3. Make sure that Mono is chosen in the Scripting Backend field.

After installing the asset, launch the demo scene 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 SimplifiedStore demo scene. It is available in the Assets > Xsolla > Demo > SimlifiedIntegrationDemo > Scenes 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 Unity SDK:

  1. Set up the Virtual Items module in your Publisher Account.
  2. Set up a file with an in-game items list.
  3. Set up the asset for your Unity 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 catalog.txt file with a list of in-game items and place it in the Assets/Xsolla/Resources folder of your project.

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 Asset for Your Unity Project

  1. Click Window > Xsolla > Edit Settings in the main menu. In the Inspector window:
    1. Fill in the Project ID.
    2. Check the Enable sandbox box.

  1. Go to Assets > Xsolla > Demo > SimlifiedIntegrationDemo > Scenes and launch the SimplifiedStore demo scene.

  1. Customize the integration demo settings if needed:
    1. Follow the Unity tutorials to customize the user interface.
    2. Set up events processing.

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 Unity project, uncheck the Enable sandbox box in the Inspector window.