Buy Button

Buy Button is a comprehensive solution for digital goods selling.

Note: If you are already using Xsolla products and want to integrate Buy Button, please contact your Account Manager.

How It Works

Step 1

Step 2

Step 3

User Flow

Integration Flow

To integrate Buy Button:

  1. Register an Xsolla Publisher Account.
  2. Create a project.
  3. Choose your monetization option(s).
  4. Choose the option for selling the items.

Note: This guide describes the minimum settings required to quick-start the solution. If you have any questions, please contact your Account Manager.

Creating a Project

  1. Go to Projects and click Create new project.
  2. In setup mode:
    1. Specify the webhook URL.
    2. Generate a secret key to sign project webhooks.

Monetization Options

Virtual Currency

The Virtual Currency option allows game developers to sell in-game currencies. Key features:

  • Sell packages of in-game currency
  • Run promotional campaigns
  • Manage in-game currency user balances
  • Auto-detect user currency and country

Setting up

  1. Go to Virtual Currency settings and configure the following parameters:
    • Name
    • Price per unit
    • Image
  2. Create as many virtual currency packages as you need and set the following parameters for each of them:
    • Price
    • Image
  3. Turn on package display in Store.

Setting up Webhooks

You need to implement the following webhooks for the Virtual Currency:

Acknowledge the receipt of a webhook by responding with HTTP code 204 without a message body. You can read more about webhooks, including examples, in the API Reference.

To test the webhook handler, open Project settings > Webhooks section.

Recipes

Our Recipes will help you try out some of the advanced features of the Virtual Currency:

Virtual Items

The Virtual Items option allows you to sell in-game content for real or virtual currencies. Key features:

  • Set prices in real and virtual currencies
  • Set up catalogs with one or several levels
  • Manage content access. For example, you can make a certain item available only to users who have reached a certain level, etc.
  • Configure brief and detailed item cards
  • Run promotional campaigns
  • Manage in-game currency user balances
  • Auto-detect user currency and country

Setting up

  1. Go to Virtual Items settings.
  2. Fill the store catalog:
    1. Create item groups
    2. Create items, specifying the following for each of them:
      • One or more groups that the item should belong to
      • SKU
      • Name and short description
      • Prices in real and virtual currencies
      • Image
  3. Turn on group display in Store.

Setting up Webhooks

You need to implement the following webhooks for the Virtual Items:

Acknowledge the receipt of a webhook by responding with HTTP code 204 without a message body. You can read more about webhooks, including examples, in the API Reference.

To test the webhook handler, open Project settings > Webhooks section.

Recipes

Our Recipes will help you try out some of the advanced features of the Virtual Items:

Game Keys

The Game Keys option allows game developers to sell keys and distribution packages right from the game’s website. Users can access the store using the Game Keys widget. Key features:

  • Choose DRM platforms via which to distribute keys and distribution packages
  • Choose the operating systems/game console versions for each DRM platform
  • Set different prices for different DRM platforms
  • Configure widget size and color theme
  • Give tips to the developer
  • Pre-orders

You can integrate the option in either basic or advanced mode.

Basic Integration

Basic integration:

  • Is quick to implement,
  • Does not require token generation or server implementation, and
  • Works well for games not requiring user pre-authorization.

You will need the Project ID parameter for the integration. You can find it in the Project settings > Webhooks section.

Setting up the module:

  1. Turn on Tokenless integration in Project settings > Integration settings.
  2. Turn off webhooks in Project settings > Webhooks.
  3. Go to the Game Keys settings and press New package.
  4. Configure package parameters:
    • SKU - a unique identifier
    • Game title
    • A brief summary of your game
  5. Choose DRM and platforms.
  6. Configure prices for the selected DRMs.
  7. Upload keys for the selected DRMs.
  8. Implement widget code to the landing page.

You can find the full list of widget parameters for the basic integration in the Selling via Widget section.

Advanced Integration

Advanced integration:

