From X-Payments Help
Jump to: navigation, search
X-Payments user manual
  1. X-Payments:General information
  2. What's New
  3. System requirements
  4. Installation
  5. Two-factor user authentication
  6. Configuring X-Payments
  7. Managing users
  8. Customizing the interface
  9. Managing payments
  10. Unistalling X-Payments
  11. Upgrading
  12. Moving X-Payments from one host to another
  13. Viewing X-Payments logs
  14. FAQ
  15. Troubleshooting
  16. Glossary
  17. Supported payment gateways
  18. Popular Payment Methods Configuration Instructions



What is the X-Cart Payments service?

X-Cart Payments is a SaaS (Software as a Service) solution allowing online merchants to use "on-site" or "merchant-hosted" credit card payment methods, like "Authorize.Net AIM", "SagePay - Direct integration", "FirstData Global Gateway - API", "PayPal Payments Pro - Direct Payment", and many others in their integrated shopping carts.

The service includes:

  • An account on a PCI DSS compliant web-hosting;
  • An SSL certificate;
  • A pre-installed and configured X-Payments application.

The X-Payments application (aka X-Cart Payments) provides a secure bridge between the integrated shopping cart software and payment gateways. The application is hosted on a reliable and PCI DSS compliant web-hosting and is secured with SSL. It helps merchants to facilitate their overall PCI DSS compliance and to accept credit card payments securely.

Besides, X-Cart Payments makes it possible to accept credit card payments right on the checkout page in X-Cart (using the so-called iFrame One-Step Checkout feature), while still providing a PCI DSS compliant payment solution for merchants. In other words, customers can pay without ever leaving your website and being redirected to the payment gateway site, in contrast to "off-site" payment methods like "PayPal Payments Standard", "Authorize.Net SIM", "SagePay - Form integration", "FirstData Global Gateway - Connect", etc. This can reassure customers and increase the conversion rates eventually, according to a research conducted by Getelastic.com.

Read more about X-Cart Payments on our website:

Which shopping cart software is compatible with X-Payments?

X-Payments provides a web-based API allowing your store to submit or retrieve data. The shopping cart software you use for your store must support this API, which means you have to get an appropriate connector mod.

See the following pages for more info:

How can I obtain an X-Payments license

X-Payments can be purchased at X-Cart website.

How many stores can be connected to a single X-Payments installation?

See details at X-Payments plans page

Can I transfer my X-Payments license and the software to a third party?

It is possible for paid X-Payments downloadable licenses, but you need to get our written consent according to the terms and conditions of the license agreement.

Installation and configuration

Why did you include PHP 5.3.0 into the X-Payments system requirements? It's relatively new, and many hosts aren't running it yet.

According to PCI DSS Requirements (paragraph 6.1),

>> 6.1 Ensure that all system components and software have the latest vendor-supplied security patches installed. Install critical security patches within one month of release.

For PHP "the latest vendor-supplied security patches" means "the latest PHP version", because they do not supply patches. When we started to develop X-Payments, there were two stable versions of PHP available: 5.2.10 and 5.3.0. By the summer of 2010, the time PCI DSS compliance becomes a must, PHP 5.3.x will probably be as widely spread as 5.2.x now. That is why we decided to use some nice improvements of PHP 5.3.0.

Can you tell me exactly what it is in v5.3.0 that's so necessary for X-Payments?

The PHP development team has announced the end of support for PHP 5.2; therefore, 5.3 is going to be the earliest PHP version out there. We have used the newest features available in PHP 5.3 to make our software more current and eliminate the need to design and then certify it all over. Thus, PHP 5.3 features a more appropriate implementation of the Singleton pattern and allows to implement widget operations in the viewer using __invoke. It also offers numerous other functions that are handy but not available in PHP older than 5.3; for instance, array_replace, array_replace_recursive, etc.

Can X-Payments be set up together with old Subscriptions add-on module to automatically bill subscribers on a regular basis?

No, it cannot. X-Cart's old Subscriptions module is not compatible with X-Payments, and it is not PCI complaint. The proper way is to use the new X-Payments Subscriptions module for X-Cart 4 and X-Cart 5.

Why is it not possible to use blank database passwords in X-Payments configuration? That's not a problem for a production copy, but my test system doesn't use passwords usually

