Set up selling game keys

You can sell game keys via a direct link, store UI, or widget.

You can sell game keys to authorized and unauthorized users.

Authorization allows you to:

• set limits on the sale of game keys for user
• personalize item catalogs and promotional offers
• use the entitlement system
• store user data in the Xsolla payment interface

You can authorize users using the Login product or your own authorization system. Detailed setup information is provided in these instructions.

Selling via direct link

Game keys can be sold via a direct link that opens the payment UI in the following format:

1https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR-ITEM-SKU}

In addition to the main query parameters, you can also pass parameters for customizing the payment interface and selling to authenticated users.

Required parameters

Add the following data to this link:

• YOUR-ITEM-TYPE — item type. Possible values:

  • game — game key package.
  • game_key — game key package on a specific platform.
  • bundle — bundle with game key packages.

• YOUR-PROJECT-ID — ID of your project that can be found in your Publisher Account next to the project name.

• YOUR-ITEM-SKU — game key package SKU, for example:

  • order456 — SKU without a specific platform.
  • pre.order123_steam — SKU with a specific platform.

We recommend using platform-specific game key packages. This helps avoid compatibility issues when using or activating the keys. In all cases, a platform-specific suffix must be added to the SKU — either automatically or manually, depending on how the key package is created:

• When you create key packages in the Publisher Account, the system automatically adds a platform-specific suffix with underscore (e.g. _steam, _playstation) to the SKU you enter.

• When you create platform-specific key packages using API calls, you can specify the platform suffix in any format that includes only lowercase and uppercase Latin alphanumeric characters, periods, dashes, and underscores.

List of supported Xsolla platforms and their example suffixes:

To ensure the link works correctly, you can retrieve the exact SKU using the Get games list API call and include it in the payment link as the SKU value. The item SKU is returned in items.unit_items.sku parameter (typically, this SKU follows the format game_key_sku_drm_sku).

Example URL for selling a game on Steam:

1https://purchase.xsolla.com/pages/buy?type=game_key&project;_id=123456&sku;=pre.order123_steam

Customizing payment UI

To make the payment UI match your game’s style, configure the theme, size, and other UI parameters as described in the guide on how to customize pay station. Add the ui_settings parameter to the URL and pass a settings.ui JSON object with Base64 encoding as the value.

Example URL for opening the payment UI with a custom theme:

1https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR-ITEM-SKU}&ui_settings=ewoJCQkic2l6ZSI6ICJzbWFsbCIsCgkJCSJ0aGVtZSI6ICJkYXJrIgoJCX0=

Selling to authenticated users

To sell keys to authenticated users, pass a user access token in the xsolla_login_token parameter. This token depends on the selected authentication method.

Example URL for opening the payment UI with a token:

1https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR_ITEM_SKU}&xsolla_login_token={ACCESS_TOKEN}

Payment testing

To test the payment flow in a sandbox mode, add the mode=sandbox parameter to the URL. You can use test bank cards to complete transactions.

Example URL for opening the payment UI in sandbox mode:

1https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR-ITEM-SKU}&mode=sandbox

Selling via store UI

You can sell game keys through the store interface. To create a store, you can:

• use Site Builder
• create your own version of the store and integrate the Shop Builder API

To sell game keys packages using the Shop Builder API:

1. To display a catalog, use the Get games list method.

2. Implement the purchase of game keys:

   • For a quick purchase of one key, use the Create order with specified item method. In response to this method, you will receive a token that must be used to open the payment interface.
   • To purchase several game keys, use the cart management methods:
     • Update cart item from current cart to add a game key to the cart.
     • Get current user’s cart to get a list of game keys in the cart.
     • Create an order with all items from the current cart to pay for game keys in the cart. In response to this method, you will receive a token that must be used to open the payment interface.

Selling via widget

You can add a widget to your page to sell game keys and customize it. To copy the widget code, go to the Widget customization section after creating the keys package in your Publisher Account.

If a game is sold on a single platform, the widget will display the game price specific to that platform.

Example: Buy now for $10.

If a game is sold on multiple platforms, the widget will display the lowest price among the platforms.

Example: Get from $10.

In the order creation window, the user can see prices for all platforms and make a choice.

You can also display the price for a specific platform in the widget by specifying the platform SKU in the drm parameter.

