Xsolla Documentation - Pay Station API v1.0

Overview

The section describes methods for working with Pay Station. Use basic authentication to call methods. To open the payment UI and enable secure payments, you first need to get a token.

Endpoint path: https://api.xsolla.com.

Open Pay Station

Pay Station is a complete payment UI that allows your users to purchase games and items on your website. To easily implement the payment UI on your website, download the script from our CDN. Use this URL to integrate the script on your website. For more information visit our GitHub repository.

Script initialization parameters:

Parameter	Type	Description
access_token	string	Token, received via API. Required.
sandbox	boolean	Set to true to test the payment process: sandbox-secure.xsolla.com will be used instead of secure.xsolla.com.
lightbox	object	Lightbox parameters (object; desktop version only).
lightbox.width	string	Lightbox frame width. If null, depends on Pay Station width. Default is null.
lightbox.height	string	Lightbox frame height. If null, depends on Pay Station height. Default is `100%`.
lightbox.zIndex	integer	Defines arrangement order. Default is 1000.
lightbox.overlayOpacity	integer	Overlay opacity (0 to 1). Default is `.6`.
lightbox.overlayBackground	string	Overlay background color. Default is `#000000`.
lightbox.modal	boolean	If true, the lightbox frame cannot be closed. Default is `false`.
lightbox.closeByClick	boolean	If true, clicking the overlay will close the lightbox. Default is `true`.
lightbox.closeByKeyboard	boolean	If true, pressing ESC will close the lightbox. Default is `true`.
lightbox.contentBackground	string	Frame background color. Default is `#ffffff`. Note that these color changes do not affect the Pay Station iframe itself, only the settings of the lightbox that hold it.
lightbox.contentMargin	string	Frame margin. Default is `10px`.
lightbox.spinner	string	Type of animated loading indicator. Can be `xsolla` or `round`. Default is `xsolla`.
lightbox.spinnerColor	string	Spinner color. No default value.
childWindow	object	Options for the child window containing the Pay Station UI. Supported in the mobile version.
childWindow.target	string	Where to open the Pay Station window. Can be `_blank`, `_self`, `_parent`. Default is `_blank`.

The script allows you to track payment UI events. Depending on the event type, you can perform various actions on the web page.

List of events:

Parameter	Description
init	Widget initialized.
open	Widget opened.
load	Payment UI (Pay Station) loaded.
close	Payment UI (Pay Station) closed.
status	User is on the status page.
status-invoice	User is on the status page; payment in progress.
status-delivering	Event when the user was moved on the status page, payment was completed, and we're sending payment notification.
status-done	User is on the status page; payment credited to the user's account.
status-troubled	Event when the user was moved on the status page, but the payment failed.

If you want to initialize the opening of the payment UI by yourself, use this link: https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN.

Note: It is necessary to use the link with the https:// prefix only for the payment UI opening.

Use the following URL for testing purposes: https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN.

Notice: Parameter access_token contains private user data. Make sure that you use server-to-server communication when getting this parameter.

Token

In order to enable secure payments, Xsolla API handles payment parameters within a token instead of receiving them directly through GET requests to the payment page. You have to obtain a new token before rendering the payment page. A token is valid for 24 hours.

Get Token

You can create a token with arbitrary user parameters. You send these parameters when obtaining the token, and we send them back to you after a successful payment. A token can only contain parameters either described in this document or predefined by the partner.

Notice: This API method can't be used under high load. When the number of requests is high, rate limits may apply. Contact your Account Manager to find out the rate limits for this API method.

HTTP REQUEST

Copy

Full screen

Small screen

POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

