Set up order status tracking
To grant items to the user, you need to make sure that the payment was successful.
To track the status of created orders and validate them, you will need to configure webhooks processing on the server side of your application.
2 webhook receiving options have been set up on Xsolla’s side when purchasing and returning items — information with payment and transaction data and information about purchased items can come separately or can be combined into one webhook.
More information on webhook receiving options
Receiving information in combined webhooks:
If you registered in Publisher Account after January 22, 2025, you receive all the information in the Successful payment for order (order_paid
) and Order cancellation (order_canceled
) webhooks. In this case, you do not need to process the Payment (payment
) and Refund (refund
) webhooks.
Receiving information in separate webhooks:
If you registered in Publisher Account on or before January 22, 2025, you receive the following webhooks:
- Payment (
payment
) and Refund (refund
) with information about payment data and transaction details. - Successful payment for order (
order_paid
) and Order cancellation (order_canceled
) with information about purchased items.
You need to process all incoming webhooks.
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:
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.
- Payment, Successful payment for order, and User validation if you receive separate webhooks
- Successful payment for order, and User validation if you receive combined webhooks
For the full list of webhooks and general information about working with them, refer to the webhooks documentation.
Set up webhooks sending
To configure webhooks on the Xsolla side:
- Open your project in Publisher Account and go to the Payments > Webhooks section.
- In the Webhook server field, specify the URL to which Xsolla will send webhooks.
https://example.com
format. HTTPS protocol is required to transfer data; HTTP protocol is not supported.- Click Enable webhooks.
Add webhook listener
Webhook listener is program code that allows receiving incoming webhooks at a specified URL address, generating a signature, and sending a response to the Xsolla webhook server.
Generation of signature
When receiving a webhook, you should ensure the security of data transmission. To achieve this, a signature must be generated from the webhook data and verified that it matches the signature sent in the HTTP request header.
To generate a signature:
- Concatenate the JSON from the request body and the project’s secret key.
- Apply the SHA-1 cryptographic hash function to the string obtained in the first step.
Sending responses to webhook
To confirm receipt of the webhook, your server must return:
200
,201
, or204
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.
If the Xsolla server doesn’t receive a response to the Successful payment for order and Order cancellation webhooks or receives a response with a 5xx
code, the webhooks are resent according to the following schedule:
- 2 attempts with a 5-minute interval
- 7 attempts with a 15-minute interval
- 10 attempts with a 60-minute interval
Maximum of 20 attempts to send webhooks are made within 12 hours from the first attempt.
If the Xsolla server doesn’t receive a response to Payment webhook or Refund webhook, or receives a response with a 5xx
code, webhooks are also resent with an increased time interval. A maximum of 12 attempts are made within 12 hours.
If the Xsolla server doesn’t receive a response to the User validation webhook or receives a response with a code of 400
or 5xx
, the User validation webhook is not resent.
In this case, an error is shown to the user and the Payment and Successful payment for order webhooks are not sent.
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:
- json
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:
- json
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.
Overview
The Xsolla event API allows you to use the GetUpdates service to receive and handle payment information directly from your application client without using webhooks on your server. Use this integration option if you want to speed up and simplify your integration by eliminating the need to set up and maintain your own server to process payment webhooks.
Interaction between your game and Xsolla:
How to set it up
To receive events from Xsolla via API:
- In your project Publisher Account, go to the Payments > Webhooks section.
- Click Use API. Settings are saved automatically.
- From the application client, send a request to
https://getupdate.xsolla.com/events
to get payment information. Refer to the API references for detailed information. In the response, you will receive payment data in the same format as the Payment webhook. - If the payment is successful, grant the purchase to the user.
API reference
Get unprocessed event list for user
- http
1GET https://getupdate.xsolla.com/events
Security: Bearer User JWT token
Response sample:
- json
1{
2 "events": [
3 {
4 "id": 49, // event_id
5 "status": 0,
6 "created_at": "2025-04-03T21:21:27Z",
7 "data": {
8 "notification_type": "payment",
9 "purchase": {
10 "order": {
11 "id": 000000001,
12 "lineitems": [
13 {
14 "quantity": 1,
15 "sku": "skill"
16 }
17 ]
18 }
19 },
20 ...
21 }
22 }
23 ]
24}
Mark event as processed
- http
1POST https://getupdate.xsolla.com/events/<event_id>/processed
event_id
is the events.id
parameter obtained from the response to the Get unprocessed event list for user API call.
Security: Bearer User JWT token
Found a typo or other text error? Select the text and press Ctrl+Enter.