Setting up game key selling

Buy Button allows you to monetize games through the sale of game keys on a game’s website for real or virtual currency.

You can sell game keys to unauthorized and authorized users.

For unauthorized users

When making a purchase, users are limited by the following conditions:

  • They can’t use the entitlement system.
  • Payment methods and Xsolla balance will not be saved in Xsolla Pay Station.

GoodsSelling method
One copy of a game (game key).Use a direct link or widget.
Several copies of the game (game keys) or several games in a cart.Pass the unique user ID and email address. The email address and other additional data (a username and country code per ISO 3166-1 alpha-2) have the Base64 encoding and are passed in the title for the x-user parameter when calling the method for getting a payment token.
One item.Use fast purchase calls of one item.
Several items in a cart.Pass the unique user ID. The unique user ID is used in the title as a number or line when calling the API-methods of the Catalog subsection from the Game keys method group (x-unauthorized-id parameter). The identifier is generated on the front-end side, for example via the identifier generation library.

For authorized users

To manage the users’ access to your application and features of Xsolla products, set up an authentication system. For this, you can use Xsolla Login or implement your own authentication system.

If you have implemented your own authentication system and need only the payment UI, generate a Pay Station access token and set up webhooks on your server.

You can use Xsolla Login for your in-game store, if you don’t have your own servers or you want to use the existing solution. The following features are performed on the Xsolla side:

  • store and manage a catalog
  • manage prices
  • store data on regional prices
  • authenticate users
  • process transactions

Authentication via Xsolla login

Xsolla Login supports the OAuth 2.0 standard protocol for user registration and authentication. The standard OAuth 2.0 protocol helps to simplify the development of the client-side application. OAuth 2.0 lets you update the access token without involving the user.

The data on authorized users can be stored:

Note
User data includes the balance in the real currency (change), saved cards, transactions history, and subscriptions.

Authentication via Pay Station access token

Note
Recommended if you want to integrate In-Game Store and Buy Button API methods.

The flow of interaction between your client and the Xsolla server:

  1. Your client sends an authentication request to your server.
  2. Your server requests an authorization token and sends a header that contains project_id/merchant_id and api_key parameters to the Xsolla server.
  3. Xsolla server returns the Pay Station access token.
  4. Your server passes the Pay Station access token to your client.
  5. The returned Pay Station access token is used as an authorization token for authentication in the In-Game Store and Buy Button API and building a store interface.

Get Pay Station access token

On the back-end of your application, implement a method to get a Pay Station access token using an HTTP POST request.

The Xsolla API uses basic HTTP authentication. The request must contain the Authorization: Basic <your_authorization_basic_key> header, where <your_authorization_basic_key> is the merchant ID:API key pair, encoded according to the Base64 standard. Go to Publisher Account to find these parameters:

  • Merchant ID is shown:
    • In the Project settings > Webhooks section.
    • In the Company settings > Company section.
    • In the URL in the browser address bar on any Publisher Account page. The URL has the following format: https://publisher.xsolla.com/​merchant ID/Publisher Account section.

  • API key is shown in Publisher Account only once when it is created and must be stored on your side. You can create a new key in the following section:
    • Company settings > API keys
    • Project settings > API keys

Notice

For more information about working with API keys, see the API reference.

Key recommendations:

  • Save the generated API key on your side. You can view the API key in Publisher Account only once when it is created.
  • Keep your API key a secret. It provides access to your personal account and your projects in Publisher Account.
  • The API key must be stored on your server and never in binaries or on the frontend.

HTTP request:

POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

To get the token, pass the following parameters in the request body:

