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

Note
To call the Xsolla API, you can use the ready-made SDK methods for game engines and platforms:

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

TaskAPI
To display a complete list of virtual items added to your StoreGet virtual items list
To display a list of groups of virtual items available for sale on the client sideGet item groups list
To get a list of virtual currencies available for sale in your Store on the client sideGet virtual currency list
To display a complete list of virtual currency packages added to your Store on the client sideGet virtual currency package list
To display a complete list of virtual currency bundles added to your StoreGet list of bundles

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.
  2. Buying a cart. In this case, the player can pre-fill a cart, then add or remove items, or change their quantities.

Fast purchase

  1. Call the Create order with specified item API. A token for opening the payment UI will be passed to the response.
  2. Open payment UI using received payment token.

Note
The information about the discount (personalized or related to the purchase) will be available to the user only in the payment UI. The use of promo codes is not provided.
Note
To call the Xsolla API, you can use the ready-made SDK methods for game engines and platforms:

Cart purchase

Implement the logic:

  1. To set up a cart and get the token:
  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.

Note
To call the Xsolla API, you can use the ready-made SDK methods for game engines and platforms:

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:

Note
If you want to get current status of the cart, call the Get current user’s cart API.

  1. Call the Create order with all items from the current cart API. The order ID and payment token will be passed to the response. The created order will receive a New order status.
  2. 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.

Note

After the first real payment is made, a strict sandbox payment policy takes effect. A payment in the sandbox mode is available only to users who are specified in Publisher Account > Company settings > Users.

Buying virtual currency and items for real currency is possible only after signing a license agreement with Xsolla. To do this, in Publisher Account, go to the Accounting > Licensing agreements section, complete the agreement form, and wait for the confirmation. It may take up to 3 business days to review the agreement.

To enable/disable sandbox mode, you need to change the value of the sandbox parameter in the request to fast purchase and purchase a cart. Sandbox mode is off by default.

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&BB API.

Get user order status on the server side via webhooks

After you have configured webhooks on your server, you can use them to get the order details and status.

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

If you have no server or you implement the logic for purchase processing on the client side, you can use the following ways:

  1. WebSocket API.
  2. Short-polling.

WebSocket API

This method involves the use of web sockets to get order statuses without receiving detailed information about the order itself. This method is preferable because only one connection is established between the Xsolla client and server, and therefore there is no additional load on the client or server.

Complete the following steps:

  1. In order for the WebSocket server and client to identify messages with an order status, create a channel identifier (the order of the parameters is important): Channel_id: order_id=$orderId&project_id=$projectId.
  2. To subscribe to the channel, connect via WebSocket Protocol to the URL: wss://store-ws.xsolla.com/sub/order/status?order_id=$orderId&project_id=$projectId. The message body contains the order ID and order status:

Copy
Full screen
Small screen

{
"order_id": int,
"status": string
}

The following order statuses are available:

  • 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

The required time for a response via web socket 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.

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.
Your progress
Thank you for your feedback!
Last updated: January 27, 2023

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

Report a problem
We always review our content. Your feedback helps us improve it.
Provide an email so we can follow up
Thank you for your feedback!