Grant purchases to user

Implement granting purchases to the user in your application using information received in the webhooks from Xsolla about the transaction details and purchased items.

To switch to the new option with receiving combined webhooks, contact your Customer Success Managers or email to csm@xsolla.com.

For the full operation of the in-game store and payment management, it is necessary to implement the processing of the main webhooks:

• If you receive combined webhooks
• If you receive separate webhooks

Webhook name	Description
User validation > User validation (user_validation)	Is sent at different stages of the payment process to ensure the user is registered in the game.
Game services > Combined webhooks > Successful payment for order (order_paid)	It contains payment data, transaction details, and information about purchased items. Use the data from the webhook to add items to the user.
Game services > Combined webhooks > Order cancellation (order_canceled)	It contains data of the canceled payment, transaction details, and information about purchased items. Use the data from the webhook to remove the purchased items.

The scheme below shows the process of purchasing and returning items using combined webhooks.

Webhook name	Description
User validation > User validation (user_validation)	Is sent at different stages of the payment process to ensure the user is registered in the game.
Payments > Payment (payment)	It contains payment data and transaction details.
Game services > Separate webhooks > Successful payment for order (order_paid)	It contains information about purchased items and the transaction details. Use the data from the webhook to add items to the user.
Payments > Refund (refund)	It contains payment data and transaction details.
Game services > Separate webhooks > Order cancellation (order_canceled)	It contains information about the purchased items and the ID of the canceled transaction. Use the data from the webhook to remove the purchased items.

The scheme below shows the process of purchasing and returning items using separate webhooks.

If item catalog personalization is implemented on your application’s side, set up processing of Catalog personalization on the partner’s side.

Set up webhooks in Publisher Account

1. Open your project in Publisher Account.
2. Click Project settings in the side menu and go to the Webhooks tab.
3. In the Webhook server field, specify the URL of your server where you want to receive webhooks in the https://example.com format. You can also specify the URL you find in a tool for testing webhooks.
4. A secret key to sign project webhooks is generated by default. If you want to generate a new secret key, click the refresh icon.
5. Click Enable webhooks.

Test webhooks in Publisher Account

If webhooks are set up successfully, a webhook testing block is displayed below the webhook setup block.

The testing section in the Publisher Account varies depending on the webhook receiving option.

In the absence of real values, you can enter arbitrary values.

You also can test webhooks when making purchases in the sandbox or live mode. Testing Refund is available only in live mode.

Sending responses to webhook

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

• 200, 201, or 204 HTTP code in case of a successful response.
• 400 HTTP-code with description of the problem if the specified user was not found or an invalid signature was passed.

Your webhook handler may also return a 5xx code in case of temporary issues on your server.

Next steps

1. Implement getting subscription information.
2. Set up user authentication.

Configuring item information in webhooks

You can configure which item data is included in the Successful payment for order and Order cancellation webhooks via the items array.

Enabling additional parameter inclusion

Enable the inclusion of additional parameters that indicate:

• whether the item is free (is_free)
• whether the item is a bonus (is_bonus)
• whether the item is part of a bundle (is_bundle_content)

To receive these parameters, you must switch your webhooks to version 2 using the Update information about webhook settings API call. In version 1 (default), these parameters are not available.

Example of an items array with additional parameters:

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "Is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      },
14      {
15        "sku": "com.xsolla.gold_1",
16        "type": "virtual_currency",
17        "is_pre_order": false,
18        "is_free": false,
19        "is_bonus": false,
20        "is_bundle_content": true,
21        "quantity": 1500,
22        "amount": "[null]",
23        "promotions": []
24      }
25 ],

Disabling bundle content inclusion

By default, webhooks include all items from the bundle as a list of individual items. You can configure the webhook to include only the bundle itself, without listing its contents.

In this case, the items included in the bundle are not included in the items array. In the array shown above, the item with the SKU com.xsolla.gold_1, which is part of the bundle, is excluded.

Example of the items array when bundle content is disabled:

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "Is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      }
14 ],

To disable bundle content inclusion, contact your Customer Success Manager or email to csm@xsolla.com.

Useful links

Integration flow