X-Payments:User manual

From Qualiteam Help

Jump to: navigation, search

Contents

Introduction

X-Payments is a PA-DSS certified web-based payment application designed for merchants who accept credit card payments using background payment gateways listed in Appendix A and who require compliance with the PCI DSS standard. X-Payments can be used together with major shopping carts including:


While processing credit card payments, X-Payments works as an intermediary between a store on one side and payment gateways and 3D-Secure systems on the other side. See detailed explanation at X-Payments:How It Works and the diagram below.

File:Xpayments_dataflow.png

Since October 11, 2013, X-Payments version 2.0 is available that is certified to the latest version of PCI Council’s standard, PA-DSS 2.0. On the list of PA-DSS certified applications on the PCI Council website, X-Payments 2.0 is listed as "X-Cart Payments":

With X-Payments 2.0 you can:

  • Accept credit card payments from your customers via online payment gateways.
  • Make your online store compliant with the PCI DSS standard which strictly recommends using only PA-DSS validated payment applications for accepting and handling credit card payments.
  • Use "stored" credit card information for new orders, re-orders or recurring payments.
  • Retain total control over the checkout process and avoid risky redirects by incorporating an iFrame credit card form in the store's checkout window.

X-Payments v1.0, the predecessor of X-Payments 2.0, is certified by PA-DSS 1.2 that expires in October 2013. Those who installed and started using X-Payments v1.0 can just continue doing so for any time ahead as it is acceptable for existing deployments. New deployments of X-Payments v1.0 are not allowed after October 28, 2013 due to the PCI Council regulations for PA-DSS certified applications, and we have already stopped selling this version.



Below are a few videos to give you a better idea of how X-Payments works:

X-Payments v2.0 checkout forms in action:




See how customers can save their credit cards for future orders in X-Cart integrated with X-Payments 2.0


How to make new orders for phone and returning customers



How to configure and sell subscriptions with X-Cart and X-Payments

Installation

This section provides information about installing X-Payments.

  • See the section "System Requirements" for a list of system requirements that need to be met before you try to install X-Payments software.
  • Study "Installing X-Payments" for detailed instructions on installing X-payments.
  • Check out "Getting Started" for instructions on how to begin using the software

System Requirements

See X-Payments:System requirements page.

Installing X-Payments

Video tutorial

Procedure

1. Download the X-Payments distribution package x-payments-x.y.z.tgz from the File Area section of your Qualiteam Account (x, y and x stand for the X-Payments version).

2. Decompress the archive to a web accessible directory on your server or your hosting account.

3. Make sure file permissions are adjusted correctly: X-Payments:Setting up file permissions for X-Payments

4. Create a copy of the file config.ini-dist.php with the name config.ini.php and open the file config.ini.php in a text editor.

5. In config.ini.php, set values for the following variables:

[mysql]
  • server="DNS name or IP address of your MySQL server" (for example, localhost or 127.0.0.1)
  • port="MySQL server port (optional)"
  • unix_socket="MySQL server socket (optional)" (for example, /tmp/mysql-5.0.51.sock)
  • dbname="MySQL database name"
  • user="MySQL server username"
  • password="MySQL server password"
[mail]
  • from="Email address for the field "From""
  • host="SMTP server, e.g. mail.localhost or ssl://yourmailserver.domain for TSL/SSL SMTP support"
  • port="SMTP port, e.g. 25"
  • user="SMTP username"
  • password="SMPT password"
  • auth="LOGIN/CRAM-MD5/DIGEST-MD5" (SMTP authentication must have one of the following values: LOGIN , CRAM-MD5, DIGEST-MD5)
  • timeout="10" (SMTP server timeout in seconds)
[location]
[proxy]
  • proxy="Proxy server to send http/https requests (used by cURL)"
Note: To avoid incorrect parsing of configuration data it is strongly recommended to enclose all passwords, paths and other data in double quotation marks. If the data itself contains double quotation marks or a backslash, put a backslash before them, like this: \" or \\

6. Make sure the file config.ini.php is not writable by web scripts.

7. Using a web browser, run the installation script install.php, e.g. https://www.example.com/xp/install.php, and follow the instructions on the screen.

Note: IMPORTANT: Once the installation is complete, you will receive an email notification at the email address that you specified during the installation. The notification includes a link to the email address validator. Click on the link, and you will be able to login to the X-Payments back-end.

8. IMPORTANT. Default codes contained in <lib/XPay/Model/Codebook.php> must be changed after the installation is done. Use maintenance script regen-codebook.php to generate a new codebook.

Running the cron.php script

X-Payments provides a script cron.php which must be executed from the command line. You can use this script to launch execution of periodic service tasks required for the correct operation of X-Payments. For example, this script removes cardholder data for orders that no longer need to be stored. It is recommended to launch this script using your favorite scheduling program (for example | cron daemon in Unix/Linux systems) once a day.

Recommended setup for running the cron.php script via crontab:

0 0 * * * cd /full/path/to/xpayments ; /path/to/php/bin -f /full/path/to/xpayments/cron.php

  • 0 0 * * * - to run the script every day
  • cd /full/path/to/xpayments - to change dir to X-Payments folder on your server
  • /path/to/php/bin - path to PHP 5.3 CLI binary on your server
  • -f - to execute /full/path/to/xpayments/cron.php script


Important: To run the script cron.php, you must use the command line interface. If the script is run not in the command line interface (for example, if you try to run it in your browser window), its execution will be interrupted for security reasons.

Getting started

To begin accepting payments using X-Cart with X-Payments:

  1. Install X-Payments.
    Note: Installation of X-Payment is not needed if you are using X-Payments Hosted solution.
  2. Log in to the X-Payments back end.
  3. Go to the ' General settings' page and adjust the general settings and preferences for your X-Payments installation.
  4. On the ' Payment Configurations' page, configure and enable one or more payment modules you want to use.
  5. On the ' Online Stores' page, add your X-Cart store to the list of online stores that you will use with X-Payments and enable it. On the 'Online store details' page for your X-Cart store, be sure to specify the payment configurations that you will use with this specific store (NB: You will not be able to connect the store to X-Payments without it).
  6. Open the details of your X-Cart store for viewing and copy or make note of the connection details needed to connect your X-Cart store to X-Payments: the configuration bundle, store ID and a set of encryption keys.
  7. Connect your X-Cart store to X-Payments. For this you will need to enable and configure the X-Payments Connector module in your X-Cart store. X-Payments Connector is available as a built-in module in X-Cart versions 4.4.0 and later. If you are using an earlier X-Cart version, you will need to download and install X-Payments Connector as an add-on module.
  8. Import payment methods from X-Payments to X-Cart.
  9. Add and enable X-Payments payment methods in X-Cart.
  10. To be able to use 3D-Secure payer authentication service (Verified by VISA, MasterCard Secure Code), configure CardinalCommerce module in X-Payments.
  11. If you are going to grant access to the X-Payments back end to other users, go to the ' Users' section and create new user accounts.
    It is impossible to create another user with full administrator privileges. Such operations as managing users and managing encryption keys are available only to the root admin user, the one whose profile was created during the installation.
  12. If you are going to store cardholder data, generate cardholder data encryption keys.

If you are using a different type of shopping cart:


Configuring X-Payments

To configure X-Payments, use the following items under the Settings menu in the X-Payments back end:

  • General settings
  • Online stores
  • Payment configurations
  • 3-D Secure settings
  • Encryption keys
Note: Non-root X-Payments users may not be able to see some or all of the above listed menu items if they do not have the respective access permissions.

General Settings

See X-Payments:General settings page.

Online Stores

X-Payments needs to be provided with information about the online stores that you wish to use with it. This can be done via the 'Online Stores' page (Settings -> Online stores) in the X-Payments back end. Here you can add new stores, enable/disable existing stores, view/edit the stores' details and delete the stores you no longer wish to use with X-Payments.

Adding an Online Store

To start using a new store with X-Payments, you must add this store to the list of your online stores in the X-Payments back end.

To add a new store:

  1. In the X-Payments back end, go to the 'Online Stores' page (Settings -> Online stores).
  2. Click the Add new button. The 'Add new online store' section opens.
  3. Complete the following fields:
    • Store name: Enter a short name by which this online store will be identified in X-Payments. This name will be used on the 'Payment Configurations' and 'Payments' pages.
    • Order prefix: Enter a prefix that will help you to distinguish orders from this online store from other orders in the payment gateway backoffice. The value entered into this field will be used as part of Reference ID for transactions originating at this store.
      Note: A full transaction Reference ID consists of the online store prefix, the payment configuration prefix and the reference ID (for example, the order ID).
    • Template: Specify the template that should be used for the page where the customers of this online store will enter payment information.
    • Payment configurations: If you have already set up the payment configurations that should be available for orders in this online store, assign them to this store by selecting the respective check boxes. If the required payment configurations have not yet been set up, just leave this field as is - you will be able to save the new store without a payment configuration assigned (the store will be marked 'Not configured'); just be sure to assign a payment configuration before connecting the store to X-Payments.
  4. Click Save. The online store is created.
    After you have clicked Save, the page will refresh and you will see the 'Online Store Details' page with the details of the online store you have just added. You can use this page to edit the information you have provided at the previous step and/or obtain the information needed to connect the store in question with X-Payments (i.e. the configuration bundle, store ID and encryption keys; see the instructions for connecting your specific type of online store for more information). Note that when you first add a store in X-Payments, it is added with the Disabled status; before you can get paid by the customers of this store via X-Payments you will need to enable it.

