If you can’t find the answer you’re looking for here, contact us via one of the following channels:

Learn about options for interacting with our Customer Service Team in the integration guide (PDF).


How can I open Pay Station in an iframe?

We recommend opening Pay Station in a lightbox using the Pay Station Embed script, which:

  • automatically determines Pay Station size and device type (desktop vs. mobile)
  • automatically receives events from the payment UI
  • allows you to change the UI theme

If you still want to open the payment UI inside an iframe, you must:

  1. Specify the device type (desktop vs. mobile) and send it within the token’s settings.ui.version parameter.
  2. Implement the postMessage mechanism receiving events from the payment UI.
  3. Get a token.
  4. Send the Pay Station window size in the token:

Pay Station sizeIframe width
large (default)670–850 px
medium590–740 px
small510–630 px

To open the Pay Station UI in an iframe, use the following link: https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN, where ACCESS_TOKEN is the payment UI token.

What are the Xsolla network IP addresses that I need to whitelist?

You must be able to accept and process webhooks from the following IP addresses:,, If you connected the Login product, additionally add processing from the IP address.

How can I integrate Partner Network, Store, Login or some other new or auxiliary Xsolla products?

To integrate Xsolla products, contact us at integration@xsolla.com and we will assist you.

How can I add paysafecard to my payment methods?

To add a new payment method, contact us at integration@xsolla.com.

Do you have SDK for Node.JS/C#/Ruby/Java/ASP, etc.?

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

Why isn’t the PHP library working on my site?

Check that you have installed all of the required files and that the relative paths are valid. You can find more information on the setup on GitHub.

User validation

What’s the user ID? How should we set up the user validation?

The user ID is a way of identifying a user in your game. You can use a database to store your user IDs. If an invalid user ID is being used, you should throw an exception. You can find an example of how to handle user validation on GitHub.

After validation is completed, what data should be returned? For example, what should be returned if user validation succeeds or fails?

If user validation succeeds, you should send a 200 response. If it fails, send a 400 response with the error code INVALID_USER.

Project settings

How do I launch the modules I activated in Publisher Account?

You will have to configure and test the modules before launching them. For details, refer to the Integration Guides. If you are experiencing problems receiving webhooks, check if the webhook server is installed correctly. If the issue persists, contact us at integration@xsolla.com.

Do we need to create new project IDs for every environment — QA, staging, production?

We recommend using separate projects so that the production environment project isn’t affected.

What’s the difference between the secret key, project key, and API key?

The secret key and project key are the same. The secret key is used for the digital signature required for secure payments. We concatenate the request’s JSON body with your project’s secret key and apply SHA-1 hashing to the resulting string. The API key is the same for all projects in your account. API key is used for API calls that are sent to the Xsolla server. The key must be held on your own server, never inside your game binaries or front ends.

What’s the difference between Webhook URL and Return URL?

The Webhook URL is the url of your webhook server. The Return URL is where the user is redirected after completing a payment.

Where can I find my Project ID/Merchant ID/Publisher ID?

Your project ID is the number beside the name of your project in the Publisher Account. It is also the number found in the following URL: https://publisher.xsolla.com/{merchant_id}/projects/{project_id}/. The Merchant ID and Publisher ID are actually the same. It is the number in the following URL: https://publisher.xsolla.com/{merchant_id}/.

Where can I find the API Key?

To generate your API key, go to Company settings > API key in the Publisher Account.

How can I invite members of my company to have access to my Publisher Account?

You can invite additional members under Company settings > Users in your Publisher Account.

I am a mobile game publisher, what should I fill in for the Website field on the project settings page?

You can fill in the URL of the game’s website or the URL of your company’s website.

Webhook settings

Do I use HTTPS for Webhook Protocol?

Yes, because the Xsolla API uses basic access authentication.

Why did the webhook URL not receive your notification?

Make sure that you have included all of the required files and that your webhook server is setup to handle required types of webhook requests.

Why aren’t webhooks sending to my mobile app?

Webhooks are only sent to a single URL endpoint, defined in your project’s settings. As such, they are server-to-server and cannot be sent to a wide variety of URLs. If you would like to enable notifications to your game, website, or mobile app, we recommend building a messaging solution in your server, which can pass data between Xsolla and your game.


Can we customize the Pay Station theme?

You can opt for a darker theme by sending settings.ui.theme = default_dark in the token. The dark theme also allows you to set the background to an image or color of your choice (see example). To change other settings, contact your Account Manager.

Can we change the appearance of messages 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 part of a standard template. This is required according to the Licensing Agreement with Xsolla, which acts as the legal Merchant of Records.


Do you have a dummy credit/debit card I can use to test payments?

Yes, you can use one of our test cards in the Sandbox mode.

Can I test the PayPal payment flow in sandbox mode?

Yes, you can test a successful PayPal payment scenario. See detailed information in the instruction.

How do I emulate a refund?

You can use the Refund webhook or go to the Support > Transaction search in Publisher Account.

