Xsolla

Overview

Xsolla is a Direct-to-Consumer (D2C) platform for mobile games that enables in-game purchases and refunds outside of the App Store and Google Play through a web shop.

The Xsolla integration in Magify allows you to:

• sell in-game products directly to players;
• use a single unified product catalog;
• track purchases and refunds in Magify analytics;
• treat D2C purchases on par with native store purchases.

The same product can be sold through:

• Native Stores — App Store or Google Play;
• Xsolla — web shop.

How Xsolla Works

Xsolla is not a store or a billing SDK. It provides an external D2C web shop.

Unlike purchases made through native stores:

• purchases happen outside the app, in a browser;
• purchase confirmation is asynchronous;
• purchases are not tied to the app session;
• financial values at purchase time are estimated, not final.

These characteristics affect:

• user experience;
• SDK flow;
• analytics;
• pending states;
• restore behavior.

The scenarios described in the following sections are expected behavior and do not indicate integration errors.

Platform Support and Payment Methods

App Store (iOS)

• Xsolla is used as an external payment provider.
• The purchase flow redirects the user to a browser.
• Availability depends on regional restrictions and Apple policies.

Google Play (Android)

• Xsolla does not replace Google Play Billing.
• Purchases do not go through Google Play In-App Billing.

The Xsolla web shop may support different payment methods depending on the region and configuration, including credit cards, Apple Pay, Google Pay, PayPal, local wallets, and others.

Roles and Responsibilities

Xsolla

Xsolla is responsible for:

• payment processing;
• the web shop and Pay Station checkout flow;
• calculation of expected (estimated) revenue;
• final revenue reconciliation;
• webhook delivery.

Magify

Magify is responsible for:

• the unified product catalog;
• product export to Xsolla;
• webhook processing;
• analytics;
• store context (store_name);
• reporting.

App / SDK

The application and SDK are responsible for:

• purchase UX logic;
• purchase timeout handling;
• pending state handling;
• restore logic;
• delayed / external purchase handling.

Purchase Lifecycle

The Xsolla purchase flow works as follows:

1. The user initiates a purchase in the app.
2. The app opens the Xsolla web shop in a browser.
3. The app goes to the background and may lose focus.
4. Xsolla sends a user_validation request to confirm that the player exists.
5. The user either completes the purchase or exits the checkout.
6. Xsolla sends:
   • payment for a successful purchase;
   • refund for a refund or chargeback.
7. The app returns to the foreground or restarts.
8. The SDK checks the purchase status.
9. The purchase is confirmed or remains in pending.

A purchase may be confirmed after an app restart. This is valid and expected behavior.

Products and Pricing

General Rules

• Products are created only in Magify.
• Every product must exist in Xsolla.
• Product catalog integration is one-way: Magify → Xsolla.
• There is no reverse import from Xsolla to Magify.

Pricing

• The same product can be sold in the native store and through Xsolla only at the same price.
• Xsolla-exclusive products may have different pricing.
• In Xsolla, prices are shown as marketing prices, usually $0.01 lower.

Rounding

Prices are rounded to two decimal places.

If more precision is provided, mathematical rounding is applied.

Xsolla-Side Setup

Project

Each Magify application requires a dedicated project in the Xsolla Publisher Account.

An Xsolla project contains:

• items (products);
• payment configuration;
• webhooks;
• API access keys.

Each project is identified by a Project ID, and the account itself by a Merchant ID. Both are required for server-to-server calls.

API Keys

The following keys are required:

• API Key — production;
• Sandbox API Key.

API keys are shown only once when they are created and cannot be retrieved later. Save them immediately after creation.

Webhooks

Webhooks are configured for each project in the Xsolla Publisher Account.

Enable the following webhook events:

• user_validation;
• payment;
• refund.

A project secret key is used to sign incoming requests. Xsolla sends the signature in the Authorization: Signature <signature> header, where the signature is the SHA-1 hash of the request body concatenated with the secret key.

Magify validates each request against this signature and rejects requests that do not match.

Magify responds to webhooks according to the Xsolla contract:

• 204 No Content — the event is accepted;
• 400 Bad Request with an error code — the event is rejected, for example when an unknown player is received in user_validation.

Sandbox Environment

