Pay Station API v2.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:

ParameterTypeDescription
access_token
stringToken, received via API. Required.
sandbox
booleanSet to true to test the payment process: sandbox-secure.xsolla.com will be used instead of secure.xsolla.com.
lightbox
objectLightbox parameters (object; desktop version only).
lightbox.width
stringLightbox frame width. If null, depends on Pay Station width. Default is null.
lightbox.height
stringLightbox frame height. If null, depends on Pay Station height. Default is 100%.
lightbox.zIndex
integerDefines arrangement order. Default is 1000.
lightbox.overlayOpacity
integerOverlay opacity (0 to 1). Default is .6.
lightbox.overlayBackground
stringOverlay background color. Default is #000000.
lightbox.modal
booleanIf true, the lightbox frame cannot be closed. Default is false.
lightbox.closeByClick
booleanIf true, clicking the overlay will close the lightbox. Default is true.
lightbox.closeByKeyboard
booleanIf true, pressing ESC will close the lightbox. Default is true.
lightbox.contentBackground
stringFrame 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
stringFrame margin. Default is 10px.
lightbox.spinner
stringType of animated loading indicator. Can be xsolla or round. Default is xsolla.
lightbox.spinnerColor
stringSpinner color. No default value.
childWindow
objectOptions for the child window containing the Pay Station UI. Supported in the mobile version.
childWindow.target
stringWhere 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:

ParameterDescription
initWidget initialized.
openWidget opened.
loadPayment UI (Pay Station) loaded.
closePayment UI (Pay Station) closed.
statusUser is on the status page.
status-invoiceUser is on the status page; payment in progress.
status-deliveringEvent when the user was moved on the status page, payment was completed, and we're sending payment notification.
status-doneUser is on the status page; payment credited to the user's account.
status-troubledEvent 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