What is the Xsolla Invoice ID and Invoice ID in the Testing tab of my project?

The Xsolla ID is your transaction ID in Xsolla. The Invoice ID is the optional transaction ID in your game. For testing, you can use any numeric value.

Why can’t I pass the testing for a Buycraft project?

Buycraft partners will get INVALID_SIGNATURE if their API key, Merchant ID, Project ID or secret key weren’t correctly entered into their Buycraft account.


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

Check the user ID to make sure it exists in your project and return code 200 to validate the payment.

How do I check the last payment account used?

Such a check is not possible at the moment.

Can we redirect the user to a certain payment method right away?

Yes, by sending the settings.payment_method parameter when opening the store UI. The user will be immediately redirected to a payment form of the chosen payment method. You can find the list of payment method IDs in the Publisher Account’s Payment methods section or using the Get payment methods.

Can we automatically redirect the user to a successful/failed payment page right after processing the payment depending on the outcome?

Yes, you can go to the Pay Station settings in Publisher Account and set the redirect policies.

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

You can send the order_id value in the external_id parameter. To enable the parameter, go to Pay Station settings and set External ID to On.

Can we override the webhook URL for every transaction?

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

Will you send us the details of failed transactions?

No, we only send webhooks in case of successful transactions. If you received the webhook, it means the transaction was successful.

How do I add the VAT consumption tax to the payment total?

VAT settings are configured by Xsolla. If you want to charge users with the VAT instead of paying it yourself, which is the default configuration, contact your Account Manager, and we will change the settings.

What does PID mean?

PID is the payment method identifier at Xsolla side.

How can we update a user’s virtual currency balance?

You can use the Update user balance API method.

Is the External ID our custom ID for our game/platform? Should we make a new External ID for every transaction?

The External ID is the invoice ID that you have in your systems. There can only be one payment with a given external_id at any time, so you should send a new one each time a user makes a payment.

What value should I set for the setExternalPaymentId method?

Set it to the same value as external_id, if you have one.

How can I set purchase.description.value up with your PHP SDK?

The purchase description is used in the Pay Station UI and email receipts. You can set the value in the token.

What are gateways?

Gateways allow receiving payouts directly from payment systems available within the Pay Station interface. Under this model of interactions, nothing changes for the player. Every purchase is made via the chosen payment method. The point is that you can attach any payment system or aggregator and receive payouts directly from the payment system providers.

Xsolla serves only as a Technical Service Provider and takes a reduced Revenue share: 1.25% + $0.10. That means you receive full-scale Xsolla solutions, but you take on the following:

  • managing tax-related issues
  • signing separate agreements with each payment system
  • retaining direct money flow from the payment systems
  • managing payment system fees, charge-backs and refunds, payout commissions, and operating costs

For example, if you work with PayPal and want to set it as a direct payment method, Payment Gateway is needed. Using this model, the interface does not change, but there are still some important differences. After the payment is processed, the end user’s money is transferred directly to your PayPal account. This method excludes Xsolla’s involvement.

What payout methods do you offer for Buycraft projects?

We offer Paypal and bank transfer for Buycraft projects.

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

Contact your Account Manager to migrate user data. Make sure you use PGP Encryption to provide security.


What’s the difference between standalone coupons, and coupons used for promotions?

A standalone coupon can be used to grant free items upon redeeming the coupon code. If you make a promotion valid for purchases with a coupon code, you can get purchase discounts and bonuses.


What is the product_id in Subscriptions?

This parameter can be used when a user has multiple paid subscriptions to different things. The product_id would distinguish a user’s multiple subscriptions.

Error messages

When I open the Pay Station UI, I’m getting Error code: 0004-0008. What does this mean?

You’re using an incorrect URL for the Sandbox mode. If you want to make a real payment, use secure.xsolla.com. If you want to make a test payment, use sandbox-secure.xsolla.com. You can learn more about what possible errors are available in the API reference.

Xsolla PHP SDK returns the INVALID_CLIENT_IP error. What should I do?

You must add your reverse proxy IP address to the webhook server.

What does the 2205 or 2207 error mean (user ID error)?

These errors mean that a valid user ID is required. Please check that you are using a user ID from your database.

What does the 1000-0003 error mean?

You need to activate the module for your project, or for Checkout, you may be missing some of the purchase parameters.

What does the 0002-0004 error mean?

This error means that you need to sign the agreement with us in order to receive your payouts. Contact your Account Manager or onboarding@xsolla.com for assistance.

Why is the Authorization header not found in webhook request?

You need to edit your .htaccess or httpd.conf Apache file. Follow Xsolla’s SDK documentation for more information.

I suppose that I can’t get the token string because of an SSL issue. Is your interface mandatory to verify SSL?

By default we enable SSL certificate verification and use the default CA bundle provided by your operating system. You can find more information on how to troubleshoot SSL issues in Xsolla’s SDK documentation.

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.
Rate this page
Rate this page
Is there anything we can improve?

Don’t want to answer

Thank you for your feedback!
Last updated: February 10, 2021

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