X-Cart:X-Payments Connector

X-Cart 4.4.0

Overview

X-Payments Connector is an add-on module for X-Cart that provides an interface for an X-Cart based online store to connect to and process payments via X-Payments, a PCI DSS Level 1 service provider.

You can find a collection of connector module packs for older X-Cart 4 versions here.

Connecting an X-Cart store to X-Payments versions 2.1-3.x

Video tutorial

Below is a video tutorial on how to connect X-Payments 2.1-3.x with X-Cart 4.6.4 or later. The video features the X-Payments connector modules for X-Cart 4.x Classic released in September 2014.

Connection instructions

The following procedure assumes that you have an X-Payments account created using https://www.x-payments.com/trial-demo.html

Follow the steps below:

1. Log in to the Admin back end of your X-Payments installation and make sure you have everything ready on the X-Payments end:
   1. In the Online Stores section of X-Payments (Settings->Online stores), add and configure an online store that will represent your X-Cart store in X-Payments.
      
      
      
   2. In the Payment Configurations section of X-Payments (Settings->Payment configurations), add and configure one or more payment configurations for this store. On the screenshot below you can see that we are adding the payment configuration based on the "First Data Payeezy Gateway (ex-Global Gateway e4)" module:
      
      
      The payment method for accepting payments via X-Payments will be created from this very configuration. Make sure the payment configuration is active ("Enabled").
      
      
      
   3. In the details of the online store you have configured in X-Payments, specify that the store will be using the payment configuration you have created and configured at the previous step.
      
      
      Make sure the store is active ("Enabled").
      
      
      
   4. Click on the name of the store you have configured in X-Payments to access the store's details. Here you will find a section titled "Connection". This section contains the configuration bundle that you will use a bit later to automatically deploy your X-Payments connection details in X-Cart. For now, leave the X-Payments page with the configuration bundle open and go on to the next step.
      
      
2. In a new browser tab or window, go to the Admin area section of your X-Cart store and, after logging in as administrator, prepare your X-Cart store for the connection:
   1. Go to the Modules section (Settings->Modules) and find the module X-Payments Connector:
      
      
      
   2. Activate the module as usual:
      
      
      
   3. Click the Configure button next to the module name to access the module settings.
      
      
      
      The module settings can also be accessed by selecting Settings->X-Payments Connector.
      
      If you see a page like the following, click Next:
      
      
      Your aim is to get to a page where you can enter your X-Payments configuration bundle:
      
      
      
3. Go back to the browser tab or window where you have the details of your online store in X-Payments and click the button to copy your configuration bundle to clipboard:
   
   
   
4. In X-Cart, paste the bundle you have copied into the appropriate field on the X-Payments Connector settings page, then click the Deploy button:
   
   
   X-Cart will take a few moments to deploy the configuration bundle. Once the deployment has been completed, a success message will be displayed at the top of the page saying that the configuration has been successfully deployed and the payment methods have been synchronized:
   
   
   
5. Now have a closer look at the X-Payments Connector settings page:
   
   
   Here you will need to configure your store's X-Payments-related settings.
   1. On the Payment methods tab, you can see the list of payment methods that have been imported from X-Payments - according to what payment configurations have been configured and enabled for your X-Cart store on the X-Payments end. After the deployment of the X-Payments configuration bundle in X-Cart, the imported payment methods are not yet active in your X-Cart store. To activate the methods you want to use, mark them as active by selecting the Active checkbox(es) next to their name(s). Be sure to click Update to save your changes. For payment methods that support tokenization in X-Payments, you can enable PCI compliant credit card saving in your X-Cart store by selecting the Use for recharges checkbox(es). Again, be sure to click Update to save your changes:
      
      
      Note that if you make any changes to your X-Payments payment methods on the X-Payments end, you will need to synchronize them with X-Cart. To synchronize your payment methods, use the Synchronize payment methods with X-Payments button:
      
      
      As a result of synchronization, any payment methods added, updated or deleted in X-Payments will be added, updated or deleted, respectively, in X-Cart.
      
      
   2. If necessary, on the Order status mapping rules tab, adjust the rules for how payment statuses recognized by X-Payments should be converted to order statuses in your X-Cart store:
      
      
      Be sure to save your changes by clicking the Apply changes button.
      
      
   3. If you wish to allow your X-Cart store users to save their credit card in their front-end profile, adjust the settings on the Save credit card setup tab; be sure to save your changes by clicking the Apply changes button.
      
      
      Note that at least one active X-Payments payment method that supports "recharges" is required to use the save credit card feature.
      
      The guidelines for adjusting the settings on the Save credit card setup tab are as follows:
      
      • Enable save credit card feature: Select this check box to enable the save credit card feature for your customers. With this feature enabled, your customers will be able to save their card in their front-end profile.
      • Set a payment method for saving cards: Select the payment method that you want to be used by customers who choose to save their card. Comment: When a customer chooses to save their credit card with your store for future payments, you need to run an authorization against their card to have the card details saved by the payment service provider and to obtain a token that will later need to be submitted for any future authorization/charge requests for that customer to use their card for payment. The payment method selected here will be used for such authorization transactions.
      • Authorization amount: Specify the small sum for which your store will request an authorization when saving a customer's card. Comment: By default, a zero value authorization is used on the customer's card when a card is being saved. However, some payment service providers do not support zero value authorizations. If this is the case with the PSP you intend to use for card saving, adjust the authorization amount value in the "Authorization amount" field according to the requirements of your PSP so you can obtain non-zero value authorizations.
        
        
   4. Use the Connection settings tab to provide some additional connection settings:
      
      
      Be sure to save your changes by clicking the Apply changes button.
      
      The guidelines for adjusting the settings on the Connection settings tab are as follows:
      
      • IP addresses for X-Payments callbacks (optional): Enter a comma-separated list of IP addresses from which your X-Payments callbacks will originate. Comment: X-Payments will send callback requests to your store from specific IP addresses. To ensure that your store accepts callback requests only from these IP addresses, specify the allowed IP addresses here as a comma-separated list. Note that the address "127.0.0.1" may not be used here. For a better understanding of what IP address(es) to put here, see Callback from X-Payments to the store.
      • Use iframe: Specify whether the X-Payments credit card form should be embedded in your X-Cart store's checkout via iframe (available with X-Payments 2.1.0 or newer).
      • Payment currency: Specify the currency that should be used for all payment transactions via X-Payments.

