Android SDKs

Overview

Use Android SDKs to integrate Xsolla products with Android apps.

System Requirements

  • Android OS 5.0 or higher
  • Internet connection is essential for Android SDKs

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.

Prerequisites

  1. Download and install Android Studio.
  2. Create a new project.
  3. Register an Xsolla Publisher Account.
  4. 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

We provide the Xsolla Sample App to demonstrate the integration capabilities and functions of SDKs. Use it as an example.

For the demo app, a project in Publisher Account is preset and an in-game store is fully configured. When you launch the demo app, the sign-up/login page is displayed. Sign up in the app or log in with a demo account (username — xsolla, password — xsolla).

Login Android SDK

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

  • authentication via email or username and password
  • authentication via the following social networks:
    • Google
    • Facebook
    • Twitter
    • LinkedIn
    • Naver
    • Baidu
  • signup
  • email confirmation
  • password reset

Privacy Policy

If you use the Login Android 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/log in 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.

Integration

To integrate the Login Android SDK:

  1. Set up Xsolla Login in your Publisher Account.
  2. Install and initialize the library.
  3. Set up event processing and SDK methods.

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.

Install the Library

The library is available in JCenter.

To install the library:

  1. Start Android Studio.
  2. Open build.gradle file of your application.
  3. Add the following line to the dependencies section, where <version_number> is the required version of the Login Android SDK:

implementation 'com.xsolla.android:login:<version_number>'

Initialize the Library

To initialize the library:

  • If you did not specify the Callback URL in your Publisher Account, add the following line to your Android project source code:

XLogin.initJwt(context, "login-project-id", null)
// OR
XLogin.initOauth(context, "login-project-id", "oauth-client-id", null)

Note: The default Callback URL is https://login.xsolla.com/api/blank.

  • if you specified Callback URL in your Publisher Account, add the following line to your Android project source code:

XLogin.initJwt(context, "login-project-id", "your-callback-url", null)
// OR
XLogin.initOauth(context, "login-project-id", "oauth-client-id", "your-callback-url", null)

Store Android SDK

The Store Android SDK is used to integrate Xsolla Store API methods with Android apps.

The solution is used for:

  • managing your in-game store
  • selling virtual items

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

Integration

To integrate the Store Android 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. Install and initialize the library.
  5. Set up event processing and SDK methods.
  6. Integrate the Xsolla Payments Android SDK and 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.

Install the Library

The library is available in JCenter.

To install the library:

  1. Start Android Studio.
  2. Open build.gradle file of your application.
  3. Add the following line to the dependencies section, where <version_number> is the required version of the Store Android SDK:

implementation 'com.xsolla.android:store:<version_number>'

Initialize the Library

To initialize the library, add the following line to your Android project source code:

XStore.init(storeProjectId, authToken);

Payments Android SDK

The Payments Android SDK is used to integrate Xsolla Pay Station API methods with Android apps.

Integration

To integrate the Xsolla Payments SDK:

  1. Set up the Store module (optional).
  2. Set up Pay Station in your Publisher Account.
  3. Get a token.
  4. Install the library.
  5. Configure Return URL.
  6. Set up event processing and SDK methods.

After the integration is complete, test the payment process.

Set up Pay Station in Publisher Account

  1. Go to your project and click Open in the Pay Station block. If you have not previously installed the Store module, click Connect in the Pay Station block.

  1. Open Pay Station settings.
  2. Specify Return URL and Redirect conditions in the Redirect policy block and click Save.

Get a Token

You need to get a token to make the SDK work properly. An access token is a string that is used to initiate the payment process.

You can get a token using Create Order with All Items from Particular Cart method from Xsolla Store SDK. Or you can use another access token, e.g. the token received from PlayFab.

Install the Library

The library is available in JCenter.

To install the library:

  1. Start Android Studio.
  2. Open build.gradle file of your application.
  3. Add the following line to the dependencies section, where <version_number> is the required version of the Payments Android SDK:

implementation 'com.xsolla.android:payments:<version_number>'

Configure Return URL

Add the following strings to the project's strings resources file to specify the Return URL configured in Publisher Account.

<string name="xsolla_payments_redirect_scheme">https</string>
<string name="xsolla_payments_redirect_host">example.com</string>
<string name="xsolla_payments_redirect_path_prefix">/payment</string>

There you should set the Return URL split into three parts. The example is for https://example.com/payment.

Test the Payment Process

After successful configuring the library, 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.

Test the payment process by making real payments:

  • Make sure that you have signed a contract with Xsolla.
  • Set .isSandbox(false) while building a Paystation Intent.

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

