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:
   • game keys or game key bundles, if you sell game keys
   • virtual items, virtual currency or bundles, if you sell in-game items
2. Set up webhooks.
3. Contact your Account Manager or email am@xsolla.com to activate Digital Distribution Hub for your project.

How to set up webhooks

Webhook setup is required:

• to validate the user and personalize the catalog by user ID in the game
• to validate the user and adding purchased virtual items and virtual currency to his inventory
• to link the transaction ID on Xsolla’s side with the transaction ID in the game developer’s system
• to pass additional user parameters in the order
• to receive purchase notifications

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.

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.

{
"$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:

{
  "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:

{
  "$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:

{
  "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:

{
  "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:

{
    "id":"123"
}

List of webhook parameters for linking transaction IDs:

Purchase notification

After the user pays for the purchase, you get:

• The payment webhook that contains payment information.
• The cart’s content webhook, which contains information about the items to be added to the inventory.

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:

• geotype
• project_id
• distribution_hub_id and api_key

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:

2. 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:

1. In the response will return an authorization token with user data.

3. Import:
   • games catalog, using the Get games list method
   • virtual items catalog, using the Get virtual items list method
   • virtual currency catalog, using the Get virtual currency list method
   • bundles with games or in-game items catalog, using the Gets a list of bundles method

1. In the request pass the token you received in step 2 and the following parameter:

4. 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.

5. 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:
   • Fill the cart with items method every time the user changes the contents of the cart
   • methods for updating the cart and deleting an item:
     • Update cart item from current cart
     • Delete all cart items from current cart
     • Delete cart item from current 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:

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.

6. 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:

1. The response returns the order ID and the cart price including taxes.

7. Display the total cart price to the user.
8. Debit user funds from your platform. Display the payment status to the user.
9. Send Pay notification and pass the following parameters in the request:

Rate this page

Is there anything we can improve? Send

Don’t want to answer

Thank you for your feedback!