Widget code example:

 1<div id="xsolla-buy-button-widget"></div>
 2
 3<script>
 4  var options = {
 5    project_id: "101010",
 6    sku: "my_key",
 7    user: {
 8      auth: "9qs9VyCIQQXBlzJQcfETIKWZDvhi4Sz1"
 9    },
10    drm: "steam",
11    item_type: "unit",
12    api_settings: {
13      sandbox: true
14    },
15    widget_ui: {
16      target_element: "#xsolla-buy-button-widget",
17      theme: {
18        foreground: "green",
19        background: "light"
20      }
21    },
22    payment_widget_ui: {
23      lightbox: {
24        height: "700px",
25        spinner: "round"
26      }
27    }
28  };
29
30  var s = document.createElement("script");
31  s.type = "text/javascript";
32  s.async = true;
33  s.src = "https://cdn.xsolla.net/embed/buy-button/3.1.8/widget.min.js";
34  s.addEventListener("load", function () {
35    var widgetInstance = XBuyButtonWidget.create(options);
36  });
37  document.getElementsByTagName("head")[0].appendChild(s);
38</script>
39
40<style>
41  #xsolla-buy-button-widget {
42    /* place code for button positioning here */
43    margin: 10px;
44  }
45
46  /* Styles the button itself */
47  .x-buy-button-widget.x-buy-button-widget__tiny .x-buy-button-widget-payment-button {
48    background-color: #ff005b;
49    color: black;
50  }
51</style>

Button customization

1. Open your project in Publisher Account and go to the Items catalog > Game keys section.
2. Select a game key and go to the Widget customization tab.

3. In the Customize block, select the background color.

4. When you add the widget code to your page, it includes inherited styles. Add the styles below to override these styles.

 1/* This should be used for button positioning but note this technically repositions the entire widget */
 2#xsolla-buy-button-widget {
 3  /* place code for button positioning here */
 4}
 5
 6/* Styles the button itself */
 7.x-buy-button-widget.x-buy-button-widget__tiny
 8  .x-buy-button-widget-payment-button {
 9  background-color: #ff005b;
10  color: black;
11}
12
13/* Button on hover */
14.x-buy-button-widget.x-buy-button-widget__tiny
15  .x-buy-button-widget-payment-button:hover {
16  background-color: #ff005b;
17}
18
19/* The following are style overrides to leave you with just the button */
20
21/* space immediately surrounding button */
22.x-buy-button-widget-button-block.x-buy-button-widget-button-block__light {
23  background-color: white;
24}
25
26/* space above button (including game title area) */
27.x-buy-button-widget.x-buy-button-widget__tiny
28  .x-buy-button-widget-game-logo {
29  height: 200px;
30  background-image: none !important;
31  background-color: white;
32}
33
34 /* Game title (located right above button) */
35.x-buy-button-widget-game-name.x-buy-button-widget-game-name__light {
36  display: none !important;
37}

How to create multiple buttons or SKUs

You can refer to Xsolla Pay2Play Widget Simple Integration 4 buttons for a code example on how this is accomplished using the Pay2Play widget.

The structure is similar to the Buy Button widget code. An example of a migration:

 1<div id="xsolla-buy-button-widget"></div>
 2<div id="xsolla-buy-button-widget-2"></div>
 3
 4<script>
 5  var options = {
 6    project_id: "191204",
 7    sku: "789",
 8    item_type: "unit",
 9    api_settings: {
10      sandbox: false
11    },
12    widget_ui: {
13      target_element: "#xsolla-buy-button-widget",
14      theme: {
15        foreground: "gold",
16        background: ""
17      }
18    },
19    payment_widget_ui: {
20      lightbox: {
21        height: "700px",
22        spinner: "round"
23      }
24    }
25  };
26
27  // options for second buy button - note the different SKU and target_element
28  var options2 = {
29    project_id: "191204",
30    sku: "123",
31    item_type: "unit",
32    api_settings: {
33      sandbox: false
34    },
35    widget_ui: {
36      target_element: "#xsolla-buy-button-widget-2",
37      theme: {
38        foreground: "gold",
39        background: ""
40      }
41    },
42    payment_widget_ui: {
43      lightbox: {
44        height: "700px",
45        spinner: "round"
46      }
47    }
48  };
49
50  var s = document.createElement("script");
51  s.type = "text/javascript";
52  s.async = true;
53  s.src = "https://cdn.xsolla.net/embed/buy-button/3.1.4/widget.min.js";
54
55  // one event listener per widget instance. repeat for more buttons, passing in different SKUs
56  s.addEventListener("load", function () {
57    var widgetInstance = XBuyButtonWidget.create(options);
58  });
59  s.addEventListener("load", function () {
60    var widgetInstance2 = XBuyButtonWidget.create(options2);
61  });
62
63  document.getElementsByTagName("head")[0].appendChild(s);
64</script>