# Virtual currency ## How it works {#general_how_it_works} Virtual currency is virtual money used to purchase 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. > [!NOTE] > In discount campaigns and campaigns with promo codes or coupons, you must use virtual currency packages. Arbitrary amounts of virtual currency can be used only in bonus campaigns. 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. **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](/api/catalog/virtual-items-currency-admin/admin-create-virtual-currency-package#virtual-items-currency-admin/admin-create-virtual-currency-package/t=request&path=&oneof=1/vc_prices). **Audience: all other audiences** * A virtual currency package can be made free — without specifying a price in real or virtual currency. This can be configured [via Publisher Account](/items-catalog/items-type/virtual-currency/#general_how_to_set_up_via_pa) or [via API calls](/items-catalog/items-type/virtual-currency/#general_how_to_set_up_via_api). Free virtual currency that is not part of a package can be created only via API calls. **End of audience: all other audiences** **Audience: Free-to-play PC games, Premium PC games, Web games** * A virtual currency package can be made free — without specifying a price in real or virtual currency. This can be configured [via your account](/items-catalog/items-type/virtual-currency/#general_how_to_set_up_via_pa_account) or [via API calls](/items-catalog/items-type/virtual-currency/#general_how_to_set_up_via_api). Free virtual currency that is not part of a package can be created only via API calls. **End of audience: Free-to-play PC games, Premium PC games, Web games** **Audience: Mobile games** * A virtual currency package can be made free — without specifying a price in real or virtual currency. This can be configured [in the account for mobile games](/items-catalog/items-type/virtual-currency/#general_how_to_set_up_via_pa_mobile_games) or [via API calls](/items-catalog/items-type/virtual-currency/#general_how_to_set_up_via_api). Free virtual currency that is not part of a package can be created only via API calls. **End of audience: Mobile games** * The amount of virtual currency in a package can be specified only as an integer. ## How to set up {#general_how_to_set_up} **Audience: all other audiences** ### Set up in Publisher Account {#general_how_to_set_up_via_pa} **End of audience: all other audiences** **Audience: Free-to-play PC games, Premium PC games, Web games, Mobile games** ### Set up in your account {#general_how_to_set_up_via_pa} **End of audience: Free-to-play PC games, Premium PC games, Web games, Mobile games** > [!NOTE] > Before setting up virtual currency or virtual currency packages, it’s recommended [to create groups](/items-catalog/catalog-features/group-items/) to help you sort items and manage how they’re displayed in your store. **Tab: Virtual currency** **Audience: all other audiences** 1. Open your project in Publisher Account and go to the [Items catalog > All items > Virtual currencies](https://publisher.xsolla.com/0/projects/0/storefront/virtual-currency) section. **End of audience: all other audiences** **Audience: Free-to-play PC games** 1. Open the project in your account and go to the [Items catalog > All items > Virtual currencies](https://xsolla.com/for/free-to-play-pc/account/0/projects/0/storefront/virtual-currency) section. **End of audience: Free-to-play PC games** **Audience: Premium PC games** 1. Open the project in your account and go to the [Items catalog > All items > Virtual currencies](https://xsolla.com/for/premium-pc-games/account/0/projects/0/storefront/virtual-currency) section. **End of audience: Premium PC games** **Audience: Web games** 1. Open the project in your account and go to the [Items catalog > All items > Virtual currencies](https://xsolla.com/for/web-games/account/0/projects/0/storefront/virtual-currency) section. **End of audience: Web games** **Audience: Mobile games** 1. Open your project in the account for mobile games and go to the [Catalog](https://xsolla.com/for/mobile-games/account/0/projects/0/storefront/virtual-currency) section. **End of audience: Mobile games** 2. Click **Create manually** and select **Virtual currency** from the drop-down list. ![create vc general](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-vc-general.svg) 3. In the **General settings** section, specify the following: 1. SKU 2. One or several groups the item should belong to (optional) 3. Name 4. Short description 5. Extended description — to add it, turn on the corresponding toggle (optional) ![create item general settings](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-general-settings.png) 4. In the **Media** section, upload one or more images or videos (optional) — from your device or via a link. In the store created with the Xsolla site editor, all item cards display the file marked as **Main**, while the remaining files are available only in item cards with a media gallery. The file marked as **Main** is also returned in the [responses of the catalog retrieval API calls](https://developers.xsolla.com/api/catalog/virtual-items-currency-catalog/get-virtual-items#virtual-items-currency-catalog/get-virtual-items/t=response&c=200&path=items/image_url). ![create item media](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-media.png) 5. In the **Price settings** section, set prices or create a free item: * To set a price, select **Paid item**, turn on the **Pricing in real currency** toggle, and specify the price. If needed, [configure regional prices](https://developers.xsolla.com/items-catalog/catalog-features/pricing-policy). * To create a free item, select **Free item**. ![create vc real price](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-vc-real-price.svg) 6. To limit the number of items available for purchase: 1. Turn on the toggle in the **Limits** section and specify the quantity. 2. Configure the limit reset frequency. To do this, select a period from the drop-down list: * **Daily**. * **Weekly**. * **Monthly**. * **Custom interval**. The interval is calculated from the item’s display start date in the store. * **No regular refresh**. 3. Set up the reset schedule by specifying the parameters that correspond to the selected period. > [!NOTE] > By default, an item is hidden from the catalog once the purchase limit is reached. If automatic limit reset is configured, the **Show item even after users reach the purchase limit** checkbox lets you keep the item visible until the next reset cycle begins. ![create item limits](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-limits.svg) 7. To configure a display time limit for the item (optional): 1. Turn on the toggle in the **Add specific display period** section. 2. Specify the time zone and the beginning and the end of the period. To leave the end of the item’s display period unspecified, turn on the **No end date** toggle. > [!NOTE] > To add another display period for the item in the catalog, click **+**. If an item has multiple display periods, each must have an end date. The display period ends at the last second of the specified minute. For example, if an end time is set to 12:00, the display period runs until 12:00:59. ![create item display](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-display.png) 8. Configure attributes using one of the following options (optional): 1. [Add attributes and their values in JSON format](https://developers.xsolla.com/items-catalog/catalog-features/item-attributes/#item_attributes_adding_json_v1). 2. [Manually create attributes and their values, and link them to items](https://developers.xsolla.com/items-catalog/catalog-features/item-attributes/#item_attributes_creation_pa). ![create item attributes](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-attributes.png) 9. If the paid item will be used in any mechanics with a random reward (e.g., loot boxes or gacha), enable the **Mark as paid randomized reward** toggle. > [!NOTE] > This parameter may be required for games distributed in countries with legal restrictions on such mechanics. 10. Click **Create**. 11. In the window that opens, select the [item status](https://developers.xsolla.com/items-catalog/catalog-features/items-availability/#items_catalog_features_items_availability) and click **Continue**. ![create item status](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-status.png) The created item will appear in the **All items** section. **Tab: Virtual currency packages** **Audience: all other audiences** 1. Open your project in Publisher Account and go to the [Items catalog > All items > Virtual currency packages](https://publisher.xsolla.com/0/projects/0/storefront/virtual-currency-package) section. **End of audience: all other audiences** **Audience: Free-to-play PC games** 1. Open the project in your account and go to the [Items catalog > All items > Virtual currency packages](https://xsolla.com/for/free-to-play-pc/account/0/projects/0/storefront/virtual-currency-package) section. **End of audience: Free-to-play PC games** **Audience: Premium PC games** 1. Open the project in your account and go to the [Items catalog > All items > Virtual currency packages](https://xsolla.com/for/premium-pc-games/account/0/projects/0/storefront/virtual-currency-package) section. **End of audience: Premium PC games** **Audience: Web games** 1. Open the project in your account and go to the [Items catalog > All items > Virtual currency packages](https://xsolla.com/for/web-games/account/0/projects/0/storefront/virtual-currency-package) section. **End of audience: Web games** **Audience: Mobile games** 1. Open your project in the account for mobile games and go to the [Catalog](https://xsolla.com/for/mobile-games/account/0/projects/0/storefront/virtual-items) section. **End of audience: Mobile games** 2. Click **Create manually** and select **Virtual currency** from the drop-down list. ![create vc pack general](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-vc-pack-general.svg) 3. In the **General settings** section, specify the following: 1. SKU 2. One or several groups the item should belong to (optional) 3. Name 4. Short description 5. Extended description — to add it, turn on the corresponding toggle (optional) ![create item general settings](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-general-settings.png) 4. In the **Media** section, upload one or more images or videos (optional) — from your device or via a link. In the store created with the Xsolla site editor, all item cards display the file marked as **Main**, while the remaining files are available only in item cards with a media gallery. The file marked as **Main** is also returned in the [responses of the catalog retrieval API calls](https://developers.xsolla.com/api/catalog/virtual-items-currency-catalog/get-virtual-items#virtual-items-currency-catalog/get-virtual-items/t=response&c=200&path=items/image_url). ![create item media](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-media.png) 5. Specify the virtual currency included in the package and its amount. 6. In the **Price settings** section, set prices or create a free item: * To set a price, select **Paid item**, turn on the **Pricing in real currency** and/or **Pricing in virtual currency** toggle, and specify the price. If needed, [configure regional prices](https://developers.xsolla.com/items-catalog/catalog-features/pricing-policy). * To create a free item, select **Free item**. > [!NOTE] > An item can have prices in several real and virtual currencies. In this case, you must specify a default currency for each type — one among the real currencies and one among the virtual currencies. > > You can specify a price in virtual currency only if the virtual currency has already been created in the project. ![create vc pack amount](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-vc-pack-amount.svg) 7. To limit the number of items available for purchase: 1. Turn on the toggle in the **Limits** section and specify the quantity. 2. Configure the limit reset frequency. To do this, select a period from the drop-down list: * **Daily**. * **Weekly**. * **Monthly**. * **Custom interval**. The interval is calculated from the item’s display start date in the store. * **No regular refresh**. 3. Set up the reset schedule by specifying the parameters that correspond to the selected period. > [!NOTE] > By default, an item is hidden from the catalog once the purchase limit is reached. If automatic limit reset is configured, the **Show item even after users reach the purchase limit** checkbox lets you keep the item visible until the next reset cycle begins. ![create item limits](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-limits.svg) 8. To configure a display time limit for the item (optional): 1. Turn on the toggle in the **Add specific display period** section. 2. Specify the time zone and the beginning and the end of the period. To leave the end of the item’s display period unspecified, turn on the **No end date** toggle. > [!NOTE] > To add another display period for the item in the catalog, click **+**. If an item has multiple display periods, each must have an end date. The display period ends at the last second of the specified minute. For example, if an end time is set to 12:00, the display period runs until 12:00:59. ![create item display](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-display.png) 9. Configure attributes using one of the following options (optional): 1. [Add attributes and their values in JSON format](https://developers.xsolla.com/items-catalog/catalog-features/item-attributes/#item_attributes_adding_json_v1). 2. [Manually create attributes and their values, and link them to items](https://developers.xsolla.com/items-catalog/catalog-features/item-attributes/#item_attributes_creation_pa). ![create item attributes](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-attributes.png) 10. If the paid item will be used in any mechanics with a random reward (e.g., loot boxes or gacha), enable the **Mark as paid randomized reward** toggle. > [!NOTE] > This parameter may be required for games distributed in countries with legal restrictions on such mechanics. 11. Click **Create**. 12. In the window that opens, select the [item status](https://developers.xsolla.com/items-catalog/catalog-features/items-availability/#items_catalog_features_items_availability) and click **Continue**. ![create item status](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-status.png) The created item will appear in the **All items** section. --------------------- ### Set up via API {#general_how_to_set_up_via_api} To set up virtual currencies, you can use the calls from the **Admin** subsection in the [Virtual items and currency](/api/catalog/virtual-items-currency-admin/admin-get-virtual-items-list/) group. > [!NOTE] > Calls from the **Admin** subsection aren’t intended for building a store catalog on the front end. You shouldn’t use them for landing pages, web stores, and in-game logics. | Task | API call | |:-----------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Create virtual currency. | [Create virtual currency](/api/catalog/virtual-items-currency-admin/admin-create-virtual-currency/). | | Get virtual currency. | [Get virtual currency](/api/catalog/virtual-items-currency-admin/admin-get-virtual-currency/). | | Get a list of virtual currencies. | [Get list of virtual currencies](/api/catalog/virtual-items-currency-admin/admin-get-virtual-currencies-list/). | | Update virtual currency. | [Update virtual currency](/api/catalog/virtual-items-currency-admin/admin-update-virtual-currency/). | | Delete virtual currency. | [Delete virtual currency](/api/catalog/virtual-items-currency-admin/admin-delete-virtual-currency/). | | Limit the amount of virtual currency available for purchase. | In the [Create virtual currency](/api/catalog/virtual-items-currency-admin/admin-create-virtual-currency/) or [Update virtual currency](/api/catalog/virtual-items-currency-admin/admin-update-virtual-currency/) API calls pass the following parameters: - `limits` — specifies the maximum quantity of virtual currency available for purchase. - `limits.recurrent_schedule` — defines how often the limit resets. | | Create a virtual currency package. | [Create virtual currency package](/api/catalog/virtual-items-currency-admin/admin-create-virtual-currency-package/). | | Get a virtual currency package. | [Get virtual currency package](/api/catalog/virtual-items-currency-admin/admin-get-virtual-currency-package/). | | Get a list of virtual currency packages. | [Get list of virtual currency packages](/api/catalog/virtual-items-currency-admin/admin-get-virtual-currency-packages-list/). | | Update a virtual currency package. | [Update virtual currency package](/api/catalog/virtual-items-currency-admin/admin-update-virtual-currency-package/). | | Delete a virtual currency package. | [Delete virtual currency package](/api/catalog/virtual-items-currency-admin/admin-delete-virtual-currency-package/). | | Limit the number of virtual currency packages available for purchase. | In the [Create virtual currency package](/api/catalog/virtual-items-currency-admin/admin-create-virtual-currency-package/) or [Update virtual currency package](/api/catalog/virtual-items-currency-admin/admin-update-virtual-currency-package/) API calls pass the following parameters: - `limits` — specifies the maximum quantity of virtual currency packages available for purchase. - `limits.recurrent_schedule` — defines how often the limit resets. | > [!NOTE] > For more information about limits, see the following guides: > * [Number limited offers](/items-catalog/catalog-features/items-catalog-number-limits/). > * [Time limit for displaying items in store](/items-catalog/catalog-features/limiting-display-time/#shop_builder_how_to_limit_display_time). > * [Regional sales restrictions](/items-catalog/catalog-features/regional-restrictions/). > * [Local prices](/items-catalog/catalog-features/pricing-policy/). > * [Managing item availability in catalog](/items-catalog/catalog-features/items-availability/#items_catalog_features_items_availability). > [!NOTE] > The display period for virtual currency in the store can be configured only using API calls. ## Display virtual currency in catalog {#how_to_display_virtual_currency} The display of virtual currency or virtual currency packages depends on how the catalog is implemented — [through the site editor](#general_how_to_display_via_site_builder) or [via API](#how_to_display_virtual_currency_via_api). ### Display via site editor {#general_how_to_display_via_site_builder} > [!NOTE] > Only virtual currency packages can be displayed in the store catalog. To display virtual currency package: **Audience: all other audiences** 1. [Create virtual currency package](/items-catalog/items-type/virtual-currency/#general_how_to_set_up_via_pa). 2. In your project in Publisher Account, go to the [Storefronts > Websites](https://publisher.xsolla.com/0/projects/0/site-builder) section. 3. Click the pane of the desired site. ![virtual items sb 1](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/virtual-items-sb-1.svg) **End of audience: all other audiences** **Audience: Free-to-play PC games** 1. [Create virtual currency package](/items-catalog/items-type/virtual-currency/#general_how_to_set_up_via_pa_account). 2. In the project in your account, go to the [Storefronts > Websites](https://xsolla.com/for/free-to-play-pc/account/0/projects/0/site-builder) section. 3. Click the pane of the desired site. **End of audience: Free-to-play PC games** **Audience: Premium PC games** 1. [Create virtual currency package](/items-catalog/items-type/virtual-currency/#general_how_to_set_up_via_pa_account). 2. In the project in your account, go to the [Storefronts > Websites](https://xsolla.com/for/premium-pc-games/account/0/projects/0/site-builder) section. 3. Click the pane of the desired site. **End of audience: Premium PC games** **Audience: Web games** 1. [Create virtual currency package](/items-catalog/items-type/virtual-currency/#general_how_to_set_up_via_pa_account). 2. In the project in your account, go to the [Storefronts > Websites](https://xsolla.com/for/web-games/account/0/projects/0/site-builder) section. 3. Click the pane of the desired site. **End of audience: Web games** **Audience: Mobile games** 1. [Create virtual currency package](/items-catalog/items-type/virtual-currency/#general_how_to_set_up_via_pa_mobile_games). 2. In your project in the account for mobile games, go to the [Web Shop](https://xsolla.com/for/mobile-games/account/0/projects/0/site-builder) section. 3. Click the pane of the desired site. ![open site in builder](https://cdn.xsolla.net/developers/current/images/guides/site-builder/open-site-in-builder.svg) **End of audience: Mobile games** 4. If your site includes multiple pages, select the one you need: a. Click the current page title at the top of the editor. b. Select the necessary page from the drop-down list. 5. In the **Store** block section, select the virtual currency package you want to sell on the website in the **Item type** field. ![virtual currency sb 2](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/virtual-currency-sb-2.svg) 6. [Set an item card layout](/solutions/web-shop/create-web-shop/create-site/#web_shop_guide_create_site_with_auth_store). 7. After making all necessary changes and preparing your website for launch: a. In the upper-right corner of the site editor, click **Publish**. b. Check the boxes next to the pages you want to publish. c. Click **Publish**. > [!NOTE] > If website publication is not available, make sure all the conditions are met: > * There are no empty sections on the website (marked with a red indicator). > * [The licensing agreement with Xsolla has been signed](/get-started/work-in-pa/legal-aspects/). > * The main page is published or selected for publication. You cannot publish child pages before the main page. 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](/items-catalog/items-type/virtual-currency/#general_how_to_set_up_via_pa). ### Get virtual currency information via API {#how_to_display_virtual_currency_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](/api/catalog/virtual-items-currency-admin/admin-get-virtual-items-list/) group. | Task | API call | |:-----------------------------|:-----------------------------------------------------------------------------------------------------------------| | Get virtual currency by SKU. | Pass the `virtual_currency_sku` parameter to the [Get virtual currency by SKU](/api/catalog/virtual-items-currency-catalog/get-virtual-currency-sku/) API call. | | Get a virtual currency list. | [Get virtual currency list](/api/catalog/virtual-items-currency-catalog/get-virtual-currency/). | | Get a virtual currency package by SKU. | Pass the `virtual_currency_package_sku` parameter to the [Get virtual currency package by SKU](/api/catalog/virtual-items-currency-catalog/get-virtual-currency-package-sku/) API call. | | Get a virtual currency package list. | [Get virtual currency package list](/api/catalog/virtual-items-currency-catalog/get-virtual-currency-package/). | ## Grant virtual currency to users {#how_to_grant_virtual_currency} 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](/items-catalog/catalog-management/import-catalog-external/), 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](/webhooks/combined-webhooks/successful-order-payment/) webhook. Refer to the [Set up order status tracking](/virtual-goods/own-ui/server-side-token-generation/set-up-order-tracking/#payments_integration_order_tracking) section for more details on this and other methods of retrieving purchase data.