After completing the connection of X-Payments with X-Cart via the X-Payments Connector module as provided above, you should be able to find your X-Payments payment methods in the Payment methods section of your store:

Attention CloudFlare users: If using Cloudflare, be sure to configure CloudFlare to allow incoming HTTPS requests from 52.36.122.200 to (xc_server)/payment/cc_xpc.php. [That is needed so X-Payments server can connect to X-Cart server.] Please refer to CloudFlare user manual for instructions on how to do that.

Connecting an X-Cart store to X-Payments v1.x (User manual for old X-Cart connector modules)

IMPORTANT NOTE: If you are using a new X-Payments version and an X-Cart version newer than 4.6.3, please read the above section.

System requirements

To be able to use the X-Payments Connector add-on module, you must have:

• Installed copy of X-Cart v4.3.0 or later;
• Installed copy of X-Payments v 1.0 or later;
• PHP extensions:

• libCurl version >= 7.10;
• OpenSSL extension;
• XML DOM extension, to parse XML data (or DOM extension for PHP 5.x).

Note: X-Cart versions 4.4.x and later already have theX-Payments Connector included into the distribution package. For these versions, you do not need to install the module - just enable it on the "Modules" page and configure it to work with your X-Payments installation.

Configuring the X-Payments Connector

Before you can start using X-Cart together with X-Payments, you must configure the X-Payments Connector.

To configure the X-Payments Connector:

1. Log in to the X-Cart Admin area.

2. Go to the Modules section (Administration menu -> Modules).

3. If not selected, select the check box for the X-Payments Connector and click Update. This will activate the module.

4. Click on the Configure link for the X-Payments Connector module.

This will open the X-Payments Connector configuration page.

5. Define connection details.

• Copy the value of the Configuration bundle field from the X-Payments' Online Store Details page, paste the string here and click Deploy. All the connection settings will be automatically specified.

The latest versions of X-Payments Connector can automatically get connection settings from the settings of the store. In the older versions, the values are to be specified manually.

• Store ID: Unique value generated in the X-Payments back-end for a particular store. This value allows X-Payments to correctly identify requests coming from this store.
• X-Payment URL: The URL of your X-Payments installation. Make sure the URL is specified correctly, otherwise the module will not be able to connect to X-Payments.
• Encryption key: A key to encrypt requests that the store sends to X-Payments. The key is generated in the X-Payments back-end.
• Decryption key: A key to decrypt responses and callback requests that the store receives from X-Payments. The key is generated in the X-Payments back-end.
• Decryption key password: A password to decrypt the Decryption key. The password is generated in X-Payments back-office.
• IP addresses for X-Payments callbacks: enter IP address of the server where X-Payments is installed. "127.0.0.1" can not be used here. If you are using a hosted X-Payments plan read this FAQ. For better understanding what IP address to put here see X-Payments:How_It_Works#Callback_from_X-Payments_to_the_store

6. Set the mapping rules you require.

The mapping rules are used to synchronize the transaction statuses in X-Payments with the statuses of the respective X-Cart orders. To associate an X-Payments transaction status with an X-Cart order status, choose the order status from the drop-down box in the column on the right.

