X-Cart:Payment Methods

Video tutorial

X-Cart 4.4or above

Managing Payment Methods

Before going live with your store, you need to define the ways in which you will accept payments from your customers. X-Cart provides a number of payment methods that you can use. Some of them require manual processing of payments by the store administrator, others depend on external online processing services like PayPal, Authorize.Net, 2Checkout, WorldPay, Sage Pay and others. You will need to enable and configure the payment methods that you will use and disable the ones that you won't.

Your store's payment methods can be managed using the 'Payment methods' section of your store's Admin area (In X-Cart versions 4.3.0 and later, this section can be found at Settings menu -> Payment methods; in earlier X-Cart versions, this section is located at Administration menu -> Payment methods). This section contains two dialog boxes - 'Payment methods':

and 'Payment gateways':

(The latter one may contain an additional drop-down box when Subscriptions module is enabled):

The 'Payment methods' dialog box provides controls allowing you to configure, enable and disable payment methods. The 'Payment gateways' dialog box allows you to add payment methods to the list in the 'Payment methods' dialog box.

Configuring and enabling payment methods

Payment methods requiring manual payment processing

By default, displayed in the 'Payment methods' dialog box are the following methods:

• Credit Card,
• Check,
• Gift Certificate,
• Phone Ordering,
• Fax Ordering,
• Money Order,
• C.O.D. (cash on delivery),
• Purchase Order,
• Personal Check,
• Business Check,
• Wire Transfer,
• Government Check,
• Traveler's Check.

