Virtual currency

How it works

Virtual currency is virtual money that is used for purchasing and selling virtual goods. Depending on its purpose, a virtual currency affects the game economy balance or is connected to monetization of the app.

Main features:

Sell any amount of virtual currency or a separate package of currency with a fixed amount.
Sell hard currency.
Sell virtual currency and packages of virtual currency for real or virtual money.
Limit the number of virtual currency packages available for purchase.
Limit the display time for virtual currency and virtual currency packages in the store.
Free items.

Contact your Customer Success Manager or email to csm@xsolla.com if you want to create a virtual currency and virtual currency package with zero value in price.

In campaigns with a discount, campaigns with promo codes or coupons, you must use virtual currency packages. Virtual currency in arbitrary amounts can only be used in campaigns with a bonus.

Options for selling currency

There are the following options for selling virtual currency:

sell any amount of virtual currency
sell packages of virtual currency

Sell any amount of virtual currency

Sell the virtual currency in amounts required by users. Implement the request for entering the required amount of currency for purchase on the client side of the application.

Sell packages of virtual currency

Sell the virtual currency in predefined amounts. This feature allows you to sell in-game currencies in packages, for which the price can be lower than if the currency was bought with a custom amount.

Example: For a package, you can define a special price that doesn’t equal the amount of virtual currency in it. For example: 1 virtual coin = 1 USD. 500 virtual coins = 450 USD.

Restrictions:

You can add only one type of virtual currency to a package.
You can create a virtual currency package without specifying its price in real or virtual currency. If such an item is displayed in the store, it will be available to users for free.
The amount of virtual currency can be specified only as the integer value.

Currency delivery

Available delivery methods:

Directly to Xsolla Inventory (default method). Before the delivery, the package of virtual currency unpacks, and the currency from the package is granted to the player inventory.
To PlayFab if you have configured the integration.

If the in-game store logic is implemented on your servers, you can configure the purchase webhooks.

Hard currency

Hard currency is a currency that is linked to the platform of purchase and can be purchased only for real money.

Restrictions:

You can give currency a status of hard only during the first setup.
You can sell packages of virtual currency with hard virtual currency only for real money.

To store hard currency separately on different platforms:

Set the Hard virtual currency toggle to On.

When calling the API endpoints for inventory management, pass the string with the platform of purchase to the platform field.

Example

Copy

Full screen

Small screen


"platform": “playstation_network”

Limiting number of virtual currency packages available for purchase

You can limit the purchase of virtual currency packages. For example, you can limit:

the number of virtual currency packages per user
welcome virtual currency packages that are only available for purchase once

If the user has reached the specified limit, the virtual currency package will not be displayed in the catalog.

You can display the maximum available number of packages and the remaining number of packages that is available to the user.

To set a purchase limit when creating a virtual currency package in Publisher Account, switch the Limit number of times one user can buy package toggle to On and specify the number of times the package can be bought.

You can use the methods of the Catalog subsection from the Virtual Items & Currency method group to get information about virtual currency packages.

In the response, you will receive the following information in addition to information about the virtual currency package:

the maximum number of virtual currency packages a user can buy
the remaining number of virtual currency packages available for the user to purchase

You can read more about how to set up or update restrictions in the Limits for user instructions.

For unauthorized users, the maximum number of virtual currency packages they can buy is always displayed. To display the remaining number of virtual currency packages to the user (subject to the current limit), pass user authorization data when you request the virtual currency packages catalog using the methods of the Catalog subsection from the Virtual Items & Currency method group.

To correctly display the number of virtual currency packages that are available to the user, you need to configure authentication.

Example of a response with user attributes:

Copy

Full screen

Small screen


{
  "items": [
    {
      "sku": "vc_package_1",
      "name": "VC Name first package",
      "groups": [],
      "attributes": [],
      "type": "bundle",
      "description": "VC Short Package Description",
      "image_url": "http://vc_package_image.png",
      "is_free": false,
      "price": {
        "amount": "2.0000",
        "amount_without_discount": "2.0000",
        "currency": "USD"
      },
      "bundle_type": "virtual_currency_package",
      "content": [
        {
          "description": "Big Rocket - short description",
          "image_url": "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png",
          "sku": "big_rocket",
          "name": "Big Rocket",
          "type": "virtual_currency",
          "quantity": 100,
          "inventory_options": {
            "consumable": {
              "usages_count": 1
            },
            "expiration_period": null
          }
        }
      ],
      "virtual_prices": [],
      "limits": {
        "per_user": {
          "total": 5,
          "available": 5
          },
        "per_item": null
       },
      "can_be_bought": true
    },
    {
      "sku": "vc_package_3",
      "name": "VC Name third package",
      "groups": [],
      "attributes": [],
      "type": "bundle",
      "description": "VC Short Package Description",
      "image_url": "http://vc_package_image.png",
      "is_free": false,
      "price": {
        "amount": "4.0000",
        "amount_without_discount": "4.0000",
        "currency": "USD"
      },
      "bundle_type": "virtual_currency_package",
      "content": [
        {
          "description": "description",
          "image_url": "http://image.png",
          "sku": "shotgun_raider",
          "name": "SHOTGUN FOR TRUE RAIDERS",
          "type": "virtual_currency",
          "quantity": 200,
          "inventory_options": {
            "consumable": {
              "usages_count": 1
            },
            "expiration_period": null
          }
        }
      ],
      "virtual_prices": [],
      "limits": {
        "per_user": {
          "total": 5,
          "available": 5
          },
        "per_item": null
       },
      "can_be_bought": true
    }
  ]
}