According to PA-DSS requirements (paragraph 3.2),

>> 3.2 Access to PCs, servers, and databases with payment applications must require a unique user ID and secure authentication.

This means that a password must be used to access the database as well. X-Payments doesn't have a test mode, and all the requirements are checked on the fly as if it were a production copy. X-Payments won't start until all the requirements are met. That is how we guarantee that the software meets PA-DSS requirements. If there were a test mode, we would have to add another level of checking, and each such level decreases the security of the software "in the field". That is why we decided to go without some cool features but keep the high level of security.

Can X-Payments be installed on server where my shopping cart software is hosted or do I need a separate web-server?

Both options are allowed. X-Payments can be set up either together with your shopping cart software provided it is run in a separate PCI compliant hosting space/account or on a separate server (X-Payments uses SSL connection to exchange data with your store).

Can X-Payments be installed on a shared hosting?

Yes, provided that a separate account is used to host X-Payments. No other software must be installed and run under this account.

Can I configure X-Payments to allow my customers to enter their billing address when entering their credit card data?

No, you cannot. To edit the billing address, a customer has to go back to the store and edit the billing address in the customer profile at the store.

How do I create a different skin for the page where customers enter their cardholder data?

To create a different template for the page where your customers enter their cardholder data, you should work with the directories <xpayments>/lib/XPay/Templates/ and <xpayments>/public/templates/ .

  • To add a new template, create a file <xpayments>/lib/XPay/Templates/<new_template_name>.html and put the HTML code for the new template into the file. Make sure you only put the code between the tags <body> and </body> as it will be automatically included into the general HTML code of the file <xpayments>/lib/XPay/Skin/Payment/Home.php. After that you will be able to select the new template from the 'Template' drop-down box at the 'Online store details' page.
  • If you want to use a different CSS style, place the CSS code into the file <xpayments>/public/templates/<new_template_name>.css, and it will be linked automatically during the page generation.
  • If you want to use a different set of images, copy the images to the directory <xpayments>/public/templates/<new_template_name>/directory.

Is it possible to configure X-Payments to have my sales processed manually?

No, it is not possible since X-Payments does not allow storing credit card numbers.

How can I manually decrypt the LinkPoint key, which is returned encrypted by default?

Use the openssl program in the command line:

openssl rsa -in oldkey.pem -out newkey.pem
  • oldkey.pem - name of the encrypted key file provided by LinkPoint
  • newkey.pem - name of the unencrypted key file to be uploaded to the server

1. When prompted to enter a password, enter the one you have received from Link Point. If you are prompted to enter a password again, just press Enter to leave the output key with no password.

2. Be sure to set secure permissions on that file once you upload it (generally, the secure permissions are "600").

3. Be sure to remove the unencrypted key from your local PC.

My payment method does not appear in the list after a successful import. What should I do?

Chances are you want to use PayPal as your payment method. If this is so, you need to [index.php?title=X-Payments:PayPal follow a few additional steps] to get PayPal to work with X-Payments.

I'm executing the cron.php script in a browser, but nothing happens

If the script is run not in the command line interface (like in a browser in our case), its execution is interrupted due to security reasons.

To run the script successfully, execute it from the command line and use a PHP interpreter version 5.3.0 or better. You can use SSH access to execute the script.

I need cron.php to send me emails when cronjobs are executed

If you use Enterprise/Downloadable X-Payments, and your hosting can send emails every time an X-Payments job is executed, you can add a certain code to crontab settings for X-Payments cron.php to make cron send you emails; for example:

cd /home/checkout/public_html/ && /usr/bin/php-cli cron.php; echo "X-Payments Cron Job was launched";

Moreover, you can email the results of cron jobs execution to yourself by making a line like the following:

cd /home/checkout/public_html/ && /usr/bin/php-cli cron.php; cat /var/log/cron/YYYY-MM-DD/errors.php;

Just be sure to replace YYYY-MM-DD with a code that defines the current date on your server.

I'm the admin and my account got locked

This could happen when a user exceeds the allowed number of unsuccessful access attempts. The account is automatically locked for the period of time specified in the 'General settings' section.

If this is the case, you should wait until the specified dangerous activity blocking period passes, and try to sign in again.

