In-game purchases

Full Implementation

We have partnered with Xsolla to offer you the possibility to integrate in-game purchases more conveniently.

Warning

In-game purchases are an invite only feature. If you are interested in using them, please get in touch with us.

In-game purchases should be available only for the users that are signed in. Guest users should not be able to purchase items. You'll need to integrate the User module if your game has a back-end or the Data module to save user progress securely.

Getting started

When using the Xsolla SDK, and once you are invited to the CrazyGames Xsolla project dashboard, you will need one of the following ways of authentication:

• Standard linked to CrazyGames user accounts:
  • Create your game on the developer portal and contact us so we can generate credentials for the token.
  • The token received from the GetXsollaUserToken() method from the SDK. This method generates a custom Xsolla token that you use with the Xsolla SDK. The purchases are linked to the CrazyGames user account automatically (see Account integration requirements).
• Custom linked to your in-game accounts:
  • You can generate the necessary Xsolla credentials yourself within our Xsolla project dashboard, and use the Xsolla SDK with the generated credentials.
  • We require orders to reference the CrazyGames userId (see User module to get this). You can either use the CrazyGames userId as user identifier when registering an order, or pass crazyGamesUserId with the value of the CrazyGames user ID in the custom_parameters.

Get Xsolla token

HTML5UnityGameMakerConstructGodotCocos

To use Xsolla via our own custom-generated token, you can retrieve the Xsolla token like this:

try {
    const token = await window.CrazyGames.SDK.user.getXsollaUserToken();
    console.log("Get Xsolla token result", token);
} catch (e) {
    console.log("Error:", e);
}

To use Xsolla via our own custom-generated token, the only Xsolla SDK setup required is adding the Project ID, which will be provided by us.

Install the Xsolla Unity SDK can here.

You don't need any additional Xsolla setup, or to handle Xsolla login, since Xsolla will automatically handle the user account creation with the user ID included in token, which is the ID of the CrazyGames user. Thus, all the purchases made using the token will be also linked to the CrazyGames user account.

You can retrieve the Xsolla token like this:

CrazySDK.User.GetXsollaUserToken((error, token) =>
{
    if (error != null)
    {
        Debug.LogError("Get Xsolla user token error: " + error);
        return;
    }
    Debug.Log("Xsolla user token: " + token);
});

🟥 Not supported

🟧 Identical to HTML5

🟥 Not supported

🟧 Identical to HTML5

We recommend that you retrieve the token every time before using it, since the tokens are usually short-lived, for example only 1 hour. Our SDK handles the token refresh.

After retrieving the token, you can use it like this:

HTML5UnityGameMakerConstructGodotCocos

// obtain player's inventory example
// xsollaProjectId will be provided by us
const resp = await fetch(
    `https://store.xsolla.com/api/v2/project/${xsollaProjectId}/user/inventory/items`,
    {
        method: "GET",
        headers: {
            Authorization: `Bearer ${token}`,
        },
    }
);

XsollaToken.Create(token);

🟥 Not supported

🟧 Identical to HTML5

🟥 Not supported

🟧 Identical to HTML5

You don't need to handle any Xsolla login functionality, since Xsolla will automatically handle the user account creation with the user ID included in the token, which is the ID of the CrazyGames user. Thus, all the purchases made using the token will be also linked to the CrazyGames user account.

You can now call the methods from the Xsolla SDK, for example XsollaCatalog.Purchase(...).

Registering orders

For the typical use case, you will use the in-game-store API Xsolla offers. Have a look at

• In-game store Integration Handbook
• In-game store API documentation

Warning

If you are integrating Xsolla on your own, make sure to pass the CrazyGames userId in your orders, either as main user identifier or in the custom_parameters. Read more in Getting started.

Testing

The GetXsollaUserToken() method will work only on CrazyGames.com. You can preview your game through the Developer Portal.

For the initial testing, we recommend testing with sandbox orders, which allow purchasing items with fake money. When you submit the game, please ensure the sandbox orders are disabled.

Order tracking

Order tracking through our SDK is optional.

When using Xsolla, you will mostly deal with 3 order statuses:

• new
• done
• canceled

Every time an order has been successfully completed (done), call our analytics module:

HTML5UnityGameMakerConstructGodotCocos

// order must be a JSON object
window.CrazyGames.SDK.analytics.trackOrder("xsolla", order);

XsollaCatalog.Purchase(skuField.text, orderStatus =>
    {
        CrazySDK.Analytics.TrackOrder(PaymentProvider.Xsolla, orderStatus);
    },
    error => { Debug.LogError($"Failed to buy, Error: {error.errorMessage}"); }
);

🟥 Not supported

🟧 Identical to HTML5

🟥 Not supported

🟧 Identical to HTML5

You can obtain the order for example from the Xsolla Order endpoint

We also encourage you to track the new and canceled orders, as these may be useful in the future.

Requirements & Guidelines

Requirements

• Ensure that there is a working 'close' button to be able to close the PayStation widget and players can resume their session properly
• If your PayStation opens in a new tab (desktop and/or mobile), ensure to notify players (via text only) on the in-game shop page that they should allow browser popups
• Ensure that any 'Back to the game' hyperlink after successful payment is hidden to avoid creating confusion for the players. You can do this by setting the 'Manual redirect condition' to None in the Settings under the PayStation menu in your Xsolla project dashboard

Common mistakes

When integrating in-game purchases, take into account these common mistakes we've noticed:

• The integration is complex. You can check the embeddable widget Xsolla provides for simpler integration.
• Make sure your game can handle payment status correctly to avoid charging players and not crediting them. For example, when they close the window during payment processing. You can rely on one of these options, and wait for the response properly:
  • Via Webhooks
  • Via client-side
• On mobile, the Back button is sometimes hidden. You can check this resource.
• Players can accidentally close the Xsolla window by clicking outside the overlay or pressing Esc. You can disable closeByClick and closeByKeyboard
  • Additional HTML5 resource
  • For Unity: in Unity, under the path Assets/Xsolla/Core/Plugins/, there is a file called paystation.jslib. In this file, the following lines need to be added as options: closeByClick: false and closeByKeyboard: false

Lootbox and similar mechanics

Please note that we do not adhere to any specialized definitions for loot boxes or similar mechanics. Loot box - a mechanic where a player receives a random item/set of random items, usually in a sealed 'box' or 'container' that can be opened either for free or for in-game/real currency. From a restriction standpoint, our main concerns are cases of purchasing items with hidden random content when they:

• are bought for money
• are bought for virtual currency that can be purchased for money

Other cases that may lead to restrictions are considered on a case-by-case basis, but the ones mentioned above are the most common.

Among the 'other loot boxes' (loot box mechanics) are included "wheel of fortune", card pack, etc., i.e. mechanics that have similar elements - hidden content, randomness of item drops, and monetization (for example, purchasing attempts to spin the wheel).

If the game includes loot boxes/ loot box mechanics, the following territories are subject to sales restrictions:

• Belgium, China, Netherlands, Serbia, Slovakia
• Additionally Taiwan, South Korea, if for items obtained from loot boxes/ in similar mechanics, the probabilities of their acquisition in percentages are NOT disclosed; it is important to note that this refers specifically to individual items with the same value (weight), not to the category of items where the weight of items may differ
• Additionally Japan, if
  • the user receives an item from the loot box with a value lower than the price paid for the loot box (i.e. the item must have a value equal to or greater than the price of the loot box)
  • the project's Terms of Service (ToS) do not include prohibition on real money trading (RMT) and trading between players on secondary markets