How to get payment token
To open the payment UI, you need to get a token. A token is a string that includes encrypted data about a game and a user. You need to implement the getting of a token to identify the user to allow the purchase.
To get a payment token:
Get user authorization token
The lifetime of the token is 24 hours after the last call to the Xsolla API. Implement the logic of receiving a new token after its expiration. It is recommended that you get a new token in the background, so the user doesn’t have to log in to the application again.
In the back-end of your application, implement getting a user authentication token. To do so, use an HTTP POST request that includes basic HTTP authentication and pass the required parameters in the request body.
Basic HTTP authentication
Xsolla API uses basic access authentication. All requests to API 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 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
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.
If an API call you need does not contain the project_id path parameter, use the API key that is valid in all the company’s projects to set up authorization.
Request body
In the request body, pass the following required parameters:
| Parameter | Type | Description |
|---|---|---|
user.id | string | Unique user ID in your system. |
user.email | string | User email to send purchase receipts. If the parameter is not passed, a required field for entering an email appears on the payment page. |
settings.project_id | integer | Game’s Xsolla ID. You can find this information in your project section in Publisher Account. |
To improve user experience, you can also pass the following parameters:
| Parameter | Type | Description |
|---|---|---|
user.name | string | User screen name displayed on receipts. |
settings.currency | string | Preferred payment currency. |
settings.language | string | Interface language. |
curl -i -X POST \
-u 2340:ZHgbSDVP6LtAJVWu \
https://api.xsolla.com/merchant/v2/merchants/<merchant_id>/token \
-H 'Content-Type: application/json' \
-d '{
"settings": {
"currency": "USD",
"language": "en",
"project_id": <project_id>
}
},
"user": {
"email": {
"value": "<user_email>"
},
"id": {
"value": "<user_id>"
},
"name": {
"value": "<user_name>"
}
}
}'
Example of a user authentication token received in response
{
"token": "1230OWrp0KF6uqvmN8jWuzLyoXMzxTyK_lc_en"
}
Get payment token
To get a payment token, create an order. An order is an item that a user wants to buy in the store. After an order is paid, the user receives the item. To test the payment flow, create an order using the Create order with specified item API call:
- If you want to perform a test on the API documentation website, click
Try it to open the interface for creating a request. - In the
Security block, in theBearer Token field, enter the token obtained while passing the authentication procedure. - In the
Body block, pass order details, e.g., quantity of item quantity. To access sandbox mode, pass"sandbox": true. - 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
Found a typo or other text error? Select the text and press Ctrl+Enter.
