CONFIGURATION

Configuration

In Unity, settings can be set up either using a settings asset or via code:

The asset allows for a codeless approach, where you don't have to modify the code to adjust the configuration.
The code approach works better for apps, where the configuration is modified dynamically (e.g., flags and values are received from the app's backend).

Asset
Code

In the Unity Editor:

Go to Window > Xsolla > SDK > Edit Settings from the main menu.
Go to the Inspector panel.
Fill in the Project ID and Login ID fields.

tip

To access the asset's settings from the code, use the following snippet:

var settings = XsollaStoreClientSettingsAsset.Instance().settings;

var settings = XsollaStoreClientSettings.Builder.Create()
    .SetProjectId("< your_project_id >")
    .SetLoginId("< your_login_id >")
    .SetLocalPurchasesRestore(true)
    .SetWebViewType(XsollaStoreClientSettings.WebViewType.Auto)
    .SetWebViewOrientationLock(XsollaStoreClientSettings.OrientationLock.Auto)
    .SetUIThemeSize(XsollaStoreClientSettings.ThemeSize.Auto)
    .SetUIThemeStyle(XsollaStoreClientSettings.ThemeStyle.Auto)
    .SetUICustomTheme("")
    .SetUseCloseButton(XsollaStoreClientSettings.CloseButton.Auto)
    .SetUIControlTintColor(Color.clear)
    .SetUIBarTintColor(Color.clear)
    .SetRedirectUrl("")
    .SetRedirectButtonText("")
    .SetRedirectDelay(6)
    .SetEmailCollectionConsentOptIn(null)
    .Build();

Android

For platform-specific settings, including Custom Tabs / TWA browser provider controls, see Configuration - Android.

iOS

important

For directing players to external web payments in the U.S., Japan, and Brazil, and/or in-app payment compliance in Europe under the DMA, see Configuration - iOS.

Buy Button Solution

The Buy Button Solution provides a complete, native payment experience with minimal integration effort. This approach handles the entire payment flow within your app using Xsolla's optimized UI components.

For a full guide (including Web Shop link-outs vs Pay Station, platform notes, and examples), see Buy Button ⚡.

When to use Buy Button Solution:

You want a quick, native payment integration
You prefer Xsolla to handle payment UI and optimization
You need support for multiple payment methods out of the box
You want automatic compliance with regional payment regulations

To enable the Buy Button Solution for your payments (works with default purchase flows only), use the snippet below:

var settings = XsollaClientSettings.Builder.Create()
    .SetUseBuyButtonSolution(true)
    .Build();

note

Make sure XsollaClientConfiguration.SimpleMode is set to Off. The Buy Button Solution won't work in Web Shop link-out mode (SimpleMode.WebShop).

Web Shop Link-outs

Use Web Shop link-outs when you want minimal code changes by redirecting the user to your existing Xsolla Web Shop to complete the purchase.

caution

In Web Shop link-out mode, the SDK does not execute its native in-app payment flow. It only opens the Web Shop and cancels any SDK purchase callbacks. Handle fulfillment and post-payment updates via your Web Shop processes (for example, webhooks or server-side logic), not via SDK purchase callbacks.

Configure by providing the Web Shop URL to settings and enabling the Web Shop simple mode in configuration:

// Provide Web Shop URL in settings
var settings = XsollaClientSettings.Builder.Create()
    .SetWebShopUrl("https://yourwebshop.xsolla.site")
    .Build();

// Enable Web Shop simple mode and pass user identifier
var configuration = XsollaClientConfiguration.Builder.Builder.Create()
    .SetSettings(settings)
    .SetSimpleMode(XsollaClientConfiguration.SimpleMode.WebShop)
    .SetUserId("<USER_ID>")
    .Build();

Purchase Restoration Settings

By default, the SDK automatically handles local purchase restoration to ensure users can recover their purchases when reinstalling your app or when the app crashes or goes out of memory during payment processing. However, this behavior should be adjusted based on your backend integration architecture.

Alternatively, if you prefer a serverless approach without maintaining webhooks, you can enable the Xsolla Events API for purchase restoration (see the subsection below) while keeping local purchase restoration enabled.

For webhook-based integrations where your backend receives and processes purchase notifications directly from Xsolla, disable local restoration to prevent conflicts with server-side transaction management:

var settings = XsollaStoreClientSettings.Builder.Create()
    //..
    .SetLocalPurchasesRestore(false)
    .SetLocalPurchasesRestoreInterval(0)
    .Build();

SetLocalPurchasesRestore: Enables or disables local purchase restoration (true by default).
SetLocalPurchasesRestoreInterval: Interval in seconds between local purchase restoration attempts (0 by default — uses SDK defaults).

warning

When to disable local purchase restoration:

Your backend uses webhooks to receive purchase notifications from Xsolla
You handle transaction lifecycle management on your server
You want to avoid duplicate purchase processing between local and server-side systems

Important limitations:

Restored purchases cannot be validated through the standard validation flow
Restored purchases don't carry the identifiers of the original Xsolla order unless restoration runs through the Events API
Transaction finishing must be handled by your backend when webhooks are used
If local purchase restoration is disabled, the SDK will not perform restoration via either local restoration or the Events API

This setting directly impacts transaction finishing behavior. When local restoration is disabled, your backend becomes responsible for managing the complete transaction lifecycle through webhook notifications. Note that with local restoration disabled, unfinished transactions will not reappear on app relaunch, making proper backend handling essential.

Using Xsolla Events API for Restoration

The Xsolla Events API serves as an alternative to webhook-based integrations, where the integrator's backend usually handles most of the logic (purchase validation, awarding, etc.). Instead of sending webhooks directly, the API intercepts them and stores their payloads in a remote queue managed by Xsolla. This approach enables serverless integrations for projects that lack backend capacity or don't require one, yet still prefer handling the entire transaction flow directly from the app.

Restoring through the Events API also gives you the order identifier from the original Xsolla purchase, so you can match a restored purchase against your own records. Inventory-backed restoration has no order to reference.

CAUTION

Opting for the Xsolla Events API disables your project's webhooks. In other words, you cannot simultaneously handle webhooks on your backend and use the Events API in your app.

To enable it, open your project in Publisher Account, go to Project settings > Integration settings, select Use API and click Save. See Events API in Publisher Account for details.

Enabling Events in the Unity SDK

Enable Events-based purchase restoration in the SDK configuration:

var settings = XsollaStoreClientSettings.Builder.Create()
    //..    
    .SetWebhooksMode(XsollaStoreClientSettings.WebhooksMode.EventsApi)
    .Build();

info

For additional information, see the webhooks page.

note

Events-based restoration requires SetLocalPurchasesRestore(true). If you disable local purchase restoration, the SDK will not query or use the Events API for restoration.

Custom Pay Station Domains

Override the default Pay Station domains for production and sandbox environments. This is useful when you have custom domain setup for your Pay Station.

var configuration = XsollaStoreClientConfiguration.Builder.Create()
    .SetSettings(settings)
    .SetCustomPayStationDomain(
        domainProduction: "pay.yourdomain.com",
        domainSandbox: "sandbox-pay.yourdomain.com"
    )
    .Build();

note

Both domains must be valid absolute URIs. Invalid domains will be logged and ignored. You can pass empty strings or null for either domain to use defaults.

Logo Visibility

Control the visibility of the Xsolla logo in Pay Station using the VisibleLogo setting:

var settings = XsollaStoreClientSettings.Builder.Create()
    .SetVisibleLogo(XsollaClientSettings.VisibleLogo.Auto)  // Auto (default)
    // .SetVisibleLogo(XsollaClientSettings.VisibleLogo.Show)  // Always show
    // .SetVisibleLogo(XsollaClientSettings.VisibleLogo.Hide)  // Always hide
    .Build();

Options:

Auto - Automatically determine whether to show the logo (default behavior)
Show - Always display the Xsolla logo
Hide - Never display the Xsolla logo

Build configuration from the settings

var configuration = XsollaStoreClientConfiguration.Builder.Create()
    // Set the settings object you've acquired in previous step here..
    .SetSettings(settings)
    .SetSandbox(true)
    .SetLogLevel(XsollaLogLevel.Debug)
    .SetLocale("en")
    .SetFallbackToDefaultLocaleIfNotSet(true)
    .SetFetchProductsWithGeoLocale(false)
    .SetFetchPersonalizedProductsOnly(true)
    .SetTrackingId("")
    .Build();

Below is the full list of configuration builder methods:

Setting	Value	Description
SetSettings	XsollaClientSettings	The settings object built in the previous step.
SetAccessToken	string	Access token for authentication (see Assign access token).
SetSandbox	bool	Enables sandbox mode for test payments (default `false`).
SetLogLevel	XsollaLogLevel	Controls the verbosity of SDK logging (`None`, `Error`, `Warning`, `Debug`).
SetDelayedConfigurationTask	Task<OnDelayedConfiguration>	Task for deferred configuration when the access token is not yet available (see Delayed access token).
SetLocale	string	Override locale for pricing and formatting (empty string for automatic).
SetFallbackToDefaultLocaleIfNotSet	bool	Use the default locale if no override is specified (default `false`).
SetFetchProductsWithGeoLocale	bool	Fetch products using geo-detected locale (default `false`).
SetFetchPersonalizedProductsOnly	bool	Return only personalized products, excluding items whose per-user purchase limit has been reached (default `true`).
SetUserId	string	Your user identifier, required for Web Shop link-out mode. Sent as `custom_parameters.custom_user_id` and returned in purchase webhooks; not used for attribution (see SetAttributionUserId).
SetAttributionUserId	string	The ID that purchase events reported to attribution platforms (AppsFlyer, Adjust, etc.) are keyed on, sent to Pay Station as `custom_parameters.custom_id`. It must equal the customer user ID your attribution SDK reports, or purchases won't match up with that user. If left empty, events are matched on the user ID in the payment token, which by default is the player's Xsolla Login user ID.¹
SetTrackingId	string	Tracking ID for analytics (empty string to omit).
SetSimpleMode	SimpleMode	Simple mode setting (`Off`, `WebShop`, `ServerTokens`).
SetCustomPayStationDomain	string, string	Override production and sandbox Pay Station domains (see Custom Pay Station Domains).

¹ If your project authenticates players through server-side custom ID login or PlayFab, or maps the user ID to a custom JWT claim, the payment token carries that value instead of the Login user ID. Call SetAttributionUserId, or purchase events won't match your attribution platform.

Assign Xsolla access token to the configuration

note

The access token JWT-structure ↗ (https://developers.xsolla.com/api/login/overview/#section/JWT-structure).

Default
Delayed (deferred)

warning

A valid access token must already be known before the SDK initialization step.

var configuration = XsollaStoreClientConfiguration.Builder.Create()
    .SetSettings(settings)
    .SetAccessToken("< your access token >")
    .Build();

If the access token is not known yet, when building the configuration, you can easily feed it into the SDK asynchronously using a Task. This works best for apps, where the access token might be acquired at some later point (e.g., from the app's backend) and cannot be provided right away.

var configuration = XsollaStoreClientConfiguration.Builder.Create()
    .SetSettings(settings)
    .SetDelayedConfigurationTask( DelayedTask() )
    .Build();

async Task<XsollaStoreClientConfiguration.OnDelayedConfiguration> DelayedTask()
{
    var task = await Server.GetXsollaTokenAsync();

    return configuration => XsollaStoreClientConfiguration.Builder.Update(configuration)
        .SetSettings( 
            XsollaStoreClientSettings.Builder.Update(configuration.settings)
                .SetProjectId(task.Result.projectId) 
                .Build();
        )   
        .SetAccessToken(task.Result.accessToken)
        .Build();
}

Updating access token at runtime

If you need to update the access token during the session (for example, after token refresh), use the UpdateAccessToken method:

storeClient.UpdateAccessToken("<new_access_token>", error =>
{
    if (error != null)
    {
        Debug.LogError($"Failed to update access token: {error.message}");
        return;
    }

    Debug.Log("Access token updated successfully");
});

tip

This is useful when your access token expires and you need to refresh it without reinitializing the entire SDK.

Using device ID instead of the access token

Below is an example with the fields required to be set for the device ID authentication approach to work:

var settings = XsollaStoreClientSettings.Builder.Create()
    .SetProjectId("< your_project_id >")
    .SetLoginId("< your_login_id >")
    // ..other properties
    .Build();

Using OAuth2 instead of the access token

Below is an example with the fields required to be set for the OAuth2 authentication approach to work:

var settings = XsollaStoreClientSettings.Builder.Create()
    .SetProjectId("< your_project_id >")
    .SetLoginId("< your_login_id >")
    .SetOAuthClientId("< your_oauth_client_id >")
    // ..other properties
    .Build();

Below is an example of the settings required for the social provider authentication approach to work:

With OAuth2

var settings = XsollaStoreClientSettings.Builder.Create()
    .SetProjectId("< your_project_id >")
    .SetLoginId("< your_login_id >")
    .SetOAuthClientId("< your_oauth_client_id >")
    .SetSocialProvider(new XsollaClientSettings.SocialProvider() {
        name = "epicgames",
        accessToken = "<social-access-token>"
    })
    // ..other properties
    .Build();

Without OAuth2

var settings = XsollaStoreClientSettings.Builder.Create()
    .SetProjectId("< your_project_id >")
    .SetLoginId("< your_login_id >")
    .SetSocialProvider(new XsollaClientSettings.SocialProvider() {
        name = "epicgames",
        accessToken = "<social-access-token>"
    })
    // ..other properties
    .Build();

Deep Links Configuration

Deep links are used to return the player back to your game after completing the payment flow.

By default, the SDK handles redirects automatically. You only need to configure the settings below if you want to override the default redirect behavior (for example, use your own redirect URL, change the auto-redirect timing, or override the redirect button/link text).

tip

On iOS, you can use Universal Links (HTTPS) for redirects back to the game to avoid the “Open in App Name?” prompt when returning from an external browser. See iOS Universal Links.

Setting up redirect URL and delay:

settings = XsollaClientSettings.Builder.Update(settings)
    .SetRedirectUrl("myapp://payment")
    .SetRedirectDelay(6)
    .SetRedirectButtonText("Back to the game")
    .Build();

Parameter explanation:

SetRedirectUrl: Overrides the URL used to redirect the player back to the game after purchase completion.
SetRedirectDelay: The delay (in seconds) before Pay Station automatically redirects the player back to the game (so the user doesn't need to tap a redirect button).
SetRedirectButtonText: Overrides the text shown on the redirect button/link in Pay Station.

tip

If you override SetRedirectUrl, it can be either a custom scheme (for example, myapp://...) or a universal link (HTTPS). Ensure your app is configured to handle the chosen type in the platform-specific project settings (iOS / Android). If you keep the SDK defaults, you typically don't need to configure anything additional.

Enable opt-in for collecting the user's email as part of the payment flow (for example, newsletter consent):

var settings = XsollaStoreClientSettings.Builder.Create()
    //..
    .SetEmailCollectionConsentOptIn(true)
    .Build();

Pass true to enable, false to disable, or null to use the default behavior.

Testing purchase flow in sandbox mode

See Testing guide for more details on how to enable the sandbox mode and avoid spending real money while testing the integration.

Android​

iOS​

Buy Button Solution​

Web Shop Link-outs​

Purchase Restoration Settings​

Using Xsolla Events API for Restoration​

Enabling Events in the Unity SDK​

Custom Pay Station Domains​

Logo Visibility​

Build configuration from the settings​

Assign Xsolla access token to the configuration​

Updating access token at runtime​

Using device ID instead of the access token​

Using OAuth2 instead of the access token​

Using a third-party social provider's access token​

Deep Links Configuration​

Email Collection Consent​

Testing purchase flow in sandbox mode​

Android

iOS

Buy Button Solution

Web Shop Link-outs

Purchase Restoration Settings

Using Xsolla Events API for Restoration

Enabling Events in the Unity SDK

Custom Pay Station Domains

Logo Visibility

Build configuration from the settings

Assign Xsolla access token to the configuration

Updating access token at runtime

Using device ID instead of the access token

Using OAuth2 instead of the access token

Using a third-party social provider's access token

Deep Links Configuration

Email Collection Consent

Testing purchase flow in sandbox mode