ParameterTypeDescription
user
objectUser details (object).
user.id
objectUser ID (object). Required.
user.id.value
stringUser ID.
user.name
objectUser screen name (object).
user.name.value
stringUser screen name.
user.email
objectUser 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
stringUser email. Must be valid according to the RFC 822 protocol. Required.
user.phone
objectUser phone number (object).
user.phone.value
stringUser phone number.
user.country
objectUser country (object).
user.country.value
stringTwo-letter uppercase country code per ISO 3166-1 alpha-2.
user.country.allow_modify
booleanWhether or not user can change the country on payment UI. false by default.
user.attributes
objectUser attributes for filtering the item list, represented as a valid JSON set of key-value pairs.
user.steam_id
objectUser's Steam ID (object).
user.steam_id.value
stringSteam ID.
user.tracking_id
objectUser tracking ID (object).
user.tracking_id.value
stringUnique tracking ID (used in marketing campaigns).
user.public_id.value
stringParameter 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
objectTraffic attributes (object).
user.utm.utm_source
stringTraffic source.
user.utm.utm_medium
stringTraffic channel (contextual ads, media ads, email lists, etc.).
user.utm.utm_campaign
stringCampaign title, transliterated or translated to English.
user.utm.utm_term
stringCampaign 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
stringCampaign content.
booleanWhether the user is a legal entity.
objectObject with legal entity details. Object and all its parameters are required if user.is_legal is ‘true’.
stringFull legal name.
stringFull legal address.
stringIndividual taxpayer identifier.
stringCountry of incorporation. Two-letter uppercase country code per ISO 3166-1 alpha-2 is used.
settings
objectCustom project settings (object).
settings.external_id
stringTransaction’s external ID.
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account. Required.
settings.language
stringInterface language. Two-letter lowercase language code.
settings.return_url
stringPage to redirect the user to after payment. Parameters user_id, foreigninvoice, invoice_id and status will be automatically added to the link.
settings.currency
stringPreferred payment currency. Three-letter currency code per ISO 4217.
settings.mode
stringSet 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
integerPayment method ID.
settings.payment_widget
stringPayment 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
objectInterface settings (object).
settings.ui.theme
stringPayment UI theme. Can be default or default_dark.
settings.ui.size
stringPayment 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
stringDevice type. Can be desktop (default) or mobile.
settings.ui.desktop
objectInterface settings for the desktop version (object).
settings.ui.desktop.header
objectHeader settings (object).
settings.ui.desktop.header.is_visible
booleanWhether to show the header in the payment UI.
booleanIf true, the header will show your logo (first provide the image to your account manager).
settings.ui.desktop.header.visible_name
booleanWhether to show the project name in the header.
settings.ui.desktop.header.visible_purchase
booleanWhether to show the purchase description (purchase.description.value) in the header. true by default.
settings.ui.desktop.header.type
stringHow to show the header. Can be compact (hides project name and user ID) or normal (default).
settings.ui.desktop.header.close_button
booleanWhether 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
objectSettings for the list of subscription plans (object).
settings.ui.desktop.subscription_list.layout
stringList template. Can be list (default) or grid.
settings.ui.desktop.subscription_list.description
stringAny text to show above the list of available subscription plans in the payment UI.
settings.ui.desktop.subscription_list.display_local_price
booleanIf 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
objectSettings for the list of virtual items (object).
settings.ui.desktop.virtual_item_list.layout
stringList template. Can be list (default) or grid.
settings.ui.desktop.virtual_item_list.button_with_price
booleanIf 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
stringDisplay virtual item groups as a vertical/horizontal menu. Can be horizontal_navigation or vertical (default).
settings.ui.desktop.virtual_currency_list
objectSettings for the list of virtual currencies (object).
settings.ui.desktop.virtual_currency_list.description
stringAny text to show above the list of virtual currencies.
settings.ui.desktop.virtual_currency_list.button_with_price
booleanIf 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
booleanWhether or not this element can be hidden on Payment UI. true by default.
settings.ui.mobile.mode
stringA user can only pay using their saved payment methods. Can be saved_accounts.
settings.ui.mobile.header.close_button
booleanWhether 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.
booleanWhether to hide the footer in the mobile version of the payment UI.
settings.ui.license_url
stringLink to the EULA.
settings.ui.components
objectMenu settings (object).
settings.ui.components.virtual_items
objectVirtual items submenu.
settings.ui.components.virtual_items.order
integerPosition of the submenu in the menu.
settings.ui.components.virtual_items.hidden
booleanWhether to show the submenu.
settings.ui.components.virtual_items.selected_group
stringGroup to show after opening the virtual items tab.
settings.ui.components.virtual_items.selected_item
stringItem to show after opening the virtual items tab (item SKU).
settings.ui.components.virtual_currency
objectVirtual currency submenu.
settings.ui.components.virtual_currency.custom_amount
booleanWhether the user can enter an arbitrary quantity of the virtual currency in the payment UI.
settings.ui.components.virtual_currency.order
integerPosition of the submenu in the menu.
settings.ui.components.virtual_currency.hidden
booleanWhether to show the submenu.
settings.ui.components.subscriptions
objectSubscription plans submenu (object).
settings.ui.components.subscriptions.order
integerPosition of the submenu in the menu.
settings.ui.components.subscriptions.hidden
booleanWhether to show the submenu.
settings.ui.mode
stringInterface 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.user_account
objectUser account details (object).
settings.ui.user_account.info
objectPage My account.
settings.ui.user_account.info.order
integerPosition of the submenu in the menu.
settings.ui.user_account.info.enable
booleanWhether to show the submenu. false by default.
settings.ui.user_account.history
objectHistory submenu.
settings.ui.user_account.history.order
integerPosition of the submenu in the menu.
settings.ui.user_account.history.enable
booleanWhether to show the submenu. false by default.
settings.ui.user_account.payment_accounts
objectMy payment accounts submenu.
settings.ui.user_account.payment_accounts.order
integerPosition of the submenu in the menu.
settings.ui.user_account.payment_accounts.enable
booleanWhether to show the submenu. false by default.
settings.ui.user_account.subscriptions
objectManage subscriptions submenu.
settings.ui.user_account.subscriptions.order
integerPosition of the submenu in the menu.
settings.ui.user_account.subscriptions.enable
booleanWhether to show the submenu. false by default.
purchase
objectObject containing purchase details.
purchase.virtual_currency
objectObject containing virtual currency details.
purchase.virtual_currency.quantity
floatPurchase amount in the virtual currency.
purchase.virtual_currency.currency
stringCurrency of the virtual currency package to use in all calculations.
purchase.virtual_items
objectObject with data about the virtual items in purchase.
purchase.virtual_items.currency
stringCurrency of the ordered items to use in all calculations.
purchase.virtual_items.items
arrayItem data (array).
purchase.virtual_items.items.sku
stringItem ID.
purchase.virtual_items.items.amount
integerItem quantity.
purchase.virtual_items.available_groups
arrayItem groups IDs (array). The payment UI will only include items within the specified group.
purchase.subscription
objectSubscription data (object).
purchase.subscription.plan_id
stringPlan ID.
purchase.subscription.operation
stringThe 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
stringProduct ID.
purchase.subscription.currency
stringCurrency of the subscription plan to use in all calculations.
purchase.subscription.available_plans
arraySubscription plans (array) to show in the payment UI.
purchase.subscription.trial_days
integerTrial period in days.
purchase.pin_codes
objectGame keys (object).
purchase.pin_codes.currency
stringCurrency of a Game key within the order to use in all calculations.
purchase.pin_codes.codes
arrayGame keys (array).
purchase.pin_codes.codes.digital_content
stringGame SKU set in Publisher Account.
purchase.pin_codes.codes.drm
stringDRM 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
objectObject with the upgrade data.
purchase.pin_codes.upgrade.id_user_history
integerID of the entry containing data on the user and their packages.
purchase.pin_codes.upgrade.id
integerUpgrade ID.
purchase.gift
objectGift details (object).
purchase.gift.giver_id
stringGiver ID.
purchase.gift.message
stringMessage from the giver.
purchase.gift.hide_giver_from_receiver
stringWhether to hide the giver identity from the recipient. true by default.
purchase.gift.friends
arrayArray with data on friends.
purchase.gift.friends.id
stringGift recipient ID.
purchase.gift.friends.name
stringGift recipient nickname.
purchase.gift.friends.email
stringGift recipient email.
purchase.coupon_code
objectInformation about a discount promo code or bonuses upon purchase (object).
purchase.coupon_code.value
stringPromo code value.
purchase.coupon_code.hidden
booleanHide the field promo code is entered into in the payment UI. false by default.
custom_parameters
objectYour 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
  • http
  • curl
  • php
  • C#
  • python
  • ruby
  • java
  • js
