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.
By default, the token lifetime is 24 hours. If you want to change this value, contact your Customer Success Manager or send an email to csm@xsolla.com. The new value will be enabled for all your company’s projects created in Publisher Account.
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.
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
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
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.
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 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.
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.
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
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.
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
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.
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.
gp_quick_payment_button
boolean
The way the Google Pay payment method is displayed. If true, the button for quick payment via Google Pay is displayed at the top of the payment UI. If false, Google Pay is displayed in the list of payment methods according to the PayRank algorithm. false by default.
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
This object contains parameters to configure anti-fraud filters. The list of parameters is shown below. To add custom parameters, contact your Customer Success Manager or email at csm@xsolla.com.
