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.
SecuritybasicAuth
Request
path Parameters
merchant_id
required
integer
Merchant ID.
Request Body schema: application/json
object
User details.
required
object
value
required
string
Unique user ID in the game stored on your side. Make sure you pass the existing user ID. In case an error occurs, refer to the answers to the FAQs.
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.
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
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. 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.
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.
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 logo is displayed in the header. To upload the image, open your project in Publisher Account and go to the Pay Station > Settings section.
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.
close_button_icon
string
The icon of the Close button in the payment UI.
Enum:
Description
arrow
The ← icon on the left side of the payment UI header.
cross
The × icon on the right side of the payment UI header.
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
is_visible
boolean
Whether to hide the footer in the mobile version of the payment UI.
license_url
string
Link to the EULA.
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.
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
My payment accounts section.
order
integer
Position of the section in the drop-down list in the payment UI.
enable
boolean
Specifies whether to display the section in the drop-down list in the payment UI. true by default. If you don’t pass this parameter, the section is displayed.
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.
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
Object containing purchase details.
object
Deprecated
Object containing checkout details.
currency
string
Currency of the purchase. Three-letter currency code per ISO 4217.
amount
number <float>
Purchase amount.
object
Deprecated
Purchase description.
value
string
General purchase description to include in the payment UI and email receipts. To pass each item individually, use the parameters of the purchase.description.items array.
Array of objects
Array
name
string
Item name.
image_url
string
Link to the item icon.
description
string
Item description in the purchase.
object
Object with the item price.
amount
string
Item price.
amount_before_discount
string
Item price before the discount.
quantity
integer
Number of items in the purchase.
is_bonus
boolean
Whether an item is free and available as a bonus. Default is false.
object
Deprecated
Object containing virtual currency details.
quantity
number <float>
Purchase amount in the virtual currency.
currency
string
Currency of the virtual currency package to use in all calculations.
object
Deprecated
Object with data about the virtual items in purchase.
currency
string
Currency of the ordered items to use in all calculations.
Array of objects
Array
sku
string
Item ID.
amount
integer
Item quantity.
available_groups
Array of strings
Item groups IDs (array). The payment UI will only include items within the specified group.
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
Deprecated
Game keys.
currency
string
Currency of a Game key within the order to use in all calculations.
Array of objects
Game keys.
Array
digital_content
string
Game SKU set in Publisher Account.
drm
string
DRM platform used to distribute the game. Can be steam, playstation, xbox, uplay, origin, drmfree, gog, epicgames, nintendo_eshop, discord_game_store, or oculus. Make sure to have configured the required DRM platforms in your Publisher Account. If not passed in the token, will be chosen by the user in the payment UI.