Request
POST https://api.xsolla.com/merchant/v2/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"
    },
    "email": {
      "value": "john.smith@mail.com"
    },
    "id": {
      "value": "user_2"
    },
    "name": {
      "value": "John Smith"
    }
  }
}
curl --request POST \
  --url https://api.xsolla.com/merchant/v2/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"},"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"},"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/v2/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/v2/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\"},\"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\"},\"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/v2/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/v2/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\"},\"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\"},\"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/v2/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"
    },
    "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/v2/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"
}

Get Token for Purchase via Checkout (Deprecated)

Use this method if you have already configured at least one of the Store modules and the Integrate Commerce API toggle in the Settings section of the Publisher Account is set to Off. Otherwise, implement receiving a token in accordance with the checkout instructions.

Set the following parameters when receiving a token for a checkout purchase.

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

ParameterTypeDescription
user
objectUser details (object).
user.id
objectUser ID (object). Required.
user.id.value
stringUser ID.
user.name
objectUser screen name (object).
user.name.value
stringUser screen name.
user.email
objectUser 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
stringUser email. Must be valid according to the RFC 822 protocol. Required.
user.phone
objectUser phone number (object).
user.phone.value
stringUser phone number.
user.country
objectUser country (object).
user.country.value
stringTwo-letter uppercase country code per ISO 3166-1 alpha-2.
user.country.allow_modify
booleanWhether or not user can change the country on payment UI. false by default.
user.attributes
objectUser attributes for filtering the item list, represented as a valid JSON set of key-value pairs.
user.steam_id
objectUser's Steam ID (object).
user.steam_id.value
stringSteam ID.
user.tracking_id
objectUser tracking ID (object).
user.tracking_id.value
stringUnique tracking ID (used in marketing campaigns).
user.public_id.value
stringParameter 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
objectTraffic attributes (object).
user.utm.utm_source
stringTraffic source.
user.utm.utm_medium
stringTraffic channel (contextual ads, media ads, email lists, etc.).
user.utm.utm_campaign
stringCampaign title, transliterated or translated to English.
user.utm.utm_term
stringCampaign 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
stringCampaign content.
booleanWhether the user is a legal entity.
objectObject with legal entity details. Object and all its parameters are required if user.is_legal is ‘true’.
stringFull legal name.
stringFull legal address.
stringIndividual taxpayer identifier.
stringCountry of incorporation. Two-letter uppercase country code per ISO 3166-1 alpha-2 is used.
settings
objectCustom project settings (object).
settings.external_id
stringTransaction’s external ID.
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account. Required.
settings.language
stringInterface language. Two-letter lowercase language code.
settings.return_url
stringPage to redirect the user to after payment. Parameters user_id, foreigninvoice, invoice_id and status will be automatically added to the link.
settings.currency
stringPreferred payment currency. Three-letter currency code per ISO 4217.
settings.mode
stringSet 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
integerPayment method ID.
settings.payment_widget
stringPayment 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
objectInterface settings (object).
settings.ui.theme
stringPayment UI theme. Can be default or default_dark.
settings.ui.size
stringPayment 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
stringDevice type. Can be desktop (default) or mobile.
settings.ui.desktop
objectInterface settings for the desktop version (object).
settings.ui.desktop.header
objectHeader settings (object).
settings.ui.desktop.header.is_visible
booleanWhether to show the header in the payment UI.
booleanIf true, the header will show your logo (first provide the image to your account manager).
settings.ui.desktop.header.visible_name
booleanWhether to show the project name in the header.
settings.ui.desktop.header.visible_purchase
booleanWhether to show the purchase description (purchase.description.value) in the header. true by default.
settings.ui.desktop.header.type
stringHow to show the header. Can be 'compact' (hides project name and user ID) or 'normal' (default).
settings.ui.desktop.header.close_button
booleanWhether 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.header.visible_virtual_currency_balance
booleanWhether or not this element can be hidden on Payment UI. true by default.
settings.ui.mobile.mode
stringA user can only pay using their saved payment methods. Can be saved_accounts.
settings.ui.mobile.header.close_button
booleanWhether 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.
booleanWhether to hide the footer in the mobile version of the payment UI.
settings.ui.license_url
stringLink to the EULA.
settings.ui.components
objectMenu settings (object).
settings.ui.mode
stringInterface 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.user_account
objectUser account details (object).
settings.ui.user_account.info
objectPage My account.
settings.ui.user_account.info.order
integerPosition of the submenu in the menu.
settings.ui.user_account.info.enable
booleanWhether to show the submenu. false by default.
settings.ui.user_account.history
objectHistory submenu.
settings.ui.user_account.history.order
integerPosition of the submenu in the menu.
settings.ui.user_account.history.enable
booleanWhether to show the submenu. false by default.
settings.ui.user_account.payment_accounts
objectMy payment accounts submenu.
settings.ui.user_account.payment_accounts.order
integerPosition of the submenu in the menu.
settings.ui.user_account.payment_accounts.enable
booleanWhether to show the submenu. false by default.
settings.ui.user_account.subscriptions
objectManage subscriptions submenu.
settings.ui.user_account.subscriptions.enable
booleanWhether to show the submenu. false by default.
purchase
objectObject containing purchase details.
purchase.checkout
objectObject containing checkout details.
purchase.checkout.currency
stringCurrency of the purchase. Three-letter currency code per ISO 4217.
purchase.checkout.amount
floatPurchase amount.
purchase.description
objectPurchase description (object).
purchase.description.value
stringGeneral 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.
purchase.description.items
array of objectsItems array.
purchase.description.items.name
stringItem name.
purchase.description.items.image_url
stringLink to the item icon.
purchase.description.items.description
stringItem description in the purchase.
purchase.description.items.price
objectObject with the item price.
purchase.description.items.price.amount
stringItem price.
purchase.description.items.price.amount_before_discount
stringItem price before the discount.
purchase.description.items.quantity
integerNumber of items in the purchase.
purchase.description.items.is_bonus
booleanWhether an item is free and available as a bonus. Default is false.
Copy
Full screen
Small screen
http
  • http
  • curl
  • php
  • C#
  • python
  • ruby
  • java
  • js
