Xsolla team created a script to simplify the integration of Pay Station into your website. Please note: for the proper work of widget please make sure that you pass the ‘access_token’. More information about getting ‘access_token’ parameter is available here.
Features:
- the most appropriate interface depending on the type of device
- tracking of events happening with Pay Station
- compliant with the AMD and CommonJS specification for defining modules
Script is located on our CDN and is available here: https://cdn.xsolla.net/payments-bucket-prod/embed/1.5.1/widget.min.js. Use this URL to integrate script on your website.
<script>
const options = {
access_token: 'abcdef1234567890abcdef1234567890'
};
const s = document.createElement('script');
s.type = "text/javascript";
s.async = true;
s.src = "https://cdn.xsolla.net/payments-bucket-prod/embed/1.5.0/widget.min.js";
s.addEventListener('load', function (e) {
XPayStationWidget.init(options);
}, false);
const head = document.getElementsByTagName('head')[0];
head.appendChild(s);
</script><script src="https://cdn.xsolla.net/payments-bucket-prod/embed/1.5.0/widget.min.js"></script>
<script>
XPayStationWidget.init({
access_token: 'abcdef1234567890abcdef1234567890'
});
</script>If your project uses CommonJS module format, you can access the widget by require()
const XPayStationWidget = require('PATH_TO_WIDGET/embed');
XPayStationWidget.init({
access_token: 'abcdef1234567890abcdef1234567890'
});Also you can use widget with RequireJS loader
define(['PATH_TO_WIDGET/embed'], function (XPayStationWidget) {
XPayStationWidget.init({
access_token: 'abcdef1234567890abcdef1234567890'
});
});- access_token — Access token
- host - Host for performing requests. The default value is secure.xsolla.com
- sandbox — Set true to test the payment process, sandbox-secure.xsolla.com will be used instead of host
- lightbox — Options for modal dialog that contains frame of Pay Station
- width — Width of lightbox frame. If null, depends on Pay Station width. Default is null
- height — Height of lightbox frame. If null, depends on Pay Station height. Default is '100%'
- zIndex — Property controls the vertical stacking order, default is 1000
- overlayOpacity — Opacity of the overlay (from 0 to 1), default is '.6'
- overlayBackground — Background of the overlay, default is '#000000'
- modal - Lightbox frame cannot be closed, default false
- closeByClick — Toggle if clicking the overlay should close lightbox, default true
- closeByKeyboard — Toggle if pressing of ESC key should close lightbox, default true
- contentBackground — Background of the frame, default is '#ffffff'
- contentMargin — margin around frame, default '10px',
- spinner — Type of animated loading spinner, can be 'xsolla', 'round', 'none' or 'custom', default is the first one
- spinnerColor — Color of the spinner, not set by default
- spinnerUrl — URL of custom spinner, default is null
- spinnerRotationPeriod — Rotation period of custom spinner, default 0
- childWindow — Options for child window that contains Pay Station. Suitable for mobile version
- target — The target option specifies where to open the Pay Station window, can be '_blank', '_self', '_parent', default is '_blank'
- iframeOnly — Open Pay Station in iframe on all devices
- queryParams — Query params to be added to Pay Station url
You can refer to the widget object, using the following methods:
- init(options) — Parameter setting
- open — Opening of payment interface (Pay Station). Opens a modal window with an iframe that appears over the site content for desktop, and in the new window for mobile and tablet devices.
- on(events, handler) — Attach an event handler function for one or more events to the widget.
- events (string) — One or more space-separated event types, such as "open" or "close status".
- handler (function) — A function to execute when the event is triggered.
- off(events, [handler]) — Remove an event handler. Calling .off() with no arguments removes all handlers attached to the widget.
- events (string) — One or more space-separated event types.
- handler (function) — A handler function previously attached for the event(s).
- init — Event on widget initialization
- open — Event on opening of the widget
- load — Event after payment interface (Pay Station) was loaded
- close — Event after payment interface (Pay Station) was closed
- status — Event when the user was moved on the status page
- status-invoice — Event when the user was moved on the status page, but the payment is not yet completed
- status-delivering — Event when the user was moved on the status page, payment was completed, and we’re sending payment notification
- status-done — Event when the user was moved on the status page, and the payment was completed successfully
- status-troubled — Event when the user was moved on the status page, but the payment failed
- user-country — Event when Pay Station have determine user country
- fcp — Event when in Pay Station occures fcp
- error — Event when in Pay Station 4 occures payment flow errors
You can access list of event using XPayStationWidget.eventTypes object.
XPayStationWidget.on(XPayStationWidget.eventTypes.STATUS, function (event, data) {
console.log(data.paymentInfo); // {
// email: "main@example.com",
// invoice: 140381877,
// status: "invoice",
// userId: "user_1",
// virtualCurrencyAmount: 100
// }
});To open Pay Station you can use .open() method or set "data-xpaystation-widget-open" attribute to HTML-element associated with the beginning of the payment, e.g. Payment button.
JavaScript call:
XPayStationWidget.open();HTML example:
<button data-xpaystation-widget-open>Buy Credits</button>Browsers are sensitive to anything that could affect user security. You should work carefully with user trusted events, such as click handling. If a payment method opens in a new browser tab, you must ensure there is a connection between this functionality and a trusted event. If the conditions for opening a new tab depend on asynchronous code, the event won’t be trusted, resulting in an error. Refactoring the callback code that opens a new tab in a synchronous style can resolve this problem.
You may encounter a similar problem when opening a new window after requesting a token for Pay Station. Below, you can see the pseudocode that DOES NOT work.
button.addEventListener("click", async () => {
const token = await getToken();
window.open(`https://www.pay-station-url-example.com?token=${token}`, "_blank");
});It looks like everything is logically arranged: first, you get the data to open a new window, and then open it. However, you lose the connection between the trusted user event and opening a new window when you organize the code this way.
It would be more correct to take a different approach:
- Immediately open a new window in response to a user-trusted click.
- Save a reference to the new window.
- Place a loader in the new window while the main content is not loaded.
- Send a request to get a token for Pay Station.
- After receiving the token, form a link for Pay Station with this token, and pass it to the opened window.
button.addEventListener("click", async () => {
const newWindow = window.open("", "_blank");
newWindow.document.body.innerHTML = "<div>Loading...</div>";
const token = await getToken();
newWindow.location = `https://www.pay-station-url-example.com?token=${token}`;
});Additional code that runs on a widget button click may also cause similar problems.
On some modern macOS versions (e.g., 15.5), there are difficulties building the project in a local environment due to an outdated version of Node.js. In some cases, using the Node.js version specified in the .nvmrc file might help, but if that doesn’t work, you can try building the project using Docker and replacing the contents of the dist directory on your local machine with the one from the Docker container.