The sandbox environment is fully isolated and uses:

• separate keys;
• separate products;
• separate transactions.

Sandbox transactions are marked as sandbox in the webhook payload and never reach production analytics.

Magify Setup

In the Magify interface, go to:

Configuration → Integrations → D2C Integration → Create New

Configure the following fields:

• Application
• Merchant ID
• Project ID
• API Key
• Sandbox API Key
• Webhook Secret
• Sandbox Webhook Secret

Product Import

Products can be imported into Xsolla in the following ways:

• automatic import every 11 hours;
• manual bulk import for production and sandbox;
• single product import from Remote Config → Native Elements.

Xsolla Webhooks

The integration uses the following Xsolla webhook events:

• user_validation — pre-purchase validation;
• payment — successful purchase;
• refund — refund or chargeback.

Webhook events are the primary source of truth for purchase status.

Pending Status and Interrupted Purchases

If a user opens the Xsolla web shop, does not complete the payment, and returns to the app, the purchase remains in pending.

The app must apply a timeout while waiting for purchase completion. If the purchase is completed later, it should be processed as a delayed / external purchase.

Some payment methods, including bank transfers, cash, and local offline methods, may be confirmed hours or days after checkout. Such purchases remain in pending until the payment webhook arrives.

Sessions and Counters

Xsolla purchases occur outside the app session.

If the user stays in the browser for an extended period:

• the app session may expire;
• session-based counters (Transaction / inApps) may reset to 0.

This does not affect purchase validity.

Restore and Re-Purchases

• Previously purchased products are filtered at the campaign level.
• Without restore, Magify does not detect Native Store purchases on iOS.
• Xsolla supports its own restore mechanism.
• Automatic restore on app launch is supported.

Store Context (store_name)

The following values are supported:

• native
• xsolla
• mixed

store_name:

• is calculated from nested campaigns;
• can be inherited from a parent campaign;
• is used for analytics in Magify.

Analytics, Revenue, and Reporting

Estimated Revenue

Xsolla sends expected revenue calculated using estimated FX rates and payment fees.

Final revenue:

• is reconciled by Xsolla;
• is typically finalized by the 10th of the following month;
• is not re-sent to Magify.

Xsolla acts as the merchant of record, so the revenue reported to Magify is net of Xsolla fees and taxes as estimated at purchase time.

Negative Revenue

The value in refund may exceed payment.

If a single purchase is fully refunded, total revenue may become negative.

Chargebacks are delivered as refund events and behave the same way in analytics.

Analytics Limitations

• Xsolla provides only in-app purchase metrics.
• Store-level breakdown is not included in Xsolla data.
• Store breakdown is handled in Magify and reflected in daily reports.

Country Field

The country value has a different source in Magify and Xsolla:

• in Magify, country reflects the device locale;
• in Xsolla, country reflects the payment method / bank country.

As a result, the values may differ.

Needs Confirmation Before Publishing

This section is for the integration team and should be removed from the published article.

1. Magify-side values were mirrored from the Aghanim article and must be confirmed for Xsolla: the UI path (Configuration → Integrations → D2C Integration), the 11-hour auto-import interval, the single-product import entry point, and the exact field labels on the D2C Integration form.
2. store_name value — xsolla is assumed by analogy with aghanim. Confirm the literal value used in analytics.
3. Merchant ID / Project ID fields — added because Xsolla requires them for server-to-server calls. Confirm whether the Magify form actually asks for them or derives them from the API key.
4. Sandbox isolation — described as fully isolated (separate keys, products, transactions) to match the Aghanim article and the Magify form fields. In Xsolla, sandbox is normally a mode within the same project, with transactions flagged as sandbox. Confirm which description matches the Magify implementation.
5. Webhook signature scheme — Authorization: Signature <SHA-1(body + secret)> per Xsolla documentation. Confirm the version Magify implements.
6. Marketing price offset ($0.01 lower) — confirm this rule applies to Xsolla the same way as to Aghanim.
7. Revenue reconciliation date (10th of the following month) — mirrored from Aghanim; Xsolla payout and reporting cycles may differ.
8. Restore mechanism — confirm that Xsolla's own restore is used and that automatic restore on app launch is supported in the Xsolla flow.