Xsolla-logo

Create token

post/merchants/{merchant_id}/token

You can create a token with arbitrary user parameters. You send these parameters when obtaining the token and receive them back after a successful payment. A token can only contain parameters either described in this document or predefined by you.

If any parameter is sent in the wrong format or has the wrong type, no token will be issued. You will receive a 422 HTTP code with the error description in the JSON body. In extended_message you will receive an information what exact parameters have been sent incorrectly.

Notice

The token you obtain after calling this API method can be used only for authorizing other requests. You can use this token to open the payment UI only if you integrated the Subscriptions product.

SecuritybasicAuth
Request
path Parameters
merchant_id
required
integer

Merchant ID.

Request Body schema: application/json
object

User details.

required
object
value
required
string

User ID.

object <= 100 characters

The user.email object is an integral part of building anti-fraud models and helps increase acceptance rates. It is both Xsolla and payment systems requirement. If the parameter is not passed, the required field for entering email appears on the payment page. A user receives a purchase receipt to the email passed in the parameter or entered on the payment page.

value
required
string

User email. Must be valid according to the RFC 822 protocol.

allow_modify
boolean

Whether a user can enter their email in the payment UI. If the user.email.value parameter is passed in the token, the value is false by default.

object
value
string

User screen name.

allow_modify
boolean

Whether a user can enter their name in the payment UI. If the user.name.value parameter is passed in the token, the value is false by default.

age
integer

User age.

object
value
string

User phone number.

object
value
string

Two-letter uppercase country code per ISO 3166-1 alpha-2.

allow_modify
boolean

Whether a user can change the country on payment UI. If country.value is passed in the token, the value is false by default.

attributes
object

User attributes for filtering the item list, represented as a valid JSON set of key-value pairs.

object
value
string

Steam ID.

object
value
string = 32 characters

Unique user ID — used in marketing campaigns. Can contain digits and Latin characters.

object
value
string

Parameter that uniquely identifies the user and is known to the user (email, screen name, etc). Allows the user to make purchases outside the game store (e.g., via cash kiosks).

object

Traffic attributes.

utm_source
string

Traffic source.

utm_medium
string

Traffic channel (contextual ads, media ads, email lists, etc.).

utm_campaign
string

Campaign title, transliterated or translated to English.

utm_term
string

Campaign keyword. If set, statistics will be based on the keywords used for ad targeting rather than on specific search queries. In Google Analytics, the specified utm_term is part of the general search terms report.

utm_content
string

Campaign content.

is_legal
boolean

Whether the user is a legal entity.

object

Object with legal entity details. Object and all its parameters are required if user.is_legal is true.

name
string

Full legal name.

address
string

Full legal address.

vat_id
string

Individual taxpayer identifier.

country
string

Country of incorporation. Two-letter uppercase country code per ISO 3166-1 alpha-2 is used.

object

Settings for configuring payment process and the payment UI for a user.

project_id
required
integer

Game’s Xsolla ID. Can be found in Publisher Account.

external_id
string

Transaction ID in the game. Has to be unique for each user payment. Refer to documentation for detailed information.

language
string

Interface language. Two-letter lowercase language code.

return_url
string

URL of the page where a user is redirected to after the payment. Refer to documentation for detailed information about configuring redirects.

object

Redirect policy settings.

redirect_conditions
string

Payment status for which a user is redirected to the return URL. Can be none, successful, successful_or_canсeled, or any.

Enum: "none" "successful" "successful_or_canceled" "any"
delay
integer

Delay (in seconds) after which a user is automatically redirected to the return URL.

status_for_manual_redirection
string

Payment status for which a button redirecting a user to the return URL is displayed. Can be none, successful, successful_or_canсeled, or any.

Enum: "none" "successful" "successful_or_canceled" "any"
manual_redirection_action
string

Pay Station behavior triggered by the user clicking the close button or the Back to the Game button. Can be redirect (by default) and postmessage. If set to redirect, a user is redirected to the URL passed in the token or specified in Publisher Account. If set to postmessage, a user is not redirected to other pages. Clicking the close icon initiates sending the close event, and clicking the Back to the Game button — the return event.

Enum: "redirect" "postmessage"
redirect_button_caption
string

Text on the button for manual redirection.

currency
string

Preferred payment currency. Three-letter currency code per ISO 4217.

mode
string

Set to sandbox to test out the payment process. In this case, use https://sandbox-secure.xsolla.com to access the test payment UI.

payment_method
integer

Payment method ID.

payment_widget
string

Payment widget. Can be paybycash or giftcard. If the parameter is set, the user is redirected to the Pay by Cash or Gift Cards widget, respectively.

Enum: "paybycash" "giftcard"
object

Interface settings.

theme
string

Payment UI theme. Can be 63295a9a2e47fab76f7708e1 for the light theme (default) or 63295aab2e47fab76f7708e3 for the dark theme. You can also create a custom theme and pass its ID in this parameter.

Enum: "63295a9a2e47fab76f7708e1" "63295aab2e47fab76f7708e3"
object

Interface settings for the desktop version.

object

Header settings.

is_visible
boolean

Whether to show the header in the payment UI.

visible_logo
boolean

If true, the header will show your logo (first provide the image to your Customer Success Manager).

visible_name
boolean

Whether to show the project name in the header.

visible_purchase
boolean

Whether to show the purchase description (purchase.description.value) in the header. true by default.

type
string

How to show the header. Can be compact (hides project name and user ID) or normal (default).

Enum: "compact" "normal"
close_button
boolean

Whether to show the Close button in the payment UI. The button closes the payment UI and redirects the user to the URL specified in the settings.return_url parameter. false by default.

object

Settings for the list of subscription plans.

description
string

Any text to show above the list of available subscription plans in the payment UI.