ParameterTypeDescription
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account beside the name of your project. Required.
user
objectUser details (object).
user.id
objectUser ID in your authorization system (object).
user.id.value
stringUser ID. Required.
user.email
objectUser email (object).
user.email.value
stringUser email. Must be valid according to the RFC 822 protocol. Required.
user.name
objectUser screen name (object). Required.
user.name.value
stringUser screen name
user.steam_id
objectUser Steam ID (object).
user.steam_id.value
stringUser Steam ID. Required if the application is published on Steam.
user.playfab_id
objectUser PlayFab ID (object)
user.playfab_id.value
stringUser PlayFab ID. Required if the application uses PlayFab services to grant items.

See examples of requests and responses in the API reference.

Notice
In the request, use only parameters from the list above. Don’t pass other parameters of the API call (custom_parameters, purchase, etc.), they are not intended to receive an authorization token.

The lifetime of the Pay Station access token when working with the in-game store and inventory is 1 hour after the last call to the Xsolla API. To change the lifetime of the Pay Station access token, contact your Account Manager.

Implement the logic of receiving a new Pay Station access token after its expiration. It is recommended that you get a new token in the background mode, so the user doesn’t have to log in to the application again.

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

The following link opens the payment UI:

Copy
Full screen
Small screen

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

Note

Buying game keys via a direct link for real currency is possible only after signing a license agreement with Xsolla. To do this, in Publisher Account, go to the Accounting > Licensing agreements section, complete the agreement form, and wait for the confirmation. It may take up to 3 business days to review the agreement.

To test payments, you can use the test environment by adding the mode=sandbox parameter to the link.

Add the following data to this link:

  • YOUR-ITEM-TYPE — item type:
    • game — game; game_key — game on a specific platform.
    • bundle — bundle.
  • YOUR-PROJECT-ID — ID of your project from the Project settings > General settings > Project ID section in Publisher Account.
  • YOUR-ITEM-SKU — game key package SKU. To sell a game on a specific platform, use the Get games list (usually this SKU looks like unit_name_drm_sku) to get the SKU.

  • Payment UI style: theme (dark or the default light theme), size, and other parameters. Specify the ui_settings parameters in the URL and pass a settings.ui JSON-object with Base64 encoding as the value. Example of the URL with UI settings:

Copy
Full screen
Small screen

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

  • Token for passing user data. Used when selling game keys to authenticated users only. This token depends on the authentication method. Example of the URL with a token:

Copy
Full screen
Small screen

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

  • The mode=sandbox parameter for payment tests. You can use test bank cards to complete payments.

Note
When making a payment, the Xsolla server sends a request to the webhook URL to verify that the user exists in the game. To avoid errors when testing payment, go to Publisher Account > Project settings > Webhooks and set the switch to OFF. If you want to use webhooks, implement successful processing of a User validation webhook.

  1. Example of the URL for testing:

Copy
Full screen
Small screen

https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOU_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:

If you are implementing your own version of the store, you can use the Store demo version as the basis and add the code snippets posted on GitHub.

To sell game keys packages, integrate the In-Game Store & Buy Button API:

  1. To display a catalog, use the Get games list method.
  2. Implement the purchase of game keys:

Choose a suitable authentication option for the methods to work correctly.

Note
When selling a game through the In-Game Store & Buy Button API, you should implement a feature that allows players to select a specific platform on the client. To get the SKU, pass the value of the items.unit_items.sku parameter from the request to get the list of games.

Selling via widget

There are several ways to develop buttons and integrate them with Xsolla API:

Button customization

  1. Open your project in Publisher Account.
  2. Click Store in the side menu.
  3. In the Game Keys pane, click Configure.
  4. Select a game key and go to the Widget customization tab.

Note
If there are no game keys, create a new one.

  1. In the Customize block, select Light as the background color.

Note
You can also modify the theme object in code so that the parameter background has an empty string as a value.

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

Notice
Added these in a style tag below the script tag that you got from the Widget customization tab for CSS inheritance/priority reasons.
Copy
Full screen
Small screen

/* This should be used for button positioning but note this technically repositions the entire widget */
#xsolla-buy-button-widget {
  /* place code for button positioning here */
}