Parameter	Type	Description
user	object	User details (object).
user.id	object	User ID (object). Required.
user.id.value	string	User ID.
user.name	object	User screen name (object).
user.name.value	string	User screen name.
user.age	integer	User age.
user.email	object	User email (object). The user.email object is an integral part of building anti-fraud models and payment processing. It is both Xsolla and payment systems requirement. Missing this parameter can lead to lower acceptance rates. Required.
user.email.value	string	User email. Must be valid according to the RFC 822 protocol. Required.
user.phone	object	User phone number (object).
user.phone.value	string	User phone number.
user.country	object	User country (object).
user.country.value	string	Two-letter uppercase country code per ISO 3166-1 alpha-2.
user.country.allow_modify	boolean	Whether or not user can change the country on payment UI. `false` by default.
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's Steam ID (object).
user.steam_id.value	string	Steam ID.
user.tracking_id	object	User tracking ID (object).
user.tracking_id.value	string	Unique tracking ID (used in marketing campaigns).
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 (object).
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 is used.
settings	object	Custom project settings (object).
settings.external_id	string	Transaction’s external ID.
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account. Required.
settings.language	string	Interface language. Two-letter lowercase language code.
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 (object).
settings.redirect_policy.redirect_conditions	string	Payment status for which a user is redirected to the return URL. Can be `none`, `successful`, `successful_or_canceled`, or `any`.
settings.redirect_policy.delay	integer	Delay (in seconds) after which a user is automatically redirected to the return URL.
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_canceled`, or `any`.
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.
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.
settings.ui	object	Interface settings (object).
settings.ui.theme	string	Payment UI theme. Can be `default` or `default_dark`.
settings.ui.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)
settings.ui.version	string	Device type. Can be `desktop` (default) or `mobile`.
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.desktop	object	Interface settings for the desktop version (object).
settings.ui.desktop.header	object	Header settings (object).
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 account 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).
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 (object).
settings.ui.desktop.subscription_list.layout	string	List template. Can be `list` (default) or `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 (object).
settings.ui.desktop.virtual_item_list.layout	string	List template. Can be `list` (default) or `grid`.
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.
settings.ui.desktop.virtual_item_list.view	string	Display virtual item groups as a vertical/horizontal menu. Can be `horizontal_navigation` or `vertical` (default).
settings.ui.desktop.virtual_currency_list	object	Settings for the list of virtual currencies (object).
settings.ui.desktop.virtual_currency_list.description	string	Any text to show above the list of virtual currencies.
settings.ui.desktop.virtual_currency_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.
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.mode	string	A user can only pay using their saved payment methods. Can be `saved_accounts`.
settings.ui.mobile.header.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.
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 (object).
settings.ui.components.virtual_items	object	Virtual items submenu.
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.ui.components.virtual_currency.custom_amount	boolean	Whether the user can enter an arbitrary quantity of the virtual currency in the payment UI.
settings.ui.components.virtual_currency.order	integer	Position of the submenu in the menu.
settings.ui.components.virtual_currency.hidden	boolean	Whether to show the submenu.
settings.ui.components.subscriptions	object	Subscription plans submenu (object).
settings.ui.components.subscriptions.order	integer	Position of the submenu in the menu.
settings.ui.components.subscriptions.hidden	boolean	Whether to show the submenu.
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.
settings.ui.user_account	object	User account details (object).
settings.ui.user_account.info	object	Page My account.
settings.ui.user_account.info.order	integer	Position of the submenu in the menu.
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.history.order	integer	Position of the submenu in the menu.
settings.ui.user_account.history.enable	boolean	Whether to show the submenu. `false` by default.
settings.ui.user_account.payment_accounts	object	My payment accounts submenu.
settings.ui.user_account.payment_accounts.order	integer	Position of the submenu in the menu.
settings.ui.user_account.payment_accounts.enable	boolean	Whether to show the submenu. `false` by default.
settings.ui.user_account.subscriptions	object	Manage subscriptions submenu.
settings.ui.user_account.subscriptions.order	integer	Position of the submenu in the menu.
settings.ui.user_account.subscriptions.enable	boolean	Whether to show the submenu. `false` by default.
purchase	object	Object containing purchase details.
purchase.virtual_currency	object	Object containing virtual currency details.
purchase.virtual_currency.quantity	float	Purchase amount in the virtual currency.
purchase.virtual_currency.currency	string	Currency of the virtual currency package to use in all calculations.
purchase.virtual_items	object	Object with data about the virtual items in purchase.
purchase.virtual_items.currency	string	Currency of the ordered items to use in all calculations.
purchase.virtual_items.items	array	Item data (array).
purchase.virtual_items.items.sku	string	Item ID.
purchase.virtual_items.items.amount	integer	Item quantity.
purchase.virtual_items.available_groups	array	Item groups IDs (array). The payment UI will only include items within the specified group.
purchase.subscription	object	Subscription data (object).
purchase.subscription.plan_id	string	Plan ID.
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 (array) to show in the payment UI.
purchase.subscription.trial_days	integer	Trial period in days.
purchase.pin_codes	object	Game keys (object).
purchase.pin_codes.currency	string	Currency of a Game key within the order to use in all calculations.
purchase.pin_codes.codes	array	Game keys (array).
purchase.pin_codes.codes.digital_content	string	Game SKU set in Publisher Account.
purchase.pin_codes.codes.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.
purchase.pin_codes.upgrade	object	Object with the upgrade data.
purchase.pin_codes.upgrade.id_user_history	integer	ID of the entry containing data on the user and their packages.
purchase.pin_codes.upgrade.id	integer	Upgrade ID.
purchase.gift	object	Gift details (object).
purchase.gift.giver_id	string	Giver ID.
purchase.gift.message	string	Message from the giver.
purchase.gift.hide_giver_from_receiver	string	Whether to hide the giver identity from the recipient. `true` by default.
purchase.gift.friends	array	Array with data on friends.
purchase.gift.friends.id	string	Gift recipient ID.
purchase.gift.friends.name	string	Gift recipient nickname.
purchase.gift.friends.email	string	Gift recipient email.
purchase.coupon_code	object	Information about a discount promo code or bonuses upon purchase (object).
purchase.coupon_code.value	string	Promo code value.
purchase.coupon_code.hidden	boolean	Hide the field promo code is entered into in the payment UI. `false` by default.
custom_parameters	object	Your custom parameters, represented as a valid JSON set of key-value pairs.

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 we will provide you an information what exactly parameters have been send incorrectly.