Request
POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

Headers:
Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json
Body:
{
  "user": {
    "id": {
      "value": "user_2",
      "hidden": true
    },
    "email": {
      "value": "john.smith@mail.com"
    },
    "country": {
      "value": "US",
      "allow_modify": true
    }
  },
  "settings": {
    "project_id": 1234,
    "language": "en",
    "currency": "USD"
  },
  "purchase": {
    "checkout": {
      "currency": "USD",
      "amount": 20
    },
    "description": {
      "value": "Purchase",
      "items": [
        {
          "name": "Rocket",
          "quantity": 5,
          "price": {
            "amount": "2",
            "amount_before_discount": "10.5"
          },
          "description": "This is a rocket."
        },
        {
          "name": "Sword",
          "quantity": 5,
          "price": {
            "amount": "2"
          },
          "description": "This is a sword."
        }
      ]
    }
  }
}
curl --request POST \
  --url https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
  --header 'authorization: Basic <your_authorization_basic_key>' \
  --header 'content-type: application/json' \
  --data '{"user":{"id":{"value":"user_2","hidden":true},"email":{"value":"john.smith@mail.com"},"country":{
"value":"US","allow_modify":true}},"settings":{"project_id":1234,"language":"en","currency":"USD"},"purchase":{"checkout":{"currency":"USD","amount":20},"description":{"value":"Purchase","items":[{"name": "Rocket","quantity":5,"price":{"amount":"2","amount_before_discount":"10.5"},"description":"This is a rocket."},{"name":"Sword","quantity":5,"price":{"amount":"2"},"description": "This is a sword."}]}}}'
<?php

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

