Integrate store into game

After you have created and configured goods (virtual items, virtual currencies, bundles, keys) in your Publisher Account, add an In-Game Store to your game:

1. Implement the display of items catalog.
2. Implement the logic for selling items.

Display of items catalog

Implement a display of items catalog via In-Game Store API calls:

Selling items

You can sell items in the following ways:

1. Fast purchase of one item. In this case, you can sell one SKU in any quantity (for example, 100 identical potions or a custom amount of virtual currency).
2. Buying a cart. In this case, the player can pre-fill a cart, add or remove items, or change their quantities.

Fast purchase

Cart purchase

1. To set up a cart and get the token:
   • On the client — if you want to implement the cart in your application by yourself.
   • On the server — if you want to use Xsolla’s solution (In-Game Store API calls) to manage the cart.
2. To open payment UI.

Set up and purchase a cart on the client

Implement the logic of adding and removing items by yourself. You also need to consider that before calling API for setting up a cart, you will not have information about which promotions will be applied to the purchase. This means that the total cost and details of the added bonus items will not be known.

1. After the player has filled a cart, call the Fill cart with items API. The current information about the selected items (prices before and after discounts, bonus items) will be passed to the response.
2. Call the Create order with all items from current cart API. The order ID and payment token will be passed to the response. The created order will receive a New order status.
3. Open payments UI.

Set up and purchase a cart on server

This variant may take longer for setting the cart up, since each change to the cart must be accompanied by API calls.

Complete the following steps:

1. Change the cart:
   • For adding an item or changing item quantity, call the Update cart item by cart ID API.
   • For removing an item, call the Delete cart item by cart ID API.

2. Call the Create order with all items from current cart API. The order ID and payment token will be passed to the response. The created order will receive a New order status.
3. Open payment UI.

Opening the payment interface

For paying items, open the payment UI. A token for opening the payment UI will be passed to the Create order with all items from current cart API response.

Implement the opening of the payment UI in one of the following ways:

• In a new window. To open the payment UI in a new browser window, use the link: https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN, where ACCESS_TOKEN is the token received when the order was created.
• Via widget. Use the Xsolla PayStation Widget script (README file contains instructions).

Testing payment process

You can test payment flow in the Sandbox mode. You can use a test bank card and any account.

Get user order status

You can use the following ways to get a user order status:

1. On the server side via webhooks.
2. On the client side via WebSocket API or IGS API.

Get user order status on the server side via webhooks

Get user order status on the client side via WebSocket API or IGS API

1. WebSocket API.
2. Short-polling.

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:

1. To allow the Xsolla websocket server and your client to identify order status messages, create a connection:

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

2. To receive new messages about order statuses, subscribe to events using the client.on function:

client.on('publication', (ctx) => {
   //handle the status
});

3. Trigger actual connection establishment:

client.connect()

4. To receive the history of changes in order statuses, connect the API history method.

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:

{
order_id: 59614241,
status: 'new'
}

The following order statuses are possible:

• New — order was created but not paid
• Paid — order is paid
• Done — 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

Websocket usage recommendations:

• The maximum waiting time for a response via websocket is 5 minutes.
• The connection should be established when opening the payment interface.
• The connection should be aborted once the final order status is received, either Canceled or Done.
• If the websocket’s lifespan expires or if there are any issues with the connection, use short-polling.

  Short-polling

  To get detailed information about items in the order after switching to the status, call the Get order API.

  Note

  A periodic order status poll is used — a simple HTTP request that receives the order status and information about the order. The recommended delay between requests is 3 seconds.
  Was this article helpful?

  Yes

  No

  Thank you!

  Is there anything we can improve? Message Send

  We’re sorry to hear that

  Please explain why this article wasn’t helpful to you. Message Send

  Thank you for your feedback!

  We’ll review your message and use it to help us improve your experience.
  Last updated: November 8, 2024

  Found a typo or other text error? Select the text and press Ctrl+Enter.