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 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 methods use basic HTTP authentication.
Client-side calls use server OAuth 2.0 authentication.

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: `​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

For more information about working with API keys, see the API reference.

Key recommendations:

  • Save the generated API key on your side. You can view the API key in Publisher Account only once when it is created.
  • Keep your API key a secret. It provides access to your personal account and your projects in Publisher Account.
  • The API key must be stored on your server and never in binaries or on the frontend.

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.

  1. 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.
The server JWT lifetime is 59 minutes.
  1. 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.

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

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 > Payments 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.

Integration flow

Was this article helpful?
Thank you!
Is there anything we can improve? Message
We’re sorry to hear that
Please explain why this article wasn’t helpful to you. Message
Thank you for your feedback!
We’ll review your message and use it to help us improve your experience.
Rate this page
Rate this page
Is there anything we can improve?

Don’t want to answer

Thank you for your feedback!
Last updated: January 22, 2024

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!