X-Payments:User manual

From Qualiteam Help

Introduction

X-Payments is a 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 v1.2 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 shopping cart on the one side and payment gateways and 3D-Secure systems on the other side.

X-Payments allows the owners of online stores to:

• allow their customers to pay for the orders with credit cards, using online payment gateways;
• make their online stores compliant with the PCI-DSS standard version 1.2, which strictly recommends using only PA-DSS verified payment applications for accepting and handling credit card payments;
• integrate with payment gateways, not supported by X-Payments 1.0 out of the box;
• change the design and URL of the payment information entering form to go with the design and URL of the online store.

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

To install X-Payments:

1. Download a distribution package from the File Area section of your Qualiteam Account. The package you need is contained in the archive file x-payments-x.y.z.tgz, where 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 the directory xpayments/var/log has write permissions for the user who runs the web server.

4. Copy the file config.ini-dist.php to config.ini.php and open config.ini.php for editing.

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"
• 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]

• web="URL (including the end-line slash) to where X-Payments is installed, e.g. https://www.example.com/xp/"

[proxy]

• proxy="Proxy server to send http/https requests (used by cURL)"

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.

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.

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, necessary for correct operation of X-Payments. For example, this script removes cardholder data for orders, which 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.

Getting started

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

1. Install X-Payments.
2. Install X-Payments Connector module for X-Cart.
3. Log in to the X-Payments back-end.
4. Go to the ' Payment Configurations' section (Settings menu->Payment Configurations) and configure one or more payment modules you want to use.
5. Go to the ' Online stores' section (Settings menu->Online stores) and configure how X-Payments will connect to your shopping cart application. Choose a payment configuration that should be used with a particular shopping cart application.
6. Import payment methods from X-Payments to X-Cart. If you plan to use PayPal as a payment method, you need to follow a few additional steps.
7. Enable X-Payments payment methods in X-Cart
8. To be able to use 3D-Secure payer authentication service (Verified by VISA, MasterCard Secure Code), configure CardinalCommerce module (Settings menu->3D-Secure Settings).
9. Define general settings (Settings menu->General Settings).
10. To be able to collect cardholder data, generate encryption keys (Maintenance menu->Encryption keys).
11. If you are going to grant access to the X-Payments back-end to other users, go to ' Users' section and create new user accounts.

Configuring X-Payments

To configure X-Payments click the items of the main menu.

General Settings

See X-Payments:General settings page.

Online Stores

To go to the 'Online Stores' section click Settings->Online Stores in the main menu. The 'Online Stores' section opens.

Use this page to enable, disable or delete online store, add new stores or view and edit the details of existing stores.

Adding an Online Store

To add a new store click the Add new button. The 'Add new online store' section opens.

Complete the following fields:

Store name: A short name, by which this online store should be identified in X-Payments.

Order prefix: A prefix to distinguish orders from this online store from other orders.

Template: A template of the page where the customers of this online store enter payment information (select from default or xcart).

Payment configurations: Select the payment configurations, which should be available for orders in this online store. If no configurations are selected, the online store receives a status 'Not configured'.

When you click Save, the online store is created. The store details page opens.

Editing Online Store Details

When you add an online store, the 'Online Store Details' page opens.

Encryption Keys

To view this store's encryption keys, click the View encryption keys link at the top of the page. The '[Store name] Encryption Keys' page opens. It contains a public key, a private key and a private key password.

The public key is used to encrypt data, sent to X-Payments from the shopping cart. The private key is used to decrypt data received by the shopping cart from X-Payments. The private key password is used to decrypt the private key.

For more information about encryption keys see the section 'Encryption keys' in this manual.

Enabling/Disabling the store

Use this page to adjust store details. When you first add a store, it is disabled and you need to enable it. To do so click [ enable ] below the store name field. When a store is enabled, the following line is displayed below the store name field:

To disable a store click [ disable ].

Store ID

The Store ID field contains a string of characters, which is used by X-Payments to identify this specific online store.

Deleting a Store

To delete a store click the Delete store link on the 'Online Store Details' page.

You can also click on the symbol next to the store name on the 'Online Stores' page.

After any of these actions the following confirmation dialog appears:

Click Yes to delete the store. Click No to cancel the operation.

Payment Configurations

In order for X-Payments to operate you need to set up at least one payment configuration.

To set up a 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. The settings differ for each payment module.

Basically what you need to do is get all the information from your payment gateway merchant account backend and enter it on this payment configuration page in X-Payments.

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.

The active 3-D Secure configuration will be used for 3-D Secure payer authentication when customers use payment methods, for which 3-D Secure authentication is turned on.

At present only CardinalCommerce module is supported. To configure it click CardinalCommerce on the '3D-Secure Settings' page.

Adjust the following settings:

Status: Specify whether 3D-Secure payment authentication should be active or inactive in your online store.

Currency: The currency your online store uses to conduct transactions.

Test/Live mode: Select from Test or Live mode.

Merchant ID: A MerchantID value provided to you by CardinalCommerce.

