Quick Start 🚀

info

To get access to the Xsolla Mobile SDK during Developer Preview phase, please fill out the form.

Let's start

important

Xsolla Mobile SDK is an evolution of the enterprise-level Xsolla SDK solution, previously designed for integration into large-scale projects from the ground up. It is widely used by mid-to-large scale developers and publishers.

This quick start guide will walk you through integrating Xsolla Mobile SDK to accept payments in your game. Using a pre-configured test project ID, we'll cover the essentials: setting up basic user authentication, importing SKUs, and processing a test payment. By the end, you'll have a functional payment system integrated into your game, demonstrating how Xsolla can streamline your monetization process. Let's get started and have your game accepting payments in just a few simple steps!

Install the SDK

During the Preview phase, please contact your Account Manager to get access to the Xsolla Mobile SDK.

Unity
Android
iOS

Open the Unity Editor.
In the main menu, click Window > Package Manager.
Add a package as a dependence:
- Click the ➕ icon and select Add package from tarball.
- Select the downloaded SDK package (.tgz).
- Click Open and wait for the import to complete.

important

Xsolla Mobile SDK for Android requires Android SDK 24 (Android 7.0) or higher.

Add Maven Central repository to your project's Gradle script (usually settings.gradle):
```
repositories {
    mavenCentral()
}
```
Also, add a new dependency for Xsolla Mobile SDK to your build.gradle:
```
dependencies {
    def version_mobilesdk = '<version_code>'

    implementation "com.xsolla.android:mobile:$version_mobilesdk"
}
```
tip
During the Preview phase, please contact your Account Manager to get access to the latest Xsolla Mobile SDK for Android.

Configure the SDK

Unity
Android
iOS

In Unity Editor:

Go to Window > Xsolla > MobileSDK > Edit Settings from the main menu
Go to Inspector panel
In the opened asset, set these pre-defined sample project properties below to their respective values:

Property Value
Project ID 77640
Login ID 026201e3-7e40-11ea-a85b-42010aa80004

tip
The provided project and login IDs are predefined and can be used for quick test integrations.
Your settings asset should look similar to this:

Property	Value
Project ID	77640
Login ID	026201e3-7e40-11ea-a85b-42010aa80004

Now, add these few lines to your scene initialization code, e.g. Start() method of a class that inherits from MonoBehaviour:

public class YourSDKIntegrationBehaviour : MonoBehaviour, IDetailedStoreListener {
    public Start() {
        var settings = XsollaStoreClientSettingsAsset.Instance().settings;

        var configuration = XsollaStoreClientConfiguration.Builder.Create()
            .SetSettings(settings)
            .SetSandbox(true)
            .SetLogLevel(XsollaLogLevel.Debug)
            .Build();

        // ...
    }

    // ...
}

First, prepare a Config for the Xsolla Mobile SDK that will define SDK's behavior.

For demonstration purposes and overall simplicity we'll stick to the activity's onCreate method:

public class YourSDKIntegrationActivity extends Activity {
    // ...

    private static final String TAG = "YourSDKIntegration";

    // ...

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // ...

        final Config.Common configCommon = Config.Common.getDefault()
            .withDebugEnabled(true)
            .withLogLevel(LogLevel.VERBOSE)
            .withSandboxEnabled(true);

        // We'll use predefined project and login IDs indented for getting
        // any test integration up and running as rapidly as possible.
        final Config.Integration configIntegration = Config.Integration.forXsolla(
            Config.Integration.Xsolla.Authentication.forAutoJWT(
                ProjectId.parse(77640).getRight(),
                LoginUUID.parse("026201e3-7e40-11ea-a85b-42010aa80004").getRight()
            )
        );

        final Config.Payments configPayments = Config.Payments.getDefault();

        final Config config = new Config(
            configCommon,
            configIntegration,
            configPayments
        );

        // ...
    }

    // ...
}

Initialize the SDK

Now, when we have our configuration ready, it's time to move onto initialization of the SDK itself.

Unity
Android
iOS

Make sure Unity InAppPurchasing plugin is already installed:

info
For information on how to install Unity InAppPurchasing plugin, refer to this page
Create the SDK module using the XsollaPurchasingModule.Builder with the configuration you prepared earlier as its parameter inside YourSDKIntegrationBehaviour's Start method:
```
var module = XsollaPurchasingModule.Builder.Create()
    .SetConfiguration(configuration)
    .Build();
```
Feed the created SDK module into the ConfigurationBuilder and populate the returned instance with the SKUs pre-created for testing purposes:
```
var configurationBuilder = ConfigurationBuilder.Instance(module)
    .AddProduct("key_1", ProductType.Consumable);
```

UnityPurchasing.Initialize(this, configurationBuilder);

Within the YourSDKIntegrationActivity class, declare a field:
```
@Nullable
private BillingClient mBillingClient = null;
```

Add these lines right below the code, where we prepared a Config to create a BillingClient:

// ... setup a `Config` ...

mBillingClient = BillingClient.newBuilder(this)
    .setConfig(config)
    .setListener(new PurchasesUpdatedListener() {
        @Override
        public void onPurchasesUpdated(
            @NonNull BillingResult billingResult, @Nullable List<Purchase> purchases
        ) {
            // Your purchases handling code (e.g. consumption) goes here..
        }
    })
    .build();

