Grant purchases to user

Implement granting purchases to the user in your application using information from Xsolla about the transaction status. You can get the information in the following ways:

• request information using the API
• receive information automatically using webhooks

Request information using API

You can get info about user purchased virtual items, virtual currency, or bundles from the player's inventory on the Xsolla side. To take into account both the purchases made via Web Shop and purchases made by other methods when granting the purchases, synchronize the info about the player's inventory on the application side and on the Xsolla side.

API calls for managing the inventory include the following groups:

• Server-side calls:
  • Grant items to users
  • Revoke inventory items
  • Grant items by purchase to users

• Client-side calls:
  • Get user’s inventory
  • Get user’s virtual balance
  • Consume item

Basic HTTP authentication

The request must contain the Authorization: Basic <your_authorization_basic_key> header, where <your_authorization_basic_key> is the merchant ID:API key pair, encoded according to the Base64 standard. Go to Publisher Account to find these parameters:

• Merchant ID is shown:
  • In the Project settings > Webhooks section.
  • In the Company settings > Company section.
  • In the URL in the browser address bar on any Publisher Account page. The URL has the following format: https://publisher.xsolla.com/​merchant ID/Publisher Account section.

• API key is shown in Publisher Account only once when it is created and must be stored on your side. You can create a new key in the following section:
  • Company settings > API keys
  • Project settings > API keys

Server OAuth 2.0 authentication

The request must contain the Authorization: Bearer <user_JWT> header where <user_JWT> is the user JWT.

To get the user JWT, follow the steps below:

1. Create a server OAuth 2.0 client:
   1. Open your project in Publisher Account. Go to Login > your Login project and click Configure.
   2. In the Security block, click OAuth 2.0.
   3. Click Add OAuth 2.0 and specify:
      • Client name.
      • OAuth 2.0 redirect URIs (Required).
      • Authentication type — server.
      • Project ID.
   4. Click Connect. You will need a generated client ID and secret key for further integration.

2. Get the server JWT. To do this, call the Generate JWT API method and pass the following parameters:
   • grant_type — JWT type. Specify the client_credentials value.
   • client_secret — server OAuth 2.0 client secret key.
   • client_id — server OAuth 2.0 client ID.

3. Get the user JWT. To do this, call the Auth by custom ID API method. The request must contain the X-Server-Authorization: <server_JWT> header, where <server_JWT> is the server JWT obtained in step 2.

Receive information using webhooks

1. Configure parameters for receiving webhooks:
   1. Open your project in Publisher Account.
   2. Click Project settings in the side menu.
   3. Go to the Webhooks section.
   4. Set the Webhooks toggle to On.
   5. In the Webhook URL field, specify the URL to receive webhooks.
   6. A secret key to sign project webhooks is generated by default. If you want to generate a new secret key, click the refresh icon.
   7. Click Save settings.

2. Implement the processing of the following types of webhooks in your application:

1. • To grant virtual items, virtual currencies, virtual currency packages, and bundles:
     • User validation
     • Payment
     • Getting cart’s content when making purchase

1. • To cancel a purchase:
     • Canceled order
     • Refund

To confirm that the webhook is received, your server must respond with:

• HTTP code 204 without a message body.
• HTTP code 400 describing the problem if the specified user was not found or if an invalid signature was passed.

You can test User validation and Payment webhooks in Publisher Account in the Project settings > Webhooks > Store section.

In the absence of real values, you can enter arbitrary values.

You also can test webhooks when making purchases in the sandbox or live mode. Testing Refund is available only in live mode.

Next steps

1. Implement getting subscription information.
2. Set up user authentication.

Useful links

Integration flow

Rate this page

Is there anything we can improve? Send

Don’t want to answer

Thank you for your feedback!