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 game, virtual items, and virtual currency distribution.

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:

  • Expands games' audience through direct connection to fast-growing distribution partners.
  • Increase revenue by adding the game 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 will be able to 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 due to the commission from the sale of game keys, virtual items and virtual currency of the largest players in the gaming industry market.

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:
    • the user’s email address to which the keys will be sent
    • the in-game ID of the user to whom the items will be added
  3. The user in the interface of the distribution partner enters the email address to receive the keys or user ID to receive items.
  4. Distribution partner calls the Create user token and passes the email address or user ID as parameters.
  5. Xsolla checks if the user exists in the game, if the game developer has webhooks enabled. The inclusion of webhooks for the sale of game keys is optional. However, it is required for the sale of virtual items and virtual currency.
  6. Xsolla creates a token with user data and sends the token to a distribution partner.
  7. A 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 game purchase. Distributor 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 game in the cart to the user.
  14. If the user continues to pay, 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 Account Manager or email am@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 enable 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 use connecting 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 parameters when validating the user, 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", "null"]
              }
            }
          },
          "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": null
        },
        "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
        arrayItem’s unique ID. Items with the game_key type use the value in the sku_drm format.
        items.type
        arrayItems type. It can have the following values: virtual_good, virtual_currency, game_key, physical_good.
        items.quantity
        integerQuantity of items.

        Purchase notification

        After the user pays for the purchase, you get:

        Integration on the distribution partner 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:

        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 or in-game items in your app or service, implement the following game purchase logic:

        1. Display a form for entering the user’s email address or user ID in-game.
          The email address is used for projects that sell game keys and game key bundles. In this case, it is also necessary to implement in the interface the possibility for the user to select DRM.
          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. For example:

        1. Pass the received email address or user ID to check if the user exists in the game and receive an authorization token. 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. In the response will return an authorization token with user data.

        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
          • the number of in-game 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 quantity of the item can be specified in the user’s cart. If you do not use a cart, the choice of the quantity of items can be implemented in the catalog.

        1. Example for specifying the quantity of items in the cart:

        1. Example for specifying the quantity 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
        stringItem’s unique ID. Items with the game_key type use the value in the sku_drm format.
        items.quantity
        integerQuantity of items.

        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 and 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.
        payment.amount
        integerAmount of payment.
        order_id
        integerOrder ID.
        ps_transaction_id
        stringTransaction ID on the distribution partner’s side.
        Note
        If the payment was refunded or not completed, send a notification about payment cancellation.
        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.
        Rate this page
        Rate this page
        Is there anything we can improve?

        Don’t want to answer

        Thank you for your feedback!
        Last updated: April 18, 2023

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