$body = new http\Message\Body;
$body->append('{"user":{"id":{"value":"user_2","hidden":true},"email":{"value":"john.smith@mail.com"},"country":{
"value":"US","allow_modify":true}},"settings":{"project_id":1234,"language":"en","currency":"USD"},"purchase":{"checkout":{"currency":"USD","amount":20},"description":{"value":"Purchase","items":[{"name": "Rocket","quantity":5,"price":{"amount":"2","amount_before_discount":"10.5"},"description":"This is a rocket."},{"name":"Sword","quantity":5,"price":{"amount":"2"},"description": "This is a sword."}]}}}');

$request->setRequestUrl('https://api.xsolla.com/merchant/v2/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/v2/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\",\"hidden\":true},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{
\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":1234,\"language\":\"en\",\"currency\":\"USD\"},\"purchase\":{\"checkout\":{\"currency\":\"USD\",\"amount\":20},\"description\":{\"value\":\"Purchase\",\"items\":[{\"name\": \"Rocket\",\"quantity\":5,\"price\":{\"amount\":\"2\",\"amount_before_discount\":\"10.5\"},\"description\":\"This is a rocket.\"},{\"name\":\"Sword\",\"quantity\":5,\"price\":{\"amount\":\"2\"},\"description\": \"This is a sword.\"}]}}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import http.client

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

payload = "{\"user\":{\"id\":{\"value\:\"user_2\",\"hidden\":true},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{
\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":1234,\"language\":\"en\",\"currency\":\"USD\"},\"purchase\":{\"checkout\":{\"currency\":\"USD\",\"amount\":20},\"description\":{\"value\":\"Purchase\",\"items\":[{\"name\": \"Rocket\",\"quantity\":5,\"price\":{\"amount\":\"2\",\"amount_before_discount\":\"10.5\"},\"description\":\"This is a rocket.\"},{\"name\":\"Sword\",\"quantity\":5,\"price\":{\"amount\":\"2\"},\"description\": \"This is a sword.\"}]}}}"

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

conn.request("POST", "/merchant/v2/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/v2/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\",\"hidden\":true},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{
\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":1234,\"language\":\"en\",\"currency\":\"USD\"},\"purchase\":{\"checkout\":{\"currency\":\"USD\",\"amount\":20},\"description\":{\"value\":\"Purchase\",\"items\":[{\"name\": \"Rocket\",\"quantity\":5,\"price\":{\"amount\":\"2\",\"amount_before_discount\":\"10.5\"},\"description\":\"This is a rocket.\"},{\"name\":\"Sword\",\"quantity\":5,\"price\":{\"amount\":\"2\"},\"description\": \"This is a sword.\"}]}}}"

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\",\"hidden\":true},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{
\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":1234,\"language\":\"en\",\"currency\":\"USD\"},\"purchase\":{\"checkout\":{\"currency\":\"USD\",\"amount\":20},\"description\":{\"value\":\"Purchase\",\"items\":[{\"name\": \"Rocket\",\"quantity\":5,\"price\":{\"amount\":\"2\",\"amount_before_discount\":\"10.5\"},\"description\":\"This is a rocket.\"},{\"name\":\"Sword\",\"quantity\":5,\"price\":{\"amount\":\"2\"},\"description\": \"This is a sword.\"}]}}}");
Request request = new Request.Builder()
  .url("https://api.xsolla.com/merchant/v2/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",
      "hidden": true
    },
    "email": {
      "value": "john.smith@mail.com"
    },
    "country": {
      "value": "US",
      "allow_modify": true
    }
  },
  "settings": {
    "project_id": 1234,
    "language": "en",
    "currency": "USD"
  },
  "purchase": {
    "checkout": {
      "currency": "USD",
      "amount": 20
    },
    "description": {
      "value": "Purchase",
      "items": [
        {
          "name": "Rocket",
          "quantity": 5,
          "price": {
            "amount": "2",
            "amount_before_discount": "10.5"
          },
          "description": "This is a rocket."
        },
        {
          "name": "Sword",
          "quantity": 5,
          "price": {
            "amount": "2"
          },
          "description": "This is a sword."
        }
      ]
    }
  }
});

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/v2/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