For example, if you associate the entry "Set order status for 'Charged' payment to" on the right with the value "Processed" from the drop-down box on the left, changing the status of an X-Payment transaction to "Charged" will automatically change the status of the respective order in X-Cart to "Processed".

7. Click the Save button.

Making a test transaction

To test the module settings and connection with X-Payments, click the Test module button. If the module is configured properly, a 'Test transaction successfully completed' message is displayed at the top of the page.

Importing the X-Payments payment methods into X-Cart

To be able to use the payment methods defined in X-Payments you should import information about them from X-Payments.

First, click the Request payment methods from X-Payments button, and X-Payments will return a list of payment methods available for this shopping cart.

After you have reviewed the list of available payment methods, click Import payment methods and proceed with the next step - adding and enabling X-Payments payment methods in X-Cart admin area.

Please note that if you have already imported payment methods from X-Payments earlier, all previously imported payment methods will be removed from the "Payment methods" list in X-Cart if you select to import payment methods again. In this case, you will have to add and enable X-Payments payment methods in X-Cart admin area once again.

Adding and enabling X-Payments payment methods in X-Cart

To be able to use X-Payments payment methods, you need to add and enable them in X-Cart admin area.

Note: If you are looking to set up PayPal's payment methods via X-Payments in your X-Cart store, please proceed with the special instructions for adding and enabling PayPal payment methods in X-Cart, and skip the instructions below. Otherwise, in case you're looking to set up other payment methods like Authorize.Net AIM or PayflowPro, please proceed with the instructions below.

Note: As PayPal requires a special configuration process as noted above, PayPal's payment methods imported from X-Payments will NEVER appear in the "Payment Gateways" list under the "X-Payments payment methods" section. Do not worry about it - you will see them when following the special PayPal configuration instructions as noted above.

1. In the Admin area of your X-Cart store, go to the Payment methods page (Settings->Payment methods).
2. On the Payment methods page, click the Payment gateways tab to open the section where you select payment gateways:
   
3. Use this section to select the payment methods you have configured in X-Payments:
   First, choose your country of business from the Your country box to ensure that you see only payment gateways available for you country:
   
   Then, choose the method you have imported from X-Payments from the list in the Payment gateways selector (Methods imported from X-Payments can be found under the X-Payments payment methods section title):
   
4. Click Add. The payment method will be added.

Now, if you click the Payment methods tab, you will be able to see the newly added payment method in the Payment methods section:

You can check its configuration by clicking the Configure link opposite its name.

Note that for X-Payments payment methods it is not possible to change the configuration using X-Cart's user interface. Should you need to change anything, you will have to make the changes in X-Payments and then import and add the method in X-Cart again.

After the payment method has been added, you need to enable it:

1. Locate the payment method you have added in the list of payment methods. You may need to scroll down the form because new methods are added to the end of the list.
2. Select the check box to the left of the payment method name.
3. Click Apply changes. The payment method will be activated.

You can edit or delete the added X-Payments payment method like any other payment methods in X-Cart.

Enabling iFrame support for One-Step-Checkout

An online store based on X-Cart version 4.1.9 (or later) and connected to X-Payments version 1.0.6 (or later) with one of the latest versions of the X-Payments connector can be configured to display the secure X-Payments generated form for entering payment card information directly on the checkout page in X-Cart - as opposed to the mode in which this form is displayed on a separate page. For the buyer everything looks as though they were entering their credit card details within your regular checkout routine. Embedding the form generated by X-Payments into X-Cart's checkout page is made possible by use of iFrame. iFrame integration for X-Cart&X-Payments checkout routines is part of the X-Payments connector functionality, so it is essential that you should use an up-to-date version of the connector to enjoy this feature. Older versions of the connector (released prior to September 2014) do not support the iFrame feature, so if you last updated your X-Payments connector for X-Cart prior to September 2014, or purchased your X-Cart prior to September 2014 and continue to use the built-in X-Payments connector that came with it, you must update your X-Payments connector be able to use the iFrame feature. Newer X-Payments connector versions (released after September 2014) already include support the iFrame feature, but we still recommend updating to the latest connector version available to ensure that your connector has all the latest features and fixes.

Steps to enable displaying the payment card form in iFrame:

1. In your X-Cart store's Admin back end, go to the X-Cart Connector settings page and enable the "Use iframe" option (If you are using an older X-Cart versions, this may be called "Use lite interface").
2. Make sure the "API version" field on the same page is set to "1.2".
3. In your X-Payments Admin back end, go to the Online Store Details page for your store and enable the "lite" template there.

Here's also a video for how to enable the iFrame feature in X-Cart working with X-Payments:

This article can be downloaded as a PDF file