You will need the following parameters for the integration:

  • Merchant ID, shown in Project settings > Webhooks
  • API key. Parameter is generated in the Company settings > API key section
  • Project ID, shown in Project settings > Webhooks
  • Secret key. Parameter is generated in the Project settings > Webhooks section

Setting up the module:

  1. Go to the Game Keys settings and press New package.
  2. Configure package parameters:
    • SKU - a unique identifier
    • Game title
    • A brief summary of your game
  3. Choose DRM and platforms.
  4. Configure prices for the selected DRMs.
  5. Upload keys for the selected DRMs.
  6. Implement widget code to the landing page.

You can find the full list of widget parameters for the advanced integration in the API Reference.

Setting up Webhooks

You need to implement the following webhooks for the Game Keys advanced integration:

Acknowledge the receipt of a webhook by responding with HTTP code 204 without a message body. You can read more about webhooks, including examples, in the API Reference.

To test the webhook handler, open Project settings > Webhooks section.

Recipes

Our Recipes will help you try out some of the advanced features of the Game Keys:

Selling Items

You can sell items via the direct link, widget, or store UI.

The direct link is used for opening the payment UI in a new window or in iframe on your website. Example: place a clickable banner to purchase an item on your website via the payment UI.

The links settings for selling game access, virtual items, and virtual currency are different.

Selling Access to Game

BASIC INTEGRATION

During basic integration of selling the games, the following link is used for opening the payment UI:

https://store.xsolla.com/pages/buy.php?type=digital_content&project_id={YOU_PROJECT_ID}&sku={YOUR-ITEM-SKU}&drm=steam

Add the following data to this link:

  • your project ID in Publisher Account (your project – Project settings – General settings – Project ID)
  • item SKU

Additional settings:

Use the following URL for testing:
https://store.xsolla.com/pages/buy.php?type=digital_content&project_id={YOU_PROJECT_ID}&sku={YOUR-ITEM-SKU}&mode=sandbox

ADVANCED INTEGRATION

During advanced integration of selling the games, the following link is used for opening the payment UI:

https://store.xsolla.com/pages/buy.php?type=digital_content&project_id={YOUR_PROJECT_ID}&sku={YOUR_ITEM_SKU}&{TOKEN_TYPE}=ACCESS_TOKEN
Add the following data to this link:
  • YOUR_PROJECT_ID – your project ID in Publisher Account (your project – Project settings – General settings – Project ID)
  • YOUR_ITEM_SKU – item SKU
  • TOKEN_TYPE – token type: xsolla_login_token for the Xsolla Login JWT and access_token for the Pay Station Access Token
  • ACCESS_TOKEN - is a token which is formed depending on the authentication type

Use the following URL for testing:

https://store.xsolla.com/pages/buy.php?access_token=ACCESS_TOKEN&mode=sandbox

Selling Virtual Items and Virtual Currency

The following link is used for opening the payment UI when selling virtual items and virtual currency:
https://store.xsolla.com/pages/buy.php?type={ITEM_TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR_ITEM_SKU}&{TOKEN_TYPE}={ACCESS_TOKEN}

Add the following data to this link:

  • item type:
    • virtual items - virtual_item
    • virtual currency - bundle
  • YOUR_PROJECT_ID – your project ID in Publisher Account (your project – Project settings – General settings – Project ID)
  • YOUR_ITEM_SKU – item SKU
  • TOKEN_TYPE – token type: xsolla_login_token for the Xsolla Login JWT and access_token for the Pay Station Access Token
  • ACCESS_TOKEN — a token that contains the purchase data
Use the following URL for testing:
https://store.xsolla.com/pages/buy.php?type={ITEM_TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR_ITEM_SKU}&{TOKEN_TYPE}={ACCESS_TOKEN}&mode=sandbox
To create a token:
  1. Get the authentication token for creating an order with a purchase.
  2. Create an order. A token for opening the payment UI will be passed to the response.

Selling via Widget

Widget is a script that you can implement into your website for selling items. The examples of a working widget are on the demo page.