If this 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 Android SDK provides the same methods for OAuth 2.0 authorization as for JWT token authorization.

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. Initialize the library.

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.

Initialize the Library

To initialize the library, add the following line to your Android project source code, specifying the following parameters:

  • login-project-idLogin ID found in Publisher Account > Login settings > Login ID.
  • oauth2-client-idClient ID received when setting up OAuth 2.0 in Publisher Account.

XLogin.initOauth(context, "login-project-id", "oauth2-client-id", null)

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

  • XLogin.refreshToken — refreshes the token.
  • XLogin.getToken — returns the current token.
  • XLogin.isTokenExpired — returns true if the token is expired.

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, Android SDK has implemented native authentication via the following social networks:

  • Google
  • Facebook

Note: Native authentication via social networks is available in Android SDK version 0.11.0 and higher.

To configure native authentication:

  1. For native authentication via Facebook, create your Facebook developer account and a new app.
  2. Set up the application page in your Facebook developer account.
  3. For native authentication via Google, set up the project in Google API Console.
  4. Set up social networks for the Login project in your Publisher Account.
  5. Open build.gradle file of your application and add the following lines to the dependencies section where <version_number> is the required version of the Android SDK:

implementation 'com.xsolla.android:login-facebook:<version_number>'
implementation 'com.xsolla.android:login-google:<version_number>'

  1. Initialize the Login library with the following parameters:
    • <facebook_id>App ID from the Facebook developer account.
    • <google_id>Client ID for web application from the Google API Console.

val socialConfig = XLogin.SocialConfig.Builder()
                .facebookAppId("<facebook_id>")
                .googleServerId("<google_id>")
                .build()
        XLogin.init(BuildConfig.LOGIN_ID, this, socialConfig)

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 the Package name of your Android app for the Google Play Package Name.
  5. Specify a fully qualified class name of the default Activity for Class Name.
  6. Generate a hash key and specify it as a 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 Android app:
    1. Click Create credentials and select OAuth client ID.
    2. Specify Android as the Application type.
    3. Specify Name.
    4. Specify Package name of your Android app as a Package name.
    5. Get the SHA-key.
    6. Specify SHA-key generated in the previous step SHA-key as a SHA-1 certificate fingerprint.
    7. Click Create.
    8. 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 the 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 the Client Secret for a web application from the Google API Console as Application Secret.
    4. Click Connect.

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 use token invalidation in your Android project, you need to pass the withLogout = true parameter in the XLogin.authenticate, XLogin.startSocialAuth, and XLogin.finishSocialAuth methods.

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.

Prerequisites

Before integrating Payments Android SDK, follow these steps:

  1. Download and install Android Studio.
  2. Create a new project.
  3. Register an Xsolla Publisher Account.
  4. 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 Android SDK:

  1. Set up the Virtual Items module in your Publisher Account.
  2. Install the library.
  3. Configure Return URL.
  4. Get a token.
  5. Open the payment UI.
  6. 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.

Install the Library

The library is available in JCenter.

To install the library:

  1. Start Android Studio.
  2. Open build.gradle file of your application.
  3. Add the following line to the dependencies section, where <version_number> is the required version of the Payments Android SDK:

implementation 'com.xsolla.android:payments:<version_number>'

Configure Return URL

Add the following strings to the project's strings resources file to specify the Return URL configured in Publisher Account.

<string name="xsolla_payments_redirect_scheme">https</string>
<string name="xsolla_payments_redirect_host">example.com</string>
<string name="xsolla_payments_redirect_path_prefix">/payment</string>

There you should set the Return URL split into three parts. The example is for https://example.com/payment.

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:

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

Create Pay Station Intent

val intent = XPayments.createIntentBuilder(getContext())
            .accessToken(AccessToken(token))
            .isSandbox(BuildConfig.IS_SANDBOX)
            .build()

Start Activity Using Created Intent

startActivityForResult(intent, RC_PAYSTATION)

Parse Activity Result

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
       super.onActivityResult(requestCode, resultCode, data)
       if (requestCode == RC_PAYSTATION) {
           val result = XPayments.Result.fromResultIntent(data)
       }
   }

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 library, 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.

Test the payment process by making real payments:

  • Make sure that you have signed a contract with Xsolla.
  • Set .isSandbox(false) while building a Paystation Intent.

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.

Prerequisites

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

  1. Download and install Android Studio.
  2. Create a new project.
  3. Set up the project in your Publisher Account.
  4. Set up a project in PlayFab.

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 the Xsolla Sample App to demonstrate the integration capabilities and functions of SDKs. Use it as an example.