display_local_price
boolean

If true, and if the user’s local currency is different from the one set for the subscription plan, the user will be able to see both prices: one in the local and one in the basic currency.

object
visible_virtual_currency_balance
boolean

Whether or not this element can be hidden on Payment UI. true by default.

object
object
close_button
boolean

Whether to show a Close button in Pay Station mobile. The button closes Pay Station and redirects the user to the URL specified in the settings.return_url parameter. false by default.

object

Menu settings.

object

Virtual items submenu settings.

order
integer

Position of the submenu in the menu.

hidden
boolean

Whether to show the submenu.

selected_group
string

Group to show after opening the virtual items tab.

selected_item
string

Item to show after opening the virtual items tab (item SKU).

object

Virtual currency submenu settings.

custom_amount
boolean

Whether the user can enter an arbitrary quantity of the virtual currency in the payment UI.

order
integer

Position of the submenu in the menu.

hidden
boolean

Whether to show the submenu.

object

Subscription plans submenu settings.

order
integer

Position of the submenu in the menu.

hidden
boolean

Whether to show the submenu.

mode
string

Interface mode in Pay Station. Can be user_account only. The header contains only the account navigation menu, and the user cannot select a product or make a payment. This mode is only available on the desktop.

is_prevent_external_link_open
boolean

Whether or not redirecting links to an external resource is disabled. false by default. When clicking an external link, the external-link-open event is sent via the postMessage mechanism. The address for the redirected link is passed in the url parameter.

is_payment_methods_list_mode
boolean

Whether the list of payment methods available in the user’s country is displayed when opening the payment UI. If false (default), the payment method passed in the settings.payment_method parameter or the method selected by the PayRank algorithm is displayed.

is_independent_windows
boolean

Whether to redirect users from the embedded launcher’s browser (WebView) to their default browser to make a purchase. false by default.

object

User account details.

object

Page My account.

order
integer

Position of the section in the drop-down list.

enable
boolean

Whether to display the section. false by default.

object

Saved methods section.

enable
boolean

Specifies whether to display the pencil icon in the payment UI that goes to the payment method editing page. true by default.

object

Manage subscriptions section.

order
integer

Position of the section in the drop-down list.

enable
boolean

Whether to display the section. false by default.

currency_format
string

Set to code to display a three-letter ISO 4217 currency code in the payment UI. The currency symbol is displayed instead of the three-letter currency code by default.

is_show_close_widget_warning
boolean

Whether to show a warning about processing the transaction when hovering over the × icon before closing the payment page. If false is passed, or the parameter is not passed, the warning is not displayed. true by default.

layout
string

Location of the main elements of the payment UI. You can open the payment UI inside your game and/or swap the columns with information about an order and payment methods. Refer to the customization instructions for detailed information.

Enum: "embed" "column_reverse" "embed_column_reverse"
is_three_ds_independent_windows
boolean

Whether to open the 3-D Secure check in a new browser window. false by default. Pass true if you use the Content Security Policy (CSP).

is_cart_open_by_default
boolean

The display of the list of items in the cart when opening the mobile version of the payment UI. If true, the list is displayed in an extended view. If false (default) or the parameters is not passed, the list is displayed in a collapsed view.

object

Object containing purchase details.

object

Subscription data.

plan_id
string

External ID of the subscription plan. Can be found in the Subscriptions > Subscription plans section of Publisher Account.

operation
string

The type of operation applied to the user’s subscription plan. To change the subscription plan, pass the change_plan value. You need to specify the new plan ID in the purchase.subscription.plan_id parameter.

product_id
string

Product ID.

currency
string

Currency of the subscription plan to use in all calculations.

available_plans
Array of strings

Subscription plans to show in the payment UI.

trial_days
integer

Trial period in days.

object

You can pass additional parameters in the token in the custom_parameters object to configure anti-fraud filters. The recommended parameters are shown in the drop-down list. See Pay Station documentation.

registration_date
string

Account creation date per ISO 8601.

total_hours
integer

Total number of in-game hours.

total_characters
integer

Number of in-game characters.

social_networks_added
boolean

Whether the player has connected social media profiles.

profile_image_added
boolean

Whether the player has uploaded a profile image.

active_date
string

Last seen date per ISO 8601.

total_friends
integer

Number of friends.

additional_verification
boolean

Whether the player uses account verification procedures.

win_rate
integer

Win rate.

last_change_password_date
string

Last password change date per ISO 8601.

chat_activity
boolean

Whether the player uses the chat function.

forum_activity
boolean

Whether the player uses the forum function.

total_bans
integer

Number of times the player was banned in the chat/forum.

profile_completed
boolean

Whether the player added additional information to their profile.

notifications_enabled
boolean

Whether the player enabled notifications.

user_level
integer

Player’s level, reputation, or rank.

karma_points
integer

Player’s karma.

total_sum
number <float>

Total amount of payments.

non_premium_currency
number <float>

Amount of non-premium currency.

total_game_events
integer

Number of in-game events the player took part in.

total_gifts
integer

Number of in-game gifts the player has sent/received.

tutorial_completed
boolean

Whether the player has completed the game’s tutorial.

completed_tasks
integer

Number of tasks/objectives completed.

items_used
boolean

Whether the player uses purchased in-game items.

pvp_activity
boolean

Whether the player takes part in PvP battles.

total_clans
integer

Number of clans the player is a member of.

unlocked_achievements
integer

Number of achievements unlocked.

total_inventory_value
number <float>

Total inventory value (in-game currency).

character_customized
boolean

Whether the player has customized their character.

session_time
string

Average session time per ISO 8601.

Responses
200

Created.

422

Unprocessable Entity.

Request samples
application/json
{
  • "settings": {
    },
  • "user": {
    }
}
Response samples
application/json
{
  • "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}