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

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 Customer Success Manager or email csm@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 add purchased in-game items 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 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.

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

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

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

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

• 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'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:

• geotype
• project_id
• distribution_hub_id and api_key

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.

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

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:

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

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

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

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