Digital Distribution Hub

Overview

Digital Distribution Hub is a solution that connects game developers with multiple distribution partners that have their own platforms or ecosystems for the distribution of games, virtual items, virtual currency, and bundles.

Distribution partners — digital platforms or ecosystems that can distribute games and in-game items and have their own storefront and billing. Examples of Xsolla distribution partners:

  • super apps that bundle multiple services
  • banking applications
  • telecom & internet service providers
  • cash kiosks
  • cashback and reward program providers
  • e-commerce marketplaces

Benefits for the game developer:

  • Expanding games’ audience through a direct connection to fast-growing distribution partners.
  • Increasing revenue by adding games to new distribution channels with a unique user base.
  • Boosting organic discoverability on third-party platforms through ads and banners.

Benefits for the distribution partner:

  • Increasing the loyalty of your users by expanding access to game content. Users can purchase game keys, virtual items, virtual currency, and bundles directly from the app or service.
  • Retention of current and attracting new users through the growing popularity of the gaming industry.
  • Increasing income from the commission of the sale of game keys, virtual items, and virtual currency from major publishers in the gaming industry.

How it works

User flow when purchasing game keys

User flow when purchasing virtual items and virtual currency

Interaction flow

  1. The game developer creates a project in Publisher Account and uploads the game keys, virtual items, virtual currency, and bundles.
  2. A distribution partner requests user data:
    • when selling games — the user’s email address to which the keys and receipt will be sent
    • when selling in-game items — the in-game ID of the user to whom the items will be added, and the user’s email address to which the receipt will be sent
  3. The user enters the following data in the distribution partner interface:
    • for game purchases — the email address to receive the keys and receipt
    • for in-game items purchases — in-game ID to add the items to the inventory and an email address to receive the receipt
  4. The distribution partner calls the Create user token method and passes the email address (required) and user ID (required when selling virtual items, virtual currency, and bundles) as parameters.
  5. Xsolla checks if the user exists in the game if the game developer has webhooks set up. Setting up webhooks is required for the sale of virtual items and virtual currency, but optional for game keys.
  6. Xsolla creates a token with user data and sends the token to the distribution partner.
  7. The distribution partner requests a game catalog or in-game items catalog.
  8. Xsolla returns the requested catalog in the response.
  9. The distribution partner receives the catalog and displays it to the user.
  10. The user makes a purchase. The distribution partner creates a cart.
  11. The distribution partner sends the user’s cart to create an order.
  12. Xsolla returns the order ID and the cart price including discounts and taxes.
  13. The distribution partner displays the total cost of the cart to the user.
  14. If the user continues with the payment, the distribution partner debits the user’s funds and displays the payment status page.
  15. The distribution partner notifies Xsolla that the order has been paid for and sends payment information.
  16. Xsolla notifies the game developer of the purchase.
  17. The user, who bought the game, receives an email with the purchase details and can activate the game keys. If the user bought virtual items or virtual currency, it is added to his inventory.

Integration on the game developer side

How to connect the Digital Distribution Hub

To promote your game through distribution channels:
  1. Connect Store in Publisher Account and download:
  2. Set up webhooks.
  3. Contact your Customer Success Manager or email csm@xsolla.com to activate Digital Distribution Hub for your project.
Note
If you are not an Xsolla partner yet, but are interested in cooperation and connecting the Digital Distribution Hub, please email business@xsolla.com.

How to set up webhooks

Webhook setup is required:

To set up webhooks:

  1. Open your project in Publisher Account.
  2. Click Project settings in the side menu and go to Webhooks.
  3. Set the Webhooks toggle to On.
  4. Specify the webhook URL.
  5. A secret key to sign project webhooks is generated by default. If you want to generate a new secret key, click refresh icon.
  6. Click Save settings.

Note
You must set up webhooks for the distribution of virtual items and virtual currency. Without webhooks, in-game items cannot be added to a user’s inventory.

User validation

Xsolla sends a User validation webhook to verify that a user exists in the game. User validation allows you to:

  • display a personalized catalog for the user if you pass user attributes in the response
  • add items to the user’s inventory after purchase

To confirm receipt of the webhook, your server should return:

  • HTTP code 204 without a message body, if the user exists in the game
  • HTTP code 400 describing the problem, if the specified user was not found or if an invalid signature was passed

