Quick start

Integration flow

To integrate the Payments solution:

1. Create a project in Publisher Account. One project corresponds to one game. If you have several games, add a project for each game.
2. Add the items you want to sell to a catalog on Xsolla’s side.
3. Test creating an order that a user will pay for.
4. Test making a test purchase and set up notifications.
5. Sign the licensing agreement with Xsolla in Publisher Account to start processing real payments.

Create catalog

Virtual items are in-game content that a user can buy for real and virtual currency. Creating a virtual item catalog on Xsolla’s side will allow you to customize regional prices and restrictions, as well as use Xsolla's system of promotions and other features that are regularly added and updated.

Create virtual items

• Configure in Publisher Account
• Configure via API

1. Open your project in Publisher Account.
2. In the side menu, click Store.
3. In the Virtual Items pane, click:
   • Connect — if you haven’t configured virtual items before.
   • Configure — if you have configured virtual items before.
4. Click Create item.

5. Specify information about an item. Required fields:
   • SKU — unique item ID
   • Item name
   • Description
   • Price in real currency
6. Set the Show item in store toggle to On.
7. Click Create item.

For the next steps, you need the SKU of the created item:

To set up virtual items, use API calls from the Admin subsection of the Virtual Items & Currency group.

Note

Refer to the integration guide for detailed information about using this API call.

Get items list

To get the list of items, call the Get virtual items list API method. In the request, pass the project_id parameter — project ID that you can find in Publisher Account:

In the response, you will receive detailed information about virtual items created in your project. For the subsequent order creation, you need the item SKU that is passed in the items.sku parameter.

Create order

An order consists of items a user wants to buy in the store. After an order is paid, the user receives the items. To make a payment, a user must be authorized in the game.

Select an integration method that suits your game to see the instructions for setting up.

• Server side
• Client side

Call the Create payment token for purchase API method and pass information about a user and items in this method. You can use this API call to sell single and multiple items.

To use sandbox mode, pass the "sandbox": true parameter in the body of the request for getting a token.

Request example:

Copy

Full screen

Small screen

curl -i -X POST \
  -u 224575:MYAPIKEY \
  https://sandbox-secure.xsolla.com/api/v2/project/224575/admin/payment/token \
  -H 'Content-Type: application/json' \
  -d '{
    "user": {
      "id": {
        "value": "myUserID"
      }
    },
    "purchase": {
      "sandbox": true,
      "items": [
        {
          "sku": "mySKU",
          "quantity": 1
        }
      ]
    }
  }'

Integrate Xsolla Login:

1. Create a project.
2. Set up your Login project in Publisher Account.
3. Connect user data storage.
4. Integrate the solution on your application side.

Using the configured Login method, create and save the authentication token to receive a payment token. The payment token is used for opening the payment UI and making the payment.

To test the payment flow, create an order using the Create order with specified item API call:

1. If you want to perform a test on the API documentation website, click Try it to open the interface for creating a request.
2. In the Security block, in the Bearer Token field, enter the token obtained while passing the authentication procedure.
3. In the Body block, pass order details, e.g., quantity of item quantity. To access sandbox mode, pass "sandbox": true.
4. In the Parameters block, pass:
   • project_id — project ID that you can find in Publisher Account.
   • item_sku — item SKU.

In the response, you will receive data you need for further work:

• token — payment token

Request example:

Copy

Full screen

Small screen

curl -i -X POST \
  'https://store.xsolla.com/api/v2/project/{project_id}/payment/item/{item_sku}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sandbox": true,
    "quantity": 5,
    "settings": {
      "ui": {
        "theme": "63295a9a2e47fab76f7708e1",
      }
    },
    "custom_parameters": {
      "character_id": "ingameUsername"
    }
  }'

Note

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

• Unity
• Unreal Engine
• Cocos Creator
• Android

Make test purchase

Open payment UI in sandbox mode

To open the payment UI in a new window, use the following URL: https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN, where TOKEN is the token obtained when creating an order.

To open the payment UI using other methods, refer to the documentation.

Make test payment

1. Open the payment UI in sandbox mode.
2. Choose the Bank card payment method.
3. Enter the bank card details. In other fields (e.g., name or address), you can enter any data. You can also specify incorrect details (card number or expiration date) to test if an error is generated.
4. Click Pay.

Test cards list

See the list of test bank cards.

Set up webhooks

If you set up integration on the server side, you need to validate created orders by sending the respective code in response to webhooks. If you set up integration on the client side, webhooks will allow you receive notifications about configured events (e.g., change of payment status).

PHP SDK

Use ready classes for processing webhooks.

To set up webhooks on Xsolla’s side:

1. Open your project in Publisher Account.
2. Click Project settings in the side menu and go to Webhooks.
3. Set the Webhooks toggle to On.
4. Specify the webhook URL.
5. A secret key to sign project webhooks is generated by default. If you want to generate a new secret key, click the refresh icon.
6. Click Save settings.

To receive notifications about user validation and successful payments, configure the following webhooks:

• User validation — for notifications to ensure the user is registered in the game.
• Payment — for notifications that the payment is made.

Configure webhook listener

Webhook listener is program code that allows receiving incoming webhooks at a specified URL address, generating a signature, and sending a response to the Xsolla webhook server.

Launch

Sign licensing agreement

Signing the licensing agreement will allow you to receive real payments via any payment methods supported by Xsolla. To sign the licensing agreement:

1. Open your Publisher Account.
2. In the side menu, go to Agreements and taxes > Agreements section.
3. On the Licensing Agreement tab, click Fill out application form.
4. Provide your information in the corresponding fields.

Your application will be reviewed within 3 business days. If there are any questions during the verification process, Xsolla will notify the contact person indicated in the application. After the checking procedure is completed on Xsolla’s side, the status of your agreement will change to Signed.

Switch to production environment

After completing the previous steps, you can start receiving real payments:

1. Make sure you signed the licensing agreement with Xsolla.
2. Remove "sandbox": true parameter from the request body when obtaining a token.
3. Open the payment UI using the following link: https://secure.xsolla.com/paystation4/?token=TOKEN.

Rate this page

Is there anything we can improve? Send

Don’t want to answer

Thank you for your feedback!