A newly created BillingClient needs to establish a connection to Xsolla services before it can be used via a BillingClient.startConnection call:

mBillingClient.startConnection(new BillingClientStateListener() {
    @Override
    public void onBillingServiceDisconnected() {
        Log.d(TAG, "Disconnected.");
    }

    @Override
    public void onBillingSetupFinished(@NonNull BillingResult billingResult) {
        // Your post-connection code goes here..
    }
});

Once the BillingClient becomes connected to Xsolla services, we can start safely fetching product details of the SKUs we're interested in. Put these lines inside the onBillingSetupFinished callback:

final QueryProductDetailsParams queryProductDetailsParams =
    QueryProductDetailsParams.newBuilder()
        .setProductList(Arrays.asList(
            QueryProductDetailsParams.Product.newBuilder()
                .setProductId("key_1")
                .setProductType(BillingClient.ProductType.INAPP)
                .build()
        ))
        .build();

mBillingClient.queryProductDetailsAsync(
    queryProductDetailsParams, new ProductDetailsResponseListener() {
        @Override
        public void onProductDetailsResponse(
            @NonNull BillingResult billingResult,
            @Nullable List<ProductDetails> productDetailsList
        ) {
            // Your product details handling code goes here..
        }
    }
);

Make a Purchase

Once the SDK is fully initialized, a purchase can be made.

Unity
Android
iOS

Modify the MonoBehavior used for configuration and initialization steps to also inherit from IDetailedStoreListener. And add the lines below to it:

public class YourSDKIntegrationBehaviour : MonoBehaviour, IDetailedStoreListener {
    // ...

    public void OnInitialized(IStoreController controller, IExtensionProvider extensions) {    
        controller.InitiatePurchase("key_1");
    }

    // ...

    public PurchaseProcessingResult ProcessPurchase(PurchaseEventArgs args) {
        if (args.purchasedProduct.definition.id == "key_1") {
            Debug.Log("Successfully purchased 'key_1'");
        }
        return PurchaseProcessingResult.Complete;
    }

    // ...

Purchasing flow is initiated using BillingClient's launchBillingFlow method. This requires at least one valid ProductDetails obtained from queryProductDetailsAsync (see initialization). Thus, we'll do that right inside the onProductDetailsResponse callback to simplify the integration:

if (billingResult.isSuccess() &&
    productDetailsList != null && !productDetailsList.isEmpty()) {
    // We'll just use the very first element on the list, but you'd normally
    // want to handle the rest of the product details as well.
    final ProductDetails productDetails = productDetailsList.get(0);

    // Create parameters for the purchasing flow..
    final BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(Arrays.asList(
                BillingFlowParams.ProductDetailsParams.newBuilder()
                    .setProductDetails(productDetails)
                    .build()
            ))
            .build();

    // Initiate a purchasing flow.
    mBillingClient.launchBillingFlow(
        YourSDKIntegration.this, billingFlowParams
    );
} else {
    Log.e(TAG,
        "Received an invalid product details response: " +
        billingResult.getResponseCode()
    );
}

When purchasing flow completes, onPurchasesUpdated is invoked. This would be a perfect moment to award the user the purchased content. Add this code into onPurchasesUpdated we declared previously (see initialization):

if (billingResult.isSuccess() && purchases != null) {
    for (int i = 0; i < purchases.size(); ++i) {
        final ConsumeParams consumeParams =
            ConsumeParams.newBuilder()
                .setPurchaseToken(purchases.get(i).getPurchaseToken())
                .build();

        mBillingClient.consumeAsync(consumeParams, new ConsumeResponseListener() {
            @Override
            public void onConsumeResponse(
                @NonNull BillingResult billingResult, String purchaseToken
            ) {
                Log.e(TAG,
                    "Purchase consumption response: " +
                    billingResult.getResponseCode()
                );
            }
        });
    }
} else {
    Log.e(TAG,
        "Received an invalid 'purchases updated' response: " +
        billingResult.getResponseCode()
    );
}

Collect payment

The SDK relies on Xsolla Pay Station for secure payment collections.

These steps will take your through a test payment collection flow:

Choose the card payment method:
Use one of the test cards listed here and click Pay to confirm the payment:
Once the payment goes through, you'll see a confirmation:

What's next?

Congratulations! 🎉 You've successfully integrated Xsolla Mobile SDK and processed your first test payment. This achievement unlocks access to over 700 global payment methods and sets the foundation for integrating more Xsolla solutions, including our powerful Web Shop.

You've mastered the basics:

✅ User authentication
✅ SKU management
✅ Secure payment processing

This is just the beginning of optimizing your game's monetization. Ready to explore more? Check out our documentation for advanced features and other Xsolla products to further boost your game's success!

important

The next thing you need to do is to create your own publisher account and setup a new project there.

note

You might also be interested in studying the extended examples provided for your convenience to get better understanding of the whole purchasing flow based on Xsolla Mobile SDK:

Let's start​

Install the SDK​

Configure the SDK​

Initialize the SDK​

Make a Purchase​

Collect payment​

What's next?​

Let's start

Install the SDK

Configure the SDK

Initialize the SDK

Make a Purchase

Collect payment

What's next?