Copy

Full screen

Small screen

{
    "extended_message": {
        "global_errors": [],
        "property_errors": {
            "settings.project_id": [
                "string value found, but an integer is required"
            ]
        }
    }
}

Copy

Full screen

Small screen

http

Request

POST https://api.xsolla.com/merchant/v1/merchants/{merchant_id}/token

Headers:
  Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json

Body:
  {
  "purchase": {
    "virtual_currency": {
      "quantity": 100
    },
    "virtual_items": {
      "items": [
        {
          "amount": 1,
          "sku": "SKU01"
        }
      ]
    }
  },
  "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"
    }
  }
}

curl --request POST \
  --url https://api.xsolla.com/merchant/v1/merchants/{merchant_id}/token \
  --header 'authorization: Basic <your_authorization_basic_key>' \
  --header 'content-type: application/json' \
  --data '{"user":{"id":{"value":"user_2"},"name":{"value":"John Smith"},"age":19,"email":{"value":"john.smith@mail.com"},"country":{"value":"US","allow_modify":true}},"settings":{"project_id":16184,"currency":"USD","language":"en","ui":{"size":"medium","desktop":{"virtual_item_list":{"layout":"list","button_with_price":true}},"components":{"virtual_currency":{"custom_amount":true}}}},"purchase":{"virtual_currency":{"quantity":100},"virtual_items":{"items":[{"sku":"SKU01","amount":1}]}}}'

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"user":{"id":{"value":"user_2"},"name":{"value":"John Smith"},"age":19,"email":{"value":"john.smith@mail.com"},"country":{"value":"US","allow_modify":true}},"settings":{"project_id":16184,"currency":"USD","language":"en","ui":{"size":"medium","desktop":{"virtual_item_list":{"layout":"list","button_with_price":true}},"components":{"virtual_currency":{"custom_amount":true}}}},"purchase":{"virtual_currency":{"quantity":100},"virtual_items":{"items":[{"sku":"SKU01","amount":1}]}}}');

$request->setRequestUrl('https://api.xsolla.com/merchant/v1/merchants/{merchant_id}/token');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'authorization' => 'Basic <your_authorization_basic_key>',
  'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

