# Create 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.

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

Endpoint: POST /merchants/{merchant_id}/token
Version: 2.0
Security: basicAuth

## Path parameters:

  - `merchant_id` (integer, required)
    Merchant ID.

## Request fields (application/json):

  - `user` (object)
    User details.
    Example: {"country":{"allow_modify":true,"value":"US"},"age":19,"email":{"value":"john.smith@mail.com"},"id":{"value":"user_2"},"name":{"value":"John Smith"}}

  - `user.id` (object, required)
    Example: {"value":"user_2"}

  - `user.id.value` (string, required)
    User ID.
    Example: "user_2"

  - `user.email` (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.
    Example: {"value":"john.smith@mail.com"}

  - `user.email.value` (string, required)
    User email. Must be valid according to the [RFC 822](https://www.w3.org/Protocols/rfc822/#z8) protocol.
    Example: "john.smith@mail.com"

  - `user.name` (object)
    Example: {"value":"John Smith"}

  - `user.name.value` (string)
    User screen name.
    Example: "John Smith"

  - `user.age` (integer)
    User age.
    Example: 19

  - `user.phone` (object)

  - `user.phone.value` (string)
    User phone number.

  - `user.country` (object)
    Example: {"allow_modify":true,"value":"US"}

  - `user.country.value` (string)
    Two-letter uppercase country code per [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
    Example: "US"

  - `user.country.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.
    Example: true

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

  - `user.steam_id` (object)

  - `user.steam_id.value` (string)
    Steam ID.

  - `user.tracking_id` (object)

  - `user.tracking_id.value` (string)
    Unique tracking ID (used in marketing campaigns).

  - `user.public_id` (object)

  - `user.public_id.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).

  - `user.utm` (object)
    Traffic attributes.

  - `user.utm.utm_source` (string)
    Traffic source.

  - `user.utm.utm_medium` (string)
    Traffic channel (contextual ads, media ads, email lists, etc.).

  - `user.utm.utm_campaign` (string)
    Campaign title, transliterated or translated to English.

  - `user.utm.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.

  - `user.utm.utm_content` (string)
    Campaign content.

  - `user.is_legal` (boolean)
    Whether the user is a legal entity.

  - `user.legal` (object)
    Object with legal entity details. Object and all its parameters are required if user.is_legal is true.

  - `user.legal.name` (string)
    Full legal name.

  - `user.legal.address` (string)
    Full legal address.

  - `user.legal.vat_id` (string)
    Individual taxpayer identifier.

  - `user.legal.country` (string)
    Country of incorporation. Two-letter uppercase country code per [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) is used.

  - `settings` (object)
    Custom project settings.
    Example: {"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"}}

  - `settings.project_id` (integer, required)
    Game’s Xsolla ID. Can be found in Publisher Account.
    Example: 16184

  - `settings.external_id` (string)
    Transaction ID in the game. Has to be unique for each user payment.

  - `settings.language` (string)
    Interface language. Two-letter lowercase [language code](https://developers.xsolla.com/doc/pay-station/features/localization/).
    Example: "en"

  - `settings.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.

  - `settings.redirect_policy` (object)
    Redirect policy settings.

  - `settings.redirect_policy.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"

  - `settings.redirect_policy.delay` (integer)
    Delay (in seconds) after which a user is automatically redirected to the return URL.

  - `settings.redirect_policy.autoredirect_from_status_page` (boolean)
    Whether to automatically redirect from the status page.

  - `settings.redirect_policy.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"

  - `settings.redirect_policy.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"

  - `settings.redirect_policy.redirect_button_caption` (string)
    Text on the button for manual redirection.

  - `settings.currency` (string)
    Preferred payment currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).
    Example: "USD"

  - `settings.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.

  - `settings.payment_method` (integer)
    Payment method ID.

  - `settings.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"

  - `settings.ui` (object)
    Interface settings.
    Example: {"components":{"virtual_currency":{"custom_amount":true}},"desktop":{"virtual_item_list":{"button_with_price":true,"layout":"list"}},"size":"medium"}

  - `settings.ui.theme` (string)
    Payment UI theme. Can be default or default_dark.
    Enum: "default", "default_dark"

  - `settings.ui.size` (string)
    Payment UI size. Can be:
  - [small](https://livedemo.xsolla.com/developers/small/): the least possible size of the payment UI. Use this value when the window size is strictly limited (dimensions: 620 x 630)
  - [medium](https://livedemo.xsolla.com/developers/medium/): recommended size. Use this value to display the payment UI in a lightbox (dimensions: 740 x 760)
  - [large](https://livedemo.xsolla.com/developers/large/): the optimal size for displaying the payment UI in a new window or tab (dimensions: 820 x 840)
    Enum: "small", "medium", "large"

  - `settings.ui.version` (string)
    Device type. Can be desktop (default) or mobile.
    Enum: "desktop", "mobile"

  - `settings.ui.desktop` (object)
    Interface settings for the desktop version.
    Example: {"virtual_item_list":{"button_with_price":true,"layout":"list"}}

  - `settings.ui.desktop.header` (object)
    Header settings.

  - `settings.ui.desktop.header.is_visible` (boolean)
    Whether to show the header in the payment UI.

  - `settings.ui.desktop.header.visible_logo` (boolean)
    If true, the header will show your logo (first provide the image to your Customer Success Manager).

  - `settings.ui.desktop.header.visible_name` (boolean)
    Whether to show the project name in the header.

  - `settings.ui.desktop.header.visible_purchase` (boolean)
    Whether to show the purchase description (purchase.description.value) in the header. true by default.

  - `settings.ui.desktop.header.type` (string)
    How to show the header. Can be compact (hides project name and user ID) or normal (default).
    Enum: "compact", "normal"

  - `settings.ui.desktop.header.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.

  - `settings.ui.desktop.subscription_list` (object)
    Settings for the list of subscription plans.

  - `settings.ui.desktop.subscription_list.layout` (string)
    List template. Can be list (default) or grid.
    Enum: "list", "grid"

  - `settings.ui.desktop.subscription_list.description` (string)
    Any text to show above the list of available subscription plans in the payment UI.

  - `settings.ui.desktop.subscription_list.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.

  - `settings.ui.desktop.virtual_item_list` (object)
    Settings for the list of virtual items.
    Example: {"button_with_price":true,"layout":"list"}

  - `settings.ui.desktop.virtual_item_list.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.
    Example: true

  - `settings.ui.desktop.virtual_item_list.view` (string)
    Display virtual item groups as a vertical/horizontal menu. Can be horizontal_navigation or vertical_navigation (default).
    Enum: "horizontal_navigation", "vertical_navigation"

  - `settings.ui.desktop.virtual_currency_list` (object)
    Settings for the list of virtual currencies.

  - `settings.ui.desktop.virtual_currency_list.description` (string)
    Any text to show above the list of virtual currencies.

  - `settings.ui.header` (object)

  - `settings.ui.header.visible_virtual_currency_balance` (boolean)
    Whether or not this element can be hidden on Payment UI. true by default.

  - `settings.ui.mobile` (object)

  - `settings.ui.mobile.mode` (string)
    A user can only pay using their saved payment methods. Can be saved_accounts.
    Enum: "saved_accounts"

  - `settings.ui.mobile.footer` (object)

  - `settings.ui.mobile.footer.is_visible` (boolean)
    Whether to hide the footer in the mobile version of the payment UI.

  - `settings.ui.license_url` (string)
    Link to the EULA.

  - `settings.ui.components` (object)
    Menu settings.
    Example: {"virtual_currency":{"custom_amount":true}}

  - `settings.ui.components.virtual_items` (object)
    Virtual items submenu settings.

  - `settings.ui.components.virtual_items.order` (integer)
    Position of the submenu in the menu.

  - `settings.ui.components.virtual_items.hidden` (boolean)
    Whether to show the submenu.

  - `settings.ui.components.virtual_items.selected_group` (string)
    Group to show after opening the virtual items tab.

  - `settings.ui.components.virtual_items.selected_item` (string)
    Item to show after opening the virtual items tab (item SKU).

  - `settings.ui.components.virtual_currency` (object)
    Virtual currency submenu settings.
    Example: {"custom_amount":true}

  - `settings.ui.components.virtual_currency.custom_amount` (boolean)
    Whether the user can enter an arbitrary quantity of the virtual currency in the payment UI.
    Example: true

  - `settings.ui.components.subscriptions` (object)
    Subscription plans submenu settings.

  - `settings.ui.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.

  - `settings.ui.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.

  - `settings.ui.user_account` (object)
    User account details.

  - `settings.ui.user_account.info` (object)
    Page My account.

  - `settings.ui.user_account.info.enable` (boolean)
    Whether to show the submenu. false by default.

  - `settings.ui.user_account.history` (object)
    History submenu.

  - `settings.ui.user_account.payment_accounts` (object)
    My payment accounts submenu.

  - `settings.ui.user_account.subscriptions` (object)
    Manage subscriptions submenu.

  - `purchase` (object)
    Object containing purchase details.
    Example: {"checkout":{"currency":"USD","amount":10},"subscription":{"gift":{"recipient":"test_recipient_v1","email":"recipient_email@email.com"}}}

  - `purchase.checkout` (object)
    Object containing checkout details.
    Example: {"currency":"USD","amount":10}

  - `purchase.checkout.currency` (string)
    Currency of the purchase. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).
    Example: "USD"

  - `purchase.checkout.amount` (integer)
    Purchase amount.
    Example: 10

  - `purchase.subscription` (object)
    Subscription data.
    Example: {"gift":{"recipient":"test_recipient_v1","email":"recipient_email@email.com"}}

  - `purchase.subscription.plan_id` (string)
    External ID of the subscription plan. Can be found in the Subscriptions > Subscription plans section of Publisher Account.

  - `purchase.subscription.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.

  - `purchase.subscription.product_id` (string)
    Product ID.

  - `purchase.subscription.currency` (string)
    Currency of the subscription plan to use in all calculations.

  - `purchase.subscription.available_plans` (array)
    Subscription plans to show in the payment UI.

  - `purchase.subscription.trial_days` (integer)
    Trial period in days.

  - `purchase.subscription.gift` (object)
    Gifted subscription details.
    Example: {"recipient":"test_recipient_v1","email":"recipient_email@email.com"}

  - `purchase.subscription.gift.recipient` (string, required)
    ID of the recipient.
    Example: "test_recipient_v1"

  - `purchase.subscription.gift.email` (string, required)
    Recipient email.
    Example: "recipient_email@email.com"

  - `purchase.subscription.gift.anonymous` (boolean)
    Whether to hide the gifter name. If true, the sender's name is hidden in the email notification. Defaults to false.

  - `purchase.subscription.gift.message` (string)
    Message for the recipient.

  - `purchase.subscription.gift.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.

  - `custom_parameters` (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](https://developers.xsolla.com/doc/pay-station/features/antifraud/).

  - `custom_parameters.registration_date` (string)
    Account creation date per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

  - `custom_parameters.total_hours` (integer)
    Total number of in-game hours.

  - `custom_parameters.total_characters` (integer)
    Number of in-game characters.

  - `custom_parameters.social_networks_added` (boolean)
    Whether the player has connected social media profiles.

  - `custom_parameters.profile_image_added` (boolean)
    Whether the player has uploaded a profile image.

  - `custom_parameters.active_date` (string)
    Last seen date per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

  - `custom_parameters.total_friends` (integer)
    Number of friends.

  - `custom_parameters.additional_verification` (boolean)
    Whether the player uses account verification procedures.

  - `custom_parameters.win_rate` (integer)
    Win rate.

  - `custom_parameters.last_change_password_date` (string)
    Last password change date per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

  - `custom_parameters.chat_activity` (boolean)
    Whether the player uses the chat function.

  - `custom_parameters.forum_activity` (boolean)
    Whether the player uses the forum function.

  - `custom_parameters.total_bans` (integer)
    Number of times the player was banned in the chat/forum.

  - `custom_parameters.profile_completed` (boolean)
    Whether the player added additional information to their profile.

  - `custom_parameters.notifications_enabled` (boolean)
    Whether the player enabled notifications.

  - `custom_parameters.user_level` (integer)
    Player’s level, reputation, or rank.

  - `custom_parameters.karma_points` (integer)
    Player’s karma.

  - `custom_parameters.total_sum` (integer)
    Total amount of payments.

  - `custom_parameters.non_premium_currency` (integer)
    Amount of non-premium currency.

  - `custom_parameters.total_game_events` (integer)
    Number of in-game events the player took part in.

  - `custom_parameters.total_gifts` (integer)
    Number of in-game gifts the player has sent/received.

  - `custom_parameters.tutorial_completed` (boolean)
    Whether the player has completed the game’s tutorial.

  - `custom_parameters.completed_tasks` (integer)
    Number of tasks/objectives completed.

  - `custom_parameters.items_used` (boolean)
    Whether the player uses purchased in-game items.

  - `custom_parameters.pvp_activity` (boolean)
    Whether the player takes part in PvP battles.

  - `custom_parameters.total_clans` (integer)
    Number of clans the player is a member of.

  - `custom_parameters.unlocked_achievements` (integer)
    Number of achievements unlocked.

  - `custom_parameters.total_inventory_value` (integer)
    Total inventory value (in-game currency).

  - `custom_parameters.character_customized` (boolean)
    Whether the player has customized their character.

  - `custom_parameters.session_time` (string)
    Average session time per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

## Response 200 fields (application/json):

  - `token` (string)

## Response 422 fields (application/json):

  - `http_status_code` (integer)

  - `message` (string)

  - `extended_message` (object)

  - `extended_message.global_errors` (array)

  - `extended_message.property_errors` (object)
    Object contains parameter names with error descriptions.

  - `request_id` (string)