Set up order status tracking
To grant items to the user, you need to make sure that the payment was successful.
Choose a method for tracking order status:
Choose the most suitable method for your project to access Xsolla data:
If you have no server or you implement the logic for purchase processing on the client side, you can use the following ways:
Get an order status on the client side using WebSocket API
The solution uses websockets to obtain order statuses without obtaining detailed information about the order. This method is preferable: only one connection is created between the client (for example, your website or mobile application) and the Xsolla server, so there is no additional load on either the client or the server.
Complete the following steps:
- To allow the Xsolla websocket server and your client to identify order status messages, create a connection:
- javascript
const client = new Centrifuge(
connectionURL,
{
data: {
user_external_id: user_external_id,
auth: auth,
project_id: project_id
}
}
)
connectionURL - wss://ws-store.xsolla.com/connection/websocket
auth - user JWT token
- To receive new messages about order statuses, subscribe to events using the
client.on
function:
- javascript
client.on('publication', (ctx) => {
//handle the status
});
- Trigger actual connection establishment:
- javascript
client.connect()
- To receive the history of changes in order statuses, connect the API history method.
- javascript
client.on('subscribed', function (ctx) {
client.history(ctx.channel, { limit: -1, since: { offset: 0 }, reverse: false }).then(function (resp) {
resp.publications.forEach((ctx) => {
/handle the status
});
}, function (err) {
//handle the status
});
});
Message body example:
- javascript
{
order_id: 59614241,
status: 'new'
}
The following order statuses are possible:
New
— order was created but not paidPaid
— order is paidDone
— order has been delivered (all receipts sent, deliveries made on Xsolla’s side, external platforms, etc.)Canceled
— order is canceled and payment refunded to a user
The required time for a response via websocket is 5 minutes. After that or if there are any problems with the websocket, it is recommended to use short-polling.
Short-polling
To get detailed information about items in the order after switching to the status, call the Get order API.
The XsollaCatalog.Purchase
method encapsulates several methods for tracking order status. The tracking mechanism is detailed in the documentation of enterprise-level SDK for Unity.
Additionally, you can implement the handling of the order status and content, which are passed to the onSuccess
callback function of the purchase method.
When using the SDK, you can track the order status in the following ways:
Subscribe to order status changes
To subscribe to order status changes, use the getOrderStatus
SDK method from the Store library and pass the following parameters to the method:
listener
— listener object of typeOrderStatusListener
.orderId
— order ID received from the purchase via the shopping cart, one-click purchase, or purchase for virtual currency as the parameter.
Example of calling the XStore.getOrderStatus method:
- kotlin
XStore.getOrderStatus(object : OrderStatusListener() {
override fun onStatusUpdate(status: OrderResponse.Status) {
if(status == OrderResponse.Status.DONE) {
Log.d("MainActivity", "Success")
}
}
override fun onFailure() {
Log.d("MainActivity", "Failure")
}
}, orderId)
We recommend to call XStore.getOrderStatus
method when opening payment UI.
Purchase methods encapsulate several methods for tracking the order status. Tracking is performed according to the following algorithm:
- A web socket connection is established.
- If the web socket connection is established successfully and order status changes to
done
orcancel
, tracking stops. If a web socket connection fails or the response contains incorrect data, the order status is tracked using short-polling. - Order status tracking continues with short-polling. A simple HTTP order status request is sent once every 3 seconds. Tracking stops if order status changes to
done
orcancel
.
Request order status
To request the current status of the payment transaction, call the getOrder
method from the Store library, passing the following parameters to it:
orderId
— the order ID, which was received when purchasing the item.callback
— the callback for successfully retrieving order information. When implementing a callback, use theGetStatusCallback
interface, and implement theonSuccess
andonError
methods.callback
— the callback for successfully retrieving order information. When implementing a callback, use theGetStatusCallback
interface, and implement theonSuccess
andonError
methods.
Order status information is passed to the onSuccess
method in an object of the InvoicesDataResponse
type. This object contains an array of InvoiceData
objects. Each InvoiceData
object corresponds to a specific stage in the order processing and contains the status of this stage.
For example, if the user initially entered invalid data when placing the order, an object with the status InvoicesDataResponse.CANCELED
will appear in the InvoiceData
list. If the user then corrects the data and successfully pays for the order, a new InvoiceData
object will appear in the array, now with the status InvoicesDataResponse.Status.DONE
.
Status tracking stops if the final payment status (InvoicesDataResponse.Status.DONE
or InvoicesDataResponse.Status.ERROR
) is received.
Example:
- kotlin
XPayments.getStatus(<token>, <isSandbox>, object : GetStatusCallback {
override fun onSuccess(data: InvoicesDataResponse?) {
Log.d(TAG, "onSuccess is fired. Result data = $data")
}
override fun onError(throwable: Throwable?, errorMessage: String?) {
Log.d(TAG, "onError is fired. ErrorMessage = $errorMessage")
}
})
You can track the order status using the CheckPendingOrder
SDK method. Pass the following parameters to the method:
AccessToken
— the payment token, which was received when purchasing the item.OrderId
— the order ID, which was received when purchasing the item.SuccessCallback
— the successful payment callback.ErrorCallback
— the request error callback.bIsUserInvolvedToPayment
— whether the user is involved in the payment process. Passtrue
for purchasing with real currency, andfalse
for free item purchasing and purchasing with virtual currency.
The tracking mechanism is detailed in the documentation of enterprise-level SDK for Unreal Engine.
To request the status and content of an order, call the CheckOrder
SDK method, passing the following parameters to it:
AccessToken
— the payment token, which was received when purchasing the item.OrderId
— the order ID, which was received when purchasing the item.SuccessCallback
— the callback for successful order checking. The response contains the order status.ErrorCallback
— the request error callback.
To track the status of created orders and validate them, you will need to configure webhooks processing on the server side of your application.
To fully operate an in-game store, it is necessary to implement the processing of the main webhooks:
Webhook | Notification type | Description |
---|---|---|
User validation | user_validation | Is sent at different stages of the payment process to ensure the user is registered in the game. |
Payment | payment | Is sent when an order is paid and contains payment data and transaction details. |
Successful payment of the order | order_paid | Is sent when a Payment webhook has been successfully processed and contains information about purchased items and the transaction ID. Use the data from the webhook to add items to the user. |
Refund | refund | Is sent when an order is canceled and contains the canceled payment data and transaction details. |
Order cancellation | order_canceled | Is sent when a Refund webhook has been successfully processed and contains information about the purchased items and the ID of the canceled transaction. Use the data from the webhook to remove the purchased items. |
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.
- Click Project settings in the side menu and go to the Webhooks section.
- In the Webhook URL field, specify the URL to which Xsolla will send webhooks.
- Click Enable webhooks.
![](https://cdn.xsolla.net/developers/v-20240906-v01/images/sdk/android/baas-integrations/webhooks-settings.png)
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 a response was not received for the Successful payment of the order and Order cancellation webhooks or if a response with a 5xx
code was received, 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 for the Payment webhook a response was not received or if a response with a 5xx
code was received, webhooks are also resent with an increased time interval. A maximum of 12 attempts are made within 12 hours.
If a response was not received for the User validation webhook or a response with a code of 400
or 5xx
was received, the User validation webhook is not resent.
In this case, an error is shown to the user and the Payment and Successful payment of the order webhooks are not sent.
Found a typo or other text error? Select the text and press Ctrl+Enter.