Difference between revisions of "X-Cart:X-Payments Connector"

From X-Cart 4 Classic
Jump to: navigation, search
(→‎Configuring X-Payments Connector)
Line 1: Line 1:
−
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 1.2 verified payment application intended for web stores accepting online credit card payments through background payment gateways.
+
==  Overview ==
−
X-Payments Connector ensures correct implementation of the following tasks:
 
−
* Importing the data on active payment methods from X-Payments to X-Cart;
 
−
* Transferring cart and customer details from X-Cart to X-Payments;
 
−
* Redirecting the customer from X-Cart to X-Payments and back to X-Cart;
 
−
* Synchronizing transaction and order details between X-Payments and X-Cart.
 
  
−
== System requirements ==
+
'''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 1.2 verified payment application intended for web stores accepting online credit card payments through background payment gateways. '''X-Payments''' '''Connector''' ensures correct implementation of the following tasks:
  
−
To successfully install and use the X-Payments Connector add-on module, you must have:
+
* Importing the data on active payment methods from '''X-Payments''' to X-Cart;
 +
* Transferring cart and customer details from X-Cart to '''X-Payments''';
 +
* Redirecting the customer from X-Cart to '''X-Payments''' and back to X-Cart;
 +
* Synchronizing transaction and order details between '''X-Payments''' and X-Cart.
 +
 
 +
==System requirements==
 +
 
 +
To successfully install and use the '''X-Payments''' '''Connector''' add-on module, you must have:
  
 
* Installed copy of X-Cart Gold/Pro v4.3.0 or later;
 
* Installed copy of X-Cart Gold/Pro v4.3.0 or later;
−
* Installed copy of X-Payments v 1.0 or later;
+
* Installed copy of '''X-Payments''' v 1.0 or later;
 
* PHP extensions:
 
* PHP extensions:
  
Line 18: Line 20:
 
:* XML DOM extension (to parse XML data).
 
:* XML DOM extension (to parse XML data).
  
 +
==Configuring '''X-Payments''' '''Connector'''==
  
−
== Installing X-Payments Connector==
+
Before you can start using X-Cart together with '''X-Payments''', you must configure '''X-Payments''' '''Connector'''.
  
−
To install the module:
+
To configure '''X-Payments''' '''Connector''':
  
−
1. Obtain a distribution package for X-Payments Connector by downloading it from the File Area section of your personal Help Desk account at [https://secure.qtmsoft.com/ https://secure.qtmsoft.com/] . The distribution package you need is contained in an archive file x-paymentscon-x.y.z.tgz where x, y and z are the version numbers of the module, which must be the same as the version of the installed copy of X-Cart.
+
1. Log in to the X-Cart Admin area.
  
−
{{Note1|If you do not remember the version of the installed copy of X-Cart, find it in the Summary/Environment info section of the X-Cart Admin area (Administration menu -> Summary). Another way to know the version is to open in a web browser http://example.com/VERSION replacing example.com with the true domain name of your X-Cart installation.}}
+
2. Go to the Modules section (Administration menu -> Modules).
  
−
3. Put the distribution package to the X-Cart root directory on your server or hosting account.
+
3. If not selected, select the check box for '''X-Payments''' '''Connector''' and click Update. This will activate the module.
  
−
* If you use a Windows-based server, or a Unix-based server without terminal access:
+
4. Click on the Configure link for '''X-Payments''' '''Connector'''.
  
−
: a. Decompress the archive with the distribution package to a directory on your system using your favorite compression program (WinZIP or any other archiver with support for TAR files).
+
This will open the '''X-Payments''' '''Connector''' configuration page.
  
−
: b. Use an FTP client to upload all files contained in the archive (retaining the directory structure) to the X-Cart root directory on your server or your hosting account.
+
[[Image:X-paymentsconnector_02.png|640px|center]]
  
−
* If you use a Unix-based server with terminal access:
+
5. Define connection details.
  
−
: a. Use an FTP client to upload the archive with the distribution package to the X-Cart root directory on your server or your hosting account.
+
:* '''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''': A comma-separated list of '''X-Payments''' IP addresses that are used by '''X-Payments''' to send callback requests.
  
−
: b. Decompress the package using one of the following commands:
+
6. Establish mapping rules.
  
−
<pre>gunzip < x-paymentscon-x.y.z.tgz | tar -xvf -</pre>
+
Mapping rules are used to synchronize transaction statuses in '''X-Payments''' with statuses of 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.
  
−
or
+
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".
  
−
<pre>tar -xzvf x-paymentscon-x.y.z.tgz</pre>
+
7. Click the '''Save''' button.
  
−
{{Note1|Make sure you keep the directory structure while unpacking and uploading the distribution package; otherwise some necessary files can be overwritten!}}
+
==Testing the module==
  
−
3. In a web browser, run the installation script http://example.com/install-xpaymentscon.php replacing example.com with the true domain name of your X-Cart installation.
+
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.
  
−
4. Follow the instructions on the screen.
+
[[Image:Xp-test_transaction.gif|322px|center|border]]
  
−
{{Note1|At the first step of the installation wizard, you will be asked to provide Auth code for this X-Cart installation. Auth code is a random code to protect the installation script from unauthorized access. The code was generated during the X-Cart installation, and you received it in an email message after the installation was complete. If you do not have this message and do not remember the code, find it in the Summary section of X-Cart Admin area (Administration menu -> Summary). Another way to know the code is to retrieve the value of the variable $installation_auth_code from the file <tt><xcart_dir>/include/install.php</tt> .}}
+
==Importing '''X-Payments''' payment methods to X-Cart==
  
 +
To be able to use the payment methods defined in '''X-Payments''' you should import information about them from '''X-Payments'''.
  
−
== Configuring X-Payments Connector ==
+
[[Image:Xp-import.gif|480px|center|border]]
  
−
Before you can start using X-Cart together with X-Payments, you must configure X-Payments Connector.
+
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.
  
−
To configure X-Payments Connector:
+
[[Image:Xp-request_result.gif|480px|center|border]]
  
−
1. Log in to the X-Cart Admin area.
+
After you have reviewed the list of available payment methods, click '''Import payment methods'''.
  
−
2.Go to the Modules section (Administration menu -> Modules).
+
{{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 database if you select to import payment methods again.}}
  
−
3. If not selected, select the check box for X-Payments Connector and click Update. This will activate the module.
+
==Adding '''X-Payments''' payment methods==
  
−
4. Click on the Configure link for X-Payments Connector.
+
To be able to use '''X-Payments''' payment methods, you need to add them in X-Cart admin area. Click <u>Settings > Payment methods</u>. Scroll down to the bottom of the page and use the <u>Payment gateways</u> section to add the payment methods you have configured in '''X-Payments'''.
  
−
This will open the X-Payments Connector configuration page.
+
[[Image:Xp-payment_methods.gif|630px|center|border]]
  
 +
Select the required payment method in the selectbox and click '''Add'''. Now the payment method you selected is added to the list of payment methods. Activate it by selecting the check box to the left of the name and clicking '''Update'''.
  
−
[[Image:x-paymentsconnector_02.png|center|640px]]
+
You can [[X-Cart:Payment_Settings#Configuring_and_enabling_payment_methods  | edit it]] like all other X-Cart payment methods.
  
 +
[[Image:Xp-added_method.gif|615px|center|border]]
  
−
5. Define connection details.
+
If you plan to use PayPal as a payment method, you need to follow [index.php?title=X-Payments:PayPal  a few additional steps].
−
 
 
−
:* Store ID: A 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: A comma-separated list of X-Payments IP addresses that are used by X-Payments to send callback requests.
 
−
 
 
−
6. Establish mapping rules.
 
−
 
 
−
Mapping rules are used to synchronize transaction statuses in X-Payments with statuses of 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.
 
  
 
[[Category:X-Cart user manual]]
 
[[Category:X-Cart user manual]]
 
[[Category:X-Cart modules]]
 
[[Category:X-Cart modules]]

Revision as of 18:26, 1 September 2010

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 1.2 verified payment application intended for web stores accepting online credit card payments through background payment gateways. X-Payments Connector ensures correct implementation of the following tasks:

  • Importing the data on active payment methods from X-Payments to X-Cart;
  • Transferring cart and customer details from X-Cart to X-Payments;
  • Redirecting the customer from X-Cart to X-Payments and back to X-Cart;
  • Synchronizing transaction and order details between X-Payments and X-Cart.

System requirements

To successfully install and use the X-Payments Connector add-on module, you must have:

  • Installed copy of X-Cart Gold/Pro 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).

Configuring X-Payments Connector

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

To configure 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 X-Payments Connector and click Update. This will activate the module.

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

This will open the X-Payments Connector configuration page.

X-paymentsconnector 02.png

5. Define connection details.

  • 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: A comma-separated list of X-Payments IP addresses that are used by X-Payments to send callback requests.

6. Establish mapping rules.

Mapping rules are used to synchronize transaction statuses in X-Payments with statuses of 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.

Testing the module

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.

Xp-test transaction.gif

Importing X-Payments payment methods to X-Cart

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

Xp-import.gif

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.

Xp-request result.gif

After you have reviewed the list of available payment methods, click Import payment methods.

Please note that if you have already imported payment methods from X-Payments earlier, all previously imported payment methods will be removed from the database if you select to import payment methods again.

Adding X-Payments payment methods

To be able to use X-Payments payment methods, you need to add them in X-Cart admin area. Click Settings > Payment methods. Scroll down to the bottom of the page and use the Payment gateways section to add the payment methods you have configured in X-Payments.

Xp-payment methods.gif

Select the required payment method in the selectbox and click Add. Now the payment method you selected is added to the list of payment methods. Activate it by selecting the check box to the left of the name and clicking Update.

You can edit it like all other X-Cart payment methods.

Xp-added method.gif

If you plan to use PayPal as a payment method, you need to follow [index.php?title=X-Payments:PayPal a few additional steps].

Retrieved from "https://help.x-cart.com/index.php?title=X-Cart:X-Payments_Connector&oldid=4147"