Processor ID: A ProcessorID value provided to you by CardinalCommerce.

Transaction password: A Transaction password provided to you by CardinalCommerce.

Transaction URL: A TransactionURL provided to you by CardinalCommerce.

Click the Test configuration button to issue a test transaction and check if all the settings are correct.

Click the Delete configuration link to delete the 3D-Secure configuration.

Click Save to save the changes.

Encryption keys

To decrypt requests from the shopping cart X-Payments uses a pair of keys. The public key is stored on the shopping cart side and is included in the requests from the shopping cart to X-Payments. The private key is securely stored on the X-Payments side. The shopping cart request to X-Payments must contain the shopping cart ID and some request-specific information (request body), encrypted with the public key. X-Payments receives this request, identifies it by the shopping cart ID and uses an appropriate private key to decrypt the request body.

The responses, generated by X-Payments to requests of the shopping cart or callback requests to the shopping cart also require encryption. To decrypt requests from X-Payments, the shopping cart must use the private key and a password that is used to decrypt the private key. The private key and password must also be securely stored on the shopping cart side.

Make sure these keys cannot be accessed without authorization. Regenerate keys regularly, at least monthly.

To manage cardholder data encryption keys click Maintenance->Encryption keys in the main menu.

On the 'Cardholder data encryption keys' there is a list of settings related to encryption keys.

Complete the following fields:

• Key time-to-live (days): Enter the number of days the encryption key must be valid for.
• Regenerate keys X days prior to key expiration date: Specify how many days before expiration date you want the encryption keys to be regenerated.
• Notify Y days prior to the key expiration date: Specify how many days before expiration date you want to be notified.
• Notify on key generation: Specify, whether you want to be notified when keys are regenerated.
• Send notifications to email: Enter an email address, where notifications must be sent to.

Managing users

To manage users click Users in the main menu.

Creating user account

To create a user account click the Add user button.

User name: Enter the user name of the new account.

Email: Enter the email address to receive notifications.

Expiration date: Enter a date, when this account should expire. For example, Sep 10, 2010. Leave this field empty to create an account which never expires.

Permissions: Select check boxes next to the sections of X-Payments, which you want the new user have access to.

Editing user account

To edit a user account click on the user name in the users list. The 'Account details' page opens. Change the desired elements and click Save.

If the account is active, you can click Lock account to lock the account:

If the account is locked, you can click 'Unlock account' to unlock it:

You can also lock/unlock accounts directly from the 'Users' page, using the controls displayed below:

To change the account e-mail address click on the right.

Enter the new e-mail address into the provided box and click Change. After you click the Change button a notification will be sent to this email, containing an email confirmation link. The email will be changed only after confirmation.

Deleting user account

To delete a user account click the Delete account link on the 'Account details' page.

You can also click on the symbol next to the user name on the 'Users' page.

After any of these actions the following confirmation dialog appears:

Managing PIN-codes

PIN codes are used as the second authentication factor, together with login and password. To be able to login to X-Payments you need to know a PIN code. Each PIN code is valid for one login only and expires right after being used.

When you install X-Payments, you receive an email message, which includes five PIN codes. You can use them to login to X-Payments back-end and generate a set of PIN codes to be used later.

When you login to X-Payments, you need to enter your email address, password and a PIN code. If you enter an incorrect PIN code, you are offered to enter it again (the PIN code number is specified). PIN codes must be used in the specified order, according to their numbers. If you enter a wrong PIN code for the second time, authentication is refused.

When you run out of the first five codes that were emailed to you, you need to generate a new set of PIN codes, which is a table of 100 codes, each of which can be used only once.

Generating PIN codes

To generate a new set of PIN codes do the following:

1. Login to X-Payments using one of the PIN codes you received by email.

2. Go to your 'Account details' page.

3. Click the Generate PIN codes button. An information message appears at the top of the page:

4. To view your PIN codes table click the View PIN codes link.

5. Now you have three ways to save your PIN codes:

• Print
• Save as picture...
• Save as text...

Click the corresponding button and follow the instructions on screen.

Generating PIN codes for other users

It is impossible to generate PIN codes for another user, using the X-Payments interface. You need to run a special script. To do so open the console and enter

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

where user@example.com is the email of the user, for whom you are generating PIN codes.

After the script completes, five PIN codes will be sent to the specified email. The user can later generate a complete PIN code table.

When all but five PIN codes from the table have been used, a reminder is shown to the user to generate a new PIN codes table.

Customizing Interface

This section contains information on managing the page displayed to customers to enter credit card information.

Creating a Custom Template

To create a different template for the page where customers enter cardholder data, you should work with 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 the 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 at 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.

There's also a xp_skin_generator tool for building X-Payments skin from your existing X-Cart skin.

Translating Customer Interface

It is possible to have the page where customers enter cardholder data translated into another language.

To do so you should edit the file <xpayments>/lib/XPay/Templates/labels.csv .

