Virtual currency

How it works

Virtual currency is virtual money used to purchase and sell virtual goods. Depending on how it is used, virtual currency affects the game economy balance or is related to application monetization.

Main features:

• Selling any amount of virtual currency or virtual currency packages with a fixed amount.
• Selling virtual currency and virtual currency packages for real or virtual currency.
• Limiting the number of virtual currency packages available for purchase.
• Limiting the display time of virtual currency and virtual currency packages in the store.
• Free virtual currency packages.

The following options are available for selling virtual currency:

• Any amount — allows you to sell virtual currency in the amount specified by the user. To use this option, implement an input field on the client side that allows the user to enter the desired amount of currency when making a purchase.
• Packages — allows you to sell virtual currency in predefined amounts. The price of a currency package is set separately and may differ from the standard price of the same amount of that currency.

1. Example: A package contains 100 gold coins and costs $90, while the price of one gold coin is $1.

Restrictions:

• You can add only one type of virtual currency to a package.
• A price in another virtual currency can be configured only via API calls.
• A virtual currency package can be made free — without specifying a price in real or virtual currency. This can be configured via Publisher Account or via API calls. Free virtual currency that is not part of a package can be created only via API calls.
• The amount of virtual currency in a package can be specified only as an integer.

How to set up

Set up via Publisher Account

• Virtual currency
• Virtual currency packages

To set up virtual currency via Publisher Account:

1. In your project in Publisher Account, go to the Items catalog > All items section.
2. Click Add and select Virtual currency from the drop-down list.

3. Specify the following parameters:
   1. Image (optional).
   2. SKU.
   3. Virtual currency name.
4. To configure how virtual currency is displayed in the store, select the appropriate status.

5. To set a price, click Set up prices and specify the price in real currency. If needed, configure regional prices.
6. Configure attributes using one of the following methods (optional):

1. 1. Add attributes and their values in JSON format.

1. 2. Manually create attributes and values and link them to specific items.

7. Check the settings and click Create currency.

Note

Before setting up a virtual currency package, you must create a virtual currency.

To set up virtual currency package via Publisher Account:

1. In your project in Publisher Account, go to the Items catalog > All items section.
2. Click Add and select Virtual currency package from the drop-down list.

3. Specify the following parameters:
   1. Image (optional).
   2. SKU.
   3. One or several groups the package should belong to.
   4. Name.
   5. Description (optional).
4. To configure how virtual currency is displayed in the store, select the appropriate status.

5. Specify the virtual currency included in the package and its amount.
6. Set prices or create a free item in the Paid or free field:

1. • To create a free package, select Free package.

1. • To set a price, select Paid package and specify the price in real currency. If needed, configure regional prices.

7. To limit the number of packages available for purchase, turn on the Limit number of times one user can buy package toggle and enter the desired quantity.
8. To configure how often the limit resets:

1. 1. From the drop-down list, select a period:
      • Daily.
      • Weekly.
      • Monthly.
      • Custom interval – this is calculated starting from the package’s display start date.
      • No regular refresh.

1. 2. Set up the reset schedule based on the selected period.

9. Configure a time limit for displaying a package (optional):

1. 1. In the Show item in store field, select Limited time.

1. 2. Specify the time zone and the beginning and the end of the period.

1. 1. If you don’t want to indicate the end of the item display period, check the No end date box.

10. Configure attributes using one of the following methods (optional):

1. 1. Add attributes and their values in JSON format.

1. 2. Manually create attributes and values and link them to specific items.

11. Check the settings and click Create package.

Set up via API

To set up virtual currencies, you can use the calls from the Admin subsection in the Virtual items and currency group.

Display virtual currency in store

The display of virtual currency or virtual currency packages depends on how the catalog is implemented — through the site builder or via API.

Display via site builder

1. Create virtual currency package.
2. In your project in Publisher Account, go to the Storefronts > Websites section.
3. In the pane of the desired site, click Open Site Builder.

4. In the Store block section, select the virtual currency package you want to sell on the website in the Item type field.

5. Set an item card layout.
6. After making all necessary changes and preparing your website for launch:
   1. In the upper-right corner of the site builder, click Publish.
   2. Check the boxes next to the pages you want to publish.
   3. Click Publish.

Once the site is published, a section with virtual currency packages will become available. If no packages are displayed, check that their status is set to Available and that no time-based display limit is active.

Get virtual currency information via API

To retrieve the catalog of virtual currencies and virtual currency packages on the client side, use the calls from the Catalog subsection of the Virtual items and currency group.

Grant virtual currency to users

Depending on the item type and integration settings, the virtual currency is granted to the user in one of the following ways:

• If you’ve integrated PlayFab, virtual currency and items are granted to the user’s PlayFab inventory automatically.
• If you use a custom delivery system, all virtual items and currency are granted on your side. We recommend setting up a webhook handler to receive order data on your backend. The necessary data is included in the Successful payment for order webhook.