For the demo app, a project in Publisher Account is preset and an in-game store is fully configured. When you launch the demo app, the sign-up/login page is displayed. Sign up in the app or log in with a demo account (username — xsolla, password — xsolla).

Integration

To integrate the Payments Android 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. Get a token.
  4. Install the library.
  5. Configure Return URL.
  6. Set up event processing and SDK methods.

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.

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.

Example of script usage:

XPlayfabWrapper.createPlayfabOrder(sku, quantity, null, BuildConfig.IS_SANDBOX, object : XPlayfabWrapper.CreatePlayfabOrderCallback {
    override fun onSuccess(paystationToken: String, playfabOrderId: String) {
        // Use paystationToken to start payment
    }

    override fun onFailure(errorMessage: String) {
        // Show error message
    }

})

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.

Install the Library

The library is available in JCenter.

To install the library:

  1. Start Android Studio.
  2. Open build.gradle file of your application.
  3. Add the following lines to the dependencies section, where <version_number> is the required version of the Payments Android SDK:

implementation 'com.xsolla.android:payments:<version_number>'
implementation 'com.xsolla.android:payments-playfab:<version_number>'

Configure Return URL

Add the following strings to the project's strings resources file to specify the Return URL configured in Publisher Account.

<string name="xsolla_payments_redirect_scheme">https</string>
<string name="xsolla_payments_redirect_host">example.com</string>
<string name="xsolla_payments_redirect_path_prefix">/payment</string>

There you should set the Return URL split into three parts. The example is for https://example.com/payment.

Test the Payment Process

After successful configuring the library, 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.
  • Set .isSandbox(false) while building a Paystation Intent.

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.

Prerequisites

Before integrating the Payments Android SDK, follow these steps:

  1. Download and install Android Studio.
  2. Create a new project.
  3. Register an Xsolla Publisher Account.
  4. 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

We provide the Xsolla Sample App to demonstrate the integration capabilities and functions of SDKs. Use it as an example.

For the demo app, a project in Publisher Account is preset and an in-game store is fully configured. When you launch the demo app, the sign-up/login page is displayed. Sign up in the app or log in with a demo account (username — xsolla, password — xsolla).

Integration

To integrate the Payments Android SDK:

  1. Set up the Virtual Items module in your Publisher Account.
  2. Install the library.
  3. Set up a JSON file with a list of in-game items.
  4. Get access data.
  5. Configure Return URL.
  6. Set up event processing and SDK methods.

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.

Install the Library

The library is available in JCenter.

To install the library:

  1. Start Android Studio.
  2. Open build.gradle file of your application.
  3. Add the following line to the dependencies section, where <version_number> is the required version of the Payments Android SDK:

implementation 'com.xsolla.android:payments:<version_number>'

See the example in Store from the demo project.

Set Up an In-Game Items List

Manually create a catalog.json file with a list of in-game items and place it in the assets folder of your project.

Example:

[
   {
      "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.

Get Access Data

You need to use access data to open Pay Station.

Example of generating access data:

val externalId = XPayments.generateExternalId()
 val accessData = AccessData.Builder()
         .projectId(BuildConfig.PROJECT_ID)
         .userId(userId)
         .isSandbox(BuildConfig.IS_SANDBOX)
         .theme("dark")
         .externalId(externalId)
         .virtualItems(listOf(AccessData.VirtualItem(sku, 1)))
         .build()

Configure Return URL

Add the following strings to the project's strings resources file to specify the Return URL configured in Publisher Account.

<string name="xsolla_payments_redirect_scheme">https</string>
<string name="xsolla_payments_redirect_host">example.com</string>
<string name="xsolla_payments_redirect_path_prefix">/payment</string>

There you should set the Return URL split into three parts. The example is for https://example.com/payment.

Test the Payment Process

After successful configuring the library, 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 of the method call:

XPayments.checkTransactionStatus(context, projectId, externalId);

Example of the receiver registration:

val filter = IntentFilter().apply {
    addAction(XPayments.ACTION_STATUS)
}
val receiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        val checkTransactionResult = intent.getParcelableExtra<XPayments.CheckTransactionResult>(XPayments.EXTRA_STATUS)
        if (checkTransactionResult?.status == XPayments.CheckTransactionResultStatus.SUCCESS) {
            // Process checkTransactionResult.paymentStatus and add items to local inventory
        } else {
            // Error
        }
    }
}
registerReceiver(receiver, filter)

{
"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.
  • Set .isSandbox(false) while building an Access Data.
  • Set .isSandbox(false) while building a Paystation Intent.