# Backpack API & Webhooks # Overview Welcome to the Backpack API, an essential tool to enhance your item-selling strategy and promotional campaigns. With Backpack, users can store information about the items they purchased or received for free. When receiving items, users don’t need to use their game ID or go to the game from the distributor site — they can keep items in the Backpack and redeem them later. All items purchased or received for free on the distributor website are available to the user in the Metaframe widget or [Xsolla Wallet](https://account.xsolla.com/backpack). User flow: 1. The user visits the distribution site. 2. The user logs in through the Xsolla account in the Metaframe widget. 3. The user purchases the item or gets it for free and selects the option to move the item to the Backpack. 4. Information about the received item is transferred to the Backpack. 5. In the Metaframe widget or Xsolla Wallet, the user opens the **Backpack** section and selects the item. 6. The user receives the item. 7. Information about the received item is transferred to the game. ## Features - **Item Storage:** Users can store information about items purchased or received for free. - **Redemption Flexibility:** Items stored in the Backpack can be redeemed at the user's convenience. ## Getting Started To get started with Backpack, check out our detailed guide on [Setting up Backpack](/doc/metaframe). This guide will walk you through the process of configuring Backpack to suit your needs. ## Key Entities Backpack revolves around three major entities: 1. **Items:** The core entities that can be distributed to users. 2. **Game:** The entity designed to combine items. 3. **Backpack:** The entity designed to to grant user items in the game. # Authorization To interact with the Backpack API, you need to set up authorization. For authorization, you have to provide 2 kinds of headers: 1. X-HOST-ID header. 2. Authorization header. ## X-HOST-ID header It is a unique header issued by Xsolla. To obtain it, please contact the integration team at integration@xsolla.com or your Customer Success Manager at csm@xsolla.com. Provide them with the project ID and merchant ID. You can find the merchant ID parameter in your Publisher Account: - 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//`. You can find the project ID parameter in your Publisher Account next to the name of the project.
Note