ParameterTypeDescription
registration_date
stringAccount creation date per ISO 8601.
total_hours
integerTotal number of in-game hours.
total_characters
integerNumber of in-game characters.
social_networks_added
booleanWhether the player has connected social media profiles.
profile_image_added
booleanWhether the player has uploaded a profile image.
active_date
stringLast seen date per ISO 8601.
total_friends
integerNumber of friends.
additional_verification
booleanWhether the player uses account verification procedures.
win_rate
integerWin rate.
last_change_password_date
stringLast password change date per ISO 8601.
chat_activity
booleanWhether the player uses the chat function.
forum_activity
booleanWhether the player uses the forum function.
total_bans
integerNumber of times the player was banned in the chat/forum.
profile_completed
booleanWhether the player added additional information to their profile.
notifications_enabled
booleanWhether the player enabled notifications.
user_level
integerPlayer’s level, reputation, or rank.
karma_points
integerPlayer’s karma.
total_sum
floatTotal amount of payments.
non_premium_currency
floatAmount of non-premium currency.
total_game_events
integerNumber of in-game events the player took part in.
total_gifts
integerNumber of in-game gifts the player has sent/received.
tutorial_completed
booleanWhether the player has completed the game’s tutorial.
completed_tasks
integerNumber of tasks/objectives completed.
items_used
booleanWhether the player uses purchased in-game items.
pvp_activity
booleanWhether the player takes part in PvP battles.
total_clans
integerNumber of clans the player is a member of.
unlocked_achievements
integerNumber of achievements unlocked.
total_inventory_value
floatTotal inventory value (in-game currency).
character_customized
booleanWhether the player has customized their character.
session_time
stringAverage 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

ParameterTypeDescription
project_id
integerProject ID.
user_id
stringUser ID.
Copy
Full screen
Small screen
http
  • http
  • curl
  • php
  • C#
  • python
  • ruby
  • java
  • js
Request
GET https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts

Headers:
  Authorization: Basic <your_authorization_basic_key>
curl --request GET \
  --url https://api.xsolla.com/merchant/v2/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/v2/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/v2/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/v2/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/v2/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/v2/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/v2/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}

ParameterTypeDescription
project_id
integerProject ID. Required.
user_id
stringUser ID. Required.
type
stringType 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
integerID of the saved account in Xsolla database. Required.
user
objectUser details (object).
user.ip
stringUser IP address. Required.
user.name
stringUsername.
objectObject with legal entity details.
stringFull legal name.
stringFull legal address.
stringIndividual taxpayer identifier.
stringCountry of incorporation. Two-letter uppercase country code per ISO 3166-1 alpha-2 is used.
purchase
objectObject containing purchase details.
purchase.virtual_currency
objectObject containing virtual currency details.
purchase.virtual_currency.quantity
floatPurchase amount in the virtual currency.
purchase.checkout
objectObject containing checkout details.
purchase.checkout.currency
stringCurrency of the purchase. Three-letter currency code per ISO 4217.
purchase.checkout.amount
floatPurchase amount.
settings
objectObject containing purchase settings.
settings.mode
stringSet to sandbox to test out the payment process. Remove the parameter for real payments.
custom_parameters
stringYour custom parameters, represented as a valid JSON set of key-value pairs.
Copy
Full screen
Small screen
http
  • http
  • curl
  • php
  • C#
  • python
  • ruby
  • java
  • js
Request
POST https://api.xsolla.com/merchant/v2/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/v2/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/v2/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/v2/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/v2/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/v2/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/v2/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/v2/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}

ParameterTypeDescription
project_id
integerProject ID.
user_id
stringUser ID.
type
stringType 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
integerID of the saved account in Xsolla database.
Copy
Full screen
Small screen
http
  • http
  • curl
  • php
  • C#
  • python
  • ruby
  • java
  • js
Request
DELETE https://api.xsolla.com/merchant/v2/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/v2/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/v2/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/v2/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/v2/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/v2/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/v2/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/v2/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");

xhr.send(data);
Response


Was this article helpful?
Thank you!
Is there anything we can improve? Message
We're sorry to hear that
Please explain why this article wasn't helpful to you. Message
Thank you for your feedback!
We'll review your message and use it to help us improve your experience.