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.

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:

• In the Xsolla storage. See Get started for Xsolla Login to set it up.
• In the PlayFab database. Use the how-to for the PlayFab storage to set it up.
• In a custom storage. Use the how-to for a custom storage to set it up.

Authentication via Pay Station access token

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

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:

See examples of requests and responses in the API reference.

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.

Selling via direct link

The following link opens the payment UI:

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

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:

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:

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.

1. Example of the URL for testing:

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:

• use Site Builder
• create your own version of the store and integrate the In-Game Store & Buy Button API

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:
   • 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 the 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.

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

Selling via widget

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

• in Publisher Account through button customization
• using the Pay Station Widget

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.

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

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

/* 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;
}

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:

<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>

Rate this page

Is there anything we can improve? Send

Don’t want to answer

Thank you for your feedback!

Continue reading