var client = new RestClient("https://api.xsolla.com/merchant/v1/merchants/{merchant_id}/token");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"age\":19,\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

import http.client

conn = http.client.HTTPSConnection("api.xsolla.com")

payload = "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"age\":19,\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}"

headers = {
    'content-type': "application/json",
    'authorization': "Basic <your_authorization_basic_key>"
    }

conn.request("POST", "/merchant/v1/merchants/{merchant_id}/token", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'

url = URI("https://api.xsolla.com/merchant/v1/merchants/{merchant_id}/token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["authorization"] = 'Basic <your_authorization_basic_key>'
request.body = "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"age\":19,\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}"

response = http.request(request)
puts response.read_body

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"age\":19,\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}");
Request request = new Request.Builder()
  .url("https://api.xsolla.com/merchant/v1/merchants/{merchant_id}/token")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Basic <your_authorization_basic_key>")
  .build();

Response response = client.newCall(request).execute();

var data = JSON.stringify({
  "user": {
    "id": {
      "value": "user_2"
    },
    "name": {
      "value": "John Smith"
    },
    "age": 19, 
    "email": {
      "value": "john.smith@mail.com"
    },
    "country": {
      "value": "US",
      "allow_modify": true
    }
  },
  "settings": {
    "project_id": 16184,
    "currency": "USD",
    "language": "en",
    "ui": {
      "size": "medium",
      "desktop": {
        "virtual_item_list": {
          "layout": "list",
          "button_with_price": true
        }
      },
      "components": {
        "virtual_currency": {
          "custom_amount": true
        }
      }
    }
  },
  "purchase": {
    "virtual_currency": {
      "quantity": 100
    },
    "virtual_items": {
      "items": [
        {
          "sku": "SKU01",
          "amount": 1
        }
      ]
    }
  }
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.xsolla.com/merchant/v1/merchants/{merchant_id}/token");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");

xhr.send(data);

Response

{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}

{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}

{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}

{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}

{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}

{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}

{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}

{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}

Additional Parameters List

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 table below. You can extend the list as needed.

See recipe

Parameter	Type	Description
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	float	Total amount of payments.
non_premium_currency	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	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.

Tokenization

To learn more about setting up tokenization for your app, see the Pay Station documentation.

Get Saved Accounts

Lists saved payment accounts of a given user.

HTTP REQUEST

Copy

Full screen

Small screen

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts

Parameter	Type	Description
project_id	integer	Project ID.
user_id	string	User ID.

Copy

Full screen

Small screen

http

Request

GET https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts

Headers:
  Authorization: Basic <your_authorization_basic_key>

curl --request GET \
  --url https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts \
  --header 'authorization: Basic <your_authorization_basic_key> '

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Basic <your_authorization_basic_key> '
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

var client = new RestClient("https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Basic <your_authorization_basic_key> ");
IRestResponse response = client.Execute(request);

import http.client

conn = http.client.HTTPSConnection("api.xsolla.com")

headers = { 'authorization': "Basic <your_authorization_basic_key> " }

conn.request("GET", "/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'

url = URI("https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Basic <your_authorization_basic_key> '

response = http.request(request)
puts response.read_body

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts")
  .get()
  .addHeader("authorization", "Basic <your_authorization_basic_key> ")
  .build();

Response response = client.newCall(request).execute();

var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key> ");

xhr.send(data);

Response

[
  {
    "id": 4612345,
    "name": "PP_saved_account",
    "payment_system": {
      "id": 24,
      "name": "PayPal"
    },
    "type": "paypal"
  }
]

[
  {
    "id": 4612345,
    "name": "PP_saved_account",
    "payment_system": {
      "id": 24,
      "name": "PayPal"
    },
    "type": "paypal"
  }
]

[
  {
    "id": 4612345,
    "name": "PP_saved_account",
    "payment_system": {
      "id": 24,
      "name": "PayPal"
    },
    "type": "paypal"
  }
]

[
  {
    "id": 4612345,
    "name": "PP_saved_account",
    "payment_system": {
      "id": 24,
      "name": "PayPal"
    },
    "type": "paypal"
  }
]

[
  {
    "id": 4612345,
    "name": "PP_saved_account",
    "payment_system": {
      "id": 24,
      "name": "PayPal"
    },
    "type": "paypal"
  }
]

[
  {
    "id": 4612345,
    "name": "PP_saved_account",
    "payment_system": {
      "id": 24,
      "name": "PayPal"
    },
    "type": "paypal"
  }
]

[
  {
    "id": 4612345,
    "name": "PP_saved_account",
    "payment_system": {
      "id": 24,
      "name": "PayPal"
    },
    "type": "paypal"
  }
]

[
  {
    "id": 4612345,
    "name": "PP_saved_account",
    "payment_system": {
      "id": 24,
      "name": "PayPal"
    },
    "type": "paypal"
  }
]

Charge With Saved Account

Charges a user via a saved payment account.

Notice: This API method can't be used under high load. When the number of requests is high, rate limits may apply. Contact your Account Manager to find out the rate limits for this API method.

HTTP REQUEST

Copy

Full screen

Small screen

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}

Parameter	Type	Description
project_id	integer	Project ID. Required.
user_id	string	User ID. Required.
type	string	Type of payment account. Required. Possible values: `card` — bank cards, `amazon` — Amazon Pay, `skrill` — Skrill Digital Wallet, `yandex` — Yandex.Money, `paymasterwebmoney` — WebMoney, `paypal` — PayPal, `qiwi` — QIWI Wallet. If you receive an HTTP 200 success status code, the request returns a transaction ID and its status. Possible statuses: processing — the transaction is in process done — the transaction successfully processed error — an error occurred processing the transaction canceled — the transaction is cancelled held — funds on the user’s account are on hold If you receive an HTTP 422 error status code, the request returns an error code with its detailed description.
account_id	integer	ID of the saved account in Xsolla database. Required.
user	object	User details (object).
user.ip	string	User IP address. Required.
user.name	string	Username.
user.legal	object	Object with legal entity details.
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 is used.
purchase	object	Object containing purchase details.
purchase.virtual_currency	object	Object containing virtual currency details.
purchase.virtual_currency.quantity	float	Purchase amount in the virtual currency.
purchase.checkout	object	Object containing checkout details.
purchase.checkout.currency	string	Currency of the purchase. Three-letter currency code per ISO 4217.
purchase.checkout.amount	float	Purchase amount.
settings	object	Object containing purchase settings.
settings.mode	string	Set to `sandbox` to test out the payment process. Remove the parameter for real payments.
custom_parameters	string	Your custom parameters, represented as a valid JSON set of key-value pairs.

Copy

Full screen

Small screen

http

Request

POST https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}

Headers:
  Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json

Body:
  {
  "card": {
    "cvn": "123"
  },
  "purchase": {
    "description": {
      "value": "currency purchase"
    },
    "virtual_currency": {
      "quantity": 100
    }
  },
  "settings": {
    "currency": "USD",
    "external_id": "ext123",
    "save": true
  },
  "user": {
    "id": "user123",
    "ip": "111.11.11.11",
    "name": "John Smith",
    "legal" : {
      "name": "My Awesome Company",
      "address": "17 Crown Street London SW2 0JW United Kingdom",
      "vat_id": "GB111111111",
      "country": "GB"
  }
}

curl --request POST \
  --url https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payments/{type}/{account_id} \
  --header 'authorization: Basic <your_authorization_basic_key>' \
  --header 'content-type: application/json' \
  --data '{"user":{"id":"user123","ip":"111.11.11.11","name":"John Smith","legal":{"name":"My Awesome Company","address":"17 Crown Street London SW2 0JW United Kingdom","vat_id":"GB111111111","country":" GB"}},"card":{"cvn":"123"},"purchase":{"virtual_currency":{"quantity":100},"description":{"value":"currency purchase"}},"settings":{"save":true,"currency":"USD","external_id":"ext123"}}'

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"user":{"id":"user123","ip":"111.11.11.11","name":"John Smith","legal":{"name":"My Awesome Company","address":"17 Crown Street London SW2 0JW United Kingdom","vat_id":"GB111111111","country":" GB"}},"card":{"cvn":"123"},"purchase":{"virtual_currency":{"quantity":100},"description":{"value":"currency purchase"}},"settings":{"save":true,"currency":"USD","external_id":"ext123"}}');

$request->setRequestUrl('https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'authorization' => 'Basic <your_authorization_basic_key>',
  'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

var client = new RestClient("https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"user\":{\"id\":\"user123\",\"ip\":\"111.11.11.11\",\"name\":\"John Smith\",\"legal\":{\"name\":\"My Awesome Company\",\"address\":\"17 Crown Street London SW2 0JW United Kingdom\",\"vat_id\":\"GB111111111\",\"country\":\"GB\"}},\"card\":{\"cvn\":\"123\"},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"description\":{\"value\":\"currency purchase\"}},\"settings\":{\"save\":true,\"currency\":\"USD\",\"external_id\":\"ext123\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

import http.client

conn = http.client.HTTPSConnection("api.xsolla.com")

payload = "{\"user\":{\"id\":\"user123\",\"ip\":\"111.11.11.11\",\"name\":\"John Smith\",\"legal\":{\"name\":\"My Awesome Company\",\"address\":\"17 Crown Street London SW2 0JW United Kingdom\",\"vat_id\":\"GB111111111\",\"country\":\"GB\"}},\"card\":{\"cvn\":\"123\"},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"description\":{\"value\":\"currency purchase\"}},\"settings\":{\"save\":true,\"currency\":\"USD\",\"external_id\":\"ext123\"}}"

headers = {
    'content-type': "application/json",
    'authorization': "Basic <your_authorization_basic_key>"
    }

conn.request("POST", "/merchant/v1/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'

url = URI("https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["authorization"] = 'Basic <your_authorization_basic_key>'
request.body = "{\"user\":{\"id\":\"user123\",\"ip\":\"111.11.11.11\",\"name\":\"John Smith\",\"legal\":{\"name\":\"My Awesome Company\",\"address\":\"17 Crown Street London SW2 0JW United Kingdom\",\"vat_id\":\"GB111111111\",\"country\":\"GB\"}},\"card\":{\"cvn\":\"123\"},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"description\":{\"value\":\"currency purchase\"}},\"settings\":{\"save\":true,\"currency\":\"USD\",\"external_id\":\"ext123\"}}"

response = http.request(request)
puts response.read_body

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"user\":{\"id\":\"user123\",\"ip\":\"111.11.11.11\",\"name\":\"John Smith\",\"legal\":{\"name\":\"My Awesome Company\",\"address\":\"17 Crown Street London SW2 0JW United Kingdom\",\"vat_id\":\"GB111111111\",\"country\":\"GB\"}},\"card\":{\"cvn\":\"123\"},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"description\":{\"value\":\"currency purchase\"}},\"settings\":{\"save\":true,\"currency\":\"USD\",\"external_id\":\"ext123\"}}");
Request request = new Request.Builder()
  .url("https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Basic <your_authorization_basic_key>")
  .build();

Response response = client.newCall(request).execute();

var data = JSON.stringify({
  "user": {
    "id": "user123",
    "ip": "111.11.11.11",
    "name": "John Smith",
    "legal" : {
      "name": "My Awesome Company",
      "address": "17 Crown Street London SW2 0JW United Kingdom",
      "vat_id": "GB111111111",
      "country": "GB"
    },
  },
  "card": {
    "cvn": "123"
  },
  "purchase": {
    "virtual_currency": {
      "quantity": 100
    },
    "description": {
      "value": "currency purchase"
    }
  },
  "settings": {
    "save": true,
    "currency": "USD",
    "external_id": "ext123"
  }
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");

xhr.send(data);

Response

{
    "transaction_id": 123458390
}

{
    "transaction_id": 123458390
}

{
    "transaction_id": 123458390
}

{
    "transaction_id": 123458390
}

{
    "transaction_id": 123458390
}

{
    "transaction_id": 123458390
}

{
    "transaction_id": 123458390
}

{
    "transaction_id": 123458390
}

Delete Saved Account

Deletes a saved payment account.

HTTP REQUEST

Copy

Full screen

Small screen

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}

Parameter	Type	Description
project_id	integer	Project ID.
user_id	string	User ID.
type	string	Type of payment account. Possible values: `card` — bank cards, `amazon` — Amazon Pay, `skrill` — Skrill Digital Wallet, `yandex` — Yandex.Money, `paymasterwebmoney` — WebMoney, `paypal` — PayPal, `qiwi` — QIWI Wallet. If you receive an HTTP 200 success status code, the request returns a transaction ID and its status. Possible statuses: processing — the transaction is in process done — the transaction successfully processed error — an error occurred processing the transaction canceled — the transaction is cancelled held — funds on the user’s account are on hold If you receive an HTTP 422 error status code, the request returns an error code with its detailed description.
account_id	integer	ID of the saved account in Xsolla database.

Copy

Full screen

Small screen

http

Request

DELETE https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}

Headers:
  Authorization: Basic <your_authorization_basic_key>

curl --request DELETE \
  --url https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id} \
  --header 'authorization: Basic <your_authorization_basic_key>'

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}');
$request->setRequestMethod('DELETE');
$request->setHeaders(array(
  'authorization' => 'Basic <your_authorization_basic_key>'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

var client = new RestClient("https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}");
var request = new RestRequest(Method.DELETE);
request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
IRestResponse response = client.Execute(request);

import http.client

conn = http.client.HTTPSConnection("api.xsolla.com")

headers = { 'authorization': "Basic <your_authorization_basic_key>" }

conn.request("DELETE", "/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'

url = URI("https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Basic <your_authorization_basic_key>'

response = http.request(request)
puts response.read_body

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}")
  .delete(null)
  .addHeader("authorization", "Basic <your_authorization_basic_key>")
  .build();

Response response = client.newCall(request).execute();

var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");

xhr.send(data);

Response

Thank you for your feedback!

We'll review your message and use it to help us improve your experience.

Rate this page

Don't want to answer

Thank you for your feedback!

Last updated: May 28, 2018

Found a typo or other text error? Select the text and press Ctrl+Enter.

Your browser is not supported. Please try a different browser

Pay Station API v1.0

Overview

Open Pay Station

access_token

sandbox

lightbox

lightbox.width

lightbox.height

lightbox.zIndex

lightbox.overlayOpacity

lightbox.overlayBackground

lightbox.modal

lightbox.closeByClick

lightbox.closeByKeyboard

lightbox.contentBackground

lightbox.contentMargin

lightbox.spinner

lightbox.spinnerColor

childWindow

childWindow.target

Token

Get Token

user

user.id

user.id.value

user.name

user.name.value

user.age

user.email

user.email.value

user.phone

user.phone.value

user.country

user.country.value

user.country.allow_modify

user.attributes

user.steam_id

user.steam_id.value

user.tracking_id

user.tracking_id.value

user.public_id.value

user.utm

user.utm.utm_source

user.utm.utm_medium

user.utm.utm_campaign

user.utm.utm_term

user.utm.utm_content

user.is_legal

user.legal

user.legal.name

user.legal.address

user.legal.vat_id

user.legal.country

settings

settings.external_id

settings.project_id

settings.language

settings.return_url

settings.redirect_policy

settings.redirect_policy.redirect_conditions

settings.redirect_policy.delay

settings.redirect_policy.status_for_manual_redirection

settings.redirect_policy.redirect_button_caption

settings.currency

settings.mode

settings.payment_method

settings.payment_widget

settings.ui

settings.ui.theme

settings.ui.size

settings.ui.version

settings.ui.is_prevent_external_link_open

settings.ui.desktop

settings.ui.desktop.header

settings.ui.desktop.header.is_visible

settings.ui.desktop.header.visible_logo

settings.ui.desktop.header.visible_name

settings.ui.desktop.header.visible_purchase

settings.ui.desktop.header.type