FAQs

Integration

How can I open Pay Station in an iframe?

We recommend that you use the Pay Station Embed script to open the payment UI in a lightbox. Using this script will allow you to:

  • automatically determine the payment UI size and device type (desktop, mobile)
  • automatically receive events from the payment UI
  • change the UI theme

To open the payment UI in an iframe:

  1. Implement the postMessage mechanism to receive events from the payment UI.
  2. Open the payment UI by following the link https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN, where TOKEN is the received token.

Potential issue: If a button for copying a payment confirmation code required by some payment systems is not displayed when opening the payment UI in an iframe, pass the allow=“clipboard-read; clipboard-write; payment” attribute to the iframe.

Example:

Copy
Full screen
Small screen
<iframe
  src="https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN"
  width="800"
  height="700"
  allow="clipboard-read; clipboard-write; payment"
></iframe>

What Xsolla network IP addresses do I need to add to the allowlist to configure webhooks?

You need to receive and process webhooks from the following IP addresses:

  • 185.30.20.0/24
  • 185.30.21.0/24
  • 185.30.23.0/24

If you integrated the Login product, additionally add processing webhooks from the following IP addresses:

  • 35.236.32.131
  • 34.94.154.26
  • 34.94.14.95
  • 34.102.48.30
  • 34.94.115.185
  • 34.94.173.132
  • 35.236.35.100
  • 35.236.117.164
  • 34.94.0.85
  • 35.235.99.248
  • 34.94.25.33

Is there SDK for Node.JS/C#/Ruby/Java/ASP, etc.?

Currently there are SDK for PHP and Android. You can build your own SDK using any language/platform, as long as it has HTTPS request functionality.

User validation

What is User ID?

The user ID is a parameter that enables identifying a user in a game. You can store user IDs in a database. When receiving invalid user IDs, throw an exception. Refer to the GitHub repository for an example of user validation.

What data should I return after validation is completed?

When validation is successful, return HTTP-code 200. In case of an error, code 400 (INVALID_USER).

Project settings

Do I need to create new projects for each environment (QA, staging, production)?

For testing, we recommend that you use separate projects to avoid affecting the production environment.

What is the difference between a secret key, project key, and API key?

A secret key and project key are the same. It is used for the digital signature that is required when processing secure payments. The request’s JSON body is concatenated with this key, and then the result is hashed with SHA-1.

The API key is used for API calls sent to the Xsolla server. This key must be held on your own server and never inside binary files or frontend. For more information about working with API keys, see the API reference.

What is the difference between a webhook URL and return URL?

A webhook URL is the URL address of your webhook server where notifications are sent. A return URL is the URL address where a user is redirected after completing a payment.

Where can I find the project ID?

Open your project in Publisher Account and go to the Project settings > General settings section.

Where can I find the merchant ID?

Open Publisher Account and go to the Company settings > Company section.

Note
The merchant ID is the same as the publisher ID.

Where can I find the API Key?

API key is shown in Publisher Account only once when it is created and must be stored on your side. You can create a key in the following section:

  • Company settings > API keys
  • Project settings > API keys

Notice

For more information about working with API keys, see the API reference.

Key recommendations:

  • Save the generated API key on your side. You can view the API key in Publisher Account only once when it is created.
  • Keep your API key a secret. It provides access to your personal account and your projects in Publisher Account.
  • The API key must be stored on your server and never in binaries or on the frontend.

If an API call you need does not contain the project_id path parameter, use the API key that is valid in all the company’s projects to set up authorization.

Webhook settings

Do I need to use HTTPS for a webhook protocol?

Yes.

Why was Xsolla notification not sent to the webhook URL?

Make sure that your webhook server supports the required types of HTTP requests (POST, GET).

Why are webhooks not sent to my mobile application?

Webhooks are sent to only a single URL address specified in your project settings. Being server-to-server, webhooks cannot be sent to several URL addresses. If you would like to receive notifications in your game, website, or mobile application, set up sending webhooks on your server to pass data between Xsolla and your game.

Customization

Can I customize the payment UI theme?

You can enable a dark theme by sending the settings.ui.theme = default_dark parameter in the token. The dark theme allows you to set the background image or change the background color (as it is in the demo). To change other settings, contact your Customer Success Manager or email to csm@xsolla.com.

Can I change the appearance of emails sent to users?

Yes. Follow the instructions on how to customize emails to users. The order of email elements cannot be changed as they are a part of a standard template. This is required according to the licensing agreement with Xsolla, which acts as the legal merchant of records.

Testing

Can I use test cards to test the payment process?

Yes, but only when you run your application or Pay Station demo in sandbox mode. Refer to the general list of test cards of different brands and issuing countries.

Can I test the PayPal payment flow in sandbox mode?

Yes. See detailed information in the instruction.

How can I test payment refunds?

You can test refunds via the Request refund API call. Refer to the instruction for more information.

What is the Xsolla Invoice ID and Invoice ID on the webhook testing tab in Publisher Account?

The Xsolla Invoice ID is the transaction ID on Xsolla’s side. For testing, you can use any numeric value.

The Invoice ID is an optional transaction ID in your game. For testing, you can enter any combination of letters and numbers.

Payments

How can I validate a payment request received in a webhook?

First, check if a specified user ID exists in your project. Then, return code 200 to validate the payment.

Can I redirect a user to a particular payment method?

When opening the store UI, you can pass the payment method ID in the settings.payment_method parameter. In this case, users are redirected to the selected payment method’s payment form. You can find the list of payment method IDs in Publisher Account in the Pay Station > Payment methods section.

Can I automatically redirect a user to a successful/failed payment page after processing a payment, depending on the result?

