Android Quick Start

信息

To get access to the Xsolla Mobile SDK during Developer Preview phase, please fill out the form ↗ (https://xsolla.com/mobile-sdk).

Getting Started

ℹ️U.S. rules Android — external payment link-outs and alternative billing solutions

Android — Effective Oct 29, 2025: Following the Epic v. Google injunction, U.S. Google Play apps may guide users to external payment methods via link-outs, use alternative billing solutions, and are no longer subject to anti-steering restrictions.

This quick start guide makes it simple to integrate the Xsolla Mobile SDK and start accepting payments in your Android game. We'll use a pre-configured test project to cover all the essentials: setting up basic user authentication, importing your products (SKUs), and processing a test payment.

By the time you're done, you'll have a working payment system right in your game, seeing firsthand how Xsolla can streamline your monetization. Let's dive in and get your game accepting payments in just a few easy steps!

⚡ DMA-ready & revenue-boosting: leverage direct APK distribution alongside in-app compliance with DMA—unlocking access to 1,000+ global payment methods and bypassing app-store fees to maximize your margins.

Install the SDK

ℹ️Prerequisites minSdk 24

Set minSdk to 24 (Android 7.0+).

For more details, see here.

Add Maven Central ↗ (https://central.sonatype.com) 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"
}

提示

During the Developer Preview Phase, for the latest version of Xsolla Mobile SDK for Android, consult with your Account Manager.

For more detailed information, see Installation.

Configure the SDK

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

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

提示

For information on Buy Button oriented solutions, see here.

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.Analytics configAnalytics = Config.Analytics.getDefault();

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

        // ...
    }

    // ...
}

提示

For more details on the configuration procedure, see Configuration.

Initialize the SDK

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

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 final BillingResult billingResult, @Nullable final List<Purchase> purchases
        ) {
            // Your purchases handling code (e.g. consumption) goes here..
        }
    })
    .build();

A newly created BillingClient instance 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 final 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 final BillingResult billingResult,
            @Nullable final List<ProductDetails> productDetailsList
        ) {
            // Your product details handling code goes here..
        }
    }
);

For more detailed information, see Initialization.

Make a Purchase

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

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 that 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()
    );
}

For more detailed information, see the standard purchasing flow.

Collect Payment

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

These steps will guide you through a test payment collection flow:

Choose the Card payment method:
Use one of the test cards listed here ↗ (https://developers.xsolla.com/doc/pay-station/testing/test-cards) 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 1000 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 set up a new project using one of the suggested methods.

提示

The Buy Button for Mobile Games enables secure and seamless links directly from your iOS and Android games in the U.S.

For detailed how-to guides, see Buy Button for Mobile Games.

备注

You might also be interested in exploring the extended example provided for your convenience to gain a better understanding of the whole purchasing flow based on Xsolla Mobile SDK.

Getting Started​

Install the SDK​

Configure the SDK​

Initialize the SDK​

Make a Purchase​

Collect Payment​

What's next?​