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.
Goods | Selling 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:
- 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:
- Your client sends an authentication request to your server.
- Your server requests an authorization token and sends a header that contains
project_id/merchant_id
andapi_key
parameters to the Xsolla server. - Xsolla server returns the Pay Station access token.
- Your server passes the Pay Station access token to your client.
- 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
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:
Parameter | Type | Description |
---|---|---|
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account beside the name of your project. Required. |
user | object | User details (object). |
user.id | object | User ID in your authorization system (object). |
user.id.value | string | User ID. Required. |
user.email | object | User email (object). |
user.email.value | string | User email. Must be valid according to the RFC 822 protocol. Required. |
user.name | object | User screen name (object). Required. |
user.name.value | string | User screen name |
user.steam_id | object | User Steam ID (object). |
user.steam_id.value | string | User Steam ID. Required if the application is published on Steam. |
user.playfab_id | object | User PlayFab ID (object) |
user.playfab_id.value | string | User PlayFab ID. Required if the application uses PlayFab services to grant items. |
See examples of requests and responses in the API reference.
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.
Selling via direct link
The following link opens the payment UI:
- curl
https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOU_PROJECT_ID}&sku={YOUR-ITEM-SKU}
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 likeunit_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 asettings.ui
JSON-object with Base64 encoding as the value. Example of the URL with UI settings:
- curl
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:
- curl
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.
- Example of the URL for testing:
- curl
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:
- To display a catalog, use the Get games list method.
- 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.
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:
- in Publisher Account through button customization
- using the Pay Station Widget
Button customization
- Open your project in Publisher Account.
- Click Store in the side menu.
- In the Game Keys pane, click Configure.
- Select a game key and go to the Widget customization tab.
- In the Customize block, select Light as the background color.
theme
object in code so that the parameter background
has an empty string as a value.- When you add the widget code to your page, it includes inherited styles. Add the styles below to override these styles.
style
tag below the script
tag that you got from the Widget customization tab for CSS inheritance/priority reasons.- css
/* 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;
}
- 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:
- js
<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>
- 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 ofoptions
like the ones above for each Buy button. Note the differentsku
(line28) andtarget_element
(line 34, targeting thediv
on line 2).
Was this article helpful?
Rate this page
Don’t want to answer
Thank you for your feedback!
Continue reading
Next steps
Set up webhooksFound a typo or other text error? Select the text and press Ctrl+Enter.