Yes, you can configure redirect conditions. Refer to the instruction for more information.

Our billing system automatically sets the order_id for each order. Can I use order_id instead of user_id when receiving a token?

No, you need user_id for everything to work correctly.

You can additionally pass the order_id in the external_id parameter. To do so:

  1. Open Publisher Account.
  2. Go to the Pay Station > Settings section.
  3. In the Additional settings block, set the Transaction external ID toggle to On.

Can I override the webhook URL for each transaction?

No, the webhook URL for all transactions is set in the project settings in Publisher Account.

Will I receive the details of failed transactions?

No, Xsolla only sends webhooks for successful transactions. If you received a notification about a payment, it means the transaction was successful.

How can I add VAT to the total payment amount?

VAT settings are configured on Xsolla’s side by default. Contact your Customer Success Manager or email to csm@xsolla.com if you want to change the settings and add VAT to a user’s total payment amount.

What does PID stand for?

PID is the payment method identifier on Xsolla’s side.

What is the External ID?

The External ID is a transaction’s ID in the game that is assigned to an order in your system. On the Xsolla side, External ID is linked to a transaction ID. That is why an enabled External ID allows Xsolla to prevent repeated payment for the same transaction.

Notice
External ID must be unique for each user payment across both test (sandbox mode) and live environments. Example: if you have a test payment with “external_id”: “1”, you can’t initiate a real payment with “external_id”: “1”.
To enable External ID in your project:
  1. Open your project in Publisher Account and go to the Pay Station > Settings section.
  2. Set the Transaction external ID toggle to On.

Do I need to generate a new External ID for each transaction?

Yes. The External ID has to be unique for each payment.

What value do I need to set for the setExternalPaymentId method?

The setExternalPaymentId method should have the same value as the external_id, if you have one.

What are gateways?

Once you have signed a contract with payment systems, you can use gateways to display these payment options in the payment UI. Players can still pay for their purchases using selected payment methods, and you would receive payouts directly from these payment system providers. To connect gateways, open your project in Publisher Account and go to the Pay Station > Gateways section.

Xsolla serves as a technical service provider and takes a reduced revenue share: 1.25% of the transaction amount + $0.10. You will have full access to all Xsolla solutions, but you must do the following:

  • manage tax-related issues
  • sign separate agreements with each payment system
  • retain direct money flow from payment systems
  • manage payment system fees, chargebacks and refunds, payout commissions, and operating costs

For example, if you work with PayPal and want to set it as a direct payment method, you can connect a gateway. The payment UI will not change — the changes will affect only the payout process. After processing a payment, a player’s money will be transferred to your PayPal account. In this case, Xsolla is not involved in the payout process.

How can I migrate user data (saved payment accounts, subscriptions, etc.) to Xsolla?

Contact your Customer Success Manager or email to csm@xsolla.com. Make sure you use PGP encryption to provide data security.

Xsolla PGP key parameters:

  • Key ID: FBA38225
  • Key type: RSA
  • Key Length: 4096
  • Fingerprint: 4D63 4B67 B265 5464 D39D 7228 67B0 672A FBA3 8225
  • User ID: admins@xsolla.com

Copy
Full screen
Small screen
-----BEGIN PGP PUBLIC KEY BLOCK-----
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
=7AyM
-----END PGP PUBLIC KEY BLOCK-----

How is a user’s country determined?

When you use the client-side API call for generating the payment token, Xsolla determines the user’s country from the IP address of the request.

When you use the server-side API call for generating the payment token, the country is determined by sequential checking of:

  • the user.country.value parameter’s value in the request body
  • the IP address in the X-User-Ip header

If none of these values are passed, an error appears. If both of these values are passed, information from the request body is used.

Error messages

Note
Refer to the documentation for more information about possible errors while opening the payment UI.

What should I do when I get the 0004-0008 error?

Check if you use the correct URL address:

What should I do when I get the 2205 or 2207 errors (user ID error)?

  • Pass a valid user ID which is user_id from your database.
  • Recommendations regarding webhook usage:
    • If you don’t want to use webhooks, make sure they are disabled in your project. To do that, go to Publisher Account, and in the Project settings > Webhooks section, set the toggle to Off.
    • If you want to use webhooks, implement successful processing of the User validation webhook.

What should I do when I get the 1000-0003 error?

Activate the respective module for your project.

What should I do when I get the 0002-0004 error?

Sign the licensing agreement with Xsolla to receive your payouts. If you need assistance, contact your Customer Success Manager or email onboarding@xsolla.com.

What should I do when I get the 3032 error?

Send information about payment tokens with errors or user IDs and project IDs to the integration team through any of the available communication channels.
Note
You can find the payment token in the URL address of the opened payment UI. If the payment UI is opened in an iframe, right-click the iframe and select an option that allows you to view the iframe’s source from the drop-down list.

Why is the Authorization header missing from the webhook request?

To fix this error, you need to edit the .htaccess or httpd.conf Apache files. Refer to the SDK documentation for more information.

Contact information

If you haven’t found an answer to your questions in the FAQs, contact us via other channels:
  • Click the chat icon in the bottom right corner and contact the integration team via a messenger. You will get an answer that resolves your problem in real time.
  • Email at integration@xsolla.com.
  • Contact your Customer Success Manager or email to csm@xsolla.com.
  • Contact integration specialist via Basecamp.
Customer Service integration guide (PDF)
Learn about the options to integrate with our Customer Service Team.
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.
Last updated: August 30, 2024

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

Contents
Report a problem
We always review our content. Your feedback helps us improve it.
Provide an email so we can follow up
Thank you for your feedback!