Xsolla-logo

Create payment token for purchaseServer-side

post/v3/project/{project_id}/admin/payment/token

Generates an order and a payment token for it. The order is generated based on the items passed in the request body.

To open the payment UI in a new window, use the following link: https://secure.xsolla.com/paystation4/?token={token}, where {token} is the received token.

For testing purposes, use this URL: https://sandbox-secure.xsolla.com/paystation4/?token={token}.

Notice

user.country.value parameter is used to select a currency for the order. If user's country is unknown, providing the user's IP in X-User-Ip header is an alternative option.
One of these two options is required for the correct work of this method.
The selected currency is used for payment methods at Pay Station.
SecuritybasicAuth
Request
path Parameters
project_id
required
integer

Project ID. You can find this parameter in your Publisher Account next to the name of the project.

Example: 44056
Request Body schema: application/json
required
object
required
object
value
string [ 1 .. 255 ] characters

User ID. For testing, you can pass any value. To accept real payments, you need to use the user ID value from your system. This ID is passed in the User validation webhook.

object
value
string [ 1 .. 255 ] characters

User screen name.

object
value
string <email> [ 3 .. 255 ] characters

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

object
value
string

Two-letter uppercase country code per ISO 3166-1 alpha-2. Is required if an IP address is not passed in the X-User-Ip header. Check the documentation for detailed information about countries supported by Xsolla.
Example: country=US

allow_modify
boolean
Default: false

Whether or not user can change the country in payment UI.

age
integer

User age.

object
value
required
string

User phone number.

allow_modify
boolean
Default: false

Whether or not user can change the phone in the payment UI. If phone.value is passed in the token, the value is false by default.

hidden
boolean
Default: true
object
value
required
string = 32 characters ^[A-Za-z0-9]{32}$

Unique tracking ID (used in marketing campaigns).

object
value
required
string = 17 characters ^\d{17}$

Steam ID.

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.

attributes
object [ 1 .. 100 ] items

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

required
object
required
Array of objects non-empty
Array (non-empty)
sku
required
string non-empty

Unique item ID. The SKU may only contain lowercase Latin alphanumeric characters, periods, dashes, and underscores.

quantity
required
number >= 1

Quantity of the item.

sandbox
boolean
Default: false

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

object

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

object

Interface settings.

theme
string
Default: "63295a9a2e47fab76f7708e1"

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 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
Default: true

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

type
string
Default: "normal"

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

Enum: "compact" "normal"
close_button
boolean
Default: false

Whether to show a Close button in desktop 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.

mode
string

Interface mode in payment UI. 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.

Value: "user_account"
object

User account details.

object

My payment accounts submenu.

enable
required
boolean
Default: false

Whether to show the submenu. false by default.

object

Page My account.

enable
required
boolean
Default: false

Whether to show the submenu. false by default.

order
required
integer >= 1

Position of the submenu in the menu.

object

Manage subscriptions submenu.

enable
required
boolean
Default: false

Whether to show the submenu. false by default.

order
required
integer >= 1

Position of the submenu in the menu.

object
visible_virtual_currency_balance
boolean
Default: true

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

object
object
close_button
boolean
Default: false

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

is_prevent_external_link_open
boolean
Default: false

Whether or not redirecting links to an external resource is disabled. 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
Default: false

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
Default: false

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

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
Default: true

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.

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
Default: false

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

is_cart_open_by_default
boolean
Default: false

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.

currency
string

Preferred payment currency. Three-letter currency code per ISO 4217. Check the documentation for detailed information about currencies supported by Xsolla.

language
string

Interface language. Two-letter lowercase language code.

external_id
string [ 1 .. 255 ] characters

Transaction external ID.

payment_method
integer >= 1

Payment method ID. It determines the display of currency in the payment interface, as some payment methods may only support certain currencies.

return_url
string <uri> <= 1000 characters

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_conditions
string

Payment status triggering user redirect to the return URL.

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

Delay after which the user will be automatically redirected to the return URL.

status_for_manual_redirection
string

Payment status triggering the display of a button clicking which redirects the user to the return URL.

Enum: "none" "vc" "successful" "successful_or_canceled" "any"
redirect_button_caption
string

Localized redirect button captions.

object or null [ 1 .. 200 ] properties

Your custom parameters represented as a valid JSON set of key-value pairs.
You can pass additional parameters through this field to configure anti-fraud filters. See Pay Station documentation.

additional property
string or integer or number or boolean
One of:
string
Responses
201

Successfully created payment token and order.

401

Basic authentication not passed or wrong. Make sure you used basic authentication or correct credentials.

422

Request body and creating cart validation error.

  • Invalid cart, created from passed items. Checks that the cart is not empty and that all items are not free.
  • Invalid request body.
Request samples
application/json
{
  • "user": {
    },
  • "purchase": {
    },
  • "settings": {
    }
}
Response samples
application/json
{
  • "token": "huooAqbXBSJxB8Q4dYBqJp4ybiInqsPb",
  • "order_id": 12345
}
System statusAll services operational

Privacy Settings

Privacy PolicyEnd User License Agreement© 2006–2024 Xsolla Inc.