All of these methods are methods that require manual processing of payments (manual payment processing is that in which the store administrator receives a customer's payment details and processes the payment him- or herself).

The default 'Credit Card' payment method requires to process credit card payments manually. If you do not intend to process credit card payments manually, learn how to set up payment methods providing online payment processing.

The $store_cc variable in the config.php file must be set to true in case you enable the default 'Credit Card' payment method and intend to process credit card payments manually.

If you wish to use one or more of these "manual payment processing" payment methods, configure and enable them as follows:

1. Select the check boxes to the left of the names of the payment methods that need to be enabled.

2. If you wish, change the method names by editing the respective fields in the METHODS column.

3. If necessary, provide instructions for using the methods (SPECIAL INSTRUCTIONS column). A customer selecting a payment method will see the instructions you provided for that method.

4. Select the type of connection that should be used for each of the payment methods (PROTOCOL column). HTTPS (the secure type of connection) should be selected for all the methods in which you expect sensitive data (like customer's credit card data) to be entered on your web-site and transferred over the Internet. For example, HTTPS should be by all means used for the Credit card method to ensure that your customers' credit card information is encrypted before being transmitted across the Web.

Important: If you decide to use the HTTPS protocol for any of the payment methods that will be available to your customers, make sure you have a valid SSL certificate installed and configured on your web-server and the variable $https_location in config.php is set up properly. For more details please refer to: Configuring HTTPS

5. Select the membership level(s) to which each specific payment method should be available (MEMBERSHIP column). Hold down the CTRL key while clicking your mouse on the names of membership levels to select more than one membership level.

6. If you wish the payment methods to be displayed to your customers in a specific order, assign position numbers to them using the fields in the POS. column.

7. If some of the methods require an additional processing charge, adjust the 'Extra charge' fields for them: enter the money amount to be charged and specify whether the amount is expressed in percent or currency units.

Note: You can specify negative surcharge. In this case this amount will work as a payment discount in the customer area.

8. If some of the shipping methods used by your store presuppose that an order is paid for at the time of delivery, specify, which of the payment methods should be offered as payment options to customers who select such shipping methods. To do so, select the 'Cash on delivery' check boxes for all the payment methods that you wish to be offered as payment options for 'COD' shipping methods. Please specifically note that payment methods marked as 'Cash on delivery' will be used only for shipping methods with COD and will not appear in the list of payment methods available for an order unless the shipping method selected by the customer is marked 'COD'.

9. Click the Update button at the bottom of the dialog box to save the changes.

Please note that payment method names and special instructions can be defined in each of the languages used by your store. The language displayed in the Language selector box at the top of the 'Payment methods' dialog box determines the language in which the names and instructions are created. To create payment method names and instructions in a different language, select the desired language from the Language selector, edit the METHODS and SPECIAL INSTRUCTIONS fields and click Update.

Payment methods providing online payment processing

Besides payment methods that require manual payment processing, X-Cart supports a number of payment methods providing online payment processing (methods in which payments are processed automatically by payment systems external to X-Cart). Methods providing online payment processing are initially not on the list of methods displayed by the 'Payment methods' dialog box, but can be added there. After being added to the list of payment methods, each payment method requiring online processing needs to be configured and enabled.

To add a payment method providing online payment processing to your list of payment methods, you need to scroll down to the 'Payment gateways' dialog box at the bottom of the page and use it to select the payment gateway or system through which the processing will be performed.

The names of selectable payment processors are contained in drop-down boxes. There may be one or two drop-down boxes with names of payment processors, depending on whether X-Cart's Subscription module is enabled or disabled. (The drop-down box labeled 'Payment gateways' is displayed at all times, and you should use it to select credit card processors, check processors, direct debit processors or payment systems like PayPal or Nochex. The drop-down box labeled 'Subscription processor' is only displayed when Subscriptions module is enabled, and it should only be used to select processors for subscription payments).

After selecting a desired payment processor, you need to click the button that will add the respective payment method to the 'Payment methods' list (Add or Continue, whichever one is displayed next to the drop-down box from which you performed the selection). The payment method will be added to the bottom of the list in the 'Payment methods' dialog box.

To configure a payment method providing online payment processing, you need to adjust the usual payment method configuration fields provided by the 'Payment methods' dialog box (PROTOCOL, MEMBERSHIP, etc) and to provide the information needed by X-Cart software to use the required payment processing API. The said information can be provided through the configuration page of the respective payment processor. A payment processor's configuration page becomes accessible through the link Configure after you add the payment method to the 'Payment methods' list.

Please note that some payment gateways (like Authorize.Net, 2Checkout. Version 2, PayPal, etc) can be set up to work in test or in live mode. Live mode is the mode in which a payment gateway normally works. In live mode, all payment transactions are real, and money actually changes hands. Test mode is provided for the purpose of testing. In test mode, payment gateways work the same way as in live mode, with the exception that no actual payments are made. The mode of operation of a payment processor (test or live) can be selected, where available, on the payment processor's configuration page.

Payment methods providing online processing are enabled in exactly the same way as methods using manual processing: you select the check box to the left of the name of a payment method that needs to be enabled and click the Update button at the bottom of the 'Payment methods' dialog box.

Note: If you choose a payment method providing online credit card payment processing and do not intend to process credit card payments manually, you should disable the default "Credit Card" payment method, that requires manual payment processing. Additionally, you can change the default "Credit Card" payment method's name to "Credit Card (offline)", and change the online payment method's name to "Credit Card". This will help you to avoid any confusion between these two payment methods.

The $store_cc variable in the config.php file must be set to false in case you disable the default 'Credit Card' payment method and do not intend to process credit card payments manually.

Note: If you use any online payment methods, make sure you do not close access to the <xcart_root>/payment directory by your .htaccess file. In case access to this directory is closed, when an external server of a payment gateway tries to send a callback to X-Cart, it gets an "access denied" reply. As a result, the order will never be processed.

Information on configuring the most popular payment methods used with X-Cart is available is the Most Popular Payment Methods Supported by X-Cart section of this manual.

Disabling payment methods

If you wish, you may temporarily disable use of any of your payment methods by customers. To disable a payment method, unselect the check box next to its name in the 'Payment methods' list and click the Update button at the bottom of the list.

Deleting payment methods

Methods providing online payment processing that you once added to the 'Payment methods' list but no longer wish to use can be deleted. To delete a payment gateway from the list of methods, click on link Delete next to its name.

Credit Card Types

Note: This section is not available in X-Cart 4.5.0 and newer versions, as all on-site (background) payment methods have been removed from X-Cart to meet PCI-DSS compliance.

If your store is going to accept credit card payments (no matter whether you will use manual or online payment processing), you need to make sure that every type of credit cards that you wish to allow your customers to use at your store is on the list of credit card types supported by your store. The list of credit card types supported by your store is provided in the 'Edit Credit Card Types' section (In X-Cart versions 4.3.0 and later, this section can be found at Settings menu -> Credit card types; in earlier X-Cart versions, this section can be found at Administration menu -> Credit card types).

After you install X-Cart, this list already includes the most popular credit card types, so you just need to ensure that everything is in place.

The columns provide the following information about each credit card type:

• CARD CODE - Code of the credit card type.
• CARD TYPE - Name of the credit card type.
• CVV2 - Whether CVV2 is required for the credit card type or not.

If necessary, it is possible to add new credit card types to the list, modify the credit card types in the list or delete selected credit card types from the list.

To add a new credit card type to the list of credit card types supported by your store:

1. In the 'Add credit card type' subsection of the 'Edit Credit Card Types' form enter the card code and the card type.
2. If the new credit card type requires CVV2, select the appropriate check box.
3. Click the Add new button.

Note: For some credit card types, X-Cart provides a JavaScript-based validation of credit card numbers. This mechanism validates a credit card number entered by a user based on the rules of credit card number formation for specific credit card types. To find out whether such validation is provided for a specific credit card type, see the file check_cc_number_script.js. If you add a new credit card type and need such a validation to be provided for it, too, please be aware that some modifications will need to be made to the file check_cc_number_script.js.

To rename a credit card type or change its CVV2 property:

1. In the 'Edit Credit Card Types' form find the card type you would like to update.
2. Edit the credit card type details. If necessary:
   1. Change the credit type name.
   2. Select/unselect the CVV2 check box.
3. Click the Update button.

To delete a credit card type from the list of credit card types supported by your store:

1. In the 'Edit Credit Card Types' form find the card type you would like to delete.
2. Select the check box next to this credit card type. Use the Check all / Uncheck all links to select/unselect all the boxes on the page.
3. Click the Delete selected button.

Troubleshooting

Customers pay with credit card but payment never gets to payment gateway and orders never get processed (but get queued instead) in X-Cart

Problem: My customers pay with their credit card successively, however their orders never get processed (but get queued instead) in my X-Cart store, and their payment never gets to my payment gateway. How do I solve the problem?

Solution: There is a default "Credit Card" payment method available in X-Cart. This default payment method requires to process credit card payments manually. If you have this payment method enabled in your X-Cart store, all orders payed via this payment method will be queued, and require manual processing of payments afterwards.

If you do not intend to process credit card payments manually, you may need to disable the default "Credit Card" payment method and set up a payment method providing online payment processing instead.

Additionally, you can change the default "Credit Card" payment method's name to "Credit Card (offline)", and change your online payment method's name to "Credit Card". This will help you to avoid any confusion between these two payment methods.