The full list and mechanism of webhooks, including examples, is described in detail in the API Reference.

In response, you can pass additional transaction parameters in the custom_parameters object.

Copy
Full screen
Small screen
    {
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "user_attributes": {
        "type": "object",
        "required": false,
        "minProperties": 1,
        "maxProperties": 100,
        "patternProperties": {
          "^[\\w-_.]{1,255}$": {
            "oneOf": [
              {
                "type": "integer"
              },
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 255
              },
              {
                "type": "array",
                "items": {
                  "type": "string",
                  "maxLength": 255
                },
                "minItems": 1,
                "maxItems": 1000
              }
            ]
          }
        },
        "additionalProperties": false
      }
    }
    }
    

    Example of the response:

    Copy
    Full screen
    Small screen
    
    {
      "user_attributes": {
        "age": 18,
        "level": 1,
        "game": "WoW",
        "is_baned": false,
        "registration_date": "2022-01-01"
      }
    }
    

    Transaction’s ID linking

    If you are using an external ID (transaction ID on your system) and want to associate it with a transaction ID on Xsolla’s side or pass additional transaction parameters, implement the following webhook processing:
    Copy
    Full screen
    Small screen
      {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "notification_type": {
            "type": "string"
          },
          "order_id": {
            "type": "integer"
          },
          "project_id": {
            "type": "integer"
          },
          "user": {
            "type": "object",
            "properties": {
              "external_id": {
                "type": "string"
              },
              "email": {
                "type": "string"
              }
            }
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "item_id": {
                  "type": "integer"
                },
                "sku":  {
                  "type": "string"
                },
                "quantity": {
                  "type": "integer"
                },
                "type": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
      

      Example of the request:

      Copy
      Full screen
      Small screen
      
      {
        "notification_type": "create_external_transaction",
        "order_id": 1,
        "project_id": 51336,
        "user": {
          "external_id": "user_id",
          "email": "public_email@test.com"
        },
        "items": [
          {
            "item_id": 101,
            "sku": "mithril_dagger",
            "quantity": 2,
            "type": "virtual_good"
          }
        ]
      }
      

      In response, you can pass additional transaction parameters in the custom_parameters object.

      Expected response:

      Copy
      Full screen
      Small screen
        {
          "id": "validation_transaction_info_response.json",
         "$schema": "http://json-schema.org/draft-07/schema#",
         "description": "DDH Project Transaction Info Response",
         "type": "object",
         "additionalProperties": true,
         "properties": {
           "id": {
             "type": "string",
             "minLength": 1
           },
          "custom_parameters": {
             "type": "object",
             "additionalProperties": true,
             "minProperties": 1,
             "maxProperties": 200
           }
         }
        }
        

        Example of the response:

        Copy
        Full screen
        Small screen
        
        {
            "id":"123"
        }
        

        List of webhook parameters for linking transaction IDs:

        ParameterTypeDescription
        notification_type
        stringType of notification.
        order_id
        integerOrder ID.
        project_id
        integerID of the project where game keys or bundles with game keys, in-game items or bundles with in-game items are loaded.
        user.external_id
        stringUser ID on the game developer’s side.
        items
        stringList of items the user has purchased.
        items.sku
        stringItem’s unique identifier.
        items.quantity
        integerQuantity of items.
        items.type
        stringItem type. Accepts virtual_good, virtual_currency, physical_good, unit values. unit type is used for games.
        items.unit_items
        arrayArray with game data.
        items.unit_items.type
        stringItem type for game key package. Accepts the game_key value.
        items.unit_items.sku
        stringUnique identifier for game key package. For a game on a specific platform, the value is in the sku_drm format. Example for a game with sku 110101 on Steam: “sku”: “110101_steam”.

        Purchase notification

        After the user pays for the purchase, you get:

        Integration on the distribution partner's side

        If you are interested in integrating the Digital Distribution Hub, please email the integration manager at psbusiness@xsolla.com and get the required parameters to work with the Digital Distribution Hub API:

        During integration, you need to send notifications about successful payments or payment cancellations (step 9). To correctly process the notifications on Xsolla’s side, please inform your manager of the server IP address from which you send the notifications. If the IP address changes, make sure to inform the manager as soon as possible.

        Note
        Distributor partners do not need to create an account in Publisher Account to work with the Digital Distribution Hub API. Creating an account in Publisher Account is necessary for game developers to work with API methods for selling game keys and in-game items.
        To distribute games in your app or service, implement the following game purchase logic:
        1. Display a form for entering:
          • the user’s email address — when selling games
          • the user’s email address and in-game ID — when selling in-game items
        Note
        The email address field must be required when selling games and selling in-game items. Xsolla sends the user a receipt with information about the payment to the specified email address.

        1. The user ID is used for projects that sell virtual items, virtual currency, and bundles with items and currency. In this case, it is also necessary to display a hint for the user to enter the ID that he received when registering in the game.

        1. Example:

        1. Pass the received user data:
          • User’s email address. Always required.
          • User’s in-game ID. Required when selling in-game items.

        1. The data is used to verify the existence of the user in the game and receive an authorization token.

        1. Use the Create user token method. Pass parameters in the request:
        ParameterTypeDescription
        project_id
        integerID of the project where game keys or bundles with game keys, in-game items or bundles with in-game items are loaded.
        user.email
        stringUser email address.
        user.id
        string or nullUnique user identifier in the game.

        1. An authorization token with user data is returned in the response.

        1. Import:

        1. In the request pass the token you received in step 2 and the following parameter:
        ParameterTypeDescription
        project_id
        integerID of the project where game keys or bundles with game keys, in-game items or bundles with in-game items are loaded.

        1. Display the games and in-game items catalog on your storefront. In the interface implement the ability to select:
          • the number of game keys and game publishing platforms
          • the number of virtual items
          • the number of virtual currency or virtual currency packages with a fixed amount of currency
          • the number of bundles

        1. If you use a cart, the number of items can be specified in the user’s cart. If you do not use a cart, the choice of the number of items can be implemented in the catalog.

        1. Example for specifying the number of items in the cart:
        1. Example for specifying the number of items in the catalog:

        1. If you don’t use a cart, go to step 6 and use the Create order with specified item method.

        1. To fill the cart, use the Fill the cart with items method.

        1. The user can add and remove items, or change their quantity in one order. You can use the following to update the cart:

        1. In this case, use Get current user’s cart after updating the cart.

        1. Pass the following parameters in requests for cart filling and updating methods:
        ParameterTypeDescription
        project_id
        integerID of the project where game keys or bundles with game keys, in-game items or bundles with in-game items are loaded.
        items.sku
        stringUnique item identifier specified by game developer in the Publisher Account.
        items.quantity
        integerQuantity of items.
        items.type
        stringItem type. Accepts virtual_good, virtual_currency, physical_good, unit values. unit type is used for games.
        items.unit_items
        arrayArray with game data.
        items.unit_items.type
        stringItem type for game key package. Accepts the game_key value.
        items.unit_items.sku
        stringUnique identifier for game key package specified by game developers in Publisher Account. For a game on a specific platform, the value is in the sku_drm format. Example for a game with sku 110101 on Steam: “sku”: “110101_steam”.

        1. After calling Fill the cart with items or Get current user’s cart, the response returns updated information about the selected products — prices before and after discounts, bonus products.

        1. To create an order and pay for items in a cart, use Create order with all items from current cart method. Pass the following parameters in the request:
        ParameterTypeDescription
        project_id
        integerID of the project where game keys or bundles with game keys, in-game items or bundles with in-game items are loaded.
        geotype
        numberDistributor partner ID on the Xsolla side.
        currency
        stringCurrency of the order. Virtual currency uses the SKU and real currency uses a three-letter ISO 4217 code.
        1. The response returns the order ID and the cart price including taxes.
        Note
        You can use the Create order with specified item method to create an order without creating a cart. In this case, users can buy only one type of item.

        1. Display the total cart price to the user.
        2. Debit user funds from your platform. Display the payment status to the user.
        3. Send Pay notification. If the payment was refunded or not completed, send a notification about payment cancellation.

        1. To correctly process notifications on Xsolla’s side, please inform your Xsolla manager of the server IP address from which you send the notifications. If the IP address changes, make sure to inform the manager as soon as possible.
        Was this article helpful?
        Thank you!
        Is there anything we can improve? Message
        We’re sorry to hear that
        Please explain why this article wasn’t helpful to you. Message
        Thank you for your feedback!
        We’ll review your message and use it to help us improve your experience.
        Last updated: October 3, 2024

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