FAQ

If you don’t find the answer you’re looking for here, we’ll be happy to help you over one of the following channels:

Integration

Q. How can I open Pay Station in an iframe?

A. 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:

  • Specify the device type (desktop vs mobile) and send it within the token’s settings.ui.version parameter
  • Implement the postMessage mechanism receiving events from the payment UI
  • Get a token
  • Send the Pay Station window size in the token:
Pay Station Size Iframe Width
large (default) 670–850px
medium 590–740px
small 510–630px

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

Q. What browsers do the Pay Station UI and the Publisher Account support?

A. Correct operation of the Pay Station UI and the Publisher Account is guaranteed in the following browsers:

  • Google Chrome 49 and above
  • Mozilla Firefox 45 and above
  • Opera 36 and above
  • Internet Explorer 11
  • Microsoft Edge 12 and above
  • Safari 9 and above
  • Android Browser 49 and above

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

A. You must be able to accept and process webhooks from the following IP addresses: 185.30.20.0/24, 185.30.21.0/24.

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

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

Q. How can I add paysafecard to my payment methods?

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

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

A. 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.

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

A. Please 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

Q. What’s the user ID? How should we do the user validation?

A. 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.

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

A. 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

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

A. 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.

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

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

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

A. 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 API key must be held on your own server, never inside your game binaries or frontends.

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

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

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

A. 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}/.

Q. Where can I find the API Key?

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

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

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

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

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

Buycraft Project Settings

Q. Where can I find my Project ID / Merchant ID / API Key / Secret Key parameters for Buycraft projects?

A. Use this guide to find these parameters and set up your project.

Q. What should I enter for the Game Title in the Agreement Info section in Buycraft settings?

A. Enter the name of your server.

Webhook Settings

Q. Do I use HTTPS for Webhook Protocol?

A. Yes, because the Xsolla API uses HTTP Basic Authentication.

Q. Why did the webhook URL not receive your notification?

A. Please 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.

Q. Why aren’t webhooks sending to my mobile app?

A. 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.

Customization

Q. Can we customize the Pay Station theme?

A. You can opt for a darker theme by sending settings.ui.theme = 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, please contact your Account Manager.

Q. Can we change the appearance of messages sent to users?

A. Please contact your Account Manager for custom email themes. The layout 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 Record.

Testing

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

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

Q. Can we test the PayPal flow in the Sandbox mode?

A. Unfortunately, PayPal payments cannot be tested in the Sandbox mode at the moment.

Q. How do I emulate a refund?

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

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

A. 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.

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

A. 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.

Payments

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

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

Q. How do I check the last payment account used?

A. Such a check is not possible at the moment.

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

A. 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 method.

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

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

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

A. 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.

Q. Can we override the webhook URL for every transaction?

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

Q. Will you send us the details of failed transactions?

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

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

A. 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, please contact your Account Manager, and we will change the settings.

Q. What does PID mean?

A. PID is the payment method identifier at Xsolla side.

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

A. You can use the Update User Balance API method.

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

A. 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.

Q. What value should I set for the setExternalPaymentId method?

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

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

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

Q. What are gateways?

A. The Gateways section in your Publisher Account is for our partners who have an existing account with a payment method and would like to receive payments to that account. When using a gateway, you would be bypassing Xsolla.

Q. What payout methods do you offer for Buycraft projects?

A. We offer Paypal and bank transfer for Buycraft projects.

Coupons

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

A. 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.

Subscriptions

Q. What is the product_id in Subscriptions?

A. 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

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

A. 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 leasrn more about what possible errors are available in the API Reference.

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

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

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

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

Q. What does the 1000-0003 error mean?

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

Q. What does the 0002-0004 error mean?

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

Q. Why is the Authorization header not not found in webhook request?

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

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

A. 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.