A CSV file is a text file where each line represents a separate data record. Each 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 opened and edited with any decent text editor. However, editing large volumes of CSV-formatted data with a text editor is likely to turn out a frustrating experience, so you might prefer to use your favorite spreadsheet software application, like MS Excel, to arrange the contents of your CSV file as columns and rows.

Here is an example of a line this file should contain:

Credit card type;CCT;ru

where:

• 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

UTF-8 character encoding is used.

If this file is missing, all the text labels on the page where customers enter cardholder data, are in English.

Viewing Payments

To view payment information click 'Payments' in the main menu. The 'Payments' page opens.

This page can include the following information: Payment ID, when the payment was submitted, the online store the payment comes from, the payment status, the last time the payment was updated, the payment amount, the payment configuration used to accept the payment, the customer IP address, Reference ID.

Click on column headers to change the way the payments are sorted. Click in the payment line to view payment details page. Click on the online store link to view online store details.

To change the set of visible columns click on the symbol in the top right corner.

Select the check boxes next to the required columns and click Apply.

Payment statuses

A payment can have one of the following statuses:

• New - The status indicating that the payment gateway has been asked to make the payment, but the result is not known yet (the payment gateway has not answered or the admin has to process the payment manually).
• Declined - The status indicating that the payment gateway declined a transaction or cancelled the payment authorization, or the customer refused to make a payment.
• Authorized - The status indicating that the amount corresponding to the order total has been successfully authorized.
• Charged - The status indicating that the payment gateway has successfully charged the payment.
• Partially refunded - The status indicating that the payment gateway has returned a part of the payment to the customer.
• Refunded - The status indicating that the payment gateway has returned the payment to the customer.

Filtering payments

To set filtering exactly the way you want it to be, click . The 'Define filters' page opens.

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.

Click to clear all the fields and start over.

When you are finished click Apply to save the changes you have made and display a list of payments filtered according to the new conditions.

Payment Details

On the 'Payments' page click in the line of the payment, which details you want to view. The 'Payment Details' page opens.

The 'Payment Details' page contains several sections. The main section contains general information about the payment. Below there is a 'Transaction list' section, which displays all the transactions which have been made within this payment.

For example the image below displays a list of transactions for a payment, which has been partially refunded. First the payment amount was authorized, then charged, and them a part of the amount was refunded.

To see the response message on each transaction click .

An example additional info message looks like this:

Additional info includes payment gateway response messages and details about CVV check and AVS check results.

Auth and Capture

X-Payments allows to perform Auth and Capture and partial Capture transactions.

To enable X-Payments to perform Auth and Capture transactions, take the following steps:

1. Make sure X-Payments supports the required types of transaction with the payment gateway you are going to use. Consult [index.php?title=X-Payments:User_manual#Appendix_A._Supported_payment_gateways the list of supported payment gateways] and find out whether multiple (m) and partial (p) transactions for your payment gateway are supported.
2. Go to the payment configuration page (Settings > Payment configurations > select the required payment from the list).

Initial transaction: select 'Auth'. If you select 'Auth and capture' you will not be able to capture funds manually.

To capture funds after an automatic Auth transaction, take the following steps:

When a customer makes a payment, the payment amount is authorized automatically, and then you need to capture the required amount. Go to payment details page (Payments > select the necessary payment from the list). Use the 'Handle transaction' section:

• Make sure the authorized amount is correct. If it is, click 'Capture'.
• If necessary, change the amount in the input box and click 'Capture'. Only the specified amount will be captured as a result.

If you know you do not need to change the capture amount (or your payment gateway does not support partial transactions), you can capture funds directly from the Payments page. To do so find the necessary payment in the payment list and click the Capture link below the payment status.

If your payment gateway supports multiple transactions, you can capture funds several times, gradually decreasing the authorized amount. When funds are not possible to capture, the 'Capture' button disappears.

Deleting payments

To delete a payment select the payments to be deleted on the 'Payments' page and click the 'Delete' button. You can also click the link on the 'Payment details' page.

After any of these actions the following confirmation dialog appears:

Click Yes to delete the payment. Click No to cancel the operation.

Clearing cardholder data

To delete cardholder data for some payments select check boxes next to them and click the Clear cardholder data button.

Transaction types

The following transaction types are available:

• Auth - payment amount is authorized, but not sent to the store owner.
• Capture - previously authorized payment amount is sent to the store owner.
• Sale - payment amount is simultaneously authorized and sent to the store owner.
• Void - payment amount authorization is canceled.
• Refund - payment amount, previously sent to the store owner, is returned to the customer.
• Info - information about the current status of handling the payment by the payment gateway is received.

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

Please review X-Payments:Upgrading page for the instructions.

PA-DSS implementation guide

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

Appendix A. Supported payment gateways

Legend:

• p - partial transaction allowed
• m - multiple transactions allowed
• cc - transaction requires passing credit card data (Sale and Auth transactions always require passing credit card data)

See also

• Glossary
• X-Payments Connector
• Connecting Magento
• Connecting Zen Cart
• X-Payments API
• X-Payments FAQ

Troubleshooting