Code for implementing the widget:

<script>
    var options = {
        project_id: "YOUR-PROJECT-ID",
        item_type: "YOUR-ITEM-TYPE",
        sku: "YOUR-ITEM-SKU",
        widget_ui: {
            target_element: '#widget-example-element'
        }
    };
    var s = document.createElement('script');
    s.type = "text/javascript";
    s.async = true;
    s.src = "//cdn.xsolla.net/embed/pay2play/3.0.0/widget.min.js";
    s.addEventListener('load', function (e) {
        var widgetInstance = XPay2PlayWidget.create(options);
    }, false);
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(s);
</script>
Add the following data to the code above:
  • YOUR-PROJECT-ID - your project ID in Publisher Account (your project – Project settings – General settings – Project ID)
  • YOUR-ITEM-TYPE - item type:
    • game – digital_content
    • physical goods – physical_good
    • virtual item – virtual_item
    • virtual currency – virtual_currency
  • YOUR-ITEM-SKU - item SKU
See our GitHub for additional information on the widget configuration.

Selling via Store UI

For selling virtual items and virtual currency via the store UI, you can implement a separate web application or implement a store UI into the game. You should use the Store API or create your own store on the basis of the demo version for getting the list of items and working with them.

Basing on Store API

You can create a frontend part of a store by integrating the Store API methods:
  1. Getting the items list.
  2. Purchasing items:
    • fast purchаse of one item. A token for opening the payment UI will be passed to the response.
    • buying several items:
      • adding an item to the cart
      • getting the list of items in the cart
      • paying for the items in the cart. A token for opening the payment UI will be passed to the response
Choose a suitable authentication option for the methods to work correctly.

Basing on Demo Version

You can check the API features using a store demo version. Its code is uploaded to GitHub. You can use it as a basis for creating your own version.

Authentication Settings

Both the authorized and unauthorized users can make purchases.

Not Authenticated Users

Users can buy games and physical goods without authentication.

Use the purchase option in basic integration for selling games.

You should pass the x-unauthorized-id user identifier in the title when calling the Store API methods for selling physical goods. You can generate the identifier as a number or line on the frontend side. Example of the library for generating an identifier.

Authenticated Users

There are the following options for authenticating users:
  1. If you integrated Xsolla Login, the requests are authenticated via the Xsolla Login JWT.
  2. If you have your own authentication system, the requests are authenticated via the Pay Station Access Token.

Setting up Authentication via Xsolla Login

  1. Follow the instructions to set up a project in Publisher Account.
  2. Implement the authentication methods callback: based on the JSON Web Token or OAuth 2.0 protocol.
If the user data is stored in the Xsolla storage, implement the following methods:If the user data is stored in the PlayFab database, use the recipe for the PlayFab storage. If you store user data in a custom storage, use the recipe for a custom storage.

Setting up Authentication via Pay Station Access Token

Authentication flow:
  1. Your client sends the authentication request to your server.
  2. Your server passes Merchant ID and API key to the Xsolla server and requests access_token.
  3. The Xsolla server sends access_token to your server.
  4. Your server sends access_token to your client.
Returned access_token is used as an authentication token to authenticate the requests sent by the game client.

Promotional Options

Coupons

The Coupon feature enables partners to create a coupon campaign which includes coupon codes that can either be uploaded by the partner or generated in Publisher Account. Coupons can grant a user virtual currency, virtual items, or trial days for a subscription plan. Customize the number of redemptions and the expiration date (if any).

See recipe

Labels

The Labels feature lets partners affix Labels to virtual items and virtual currency package promotions. For example, "Best Value".

See recipe

Bonuses

The Bonus feature lets users receive a bonus item when they make a purchase. A bonus can be any of the following:

  • Virtual currency
  • Trial days for a subscription
  • Virtual item(s)
  • Game(s)
  • Physical goods (e.g. merchandise)

See recipe

Recipes

Our Recipes will help you try out some of the advanced features of the Buy Button:

Tutorials