/* Styles the button itself */
.x-buy-button-widget.x-buy-button-widget__tiny
  .x-buy-button-widget-payment-button {
  background-color: #ff005b;
  color: black;
}

/* Button on hover */
.x-buy-button-widget.x-buy-button-widget__tiny
  .x-buy-button-widget-payment-button:hover {
  background-color: #ff005b;
}

/* The following are style overrides to leave you with just the button */

/* space immediately surrounding button */
.x-buy-button-widget-button-block.x-buy-button-widget-button-block__light {
  background-color: white;
}

/* space above button (including game title area) */
.x-buy-button-widget.x-buy-button-widget__tiny
  .x-buy-button-widget-game-logo {
  height: 200px;
  background-image: none !important;
  background-color: white;
}

 /* Game title (located right above button) */
.x-buy-button-widget-game-name.x-buy-button-widget-game-name__light {
  display: none !important;
}

Notice
  • The id/class names above and the code snippet are used in conjunction with the copied widget code (the image at step 5). For this reason, it is important that you implement the copied widget code.
  • You can use the code above as is or modify the code based on your scenario. The code comments (lines 1, 3, 5, 11, 16, 18, 22, 29) are there to help determine what each CSS rule targets and assist in future styling. For example, if you want just the button (and not the entire widget), you’ll need to substitute the background color of your page in the places below where the color is white — lines 20 and 27.

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:

Copy
Full screen
Small screen

<div id="xsolla-buy-button-widget"></div>
<div id="xsolla-buy-button-widget-2"></div>
    <script>
      var options = {
        project_id: "191204",
        sku: "789",
        item_type: "unit",
        api_settings: {
          sandbox: false,
        },
        widget_ui: {
          target_element: "#xsolla-buy-button-widget",
          theme: {
            foreground: "gold",
            background: "",
          },
        },
        payment_widget_ui: {
          lightbox: {
            height: "700px",
            spinner: "round",
          },
        },
      };
      // options for second buy button - note the different SKU and target_element
      var options2 = {
        project_id: "191204",
        sku: "123",
        item_type: "unit",
        api_settings: {
          sandbox: false,
        },
        widget_ui: {
          target_element: "#xsolla-buy-button-widget-2",
          theme: {
            foreground: "gold",
            background: "",
          },
        },
        payment_widget_ui: {
          lightbox: {
            height: "700px",
            spinner: "round",
          },
        },
      };
      var s = document.createElement("script");
      s.type = "text/javascript";
      s.async = true;
      s.src = "https://cdn.xsolla.net/embed/buy-button/3.1.4/widget.min.js";

// one event listener per widget instance. repeat for more buttons, passing in different SKUs
      s.addEventListener(
        "load",
        function (e) {
          var widgetInstance = XBuyButtonWidget.create(options);
        },
        false
      );
      s.addEventListener(
        "load",
        function (e) {
          var widgetInstance2 = XBuyButtonWidget.create(options2);
        },
        false
      );
      var head = document.getElementsByTagName("head")[0];
      head.appendChild(s);
    </script>

Notice
  • Lines 1 and 2 — one div per button, each with a unique ID.
  • Starting on line 26 are the options for the second button (laid out in the options2 object). You will need a set of options like the ones above for each Buy button. Note the different sku (line28) and target_element (line 34, targeting the div on line 2).
Was this article helpful?
Thank you!
Is there anything we can improve? Message
We’re sorry to hear that
Please explain why this article wasn’t helpful to you. Message
Thank you for your feedback!
We’ll review your message and use it to help us improve your experience.
Rate this page
Rate this page
Is there anything we can improve?

Don’t want to answer

Thank you for your feedback!

Continue reading

Next steps

Set up webhooks
Last updated: January 31, 2023

Found a typo or other text error? Select the text and press Ctrl+Enter.

Report a problem
We always review our content. Your feedback helps us improve it.
Provide an email so we can follow up
Thank you for your feedback!