How to use new Commerce API methods
How it works
You can connect the
Main features:
- Authorization via Xsolla Login or Pay Station access token
- Virtual items management
- User inventory management
- Cart and order management
Who can use it
- Partners who develop a store interface and want to use a third-party solution to implement the server side.
- Partners who have already implemented server integration with Xsolla and want to connect Store with new
Commerce API methods.
How to get it
To connect the
- Set up the Virtual Items module in your Publisher Account.
- Set up authentication.
- Implement methods for store management.
For integration you will need the Project ID shown in Project settings > Webhooks. The Project ID is used in
Setting up the Virtual Items module in Publisher Account
- Go to Projects and click on the Create project button.
- Add Project name and click Create.

- Go to Project settings > Integration settings and check that Integrate
Commerce API toggle is set to On. - Connect Store to your project.
- Connect the Virtual Items module.

- Create a group of items.

- Create items.

- Turn on the group display in Store after the items were created.

Authentication setup
The following user authentication options are available:
- Via Xsolla Login. Choose this option if you have not implemented server integration with Xsolla.
- Via Pay Station access token. Choose this option if you have implemented server integration with Xsolla.
Authentication via Xsolla Login
- Set up a Publisher Account project following the instructions.
- Implement the call of the authorization methods with the help of the JSON Web Token or OAuth 2.0 protocol.
If the user data is kept in the Xsolla data storage, implement the call of the following methods:
- Register (JWT or OAuth 2.0)
- Authentication (any of the following):
- Reset password
If the user data is kept in the PlayFab data storage, use the PlayFab recipe.
If the user data is kept on your side, use the Custom storage recipe.
Authentication via Pay Station access token
Authentication flow:
- Your application (client) sends the authentication request to your server.
- Your server sends the Merchant ID and API key to the Xsolla server and requests access_token.
- Xsolla server sends access_token to your server.
- Your server sends access_token to your client.
The returned access_token is used as an authorization token for authentication in the
Store management methods
Store management methods include the following groups of methods:
- Virtual item management:
- Cart and order management:
- User inventory management:
Get virtual items list
Implement the Get virtual items list API method to show the full list of virtual items added to your store.
Example
- js
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/items/virtual_items?locale=en");
xhr.send(data);
//RESPONSE
"items": [
{
"attributes": [],
"description": "Conquer your foes with vindication using the Basic Blaster! ",
"groups": [
"all",
"featured",
"Xsolla",
"weapons"
],
"image_url": "https://cdn.xsolla.net/img/misc/images/0c59a7698d4f66c1008b27ee752089b7.png",
"is_free": false,
"name": "Xsolla Basic Blaster 1",
"order": 1,
"price": {
"amount": "0.9950000000000000",
"amount_without_discount": "1.9900000000000000",
"currency": "USD"
},
"sku": "gun_1",
"type": "virtual_good"
Get item groups list
- Implement the Get item groups list API method to show the full list of virtual items groups added to your store.
- For each value of the sku parameter returned in the Get virtual items list method, specify the external_id of the group to which it belongs. Match sku and external_id in the same way as the items are grouped in Publisher Account.
Example
- js
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/items/groups");
xhr.send(data);
//RESPONSE
"groups": [
{
"children": [],
"description": "all",
"external_id": "all",
"id": 10,
"image_url": "http://none",
"level": 0,
"name": "all",
"order": null,
"parent_external_id": null
}
Get cart
Implement the Get cart by ID or Get current user’s cart API method for purchasing virtual items. Cart ID will be used to add/remove items.
Example
- js
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/cart/custom_id?locale=en¤cy=USD");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
xhr.send(data);
//RESPONSE
{
"cart_id": "custom_id",
"is_free": true,
"items": [],
"price": null
}
Create order with all items
- Implement one of the API methods:
- Create order with all items from particular cart if you got the cart by ID.
- Create order with all items from current cart if you got the current cart.
The created order will receive a New order status.
- To open the payment UI in a new window, use the following link:
https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN
, whereACCESS_TOKEN
is the token received when the order was created. - To test the payment process:
- Use the following URL:
https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN
. - Set the sandbox parameter to true in the request.
- Use the list of bank cards for testing.
- Use the following URL:
Example
- js
var data = JSON.stringify({
"currency": "USD",
"locale": "en",
"sandbox": false
});
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://store.xsolla.com/api/v2/project/44056/payment/cart/custom_id");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
xhr.send(data);
//RESPONSE
{
"order_id": 641,
"token": "f4puMEFFDZcx9nv5HoNHIkPe9qghvBQo"
}
Get order
Implement the Get order API method to determine if the purchase has already been processed. The following order statuses are possible:
- New — order is created but not paid
- Paid — order is paid
- Cancelled — order is cancelled
- Done — order is paid and the item is added to the inventory
Example
- js
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/order/656");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
xhr.send(data);
//RESPONSE
{
"content": {
"is_free": false,
"items": [
{
"is_free": false,
"price": {
"amount": "0.9950",
"amount_without_discount": "1.9900",
"currency": "USD"
},
"quantity": 123,
"sku": "gun_1"
}
],
"price": {
"amount": "122.3850",
"amount_without_discount": "122.3850",
"currency": "USD"
}
},
"order_id": 656,
"status": "new"
}
Get user’s inventory
Implement the Get user’s inventory API method to get a list of items added to the inventory after the purchase.
Example
- js
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/user/inventory/items");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
xhr.send(data);
//RESPONSE
{
"items": [
{
"description": "Conquer your foes with vindication using the Basic Blaster! ",
"image_url": "https://cdn.xsolla.net/img/misc/images/0c59a7698d4f66c1008b27ee752089b7.png",
"instance_id": null,
"long_description": "Conquer your foes with vindication using the Basic Blaster! Conquer your foes with vindication using the Basic Blaster! ",
"name": "Xsolla Basic Blaster 1",
"quantity": 22,
"sku": "gun_1",
"type": "virtual_good"
},
{
"description": "Protect your noggin' with style",
"image_url": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png",
"instance_id": null,
"long_description": "merchant_virtual_items_virtual_item_long_description_159429",
"name": "Xsolla Helmet",
"quantity": 18,
"sku": "helmet_1",
"type": "virtual_good"
}
]
}
Was this article helpful?
Rate this page
Don’t want to answer
Thank you for your feedback!
Found a typo or other text error? Select the text and press Ctrl+Enter.