Create token

Create tokenServer-side

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

This API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.

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

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.

object

value

string

User screen name.

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

Unique tracking ID (used in marketing campaigns).

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

Custom project settings.

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.

language

string

Interface language. Two-letter lowercase language code.

return_url

string

Page to redirect the user to after payment. Parameters user_id, foreigninvoice, invoice_id and status will be automatically added to the link.

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.
autoredirect_from_status_page	boolean Whether to automatically redirect from the status page.
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 default or default_dark.

Enum: "default" "default_dark"

size

string

Payment UI size. Can be:

small: the least possible size of the payment UI. Use this value when the window size is strictly limited (dimensions: 620 x 630)
medium: recommended size. Use this value to display the payment UI in a lightbox (dimensions: 740 x 760)
large: the optimal size for displaying the payment UI in a new window or tab (dimensions: 820 x 840)

Enum: "small" "medium" "large"

version

string

Device type. Can be desktop (default) or mobile.

Enum: "desktop" "mobile"

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 a Close button in Pay Station desktop. The button closes Pay Station 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.

layout	string List template. Can be `list` (default) or `grid`. Enum: "list" "grid"
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

Settings for the list of virtual items.

layout	string List template. Can be `list` (default) or `grid`. Enum: "list" "grid"
button_with_price	boolean If `true`, the price will be shown on the button. If `false`, the price will be shown on the left of the button. `false` by default.
view	string Display virtual item groups as a vertical/horizontal menu. Can be `horizontal_navigation` or `vertical_navigation` (default). Enum: "horizontal_navigation" "vertical_navigation"

object

Settings for the list of virtual currencies.

description	string Any text to show above the list of virtual currencies.
button_with_price	boolean If `true`, the price will be shown on the button. If `false`, the price will be shown on the left of the button. `false` by default.

object

visible_virtual_currency_balance

boolean

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

object

mode

string

A user can only pay using their saved payment methods. Can be saved_accounts.

Value: "saved_accounts"

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

is_visible

boolean

Whether to hide the footer in the mobile version of the payment UI.

license_url

string

Link to the EULA.

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

object

User account details.

object

Page My account.

order	integer Position of the submenu in the menu.
enable	boolean Whether to show the submenu. `false` by default.

object

History submenu.

order	integer Position of the submenu in the menu.
enable	boolean Whether to show the submenu. `false` by default.

object

My payment accounts submenu.

order	integer Position of the submenu in the menu.
enable	boolean Whether to show the submenu. `false` by default.

object

Manage subscriptions submenu.

order	integer Position of the submenu in the menu.
enable	boolean Whether to show the submenu. `false` by default.

object

Object containing purchase details.

object

Object containing checkout details.

currency	string Currency of the purchase. Three-letter currency code per ISO 4217.
amount	integer <float> Purchase amount.

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

Gifted subscription details.

recipient required	string ID of the recipient.
email required	string Recipient email.
anonymous	boolean Whether to hide the gifter name. If `true`, the sender's name is hidden in the email notification. Defaults to `false`.
message	string Message for the recipient.
redirect_url	string Provide a link here to a page with additional information about the gifted subscription or to the account creation page. The gift recipient can navigate to this page from the subscription gift email notification.

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	integer <float> Total amount of payments.
non_premium_currency	integer <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	integer <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

{"purchase": {"checkout": {"currency": "USD",
"amount": 10
},
"subscription": {"gift": {"recipient": "test_recipient_v1",
"email": "recipient_email@email.com"
}
}
},
"settings": {"currency": "USD",
"language": "en",
"project_id": 16184,
"ui": {"components": {"virtual_currency": {"custom_amount": true
}
},
"desktop": {"virtual_item_list": {"button_with_price": true,
"layout": "list"
}
},
"size": "medium"
}
},
"user": {"country": {"allow_modify": true,
"value": "US"
},
"age": 19,
"email": {"value": "john.smith@mail.com"
},
"id": {"value": "user_2"
},
"name": {"value": "John Smith"
}
}
}

Response samples

application/json

{"token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}