Xsolla ensures the limits are not exceeded and prevents users from purchasing more virtual currency packages than the set limit.

When opening the payment interface and paying for a package, all unpaid orders with this package become invalid.

Example: the user can open the payment form for a package with a purchase restriction in several browser tabs until the package has been purchased. This automatically results in the creation of multiple orders for the same package. After purchasing a package in one tab, Xsolla will void all unpaid orders with the same package.

Limiting the display time for virtual currency and virtual currency packages in the store

You can set the display period for a virtual currency and virtual currency package in the store to:

maintain the relevance of the catalog at a given time, for example, during holiday sales
create a virtual currency and virtual currency packages in advance without displaying it in the catalog
motivate users to buy virtual currency and virtual currency packages by displaying a timer next to the item

When you create a catalog interface using Site Builder, the timer is displayed automatically. When you create a catalog in your own interface, you need to implement the timer.

The display period of virtual currency in the store can only be setted up using API methods.

To set a time limit for displaying a virtual currency in the store via API, pass the following parameters in the Create virtual currency or Update virtual currency API call:

periods[0].date_from with the date and time of the beginning of item display period in YYYY-MM-DDThh:mm:ss±TMZ format, where TMZ is the time zone indicator in hh:mm GMT format.
periods[0].date_until with the date and time of the end of the item display period in YYYY-MM-DDThh:mm:ss±TMZ format, where TMZ is the time zone indicator in hh:mm GMT format. To not indicate the end of an item’s display period, pass null.

You can set up multiple periods for displaying a virtual currency in the store. To do this, in the Create virtual currency or Update virtual currency method, pass an array of objects with the start and end dates of all periods.

Example:

Copy

Full screen

Small screen

"periods": [
      {
        "date_from": "2022-06-10T14:00:00+03:00",
        "date_until": "2022-06-30T14:00:00+03:00"
      },
       {
        "date_from": "2022-07-10T14:00:00+03:00",
        "date_until": "2022-07-30T14:00:00+03:00"
      },
       {
        "date_from": "2022-08-10T14:00:00+03:00",
        "date_until": "2022-08-30T14:00:00+03:00"
      }
]

To set a time limit for displaying a virtual currency package in the store via Publisher Account, select Time period and specify the time zone, the beginning, and end of the period. To not indicate the end of the package display period, check the No end date box.

To set a time limit for displaying a package in the store via API, pass the following parameters in the Create virtual currency package or Update virtual currency package API call.

periods[0].date_from with the date and time of the beginning of item display period in YYYY-MM-DDThh:mm:ss±TMZ format, where TMZ is the time zone indicator in hh:mm GMT format.
periods[0].date_until with the date and time of the end of the item display period in YYYY-MM-DDThh:mm:ss±TMZ format, where TMZ is the time zone indicator in hh:mm GMT format. To not indicate the end of an item’s display period, pass null.

You can set up multiple periods for displaying a package in the store. To do this, in the Create virtual currency package or Update virtual currency package method, pass an array of objects with the start and end dates of all periods.

Example:

Copy

Full screen

Small screen

"periods": [
      {
        "date_from": "2022-06-10T14:00:00+03:00",
        "date_until": "2022-06-30T14:00:00+03:00"
      },
       {
        "date_from": "2022-07-10T14:00:00+03:00",
        "date_until": "2022-07-30T14:00:00+03:00"
      },
       {
        "date_from": "2022-08-10T14:00:00+03:00",
        "date_until": "2022-08-30T14:00:00+03:00"
      }
]

Who can use it

For partners who want to set up game economy or monetization by adding virtual currency to the game and selling virtual items for it
For partners who have integrated at least one of the following products:
- In-Game Store with the configured Virtual Items module.
- Buy Button with the configured Game Keys module.

How to get it

Prerequisites

Sign up to Xsolla Publisher Account.
Open your project.

Configure modules for In-Game Store or Buy Button.

Set up virtual currency

You can set up virtual currencies in one of the following ways:

use Publisher Account
use API calls

Set up virtual currency in Publisher Account

Set up virtual currency via API calls

Use the API calls from the Admin subsection of the Virtual Items & Currency API endpoints.

Thank you for your feedback!

We’ll review your message and use it to help us improve your experience.

Last updated: October 10, 2023

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

Your browser is not supported. Please try a different browser

Popular articles

Or choose frequently asked ones:

Answer based on the following sources:

Leave us some feedback (optional)

Leave us some feedback (optional)

In-Game Store

Virtual currency

How it works

Options for selling currency

Sell any amount of virtual currency

Sell packages of virtual currency

Currency delivery

Hard currency

Limiting number of virtual currency packages available for purchase

Limiting the display time for virtual currency and virtual currency packages in the store

Who can use it

How to get it

Prerequisites

Set up virtual currency

Set up virtual currency in Publisher Account

Set up virtual currency via API calls