By default, X-Payments limits the number of unsuccessful login attempts to the maximum of 6 and does not allow new login attempts for 30 minutes (this is controlled via Settings -> General settings -> Dangerous activity blocking period).

I lost my password. What do I need to do?

  1. Go to
  2. Click the 'Forgot password' link on the login page. An email message will be sent to you with a link containing your profile confirmation token.
  3. Follow the link to reset the password.

If the profile confirmation token has expired for some reason (e.g. you missed the email message and did not click the link in time), and you cannot set a new password for your account, just use the 'Forgot password' link on the login page again.

Where can I find my X-Payments logs?

X-Payments logs and X-Cart logs related to X-Payments can be found as follows:

On the X-Payments end: See the <xpay-dir>/var/log/ directory. If you are using an X-Payment Hosted account, you can see this folder as "var/log" in your X-Payments FTP account.

On the X-Cart 4 end: See the <xcart-dir>/var/log/x-errors_xpay_connector-YYMMDD.php files

Starting with X-Payments version 3.0, it is possible to view X-Payments logs directly via the Activity and error logs section of the X-Payments admin interface (Settings -> View logs), without the need for FTP.

How to increase PayPal Payflow Pro "TIMEOUT" value

In the file <xpay_dir>/lib/XPay/Module/PaypalWPPPEDirectPayment.php, locate the line # 249:

<source> $bouncerData->setTimeout(45); </source>

and change 45 to some other value in seconds (a number between 30..60 is recommended)

How to enable the use of TLS/SSL SMTP

In the file <xpdir>/config/config.ini.php, locate the line:


and replace it with the following:


How to configure Elavon Converge/Virtual Merchant - Merchant Provided Form

Suggested X-Payments settings:

  • set Initial transaction to auth & capture
  • merchantID is the same as elavon "accountID"
  • get the userid from elavon
  • get the PIN from elavon

Then setup myvirtualmerchant settings:

terminal > advanced > system setup

  • Use HTTP Referrers [ unchecked ]
  • Auto Pend HTTP Transactions [x]
  • Auto Settlement [x]

EVERYTHING else is empty

PS: Many thanks to carpeperdiem for sharing!

We have to update the existing Merchant ID to a new one in Chase Paymentech configuration page. How do we change it in X-Payments?

First of all, the Merchant ID in an X-Payments payment configuration must match the one for your merchant account on the Chase Paymentech end. So, the best way will be to update the ID first on the Chase Paymentech end, and right after that to update it in X-Payments.

Please note that, after changing the Merchant ID, most likely it will be impossible to run secondary operations on payments that have been made using the previous Merchant ID from Chase, such as Capturing funds, Voids and Refunds. The same applies to the saved (tokenized) cards. Because the transactions are tied to the merchant account. So, if you change the merchant account in X-Payments, you’ll still be able to run those operations for the previous payments, but only from the Chase Paymentech merchant backend, not via X-Payments. Surely, the new payments which are processed with the new merchant account will work fine.

X-Payments payment processing should work fine without any changes in the X-Payments Connector configuration on the store end.

X-Payments Hosted FAQ

What do I need to put as "Callback IP"?

If you use X-Payments Hosted at "*.xpayments.com" domain you need to specify

How to configure an FTP client to connect to the yourdomain.x-checkout.com to access skins and logs?

X-Payments 3.x does not support FTP connections. You can use XP 3.x admin back-end to access skins and logs in this version.

The instructions below are valid only for X-Payments versions 2.x and earlier.

To establish an FTP connection, you should use the details from the email received when your account was created:

  • host: yourdomain.x-checkout.com
  • user: skins@yourdomain.x-checkout.com
  • password: the one that you've received

Please make sure that the "Explicit FTP over TLS" mode is used. This is required because plain text authentication is not allowed for PCI compliance.

Instructions for FileZilla FTP Client:

  1. Start FileZilla
  2. Go to File -> Site Manager
  3. Click New site
  4. Enter the connection settings:
    • Host: yourdomain.x-checkout.com
    • Port: leave blank
    • Protocol: FTP - File Transfer Protocol
    • Encryption: Require explict FTP over TLS
    • Logon type: Normal
    • user: skins@yourdomain.x-checkout.com
    • password: the one that you've received
  5. Click the Connect button

PDF button.png This article can be downloaded as a PDF file