Merchant ID.
Pay Station API (2.0)
- Version: 2.0.0
- Servers:
https://api.xsolla.com/api
Pay Station allows partners to monetize their products by providing users with a convenient UI to pay for in-game purchases in the game store. To set up opening the payment UI, refer to these instructions.
The Pay Station API provides the following groups of calls:
- Token — includes the API call to generate a token with arbitrary user parameters for further payment processing via the payment UI.
- Tokenization — includes API calls to securely process payments without opening the payment UI or involving the user.
- Reports — includes API calls to return data on user transactions, generate reports, and get payouts breakdown by currency.
- Refund — includes API calls to request full and partial refunds.
- Testing — includes the API call to test the chargeback process.
You can find detailed information about configuring the payment UI in the Payments solution integration guide.
Note
You can also refer to the Xsolla Base API section in the Postman collection to test API calls used for integration.
Download OpenAPI description
Languages
Servers
https://api.xsolla.com/merchant/v2/
Mock server
https://xsolla.redocly.app/_mock/api/pay-station/
Request
You can create a token with arbitrary user parameters. You send these parameters when obtaining the token and receive them back after a successful payment. A token can only contain parameters either described in this document or predefined by you.
If any parameter is sent in the wrong format or has the wrong type, no token will be issued. You will receive a 422 HTTP code with the error description in the JSON body. In extended_message you will receive an information what exact parameters have been sent incorrectly.
By default, the token lifetime is 24 hours. If you want to change this value, contact your Customer Success Manager or send an email to csm@xsolla.com. The new value will be enabled for all your company’s projects created in Publisher Account.
Notice
The token you obtain after calling this API method can be used only for authorizing other requests. You can use this token to open the payment UI only if you integrated the Subscriptions product.
To open the payment UI in a new window, use the following link: https://secure.xsolla.com/paystation4/?token={token}, where {token} is the received token.
For testing purposes, use this URL: https://sandbox-secure.xsolla.com/paystation4/?token={token}.
Notice
This API call does not contain the project_id path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.
Security
basicAuth
User details.
Unique user ID in the game stored on your side. Make sure you pass the existing user ID. In case an error occurs, refer to the answers to the FAQs.
The user.email object is an integral part of building anti-fraud models and helps increase acceptance rates. It is both Xsolla and payment systems requirement. If the parameter is not passed, the required field for entering email appears on the payment page. A user receives a purchase receipt to the email passed in the parameter or entered on the payment page.
User email. Must be valid according to the RFC 822 protocol.
Two-letter uppercase country code per ISO 3166-1 alpha-2.
User attributes for filtering the item list, represented as a valid JSON set of key-value pairs.
Traffic attributes.
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.
Object with legal entity details. Object and all its parameters are required if user.is_legal is true.
Country of incorporation. Two-letter uppercase country code per ISO 3166-1 alpha-2 is used.
Settings for configuring payment process and the payment UI for a user.
Transaction ID in the game. Has to be unique for each user payment. Refer to documentation for detailed information.
Interface language. Two-letter lowercase language code.
URL of the page where a user is redirected to after the payment. Refer to documentation for detailed information about configuring redirects.
Redirect policy settings.
Payment status for which a user is redirected to the return URL. Can be none, successful, successful_or_canсeled, or any.
Enum"none""successful""successful_or_canceled""any"
Delay (in seconds) after which a user is automatically redirected to the return URL.
Payment status for which a button redirecting a user to the return URL is displayed. Can be none, successful, successful_or_canсeled, or any.
Enum"none""successful""successful_or_canceled""any"
Pay Station behavior triggered by the user clicking the close button or the Back to the Game button. Can be redirect (by default) and postmessage. If set to redirect, a user is redirected to the URL passed in the token or specified in Publisher Account. If set to postmessage, a user is not redirected to other pages. Clicking the close icon initiates sending the close event, and clicking the Back to the Game button — the return event.
Enum"redirect""postmessage"
Preferred payment currency. Three-letter currency code per ISO 4217.
Set to sandbox to test out the payment process. In this case, use https://sandbox-secure.xsolla.com to access the test payment UI.
Payment widget. Can be paybycash or giftcard. If the parameter is set, the user is redirected to the Pay by Cash or Gift Cards widget, respectively.
Enum"paybycash""giftcard"
Interface settings.
Payment UI theme. Can be 63295a9a2e47fab76f7708e1 for the light theme (default) or 63295aab2e47fab76f7708e3 for the dark theme. You can also create a custom theme and pass its ID in this parameter.
Enum"63295a9a2e47fab76f7708e1""63295aab2e47fab76f7708e3"
Interface settings for the desktop version.
Header settings.
If true, the logo is displayed in the header. To upload the image, open your project in Publisher Account and go to the Pay Station > Settings section.
Whether to show the purchase description (purchase.description.value) in the header. true by default.
How to show the header. Can be compact (hides project name and user ID) or normal (default).
Enum"compact""normal"
Whether to show the Close button in the payment UI. The button closes the payment UI and redirects the user to the URL specified in the settings.return_url parameter. false by default.
Settings for the list of subscription plans.
Any text to show above the list of available subscription plans in the payment UI.
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.
Menu settings.
Virtual items submenu settings.
settings.ui.components.virtual_items.hiddenboolean
Whether to show the submenu.
Group to show after opening the virtual items tab.
Virtual currency submenu settings.
Whether the user can enter an arbitrary quantity of the virtual currency in the payment UI.
settings.ui.components.virtual_currency.hiddenboolean
Whether to show the submenu.
Display mode of the payment UI for managing saved payment methods. Can be set to user_account or omitted. In this mode, the user can only change the language, add new payment methods, and remove existing ones.
Note
When this parameter is passed, the redirect button is not displayed. To redirect a user after saving a payment method, configure automatic redirects.
Whether or not redirecting links to an external resource is disabled. false by default. When clicking an external link, the external-link-open event is sent via the postMessage mechanism. The address for the redirected link is passed in the url parameter.
Whether the list of payment methods available in the user’s country is displayed when opening the payment UI. If false (default), the payment method passed in the settings.payment_method parameter or the method selected by the PayRank algorithm is displayed.
Whether to redirect users from the embedded launcher’s browser (WebView) to their default browser to make a purchase. false by default.
User account details.
Saved methods section.
Specifies whether to display the pencil icon in the payment UI that goes to the payment method editing page. true by default.
Set to code to display a three-letter ISO 4217 currency code in the payment UI. The currency symbol is displayed instead of the three-letter currency code by default.
Whether to show a warning about processing the transaction when hovering over the × icon before closing the payment page. If false is passed, or the parameter is not passed, the warning is not displayed. true by default.
Location of the main elements of the payment UI. You can open the payment UI inside your game and/or swap the columns with information about an order and payment methods. Refer to the customization instructions for detailed information.
Enum"embed""column_reverse""embed_column_reverse"
Whether the 3-D Secure verification opens in a new browser window. If your setup enforces a Content Security Policy (CSP), set to true.
Default false
The display of the list of cart items and financial details in the payment UI. If true, information is displayed in an extended view. If false (default) or the parameter is not passed, information is displayed in a collapsed view.
The way the Google Pay payment method is displayed. If true, the button for quick payment via Google Pay is displayed at the top of the payment UI, regardless of the user’s device and browser. If false, Google Pay is displayed in the list of payment methods according to the PayRank algorithm. If the parameter is not passed, Google Pay is displayed at the top of the payment UI on any user’s devices and browsers, except Safari — on Safari, it is displayed in the list of payment methods.
Whether to display the button for quick payment via Apple Pay at the top of the payment UI on supported devices. true by default. If false, Apple Pay is displayed in the list of payment methods according to the PayRank algorithm.
Note
On Android devices and any other devices that don’t support payment with Apple Pay, this payment method will be hidden from the list of available ones regardless of the parameter value.
settings.ui.is_search_field_hiddenboolean(is_search_field_hidden)
Whether to show a payment method search bar in the payment UI. If true, the search bar is hidden. false by default.
settings.ui.is_language_selector_hiddenboolean(is_language_selector_hidden)
Whether the language selector is hidden on the payment page. If false (by default), the selector is displayed.
Alternative view of the payment UI screen when opened. For example, it can display prioritized payment methods.
When set to apple-pay, the user sees the Apple Pay button as the primary payment option along with a link to the list of other payment methods. This logic doesn’t apply to Android devices.
Value"apple-pay"
Object containing purchase details.
Subscription data.
External ID of the subscription plan. Can be found in the Subscriptions > Subscription plans section of Publisher Account.
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.
Subscription plans to show in the payment UI.
This object contains parameters to configure anti-fraud filters. The list of parameters is shown below. To add custom parameters, contact your Customer Success Manager or email at csm@xsolla.com.
Account creation date per ISO 8601.
Whether the player has connected social media profiles.
Last seen date per ISO 8601.
Whether the player uses account verification procedures.
Last password change date per ISO 8601.
Whether the player added additional information to their profile.
Whether the player takes part in PvP (Player(s) versus player(s)) battles.
Average session time per ISO 8601.
- https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token
- Mock serverhttps://xsolla.redocly.app/_mock/api/pay-station/merchants/{merchant_id}/token
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token' \
-H 'Content-Type: application/json' \
-d '{
"settings": {
"currency": "USD",
"language": "en",
"project_id": 16184,
"ui": {
"size": "medium"
}
},
"user": {
"email": {
"value": "email@example.com"
},
"id": {
"value": "user_2"
},
"name": {
"value": "John Smith"
}
}
}'Response
application/json
{ "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT" }