Keep X-HOST-ID confidential, as it is part of the authentication key.
## Authorization header Set up user authentication via Xsolla account on Xsolla Wallet by following this [guide](/doc/metaframe/integration-guide/set-up-xsolla-account-login/). This process involves actions in the Publisher Account and assistance from our integration team. Once the Xsolla account client is set up, use [this endpoint](/api/login/operation/generate-jwt/) to generate a token. The token is valid for 1 hour, after which you'll need to invoke the endpoint again for a new token. Use the obtained token by providing the Authorization header with the Bearer token string. # Webhooks Webhook notifications associated with the Backpack are listed under the Webhooks tag. For more in-depth information about working with webhooks, refer to our [main webhook documentation](https://developers.xsolla.com/webhooks/overview/#section/Overview). To set up webhooks: 1. Open your project in the [Publisher Account](https://publisher.xsolla.com/). 2. Click **Project settings** in the side menu and navigate to **Webhooks**. 3. Specify the URL where you want to receive webhooks in the `https://example.com` format. 4. A secret key to sign project webhooks is generated by default. To generate a new secret key, click the refresh icon. 5. Click **Enable webhooks**. If you have set up a [Metaframe webhook](/doc/metaframe/wallet/metaframe-webhooks/), please contact the integration team at [integration@xsolla.com](mailto:integration@xsolla.com) or your Customer Success Manager at [csm@xsolla.com](mailto:csm@xsolla.com). They will assist you in setting up a second webhook for the project. Version: 1.0.0 ## Servers ``` https://metaframe.xsolla.com ``` ## Security ### bearer For details check the Authorization section in the left menu. Type: http Scheme: bearer Bearer Format: JWT ## Download OpenAPI description [Backpack API & Webhooks](https://developers.xsolla.com/_bundle/@l10n/ja/api/backpack/index.yaml) ## Game Operations related to creating and updating game entities. Game entities are used to combine and sort items. ### Create game - [POST /web/backpack/merchants/{merchantId}/projects/{projectId}/games](https://developers.xsolla.com/ja/api/backpack/game/create-game.md): Creates a game entity for a specified project. ### Get games - [GET /web/backpack/merchants/{merchantId}/projects/{projectId}/games](https://developers.xsolla.com/ja/api/backpack/game/get-games.md): Retrieves external IDs and names of the created game entities. ### Update game - [PUT /web/backpack/merchants/{merchantId}/projects/{projectId}/games](https://developers.xsolla.com/ja/api/backpack/game/update-game-details.md): Updates game entity details ## Items Operations for creating, managing, and distributing items to users via Backpack. Items are the core entities associated with games. ### Create game keys - [POST /web/backpack/merchants/{merchantId}/projects/{projectId}/user/{userId}/game_keys](https://developers.xsolla.com/ja/api/backpack/items/create-game-keys.md): Creates a list of game keys and adds them to Backpack of the specified user. ### Create promo codes - [POST /web/backpack/merchants/{merchantId}/projects/{projectId}/user/{userId}/promo_codes](https://developers.xsolla.com/ja/api/backpack/items/create-promo-codes.md): Creates a list of promo codes with items and adds them to Backpack of the specified user. To get items created using this method, the user copies the promo code from Backpack and enters it on the gaming platform or in the game. ### Create virtual currency - [POST /web/backpack/merchants/{merchantId}/projects/{projectId}/user/{userId}/virtual_currency](https://developers.xsolla.com/ja/api/backpack/items/create-virtual-currency.md): Creates a list of virtual currency packages and adds them to Backpack of the specified user. ### Create virtual items - [POST /web/backpack/merchants/{merchantId}/projects/{projectId}/user/{userId}/virtual_items](https://developers.xsolla.com/ja/api/backpack/items/create-virtual-items.md): Creates a list of virtual items and adds them to Backpack of the specified user. ### Get user's Backpack items - [GET /web/backpack/merchants/{merchantId}/projects/{projectId}/users/{userId}/items](https://developers.xsolla.com/ja/api/backpack/items/user-backpack-items-list.md): Returns the list of items from Backpack of a specified user. Items can be game keys, virtual items, and virtual currency. ### Delete item from Backpack - [DELETE /web/backpack/merchants/{merchantId}/projects/{projectId}/users/{userId}/items/{itemId}](https://developers.xsolla.com/ja/api/backpack/items/delete-item.md): Deletes the specified item from Backpack of the specified user. ## Webhooks Various events and notifications related to Backpack functionality, such as player validations and item redemptions. ### Player ID validation (deprecated) - [POST user-validation](https://developers.xsolla.com/ja/api/backpack/webhooks/user-validation.md): This webhook is deprecated. Xsolla sends the User validation webhook instead. Xsolla sends a webhook with the user_validation type to the webhook URL to verify that a player is registered in the game. The request is sent before moving virtual items or currency to the game process. ### Move item to game (deprecated) - [POST move-item-to-game](https://developers.xsolla.com/ja/api/backpack/webhooks/move-item-to-game.md): This webhook is deprecated. Xsolla sends the Successful payment for order webhook instead. Xsolla sends a webhook with the move_to_game type to the webhook URL to deliver the item to player in the game. ## Backpack Endpoints for granting users items from their Backpack, including game keys, virtual items, and virtual currency. ### Get user's Backpack items - [GET /web/backpack/items](https://developers.xsolla.com/ja/api/backpack/user/get-user-backpack-items.md): Returns the list of items from user's Backpack. Items can be game keys, virtual items, and virtual currency. ### Get user's Backpack item - [GET /web/backpack/items/{itemId}](https://developers.xsolla.com/ja/api/backpack/user/get-user-backpack-item.md): Returns a specified item from the user's Backpack. The item can be a game key, a virtual item and a virtual currency. ### Move user's virtual currency to game - [POST /web/backpack/virtual_currency/move_to_game](https://developers.xsolla.com/ja/api/backpack/user/move-user-virtual-currency-to-game.md): Grants the user virtual currency from Backpack in the game. ### Moves user's virtual currency to Xsolla Wallet - [POST /web/backpack/virtual_currency/receive](https://developers.xsolla.com/ja/api/backpack/user/move-user-virtual-currency-to-wallet.md): Grants the user virtual currency from Backpack in Xsolla Wallet. ### Move user's virtual item to game - [POST /web/backpack/virtual_items/move_to_game](https://developers.xsolla.com/ja/api/backpack/user/move-user-virtual-item-to-game.md): Grants the user virtual item from Backpack in the game.