View source for X-Cart:X-Payments Connector

{{XC_4.4.0}}

==  Overview ==

X-Payments Connector is an add-on module for X-Cart that provides an interface to connect X-Cart to X-Payments, a PA-DSS v 3.x verified payment application intended for web stores accepting online credit card payments through background payment gateways. See more about X-Payments at http://www.x-cart.com/extensions/modules/xpayments.html

==Connecting an X-Cart store to X-Payments v2.1 or later==

===Video tutorial===

Below is a video tutorial on how to connect X-Payments 2.1 or later with X-Cart 4.6.4 or later. The video features the X-Payments connector modules for X-Cart 4.x Classic [http://blog.x-cart.com/x-cart-4.x-connectors-for-xpayments-updated.html released in September 2014].

<youtube>DBofEELRU-s</youtube>

===Connection instructions===

# Log in to the Admin back end of your X-Payments installation and make sure you have everything ready on the X-Payments end:
## In the Online Stores section of X-Payments ('''Settings'''->'''Online stores'''), add and configure an [https://www.x-payments.com/help/X-Payments:Managing_store_connections online store] that will represent your X-Cart store in X-Payments.<br />[[File:xp_online_store_details.png|border]]<br /> 
## In the Payment Configurations section of X-Payments ('''Settings'''->'''Payment configurations'''), add and configure a [https://www.x-payments.com/help/X-Payments:Payment_configurations payment configuration] for this store.<br />[[File:xp_paymconfig_details.png|border]]<br />The payment method for accepting payments via X-Payments will be created from this very configuration. Make sure the payment configuration is active ("Enabled").<br />[[File:xp_paymconfig_enabled.png|border]]<br />
## 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.<br />[[File:xp_assign_paymconfig.png|border]]<br />Make sure the store is active ("Enabled").<br />[[File:xp_online_store_enabled.png|border]]<br />
## 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.
# 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:
## Go to the Modules section ('''Settings'''->'''Modules''') and find the module X-Payments Connector:<br />[[File:xc4_xp_connector_module.png|border]]<br />
## Activate the module as usual:<br />[[File:xc4_xp_connector_module1.png|border]] 
## Click the '''Configure''' button next to the module name to access the module settings.<br />[[File:xc4_xp_connector_module1_1.png|border]]<br />If you see a page like the following, click '''Next''':<br />[[File:xc4_xp_connector_module_configure1.png|border]]<br />Your aim is to get to a page where you can enter your X-Payments configuration bundle:<br />[[File:xc4_xp_connector_module_configure2.png|border]]<br /> 
# 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:<br />[[File:xc4_xp_confbundle2clipboard.png|border]]<br />
# 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:<br />[[File:xc4_xp_connector_module_configure3.png|border]]
To be continued...

==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.''' 

===Video tutorial===

<youtube>BzjCBjxZ4XM</youtube>

===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).

{{Note1| Note: X-Cart versions 4.4.x and later already have the'''X-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 <u>Configure</u> link for the X-Payments Connector module.

This will open the X-Payments Connector configuration page.

: [[File:X-paymentsconnector_02.png]]

5. Define connection details.

:* Copy the value of the '''Configuration bundle''' field from the [[X-Payments:Managing_store_connections#Editing_Online_Store_Details|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 [[X-Payments:FAQ#What_do_I_need_to_put_as_.22Callback_IP.22.3F|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.

: [[File:Xp-test_transaction.gif|322px|border]]

===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'''.

: [[File:Xp-import.gif|480px|border]]

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.

: [[File:Xp-request_result.gif|480px|border]]

After you have reviewed the list of available payment methods, click '''Import payment methods''' and proceed with the next step - [[X-Cart:X-Payments_Connector#Adding_X-Payments_payment_methods | adding and enabling X-Payments payment methods]] in X-Cart admin area.

{{Note1|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 [[X-Cart:X-Payments_Connector#Adding_X-Payments_payment_methods | 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.

{{Note1 | <b>Note</b>: If you are looking to set up <u>PayPal's</u> payment methods via X-Payments in your X-Cart store, please proceed with the <u>[[X-Cart:Adding_and_enabling_PayPal_payment_methods_in_X-Cart | special instructions]]</u> 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 <u>Authorize.Net AIM</u> or <u>PayflowPro</u>, please proceed with the instructions <u>below</u>.}}

{{Note1 | <b>Note</b>: As <u>PayPal</u> requires a special configuration process as noted above, <u>PayPal's</u> 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.}}

# In the Admin area of your X-Cart store, go to the <u>Payment methods</u> page (<u>Settings->Payment methods</u>).
# On the <u>Payment methods</u> page, click the <u>Payment gateways</u> tab to open the section where you select payment gateways:<br />[[File:Payment_gateways453.png]]
# Use this section to select the payment methods you have configured in '''X-Payments''':<br />First, choose your country of business from the '''Your country''' box to ensure that you see only payment gateways available for you country:<br />[[File:Xp_payment_methods1.png|border]]<br />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):<br />[[File:Xp_payment_methods.png|border]]
# Click '''Add'''. The payment method will be added.

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

: [[File:Xp-added_pmethod.png]]
You can check its configuration by clicking the <u>Configure</u> 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:
# 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.
# Select the check box to the left of the payment method name.
# Click '''Apply changes'''. The payment method will be activated.

You can [[X-Cart:Payment_Settings#Configuring_and_enabling_payment_methods  | edit or delete]] the added X-Payments payment method like any other payment methods in X-Cart.

===Enabling iFrame support for One-Step-Checkout===

{{X-Cart:IFrame_One-Step_Checkout_for_X-Payments}}

<noinclude>{{pdf_single}}</noinclude>

[[Category:X-Cart user manual]]
[[Category:X-Cart modules]]
[[Category:X-Cart video tutorials]]