Connecting an Online store

Online Stores List

Online stores added to X-Payments can be viewed and managed on the 'Online Stores' page (Settings -> Online stores). On this page you can see your online stores as a list:

For each store on the list you can see its current status: Enabled or Disabled; stores that have been saved without a payment configuration assigned are marked Not configured (This can be corrected by editing the store's details).

On this page you can:

  • Open the details of a specific store for viewing/editing;
  • Enable/disable stores;
  • Delete stores.

Viewing an Online Store's Details

To view the details of a specific store, click on its name in the list. The 'Online store details' page opens showing all the information related to the store:

On this page you can:

  • View/edit the store's details;
  • Enable/disable the store;
  • Delete the store.

Note the following important pieces of information that can be obtained on this page:

  • Encryption Keys: These are used to ensure the security of communication between your store and X-Payments.
    The standard set of encryption keys for each store includes the following:
    - the public key used to encrypt data sent to X-Payments from the store;
    - the private key used to decrypt data sent from X-Payments to the store;
    - the private key password used to decrypt the private key.
    To view or re-generate the store's encryption keys, use the View online store encryption keys link at the top of the 'Online Store Details' page.
  • Store ID and Configuration bundle: These values are generated automatically when you add a new store to X-Payments. They are needed to poperly connect X-Payments to your store. The store ID allows X-Payments to correctly identify requests coming from your store. The configuration bundle is a string that contains a set of X-Payments connection settings.

Enabling/Disabling an Online Store

To enable/disable an online store, do one of the following::

  • On the 'Online Stores' page:
    X-Payments 1.0: Click the [ enable ] / [ disable ] link opposite the store name:

    X-Payments 2.0: Click the button dropdown element opposite the store name and select the required action (Enable / Disable) from the menu:

  • On the 'Online store details' page:
    X-Payments 1.0: Click the [ enable ] / [ disable ] link below the 'Store name' field:

    X-Payments 2.0: Click the button dropdown element near the 'Store name' field or at the bottom of the page and select the required action (Enable (and save)/Disable (and save)).

Editing an Online Store's Details

To edit information about an online store:

  • On the 'Online Store Details' page:
    Edit the contents of any editable fields and click Save.

Deleting an Online Store

To delete an online store, do one of the following:

  • On the 'Online Stores' page:
    X-Payments 1.0: Click the delete icon File:Xp-14_x_button.gif opposite the store name. Confirm the deletion.
    X-Payments 2.0: Click the button dropdown element opposite the store name and select the required action (Delete store) from the menu. Confirm the deletion.
  • On the 'Online store details' page:
    X-Payments 1.0: Click the Delete store link at the bottom of the page:

    Confirm the deletion.
    X-Payments 2.0: Click the button dropdown element near the 'Store name' field or at the bottom of the page and select the required action (Delete store).

    Confirm the deletion.

Payment Configurations

In order for X-Payments to operate, you must set up at least one payment configuration, enable it and assign it to the online store you are going to use with X-Payments. This can be done on the 'Payment Configurations' page (Settings -> Payment configurations).

Adding a Payment Configuration

To add a new payment configuration, select the name of the required payment module from the drop-down box and click the Add new button.

The 'Add new payment configuration' page opens.

Note that the settings on this page will differ depending on the selected payment module. For instance, here's the 'Add new payment configuration' page for AuthorizeNet.AIM:

File:XP2.0_authorizenet_aim.png

Basically, what you need to do is get the information from your payment gateway merchant account back end and enter it on this payment configuration page in X-Payments. When you're done, be sure to click Save to save the payment configuration. After this the payment configuration is added to the list of available payment configurations on the 'Payment Configurations' page (Settings -> Payment configurations) and can be assigned to specific online stores.

Find more information on setting up the following payment configurations:

Payment Configurations List

Payment configurations that have been added in your X-Payments installation can be viewed and managed on the 'Payment Configurations' page (Settings -> Payment configurations). On this page you can see the list of available payment configurations:

For each payment configuration on the list you can see the name of the payment module employed, the number of submitted payments and the current status of the payment configuration (Enabled or Disabled). Payment configurations set to work in test mode are marked with the "test" icon.

X-Payments 2.1: Payment configurations that support 3-D Secure payer authentication are marked as such: the ones that use 3-D Secure via Cardinal Commerce have the link "3D Secure: CardinalCommerce" next to their name (the link leads to a page where 3-D Secure settings for the respective payment configuration can be adjusted); the ones that rely on the 3D Secure solution provided by the payment gateway are marked by the words "3D Secure: Built in". For each payment configuration supporting 3-D Secure transactions there's an icon showing the current status of 3-D Secure payer authentication service (Enabled or Disabled).

X-Payments 2.1: Payment configurations that support KOUNT Antifraud screening are marked as such. The Configure link allows you to access the KOUNT Antifraud screening settings page for the respective payment configuration. For each payment configuration supporting KOUNT there's an icon showing the current status of the antifraud screening service (Enabled or Disabled).

On 'Payment Configurations' page you can:

  • Open the details of a specific payment configuration for viewing/editing;
  • Enable/disable payment configurations;
  • Delete payment configurations;
  • X-Payments 2.1: Access the CardinalCommerce 3D-Secure configuration settings page and the KOUNT Antifraud screening settings page for any payment configuration that supports these services.

Assigning a Payment Configuration to an Online Store

A payment configuration added and configured in X-Payments can be assigned to a specific store using one of the following methods:

  • Via the 'Online store details' page:
  1. Open the details of the store to which you wish to assign a payment configuration for viewing/editing.
  2. In the Payment configurations box, select the payment configuration that needs to be assigned.
  3. Click Save.
  • Via the 'Payment configuration details' page:
  1. Open the payment configuration's details page for viewing/editing.
  2. In the Use in online stores box, select the store to which the payment configuration needs to be assigned.
  3. Click Save.

Viewing a Payment Configuration's details

To view the details of a specific payment configuration, click on its name in the 'Payment Configurations' list. The 'Payment configuration details' page opens showing all the information related to the payment configuration.

On this page you can:

  • View/edit the details of the payment configuration;
  • Enable/disable the payment configuration;
  • Delete the payment configuration.

Enabling/Disabling a Payment Configuration

To enable/disable a payment configuration, do one of the following:

  • On the 'Payment Configurations' page:
    X-Payments 1.0: Click the [ enable ] / [ disable ] link opposite the payment configuration name.
    X-Payments 2.0: Click the button dropdown element opposite the payment configuration name and select the required action (Enable / Disable) from the menu:

  • On the 'Payment configuration details' page:
    X-Payments 1.0: Click the [ enable ] / [ disable ] link below the 'Name' field.
    X-Payments 2.0: Click the button dropdown element near the 'Name' field or at the bottom of the page and select the required action (Enable (and save)/Disable (and save)).

Editing a Payment Configuration's Details

To edit information about a payment configuration:

  • On the 'Payment configuration details' page:
    Edit the contents of any editable fields and click Save.

Deleting a Payment Configuration

To delete a payment configuration, do one of the following:

  • On the 'Payment Configurations' page:
    X-Payments 1.0: Click the delete icon File:Xp-14_x_button.gif opposite the payment configuration name. Confirm the deletion.
    X-Payments 2.0: Click the button dropdown element opposite the payment configuration name and select the required action (Delete configuration) from the menu. Confirm the deletion.
  • On the 'Payment configuration details' page:
    X-Payments 1.0: Click the Delete configuration link at the bottom of the page. Confirm the deletion.
    X-Payments 2.0: Click the button dropdown element near the 'Name' field or at the bottom of the page and select the required action (Delete configuration). Confirm the deletion.

Encryption keys

X-Payments uses two types of encryption keys:

  • "Store" encryption keys;
  • Cardholder data encryption keys.

"Store" encryption keys

Encryption keys of this type ensure the security of communication between X-Payments and the online stores connected to it. They are generated specifically for each online store that needs to be connected to X-Payments and can be found on the '"Store" encryption keys' page ('Online store details' page -> View online store encryption keys link). These keys must be stored securely and re-generated by X-Payments admin regularly, at least monthly. Information on the cryptographic algorithm employed to secure the communication between X-Payments and online stores is available here: Public-key cryptography.

To re-generate "Store" encryption keys, use the Re-generate keys button on the '"Store" encryption keys' page:

Then copy the new encryption codes and paste them into X-Cart in the appropriate fields (Payment Methods → Credit Card → X-Payments connector module settings, see how to configure X-Cart Connector).

For Magento shops - entire configuration bundle for a Magento integrated shop needs to be updated, i.e. copies from Magento shop configuration page at X-Payments admin back-end and pasted&deployed at X-Payments configuration page in Magento admin back-end.

Cardholder data encryption keys

Encryption keys of this type ensure the security of cardholder data stored by X-Payments - when X-Payments is configured to store cardholder data.

If you are going to store cardholder data in X-Payments, after enabling the option Store cardholder data in X-Payments General settings, you will need to have a set of cardholder data encryption keys generated for your X-Payments installation. Unlike "store" encryption keys, cardholder data encryption keys are not displayed anywhere within the X-Payments user interface, so you will not be able to see them. However, you will need to make sure these keys exist in the system and are re-generated regularly. This is really easy because you will have to "tell" X-Payments to generate a set of cardholder data encryption keys only for the very first time; after this, you will be able to configure X-Payments to re-generate the keys automatically once in a set period of time. Re-generation of cardholder data encryption keys will be done as a cron job (based on running cron.php). You will also have the ability to re-generate the keys at any time manually should it be needed. To make sure the keys are actually re-generated at expected times, you will be able to view the encryption key generation history for your X-Payments installation and to configure X-Payments to notify you about such events as upcoming expiration of current cardholder data encryption keys and successful generation of new encryption keys.

In the X-Payments back end, cardholder data encryption keys are managed using the 'Encryption keys' page (Settings -> Encryption keys).

On this page you can:

  • Adjust your cardholder data encryption key preferences (key time-to-live, frequency of re-generation, notifications, etc);
  • (Re)generate cardholder data encryption keys;
  • Find out the current status of cardholder data encryption keys for your X-Payments installation;
  • Re-encrypt stored cardholder data using new encryption keys;
  • Delete outdated encryption keys.


Cardholder data encryption key preferences

The encryption key preferences for your X-Payments installation can be adjusted using the 'Cardholder data encryption keys' section:

  • Key time-to-live (days): Enter the number of days for which cardholder data encryption keys will be valid. After the number of days specified here the keys will expire.
  • Regenerate keys X days prior to key expiration date: Specify how many days before the expiration date you want the encryption keys to be automatically re-generated. This setting is needed so that you will still have time to re-generate your keys if your keys are not re-generated at expected time (for example, if cron fails).
  • Notify Y days prior to the key expiration date: Specify how many days before the expiration of your cardholder data encryption keys you want to be notified about the upcoming key expiration.
  • Notify on key generation: Specify whether you want to be notified when cardholder data encryption keys are re-generated.
  • Send notifications to email: Enter the email address for cardholder data encryption keys expiration notifications. If you fail to provide an email address here, the notifications will only be displayed in the X-Payments Dashboard.


Viewing cardholder data encryption key status

Before any encryption keys have been generated, or after you have removed all active keys, the 'Encryption keys' page displays a message saying that you have no active keys:

If you already have cardholder data encryption keys in the system, the 'Encryption keys' page shows information about the currently stored keys:

For each set of keys the following information is available:

  • time of creation;
  • whether the keys were generated by admin or automatically;
  • key status;
  • time until when the keys will be valid / time when the keys expired;
  • whether there is any stored cardholder data in the system that is encrypted using these keys (Has encrypted data / Has no encrypted data).

Possible key statuses:

  • Active
  • Expired (automatically replaced by new keys after their time-to-live had expired)
  • Canceled (re-generated by admin before the expiration of their time-to-live period)

(Re)generating cardholder data encryption keys

One of the actions that need to be completed to enable X-Payments to store cardholder data is generate cardholder data encryption keys.

To generate new cardholder data encryption keys:

  1. Go to the 'Encryption keys' page in the X-Payments back end (Settings -> Encryption keys).
  2. Click the Generate new keys button.

A new set of cardholder data encryption keys will be generated. You will see a new record with information about the new set of keys added to the list on the 'Encryption keys' page. From this moment the new set of encryption keys will be used to encrypt any new data being saved in X-Payments.

Do not forget to copy the new encryption codes and paste them into X-Cart in the appropriate fields (Payment Methods → Credit Card → X-Payments connector module settings, see how to configure X-Cart Connector).!


Re-encrypting stored cardholder data with new encryption keys

If you already had active cardholder data encryption keys in the system when you re-generated your keys, the status of those keys will be changed to "Canceled". Stored cardholder data that was encrypted using those keys will remain encrypted with those keys. Any data that will be saved after the re-generation of the keys will be encrypted using the new keys. To re-encrypt all stored data using your new keys, click the Reencrypt data button.

Note: The 'Reencrypt data' button is not displayed if there is no encrypted cardholder data.

Removing outdated cardholder data encryption keys

You can remove any cardholder data encryption keys you no longer need. Please note that removing a key set that has encrypted data will result in deleting the encrypted data. To remove a set of cardholder data encryption keys:

  • X-Payments 1.0: Click the Delete icon opposite the set of keys you want to remove.

    Confirm the deletion.
  • X-Payments 2.0: Click the Delete button opposite the set of keys you want to remove.

    Confirm the deletion.



3D-Secure Settings

3-D Secure Payer Authentication gives you Verified by Visa and MasterCard SecureCode. It was designed to secure electronic commerce by providing the ability to conduct fully authenticated electronic payment transactions and to access confidential information safely, securely and privately, minimizing fraud and chargebacks.

X-Payments allows you to use 3-D Secure Payer Authentication service for a number of payment methods that support it:

  1. Such payment solutions as PayPal's Payflow Pro, Cardinal Commerce Centinel, Elavon Payment Gateway, Global Iris/HSBC - RealAuth Remote and Sage Pay Go - Direct Interface provide their own built-in integrated 3-D Secure authentication solutions that can be used with X-Payments;
  2. For many other payment solutions - including but not limited to PayPal Payments Pro, Authorize.Net AIM and CIM, Bean Stream/FirstData Canada, Caledon, CyberSource - SOAP toolkit API - it is possible to use 3-D Secure authentication via CardinalCommerce (X-Payments provides an integrated module for this purpose).

If you are going to use a payment solution that provides a built-in 3-D Secure authentication service, you do not need to set up 3-D Secure in X-Payments: 3-D Secure authentication will work for your payment transactions out of the box. However, if you are going to use 3-D Secure via CardinalCommerce, you will need to configure some 3-D Secure settings in X-Payments.

CardinalCommerce's 3-D Secure is configured differently in different versions of X-Payments. For instructions, see the appropriate section below:



Managing your 3-D Secure system configuration in X-Payments 1.0 or 2.0

To start using CardinalCommerce 3-D Secure payer authentication in X-Payments 1.0 or 2.0:

  1. Sign up for the respective service with CardinalCommerce (CardinalCommerce can be contacted at xpayments@cardinalcommerce.com).
  2. CardinalCommerce 3-D Secure requires X-Payments to temporarily store cardholder data, so make sure that storage of cardholder data has been enabled in the Settings -> General settings section and cardholder data encryption keys have been properly generated.
  3. Add a 3-D Secure system configuration for the CardinalCommerce module.
  4. Enable your CardinalCommerce 3-D Secure system configuration.
  5. Assign your CardinalCommerce 3-D Secure system configuration to the payment configuration for which you want to use 3-D Secure.


To add a 3-D Secure system configuration for the CardinalCommerce module:

  1. On the '3D-Secure Settings' page (Settings -> 3-D Secure settings), click Add new next to New configuration for: CardinalCommerce.

    A page titled 'Add new 3D-Secure configuration' will be opened displaying the dialog box for providing your CardinalCommerce module configuration settings:
  2. Adjust the configuration settings for CardinalCommerce module:
    • Currency: The currency your online store uses to conduct transactions.
    • Test/Live mode: The mode in which you wish to use 3-D Secure (Test or Live).
    • Merchant ID: The MerchantID value provided to you by CardinalCommerce.
    • Processor ID: The ProcessorID value provided to you by CardinalCommerce.
    • Transaction password: The Transaction password provided to you by CardinalCommerce.
    • Transaction URL: The TransactionURL provided to you by CardinalCommerce. The transaction URL for testing purposes is https://centineltest.cardinalcommerce.com:443/maps/txns.asp.
  3. When you are done adjusting all the fields, click Save to save the changes.

That is all, you have just added your 3-D Secure system configuration. Now you need to enable it and assign it to the payment configuration or which you want to use 3-D Secure.

After a 3-D Secure system configuration has been added, you can see it on the '3-D Secure Settings' page:

The following actions are available:

  • View/edit the configuration details;
  • Enable/disable the configuration;
  • Delete the configuration.

To view/edit the details of your 3-D Secure system configuration:

  • On the '3-D Secure settings' page: Click on the name of the configuration (CardinalCommerce). The page showing the configuration details will be opened. If necessary, adjust the settings and click Save.

To enable/disable your 3-D Secure system configuration:

  • On the '3-D Secure settings' page:
    X-Payments 1.0: Click the [ enable ] / [ disable ] link opposite the configuration name.
    X-Payments 2.0: Click the button dropdown element opposite the configuration name and select the required action (Enable / Disable) from the menu.
  • On the '3-D configuration: <configuration name>' page:
    X-Payments 1.0: Click on the 'Configuration is active [ make inactive ] / 'Configuration is inactive [ make active ] link.
    X-Payments 2.0: Click the button dropdown element near the configuration name and select the required action (Enable/Disable).

To delete your 3-D Secure system configuration:

  • On the '3-D Secure settings' page:
    X-Payments 1.0: Click the delete icon File:Xp-14_x_button.gif opposite the configuration name.
    X-Payments 2.0: Click the button dropdown element opposite the configuration name and select the required action (Delete configuration) from the menu.
  • On the '3-D configuration: <configuration name>' page:
    Click on the Delete configuration link at the bottom of the page. Confirm the deletion.

To assign your 3-D Secure system configuration to a payment configuration:

  • Locate the payment configuration to which you want to assign your 3-D Secure system configuration, open its details for viewing|editing, enable the option Use external module (CardinalCommerce) and save the changes.
    Note: The setting 'Use external module (CardinalCommerce)' appears on the payment configuration page only after steps 1-3 of the 'add a 3-D Secure system configuration' procedure have been properly completed.



Managing your 3-D Secure system configuration in X-Payments 2.1

To start using CardinalCommerce 3-D Secure payer authentication in X-Payments 2.1:

  1. Sign up for the respective service with CardinalCommerce (CardinalCommerce can be contacted at xpayments@cardinalcommerce.com).
  2. CardinalCommerce 3-D Secure requires X-Payments to temporarily store cardholder data, so make sure that storage of cardholder data has been enabled in the Settings -> General settings section and cardholder data encryption keys have been properly generated.
  3. Add and enable 3-D Secure for each payment configuration in your X-Payments installation that needs to use 3-D Secure via CardinalCommerce.
  4. In the details of all the online stores that will be using your 3-D Secure enabled payment configuration, specify the template that should be used for the 3-D Secure payer authentication step.


To add and enable 3-D Secure for a payment configuration:

  1. Go to the 'Payment Configurations' page (Settings -> Payment configurations) and locate the payment configuration for which you want to enable 3-D Secure payer authentication via CardinalCommerce. Click on the "3-D Secure: CardinalCommerce" link for this payment configuration. For example, if we want to configure 3-D Secure payer authentication for Authorize.Net AIM, we need to select this link:

    A page titled 'CardinalCommerce 3D-Secure configuration settings' opens:
  2. Use the 'CardinalCommerce 3D-Secure configuration settings' page to provide your CardinalCommerce module configuration settings for the selected payment configuration:
    1. Adjust the following fields:
      • Merchant ID: The MerchantID value provided to you by CardinalCommerce.
      • Processor ID: The ProcessorID value provided to you by CardinalCommerce.
      • Transaction password: The Transaction password provided to you by CardinalCommerce.
      • Test/Live mode: The mode in which you wish to use 3-D Secure (Test or Live).
      • Transaction URL: The TransactionURL provided to you by CardinalCommerce. The transaction URL for testing purposes is https://centineltest.cardinalcommerce.com:443/maps/txns.asp.
    2. When you are done adjusting all the fields, click Save to save the changes.
      The 3-D Secure system configuration will be created.
  3. Enable the 3-D Secure system configuration you have created: On the 'CardinalCommerce 3D-Secure configuration settings' page for your selected payment configuration, click the Disabled button located next to the title "Payment configuration: <Payment configuration name> 3-D Secure", and select the action Enable from the button menu:

    This will enable 3-D Secure payer authentication via CardinalCommerce for the selected payment configuration.


The status of 3-D Secure payer authentication service for any payment configuration can be found on the 'Payment configurations' page (Settings -> Payment configurations):

or on the 'Payment configuration details page:

File:3d_secure_status1.png


To disable/re-enable 3-D Secure for a payment configuration:

  1. Go to the 'Payment Configurations' page (Settings -> Payment configurations) and locate the payment configuration for which you want to disable/re-enable 3-D Secure payer authentication via CardinalCommerce. Click on the "3-D Secure: CardinalCommerce" link for this payment configuration. This opens the 'CardinalCommerce 3D-Secure configuration settings' page.
  2. Use the action button located at the top of the page next to the title "Payment configuration: <Payment configuration name> 3-D Secure" to select the action you require (Disable/Enable):


To specify the template that should be used in a specific store for 3-D Secure checks:

  1. Go to the 'Online Stores' page (Settings -> Online stores), click on the name of the store for which you want to set the template that should be used for the 3-D Secure payer authentication step.
  2. On the page that opens, select the template you require from the Template for 3-D Secure check box:
  3. Click Save at the bottom of the page to save the changes.



Kount fraud screening

To help you protect your business against fraud, X-Payments 2.1 provides integration with a powerful fraud detection and prevention solution by Kount. Kount delivers an all-in-one, SaaS model fraud and risk management platform for merchants operating in card-not-present (CNP) environments and looking to root out fraudsters and increase revenue. For each transaction, Kount’s real-time "decisioning" engine analyzes hundreds of relevant variables and activity across the globe. Kount applies a multitude of proven and patented technologies including Multi-layered Device Fingerprinting®, Proxy Piercer® geolocation tools, statistical scoring, rules-based fraud detection, cross-merchant linking, and Persona behavioral modeling. Kount's proprietary technology has reviewed hundreds of millions of transactions and provides maximum protection for some of the world's best-known brands.

For more information or to request a personal demo of Kount, contact Kyle Allred at KBA@Kount.com or call 208-489-2773.

To start using Kount for online payment fraud screening in X-Payments, complete the following steps:

  1. Sign up for a Merchant account with Kount at http://www.kount.com. You will be provided with some credentials that you will need to configure Kount fraud screening in X-Payments: your Merchant ID and your Site ID. Take note of this information.
  2. Go to the desired Kount Agent Web Console (AWC), test or production, and request your Public certificate and Private key. You will need to convert the files to .PEM format and set your private key passphrase. Kount will provide detailed instructions for that.
  3. Upload the public certificate and private key files to the directory <xp-dir>/var/certs/kount/ within your X-Payments installation.
  4. In the AWC, adjust credit card validation rules for your online store.
  5. Log in to X-Payments and locate the payment configuration for which you want to use Kount fraud screening.
  6. Go to the 'KOUNT Antifraud screening settings' page for this payment configuration by clicking the "KOUNT Antifraud screening: Configure" link:
    • On the 'Payment configurations' page (Settings -> Payment configurations) you can find this link here:
    • On the 'Payment configuration details' page it is here:
      File:Kount_configure2.png
  7. Use the 'KOUNT Antifraud screening settings' page for the selected payment configuration to configure your Kount integration module:
    1. Adjust the following settings:
      • Merchant ID: Specify your Merchant ID as was provided to you by Kount.
      • Site ID: Specify your Site ID.
      • Public certificate file name: Specify your public certificate file name.
      • Private key file name: Specify your private key file name.
      • Private key passphrase: Specify your private key passphrase.
      • Test/Live mode: Use this to set the operation mode for Kount fraud screening service - Test or Live. For access to the Kount AWC in Live mode use the address https://awc.kount.net, in Test mode - the address https://awc.test.kount.net.
      • Description of products: Common name of the products sold by your store.
    2. When you are done adjusting all the fields, click Save to save the changes.
  8. Enable Kount fraud screening for the selected payment configuration: On the 'KOUNT Antifraud screening settings' page for your selected payment configuration, click the Disabled button located near the top of the page close to the title "Payment configuration: <Payment configuration name> KOUNT Antifraud screening", and select the action Enable from the button menu:

    Once the button switches to Enabled, Kount screening for the selected payment configuration will be enabled.


Once Kount antifraud screening has been configured and enabled for a specific payment configuraton, any new payment transactions for this payment configuration will be screened by Kount, and you will be able to view the screening results on the Payment details page:


In X-Cart stores, it is also possible to view the results of screening by Kount in the order details via the store's back end. On the order details page, you will need to click the View payment information link:

File:View_payment_info_Kount_results.png

Kount screening results will be displayed in a popup window:



Managing users

X-Payments root admin can create additional user accounts to allow access to the X-Payments back end to other users.

Unlike root admin who has full access to X-Payments functionality, non-root X-Payments users have limited privileges:

  • can edit their own user name, email address and password;
  • can generate PIN codes for personal use;
  • may have access to payment details / cardholder data / subscriptions - if the respective permissions have been given to them by the root admin;
  • may view/edit X-Payments' general settings / online stores list and details / payment configurations / 3D Secure settings - if the respective permissions have been given to them by the root admin;
  • cannot add/manage other user accounts;
  • cannot access cardholder data encryption keys.

Adding a New User Account

To add a new user account:

  1. In the X-Payments back end, go to the 'Users List' page (Settings -> Users).
  2. Click the Add user button. The 'Create new account' page opens.
  3. Complete the following fields:
    • User name: Enter a name by which the user will be identified in X-Payments.
    • Email: Enter the user's email address. This will be used for various notifications as defined on the 'General settings' page.
    • Expiration date: If you want the user account to be automatically deactivated after a certain period of time, enter the account expiration date; for example, Sep 10, 2010. After this date the account will be locked with the status Locked due to account expired. You will be able to unlock the user by changing the account expiration date. You can leave the field empty to create an account that never expires. It is possible to enable email notifications for users whose account is about to expire (See the 'Account expires' setting in 'General settings/Email Notifications').
    • Inactivity period: Enter the number of days of account inactivity (not logging in, etc) after which the account will be locked. After the specified number of days of inactivity the user account will be locked with the status Locked due to account inactivity. Recommended values are 1 to 90; if a number outside this range is used, the defined 'Inactivity period' value will be ignored, and the account will be locked automatically after 90 days. Inactivity period is counted from the moment the user last logged in or, if the user never logged in, from the time of account creation. It is possible to enable email notifications for users whose account is about to be locked due to user inactivity (See the 'Account is locked due to user inactivity' setting in 'General settings/Email Notifications').
    • Permissions: Set user permissions for the user account being created by selecting the sections of the X-Payments back end to which you want the new user to have access.
    • Note: (Optional) Enter a comment for yourself regarding the user account being created. The comment will not be visible to the user.
  4. Click Save changes. The user account is created. An email notification is sent to the account owner.
    After you have clicked Save changes, the page will refresh and you will see the 'Account details: <user name>' page with the details of the user account you have just added. You can use this page to edit the account details.

Note that after a user accounts is created, it needs to be activated by the account owner. User accounts that have not yet been activated have the status Waiting for email activation. To activate their newly created user account, a user must use the account activation link provided in the 'account created' notification message sent to their email address. After clicking on this link the user will be prompted to set their password for access to the X-Payments back end. After successful account activation, the status of the user account in X-Payments will be updated to Active.

Users List

Existing user accounts can be viewed and managed on the 'Users List' page (Settings -> Users):

For each user account on the list you can see its current status. The possible account statuses are as follows:

  • Full permissions: This is the permanent status used for the X-Payments root admin. It cannot be changed nor assigned to any other user in X-Payments.
  • Active: This is the normal working status of a user account; it means that the user can log in to the X-Payments back end and perform actions within the permissions scope defined by their account details. The 'Active' status is set for all user accounts automatically after account activation / email address change confirmation by the user; it can also be assigned to a user account manually by the root admin after the account was locked (see the instructions for changing the account status below).
  • Waiting for email activation: This is an automatic status; it is used for newly created user accounts before account activation by the account owner.
  • Waiting for email verification: This is an automatic status; it is used for user accounts for which registration email address has been changed by the X-Payments root admin, but the change has not yet been confirmed by the account owner.
  • Waiting for password recovery: This is an automatic status; it is used for user accounts for which password recovery has been requested.
  • Locked due to account inactivity: This is an automatic status assigned to a user account after the expiration of the account inactivity period, as provided by the user account details (see the instructions for Changing a User's Account Status).
  • Locked due to danger activity: This is an automatic status temporarily assigned to a user account for which repeated failing login attempts are detected (related to the 'Dangerous activity blocking period (minutes)' option in X-Payments General settings).
  • Locked due to account expired: This is an automatic status assigned to a user account after the account expiration date, as provided by the user account details. To unlock a user account in this state, X-Payments root admin must change the 'Expiration date' value in the account details.
  • Locked by administrator: This is a status that can be used to temporarily disable a user account; it can be set manually by the X-Payments root admin (see the instructions for Changing a User's Account Status).

On this page you can:

  • Open the details of a specific user account for viewing/editing;
  • Lock active user accounts / unlock user accounts with the Locked by administrator, Locked due to danger activity and Locked due to account inactivity status;
  • Delete user accounts.

Viewing a User's Account Details

To view the details of a specific user account, click on the user name in the Users List. The 'Account details: <user name>' page opens showing all the information related to the user account:

On this page you can:

  • View/edit the user account details (user name, email address, expiration date, inactivity period, user permissions, etc);
  • Change the user account status (lock the account if it is active / unlock the account if it is locked);
  • Delete the user account.

Editing a User's Account Details

The 'Account details: <user name>' page allows you to edit the details of a specific user account.

To edit such details as user name, expiration date, inactivity period, user permissions and comment about the user, simply edit the contents of the respective fields and click Save.

To change the user's email address:

  1. Click on the 'Change user email' link:
    File:XP2.0_change_user_email_link.png
    The 'Change user email' box will be expanded providing a field where you can enter a new email address:
    File:XP2.0_change_user_email_box.png
  2. Use the New e-mail field to enter a new email address.
  3. Click Change.
    After you click the Change button, a notification will be sent to the email owner with a confirmation link. The user will need to click on this link to confirm the change of the email address. The email address stored in the user account details will be updated only after the confirmation. Until that time the email address in the user's account details will be displayed like so:
    <old email address>
    will be changed to <new email address>

Changing a User's Account Status

The current status of a user account is visible on the 'Users List' page:

and on the 'Account details: <user name>' page:

To change the status of a user account, do one of the following:

  • On the 'Users List' page:
    X-Payments 1.0: Click the [ lock ] / [ unlock ] link opposite the user name:
    File:Xp-33_active_user.gif
    X-Payments 2.0: Click the button dropdown element opposite the user name and select the required action (Lock / Unlock) from the menu:

  • On the 'Account details: <user name>' page:
    X-Payments 1.0: Click the Lock account / Unlock account button below the account status:
    File:Xp-29_lock_user.gif
    X-Payments 2.0: Click the button dropdown element at the bottom of the page and select the required action (Lock account/Unlock account):

Requesting Password Change for a User Account

There may be times when you will want to request that one or more users of your X-Payments installation change their X-Payments password(s).
To request password change:

  • On the 'Account details: <user name>' page:
    X-Payments 2.0: Select the Force to change password on next login check box and click Save changes.

Deleting a User Account

To delete a user account, do one of the following:

  • On the 'Users List' page:
    X-Payments 1.0: Click the delete icon File:Xp-14_x_button.gif opposite the user name. Confirm the deletion.
    X-Payments 2.0: Click the button dropdown element opposite the user name and select the required action (Delete account) from the menu. Confirm the deletion.
  • On the 'Account details: <user name>' page:
    X-Payments 1.0: Click the 'Delete account' link:

    Confirm the deletion.
    X-Payments 2.0: Click the button dropdown element at the bottom of the page and select the required action (Delete account). Confirm the deletion.

Managing PIN-codes

X-Payments provides a reliable level of user authentication: to be able to log in to the X-Payments back end, a user needs not just a login and password, but also an additional value - a PIN code.

A set of PIN codes is generated for each X-Payments user account at the time of account creation. After installing X-Payments, the administrator receives an email message that includes five PIN codes. These can be used to log in to the X-Payments back end for the first few times. When the administrator feels they are about to run out of available PIN codes, he or she can log in to the X-Payments back end and order a new PIN codes set to be generated (See the instructions below). Other X-Payments users receive their PIN codes in a similar way: when a new user account is created, the PIN codes list is mailed to the email address associated with that account. When the user needs more PIN codes, they can log in to X-Payments and generate more.

A standard X-Payments PIN codes set includes 100 codes, each of which can be used only once. PIN codes must be used in the specified order, according to their numbers. If you enter an incorrect PIN code on login, you will be offered to try again, and X-Payments will request the same PIN code number until you enter it correctly.

When you have used all but five last PIN codes from your PIN codes table, a reminder for you to generate new PIN codes will be displayed on the Dashboard in X-Payments while you are logged in:

Generating PIN codes using the X-Payments interface

When you are about to run out of PIN codes for logging in to the X-Payments back end, log in to X-Payments using one of the PIN codes you still have and generate a new PIN codes table.

To generate a new PIN codes list, do the following:

  1. In the X-Payments back end, go to your 'Account details' page.
  2. Click the Generate PIN codes button.
    File:XP2.0_view_generate_PIN_codes.png
    A new set of PIN codes for your account will be generated (You will see a success message at the top of the page).
  3. Click the View PIN codes link. A table with your PIN codes list will be displayed.
  4. Choose how you would like to save your PIN codes by clicking the respective button below the table:
    • Print
    • Save as picture...
    • Save as text...
  5. Follow the instructions on the screen to save the PIN codes.

Generating PIN codes using the script pin.php

It is impossible to generate PIN codes for another user using the X-Payments interface, but you can do so by running a special script. You will need to specify the email address of the X-Payments user for whom the PIN codes will be generated.

Note: This method can be used by the X-Payments admin to generate five PIN codes for himself as well.

To generate PIN codes using this method, open the console and enter:

<path to PHP interpreter> php pin.php user@example.com

(Be sure to enter the actual path to PHP interpreter and replace user@example.com with the email address of the user who needs PIN codes).

After the script completes, five PIN codes will be sent to the specified email. After logging in to X-Payments, the user will be able to generate a complete PIN code table.

Customizing the Interface

This section contains information on customizing the page where customers enter their credit card information.

IMPORTANT: X-Payments has a protection mechanism that allows it to detect modifications made to the template files of the page where customers enter cardholder data. This mechanism ensures that the page is not modified/tampered with without X-Payments administrator knowing. After any modifications have been made to X-Payments templates, the administrator is notified with a message in the Dashboard and checkout form stops working. To approve the changes and enable X-Payments checkout form, login as main administrator user and click the "Approve" link which appears in the message at the top of the Dashboard page (see a screen shot below).

File:Warning_customer_interface_changed.png


Creating a Custom Template

To create a different template for the page where customers enter 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 this 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 on 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.
  • Changes to templates of X-Payments need to be approved in the dashboard before using. You will see a warning box right after logging into X-Payments admin back-end.


Also, it is recommended to read this forum thread: http://forum.x-cart.com/showthread.php?t=69939


Replacing Images

The images that define the look of your X-Payments front end can be changed. Below is the list of images that are used for the front end in X-Payments 1.0 (default X-Payments template):

  • icon_error.gif -- the error icon. This image is marked in red on the screenshot.
  • logo_card.png -- the Credit Card logo. This image is marked in blue on the screenshot.
  • question.gif -- the question mark. This image is marked in green on the screenshot.



To replace the images, upload the necessary files to the <xpayments_dir>/public/templates/default/ directory via FTP.

The instruction above describes how to change the look of the default X-Payments template, but of course you can change the images of any other template. To do so you should go to the <xpayments_dir>/public/templates/ directory and find the folder that has the same name as the template for which you need to change images (for example, "xcart"). There you will find the images that will need to be changed. Replace them with your own images by uploading the images via FTP.

Do not forget to approve all the changes.

Adding a Favicon

It is possible to add a favicon for the X-Payments front end.

To add a favicon, do the following:

  1. Create an image file that you would like to use as the favicon and save it with the same name as your template name in X-Payments. For example, if your online store uses "mytemplate" X-Payments template, you should save the favicon as "mytemplate.ico".
  2. Upload the created file to the <xp-dir>/public/templates directory on your X-Payments server.
  3. Make sure the file permissions have been set correctly (e.g., open the file in your browser: https://example.com/public/templates/mytemplate.ico)
  4. Approve the changes you have made to the X-Payments files on the Dashboard page in the X-Payments back end.


Translating the User Interface / Editing Text Labels

Text elements that appear in the X-Payments user interface are specified with the help of text labels. This enables you to easily customize the text of the X-Payments user interface, including both the X-Payments Admin back end and the front end where your customers enter their payment details.

You can take the following approaches when customizing the user interface text in X-Payments:

  • Translate the entire user interface of X-Payments - or just the part visible to customers - into another language (or more than one languages);
  • Override the text of individual labels.

In both cases, you need to prepare a custom text labels set in the form of a CSV file and save it as <xpayments>/lib/XPay/Templates/labels.csv.

A CSV file is a text file where each line represents a separate data record. Each data record consists of fields separated by a designated delimiter (a semicolon in our case).

Being a text file, a file in the CSV format can be created and edited with any decent text editor. Alternatively, you may be able to create the translation using your favorite spreadsheet software application, then convert it to UTF-8 encoded .csv.

Here's an example of a line for the labels.csv file:

Credit card type;CCT;ru

In this line from the example above:

  • Credit card type is a text label in English;
  • CCT is this text label in the required language;
  • ru is a two-letter code of the required language.

Without the labels.csv file, all the text labels in X-Payments will be displayed in the default language, which is English. With the addition of a custom text labels set saved as <xpayments>/lib/XPay/Templates/labels.csv, label texts will be pulled from this file. If the custom text labels set contains labels for more than one languages, the language will be selected based on the user's language preferences.


Managing Payments

Payments Page

Payments made via X-Payments can be viewed/managed using the 'Payments' page.

Note: Non-root X-Payments users may not be able to view this page if they do not have the respective access permissions.

On the 'Payments' page, the list of payments is presented in the form of a table:

For each individual payment the following information is available:

  • Reference ID - the payment's reference number;
  • Payment ID - the payment's ID number;
  • Submitted - when the payment was submitted;
  • Online store - the online store from which the payment originated;
  • Status - the payment status (See Payment Statuses for more information);
  • Last update - the last time that the payment was updated;
  • Amount - the payment amount;
  • Payment configuration - the payment configuration that was used to accept the payment;
  • Customer IP - the IP address of the customer who made the payment;

You will see only some of the above information because the 'Payments' table can display no more than six columns simultaneously. To change the set of visible columns in the 'Payments' table:

  1. Click on the 'Settings' icon in the top right hand corner of the table:
  2. Unselect the check boxes for the columns you do not need; then, select the check boxes for the columns you want enabled.
  3. Click Apply.

It is possible to change the payments' sort order. To change the way the payments are sorted, simply click on the table column headers.

It is possible to filter payments / find specific payments based on certain criteria. See Filtering payments / Advanced search

On the 'Payments' page you can:

  • Open the details of a specific payment for viewing;
  • Clear cardholder data for some or all payments (Note: The user does not have to have the permission to view cardholder data to be able to clear cardholder data);
  • Delete payments.

Payment Statuses

The 'Status' column of the 'Payments' table shows payment statuses. The possible payment statuses are as follows:

  • New - The payment has been initiated, but the result is not known yet (for example, response from the payment gateway has not been received).
  • Authorized - The money in the customer's account has been placed on hold to ensure the availability of funds for capture.
  • Charged - The payment amount has been moved from the customer's account to the merchant's account.
  • Refunded - The payment has been returned to the customer.
  • Partially refunded - The payment has been partially returned to the customer.
  • Declined - The payment has been declined (The payment gateway declined the transaction or cancelled the payment authorization, or the customer refused to complete the payment).

Filtering payments / Advanced search

X-Payments allows you to filter the 'Payments' table to find specific payments based on certain criteria:

  1. X-Payments 2.0: Click the File:XP2.0_advanced_search_link.png link above the Payments table. In X-Payments 1.0, use the link File:Xp-19_custom_filter.gif.
    The 'Advanced search' form opens:
  2. Use the 'Advanced search' page to provide your search criteria:
    • Date: Select whether the payments should be submitted or updated during the dates you specify below. You can select from 'All dates', 'Day', 'Week', 'Month', 'Year' or 'Specified period. If you select 'Specified period, enter the exact dates below.
    • Payment ID: Enter the ID of the payment you want to be displayed.
    • Reference ID: Reference ID is passed from the shopping cart. It identifies the order, for which this payment is made, on the side of the shopping cart.
    • Status: Select the check boxes next to payment statuses you want to be displayed.
    • Amount: Enter the amount of payments you want to be displayed and select the currency in the third selectbox.
    • Online store: Select which store the payments should come from.
    • Payment configuration: Select the payment configuration, used for payments you want to be displayed.
    • Customer IP: Enter the IP address of the customer, whose payments you want to be displayed.
  3. Click Search payments. The 'Advanced search' form disappears. Now you should be able to see a list of payments filtered according to the search criteria you provided.

To clear the 'Advanced search' form and start over:

X-Payments 2.0: Use the Reset form button at the bottom of the form.
X-Payments 1.0: Use the File:Xp-20_reset_filter.gif link.

Viewing Payment Details

To view the details of a specific payment, locate the payment in the 'Payments' table and click on its Reference ID, or click on the 'Details' link pertaining to the payment in the last table column on the right. The 'Payment details' page opens:

The main section of the 'Payment details' page contains general information about the payment.

Below there is the 'Transaction list' section that displays all the transactions pertaining to this payment.

You may see the following types of transactions:

  • Auth: Transaction to place a pending charge or hold on the customer's payment account.
  • Capture: Transaction to capture a previously authorized payment amount - fully or partially. Transactions of this type are the result of the merchant using manual capture in a two-step payment flow (See Auth and capture).
  • Sale: Transaction to authorize and automatically capture a payment amount (authorization and capture actions are completed simultaneously).
  • Void: Transaction to void a previous authorization.
  • Refund - Transaction to return a previously received payment amount from the merchant to the customer - fully or partially.
  • Info - Transaction to obtain information about the current status of handling the payment from the payment gateway.

For example, the image below displays a list of transactions for a payment that was partially refunded. First the payment amount was charged, then a part of the amount was refunded:

To see detailed information on a specific transaction:

X-Payments 1.0: Click File:Xp-26_additional_info.gif. You will see something like the following:
X-Payments 2.0: Click File:XP2.0_view_transaction_details.png. You will see something like the following:
.

If there is stored cardholder data associated with the payment, users who have the permission to view cardholder data can see it in a separate section in the right hand side of the screen. If no stored cardholder data is available, the section is displayer like so:

File:XP2.0_cardholder_data_not_available.png

Deleting payments

To delete a payment, do one of the following:

  • On the 'Payments' page:
    Select the payment(s) you wish to delete and click the Delete button.
  • On the 'Payment details' page:
    X-Payments 1.0: Click the File:Xp-28_delete_payment_link.gif link. Confirm the deletion.
    X-Payments 2.0: Click the File:XP2.0_delete_this_payment.png link. Confirm the deletion.

Clearing cardholder data

Stored cardholder data for some or all payments can be removed via the 'Payments' page: To remove cardholder data for specific payments, select the check boxes next to them and click the Clear cardholder data button. To remove all stored cardholder data, click the Clear all cardholder data button.

It is also possible to remove stored cardholder data for a specific payment via the 'Payment details' page of that payment: click the Clear cardholder data link in the section that displays stored cardholder data.

Auth and capture: Capturing funds

Depending on the type of order fulfillment process used by your store, you may choose to set up your account in such a way that the capture of funds from your buyers' accounts will not happen automatically at the time of payment processing, but will be delayed so you can capture the funds manually at a later time (You will need to ensure that your preferred payment gateway supports this feature).

To enable manual capture transactions in X-Payments, you will need to adjust your payment configuration settings accordingly:

  1. Go to the 'Payment configurations' page (Settings -> Payment configurations) and select the payment configuration for which you need to enable manual capture.
  2. On the 'Payment configuration details' page, set the Initial transaction to Auth:

    Choosing Auth ensures that, when a customer makes a payment, the payment amount will be authorized, but not captured - until the time you decide to capture funds manually.
    Note: In the case of Auth and capture, the authorization is immediately followed by automatic capture, so you will not be able to capture funds manually.

To capture funds after the initial 'Auth' transaction:

  1. On the 'Payments' page, locate the payment for which you want to capture funds and open its details for viewing. The 'Payment details' page opens.
  2. On the 'Payment details' page, locate the section for Capture/Void actions:
    X-Payments 1.0:

    X-Payments 2.0:
    File:XP2.0_capture_void.png
  3. Make sure that the amount shown in the input box is correct. If you need to capture a partial amount, adjust the contents of the input box accordingly - only the specified amount will be captured.
  4. Click Capture.

If your payment gateway supports multiple capture transactions, you can capture funds several times, gradually decreasing the authorized amount.

You can also capture funds (the whole amount) directly from the 'Payments' page. To capture funds for a payment, simply click on the Capture link next to the payment status:
X-Payments 1.0:

X-Payments 2.0:


If funds are not available for capture, the Capture button disappears.

Voiding authorizations

Depending on the payment gateway you use, you may be able to void authorizations.

To void an authorization:

  1. On the 'Payments' page, locate the payment for which you want to void an authorization and open its details for viewing. The 'Payment details' page opens.
  2. On the 'Payment details' page, locate the section for Capture/Void actions:
    X-Payments 1.0:

    X-Payments 2.0:
    File:XP2.0_capture_void.png
  3. Click Void.

Note that once an authorization has been voided, you will no longer be able to capture the payment - it will be declined.

Issuing refunds

Depending on the payment gateway you use, you may be able to refund payments received from your customers - fully or partially.

To issue a refund:

  1. On the 'Payments' page, locate the payment for which you want to make a refund and open its details for viewing. The 'Payment details' page opens.
  2. On the 'Payment details' page, locate the section for Refund actions:
    X-Payments 2.0:
    File:XP2.0_refund.png
  3. Click Refund.

Accept/Decline: Managing High Risk Transactions

Some payment gateways provide merchants with fraud protection tools that allow them to identify potentially fraudulent transactions and manage their own fraud risk – to make their own decisions about which payments to accept or decline.

For example, some payment solutions by PayPal allow the merchant to set up Fraud Protection filters which make it easier for the merchant to detect and respond to fraudulent transactions. Depending on the merchant's preferences, the transactions identified as having a higher likelihood of risk can be rejected or held pending for review by the merchant so the merchant can explicitly accept or deny the payment.

X-Payments supports this feature for some payment gateway integrations (See Appendix A. Supported payment gateways, "Accept" and "Decline" columns).

When a transaction is identified as high-risk by the payment gateway, the payment gets the Authorized with warning/Charged with warning status in X-Payments:

The following section appears on the 'Payment details' page for the payment:

File:XP2.0_accept_decline.png

You can use the Accept and Decline buttons in this section to specify whether you want to accept or decline the transaction.

If the transaction is accepted, the payment status is updated from Authorized with warning or Charged with warning to simply Authorized or Charged. If the transaction is declined, the payment becomes Declined.

Emulating transactions

Sometimes a situation may occur when you need to change the status of a payment in X-Payments without actually completing the respective transaction via the payment gateway. For example, you may need to "mark" a payment as captured when you know that the funds have been successfully moved to your account, but the information about the payment status change was not sent to X-Payments (i.e., X-Payments did not receive a callback request from the payment gateway - because the payment gateway does not support this feature or was down). In this case you should use the 'Emulate transaction' feature.

To emulate a transaction:

X-Payments 1.0:

  1. On the payment details page, click the Emulate transaction link. The 'Emulate transaction' section opens:
  2. Make sure that the amount shown in the input box is correct. If you need to use a partial amount, adjust the contents of the input box accordingly - the transaction will be completed only for the specified amount (NB: Your payment gateway must support partial transactions!).
  3. Click the transaction action button (for example, Capture).

X-Payments 2.0:

  1. On the payment details page, locate the section for Capture/Void/Refund actions:
    File:XP2.0_capture_void.png or File:XP2.0_refund.png
  2. Make sure that the amount shown in the input box is correct. If you need to use a partial amount, adjust the contents of the input box accordingly - the transaction will be completed only for the specified amount (NB: Your payment gateway must support partial transactions!).
  3. Capture/Refund transactions: Select the Emulate transaction check box below the input box.
    Void: Select the Emulate transaction check box next to the Void button.
  4. Click the transaction action button (Capture, Refund or Void).

As a result, the transaction status will be updated in X-Payments - without the information being sent to the payment gateway. The information about the transaction status change will also be sent to the online store, and - provided that the online store supports this feature (X-Cart does) - the order status in the store will be automatically updated as well.

Tokenization and Re-Use of Saved Credit Cards (X-Payments 2.0 and X-Cart 4.6.1 or later)

As an online merchant you might like the idea of enabling your customers to save a credit card for repeated use at your store. If you have returning customers or want to sell subscriptions, this certainly makes sense, as this way credit card details will have to be entered and saved just once, and you won't have to ask your customers for their payment details every time they need to make a purchase.

However, according to PCI DSS, an industry-wide standard that must be met by any organization that stores, processes, or transmits cardholder data, storing customers' credit card details is not allowed for regular merchants - unless they take steps to implement a number of security aspects and undergo an expensive and time consuming process of certification to ensure that all the PCI DSS requirements have been thoroughly met.

X-Payments 2.0 provides a PCI DSS compliant solution that allows you to charge customer credit cards again (for new orders or for subscriptions) when you use certain payment gateways. You get all the benefits of storing your customers' credit card details - without actually storing them on your system. This is made possible through the use of the so-called "tokenization". Tokenization is a means of protecting sensitive cardholder data that was designed to reduce the risks associated with storing credit card information for merchants. The technology is meant to prevent the theft of the credit card information in storage. It replaces your customer's credit card details with a special number (token) that can be used to charge again the customer’s credit card via an integrated payment gateway. As sensitive information is stored not on the merchant site, but in a secure PCI DSS compliant environment of the payment system, use of tokenization significantly simplifies PCI DSS compliance for the merchant.

Support for tokenization and re-use of saved credit card data stored in a secure data center of the payment system away from the merchant site are new features of X-Payments 2.0 (not supported by X-Payments 1.0). In X-Cart, these features are supported starting with version 4.6.1.

To find out whether a specific payment gateway integrated with X-Payments supports tokenization, see the list of Supported payment gateways for X-Payments.

Enabling Payments with Saved Credit Cards

To enable payments with saved credit cards, do the following:

  1. Ensure that you are using an X-Payments integrated payment method with support for tokenization.
  2. In X-Cart Admin area, open the payment method's configuration page, select the Use for recharges check box and click Update:
  3. Go to the 'Payment methods' page. You should see a new payment method added to the list - Use saved credit card:
  4. Configure the Use saved credit card method as needed. For example, you can edit the name of this payment method, set an extra charge fee or make this payment method available only to users with a specific membership.
  5. Make sure the Use saved credit card method is enabled.

This is all. Now your store has some exciting new features:

  • During checkout, registered customers can save their credit card details for future orders at your store:

    Customers who have saved credit cards in their account can choose which card to use for each specific order:

    They can also manage saved credit cards in their user account details:


  • You can create subscriptions and accept subscription payments from your customers' saved credit cards. See Managing Subscriptions.


Charging Saved Credit Cards

X-Payments 2.0 used with X-Cart 4.6.1 or later allows you to charge again credit cards that have been used at your store to pay you via an X-Payments intergated payment method with support for tokenization and have been saved in the customer's user account for future use at your store.

There are two ways you can go about charging a saved credit card - via X-Payments back end or via X-Cart back end.

To charge a saved credit card via X-Payments back end:

  1. Find the initial payment that was made using the credit card that needs to be charged and open its details for viewing. To find the payment, use filtering/advanced search.
  2. On the 'Payment details' page displaying the details of the initial payment, click the 'Charge this card again' link. A popup form titled 'Charge this card again' will appear where the parameters of the new payment can be specified:
  3. In the 'Charge this card again' form, enter the amount that needs to be charged. If you wish you can also provide a comment for yourself - something to make your job easier later when you will be figuring out what this payment is for.
  4. Click the Charge this card again button at the bottom of the form. Confirm the action. The credit card will be charged, and the new payment will be created in X-Payments. The newly created payment will be marked as associated with the initial payment:
  5. Once the credit card has been charged, go to your X-Cart store's Admin back end and check the 'Order management' section. This section should now contain an empty new order with an order total equalling the amount that has been charged.
  6. Use X-Cart's built-in Advanced Order Management module to edit the empty new order and add the missing information (products, shipping and taxes information, customer information, etc) as needed.

Video - How to make new orders from X-Payments 2.x back-end:


To charge a saved credit card via X-Cart back end:

  1. In X-Cart's Admin area, go to the 'Create order' page and start creating a new order like you normally do using the built-in Advanced Order Management module. At the step of selecting the customer, select the owner of the credit card that needs to be charged (The credit card needs to be stored in this customer's user account). Click Create new order.
  2. Continue creating the new order - add products, customer information, etc. At the step of selecting a payment method, select Other + Use saved credit card:

    Important: At each step of creating the order (Edit ordered products, Edit customer information, Edit order totals), click the Save button after making any changes; otherwise your changes will not be applied.
  3. After providing all the necessary information and saving the changes, click the Back to details button to go back to review order details. On the 'Order details' page you will see a list of credit cards that the customer has saved in their user account:
  4. Select the card you require, use the 'Amount' input box to specify the amount that needs to be charged and click Charge card. The store will connect to X-Payments, and the selected card will be charged.

Video - How to create a new order in X-Cart 4.6.1 integrated with X-Payments 2.x:


Viewing Payments Made with Saved Credit Cards

In X-Payments, all payments made using a saved credit card are linked to the initial payment made using this card and are considered "based" on this payment. You can tell whether a payment was made using a saved credit card by the contents of its Reference ID field: independent payments have reference IDs like "#N", whereas payments based on another payment (payments made using a saved credit card) have a link in the Reference ID field that looks like "Payment #N" and points to the 'Payment details' page of the initial payment.

You can view the full list of payments for a specific saved credit card by using this button on the 'Payment details' page of the initial payment made using this credit card:


Managing Subscriptions

X-Payments 2.0 used with X-Cart 4.6.1 or later allows you to set up a subscription for any payment made by a customer using a payment method that supports tokenization.

To set up a subscription:

  1. In your X-Cart store, create a product buying which will serve as a subscription setup fee, or first subscription payment, for your customers.
  2. When a customer buys this product, find the respective payment in X-Payments and open its details. If the payment was made using a saved credit card, locate the initial payment made using this card and open its details.
  3. On the 'Payment details' page, click on the 'Recurring payments' link:

    The 'Subscription management' page opens:
  4. On the 'Subscription management' page, use the 'Subscription charges settings' form to configure the subscription: choose how frequently the customer is to be charged for the subscription and specify the amount that will be charged every period. Click Save at the bottom of the form to save the changes.
  5. After saving the subscription settings, note that the subscription now has the disabled status:

    To activate the subscription, click the button dropdown element at the bottom of the form and select Activate subscription:

That is all. Now X-Payments can charge the customer's saved credit card according to the subscription settings you have specified.

When you start receiving subscription payments from your customers, you will be able to track each subscription payment down to the initial payment on which it was made: simply follow the "Payment #N" link in the table cell specifying the payment's Reference ID.

To view all payments for a specific subscription, open the details of its initial payment and, on the 'Payment details' page, click on the 'Recurring payments' link. The list of all payments made on this subscription will be displayed in the 'Related payments' section of the 'Subscription management' page.

Every subscription payment is a separate payment in X-Payments, and you can manage it the same way as any other ordinary payment in X-Payments (refund, decline, etc).

In X-Cart, a separate order is created automatically for each subscription payment. Orders created for subscription payments are initially empty (no products, no shipping, no taxes - just the order total), but, if you need, you can edit them using X-Cart's built-in Advanced Order Management module to complete the missing information.


Video - Built-in subscriptions management in X-Payments 2.x integrated with X-Cart 4.6.1:

Uninstalling X-Payments

To uninstall X-Payments:

  1. Delete all files and folders from the installation directory.
  2. Delete data from the database by executing the following SQL query:
DROP DATABASE IF EXISTS <DB_NAME>;

Upgrading

See X-Payments:Upgrading for instructions.

PA-DSS implementation guide

Get to know how to achieve conformity to PCI-DSS standard when using X-Payments.

Troubleshooting

See X-Payments:Troubleshooting

Appendix A. Supported payment gateways

Legend:

  • Auth: Allows to authorize the availability of funds for a transaction (The buyer's funds are temporarily placed on hold to ensure the availability of the authorization amount for capture).
  • Capture: Allows to capture the amount of the authorization (The money authorized for the order is moved from the buyers's account to the merchant's account).
  • Sale: Supports transactions of 'Sale' type (Authorization and capture actions are completed simultaneously at the time the payment is processed).
  • Void: Allows the removal of an authorization hold from the buyer's account by the merchant.
  • Refund: Allows to issue refunds (The money is returned to the buyer's account).
  • Get Status: Can provide information about the status of a transaction to X-Payments.
  • Accept, Decline: Allows to accept or reject transactions with a higher likelihood of risk.
  • Test: Can test whether the merchant account details entered in X-Payments are valid.
  • 3D-Secure via Cardinal Commerce: Supports 3-D Secure payer authentication via Cardinal Commerce.
  • Tokenization: Supports tokenization (Allows to charge customer credit cards again - without X-Payments storing cardholder data).
  • p: Supports partial transactions (For example, "Capture + p" = Allows to capture a partial amount of the authorization).
  • m: Supports multiple transactions (For example, "Capture + m" = Allows to perform the capture action multiple times).


Payment service provider Payment system Sale Auth Capture Void Refund Get status Accept Decline Test 3D-Secure via
Cardinal Commerce
Tokenization
PayPal PayFlow Pro + + +
p, m
+ +
p, m
- + + - 3d Secure
built in
-
PayPal PayPal Payments Pro (PayPal API) + + +
p, m
+ +
p, m
+ + + + + +
PayPal PayPal Payments Pro (Payflow API) + + +
p, m
+ +
p, m
- + + - + -
Australia and New Zealand Banking Group Limited ANZ eGate + - - - - - - - - - -
American Express American Express Web-Services API Integration + + +
p, m
- +
p, m
- - - - - +
CyberSource Corporation Authorize.Net AIM + + +
p
+ - - - - - + -
CyberSource Corporation Authorize.Net AIM XML + + +
p
+ +
p
- - - - + -
CyberSource Corporation Authorize.Net CIM + + +
p
+ +
p
- - - - + +
Beanstream Internet Commerce Inc. Bean Stream/FirstData Canada + + +
p, m
+ +
p, m
- - - - + -
BluePay BluePay + + + + +
p, m
- - - - - -
Braintree, a division of PayPal, Inc. Braintree + + +
p, m
+ +
p, m
- - - - - +
Caledon Computer Systems, Inc. Caledon + + +
p, m
- +
p, m
- - - - + -
CardinalCommerce Corporation Cardinal Commerce Centinel + + +
p
+ +
p
- - - - 3d Secure
built in
-
Chase Paymentech Chase Paymentech + + +
p
+
p
+
p
- - - - - +
CyberSource CyberSource - SOAP toolkit API + + +
p
+ +
p, m
- - - - + +
DIBS Payment Services AB DIBS + + +
p, m
+ +
p, m
- - - - + -
5th Dimension Logisitics, LLC 5th Dimension Gateway + + +
p
+ +
p
- - - - - -
SecurePay Pty Ltd DirectOne - Direct Interface + - - - - - - - - - -
Elavon, Inc. Elavon Payment Gateway + + + + + - - - - 3d Secure
built in
+
Electronic Clearing House, Inc. ECHO NVP + + - + - - - - - + -
Barclaycard Business ePDQ MPI XML (Phased out) + + +
p
+ +
p, m
- - - - - -
eProcessing Network, LLC eProcessing Network - Transparent Database Engine + + +
p
+ + - - - - - -
Moneris Solutions eSelect DirectPost + + +
p, m
- +
p, m
- - - - + -
Web Active Corporation Pty Ltd eWay Realtime Payments XML + - - - + - - - - - -
Global Payments, Inc Global Iris/HSBC - RealAuth Remote + + + + + - - - - 3d Secure
built in
+
GoEmerchant, LLC GoEmerchant - XML Gateway API + + +
p
+ +
p, m
- - - - - -
Ingenico Payment Services (former Ogone) Ogone/ePDQ e-Commerce + + +
p
+ +
p, m
- - - - - -
Intuit, Inc. Innovative Gateway Innovative Gateway + + - - - - - - - - -
Intuit Inc. QuickBooks Payments + + +
p
+ +
p
- - - - - +
iTransact, Inc. iTransact XML + + +
p, m
+ +
p, m
- - - - - -
First Data Corporation First Data Global Gateway e4(SM) Web Service API + + +
p
+ +
p, m
- - - - - +
Meritus Payment Solutions Meritus Web Host + + +
p
+ +
p, m
- - - - - +
(works only in "Sale" mode, is disabled in "Auth only" mode)
Netbilling, Inc. Netbilling - Direct Mode 3.1 + + +
p
- +
p, m
- - - - + -
Netregistry Pty Ltd NetRegistry + + - - +
p, m
- - - - - -
PayGate PayGate Korea + + + + + - - - - - -
Payment Services Interactive Gateway Inc. PSiGate XML API + + +
p
+ +
p, m
- - - - + -
Quantum Services LLC QuantumGateway - Transparent QGWdatabase Engine + + +
p, m
+ - - - - - - -
Quantum Services LLC QuantumGateway - XML Requester + + +
p, m
+ +
p, m
- - - - - +
Realex Payments Realex + + + + + + - - - 3d Secure
built in
+
Sage Pay Sage Pay Go - Direct Interface + + + + +
p, m
- - - - 3d Secure
built in
+
SecurePay.com Inc. SecurePay + + - - - - - - - - -
SecurePay - A Business of Australia Post SecurePay Australia + - - - - - - - - + -
Skipjack Financial Services, Inc. SkipJack + + +
p
+ +
p
+ - - - - -
GorCorp Inc. USA ePay - Transaction Gateway API + + +
p
+ +
p
- - - - + -
Elavon, Inc. Virtual Merchant - Merchant Provided Form + + - - - - - - - - -
Plug and Pay Technologies WebXpress + + +
p
+ +
p
- - - - + -
Worldpay Worldpay Corporate Gateway - Direct Model + + +
p
+ +
p, m
- - - - - -
WorldPay US, Inc. WorldPay US + + +
p
+
p
+
p
- - - - - +

See also


This article can be downloaded as a PDF file
Personal tools
entry points
x-cart on social