X-Payments Help - User contributions [en]

X-Payments:Using X-Payments with Zoey

2018-02-01T08:26:45Z

Alex Mulin:

__NOTOC__
A Zoey store can be connected to [[X-Payments:User_manual|X-Payments]] web-based payment application to process payments from customers and save their credit card data in a PCI DSS compliant way.

This section provides information on how to connect and use X-Payments with your Zoey store.

==What's New==

:* [[X-Payments:What%27s_New_in_X-Payments_Connector_for_Zoey | What's New in X-Payments Connector for Zoey]]

==Connecting Zoey to X-Payments==
Connecting your Zoey store to X-Payments includes two consecutive steps:
:* [[X-Payments:Configure the connection to your Zoey store in the X-Payments back end | Configure the connection to your Zoey store in the X-Payments back end]] (Instructions for X-Payments 2.1.1 and later)
:* [[X-Payments:Configure the connection to X-Payments in the Zoey store Control Panel | Configure the connection to X-Payments in the Zoey store Control Panel]] (Zoey Connector 1.8.4 or later )

==Video tutorials (outdated)==

:* [[X-Payments:Video_Tutotials_on_Using_X-Payments_with_Zoey | Video Tutotials on Using X-Payments with Zoey]]

X-Payments:PA-DSS implementation guide for X-Cart Payments 3

2017-11-24T10:29:40Z

Alex Mulin: /* Communication */

==Introduction==
The purpose of this PA-DSS Implementation Guide is to inform employees of organizations using the X-Cart Payments payment application by Qualiteam Software Limited about the methods and means of protection of account data in the X-Cart Payments software.
 
The methods include the need for compliance with the information security standards in the payment card industry developed by the international payment systems Visa and MasterCard - Payment Card Industry Data Security Standard (PCI DSS) and Payment Application Data Security Standard (PA-DSS). For additional information about PCI DSS, please visit the [https://www.pcisecuritystandards.org/ Official PCI Security Standards Council Site].
 
The document provides instructions on how to implement the application in a PCI DSS compliant manner.
 
Full product name - X-Cart Payments. 
Product version - 3.1.x.
 
Any servers used to run the X-Cart Payments payment application must be configured according to this PA-DSS Implementation Guide.
 
This PA-DSS Implementation Guide should be updated:
:* at least annually;
:* after changes in the payment application (if required);
:* after changes in the PCI DSS and PA-DSS standards.
 
The updated Version of the PA-DSS Implementation Guide has to be sent to all the merchants using X-Cart Payments.
 
The history of changes to the X-Cart Payments PA-DSS Implementation Guide is provided in the table below.
 
'''Table.1. X-Cart Payments PA-DSS Implementation Guide history of changes''' 
{| class="wikitable" width=90%
|-
! scope="col" style="width: 10%;"| '''Author'''
! scope="col" style="width: 10%;"| '''Date'''
! scope="col" style="width: 10%;"| '''Number'''
! scope="col" style="width: 60%;"| '''Change description'''
|- style="vertical-align:top;"
| Alex Mulin
| 05/17/2016
| 01
| The original version of the document, designed to meet the requirements of PCI DSS version 3.1 and PA DSS version 3.1
|-
| Alex Mulin
| 05/17/2017
| 02
| The original version of the document, designed to meet the requirements of PCI DSS version 3.2 and PA DSS version 3.2
|-
|}
 

==Data protection==
The PCI DSS and PA-DSS standards prohibit storage of sensitive authentication data (after authorization) or cardholder data in cleartext. 
Cardholder data includes:
:* Primary Account Number (PAN)
:* Cardholder Name
:* Expiration Date
:* Service Code
 
Sensitive authentication data (SAD) includes:
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
 
X-Cart Payments has the ability to store parts of cardholder data temporarily to perform 3D Secure verification and certain types of transactions for some of the integrated payment processors. During storage, cardholder data is encrypted using RSA 2048 algorithm and AES 256 for key encryption. When its storage period is over, the data is removed automatically via "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.
 
X-Cart Payments may not be configured to store permanently in the database the following types of data:
:* Full PAN
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature.
 
The payment application masks PAN on display (except for the moment when the user enters the card number).
X-Cart Payments can display masked PAN on the "Payment details" pages and in the "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. The same data (partially masked with asterisks) may be passed via the API to the integrated software products. X-Cart Payments does not have the ability to display full PAN anywhere, and there are no settings that can change this behavior of the user interface.
 

==Data Collected while Testing==
Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:
# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever choose to collect credit card information to troubleshoot a problem that a customer of yours is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access.
#* Only collect a limited amount of data (no more than is needed to solve the problem).
#* Sensitive authentication data must be encrypted during storage. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Sensitive authentication data must be securely deleted immediately after use.
To prevent uncontrolled storage of cardholder data (for example, in case of operating system failure), it is recommended to disable the swap file or move it to a specially prepared encrypted partition.
 
==Authentication and access==
The X-Cart Payments payment application has an only user type. This type cannot get access to payment card numbers and does not have any administrative privileges that may affect PA-DSS compliance.
There are no built-in/default user accounts in X-Cart Payments. You must carefully control access to X-Cart Payments. Follow these rules:
:* Restrict the number of employees who have access to X-Cart Payments to only those who have a business need.
:* Always provide unique usernames for each person who needs access.
:* Do not use system-default usernames and/or passwords.
:* Ensure that web server is run under a non-privileged user account and the application has access to the database from a limited privilege user account.
 
To set password lifetime:
# Log in to X-Cart Payments.
# Go to Settings -> General Settings.
# In the "User account password lifetime" field, enter the number of days for which the user account password needs to be valid. The maximum allowed password lifetime is 90 days.
The following related rules apply:
:* The minimum password length is 8 characters.
:* A password must contain both numbers and lower- and uppercase characters.
:* The last 4 passwords must be unique.
:* A user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password.
:* A user is logged off after an inactivity period of 15 minutes.
 
PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:
:* For your Web hosting account administration area (Web hosting account where your online store is hosted);
:* For FTP access to the Web server;
:* For Remote Desktop Connection to the Web server (if available);
:* To connect to the MySQL server that contains your store data.
 
Linux authentication mechanism is used for login in the servers with running X-Cart Payments.
Accounts for access to the operating system are managed by the Linux administrator.
For Linux operating system accounts, you must configure the following attributes of the password policy:
:* use personal accounts, do not use any group, shared, or generic accounts and passwords;
:* changes to user passwords at least once every 90 days;
:* require a minimum length of at least seven characters;
:* contain both numeric and alphabetic characters;
:* do not use last four passwords used previously;
:* block account after six invalid logon attempts (minimum 30 minutes or until an administrator enables the user ID).
 
Two-factor authentication must be used for remote access to the operating system. The authentication methods, also known as factors, are:
:* something you know, such as a password or a passphrase;
:* something you have, such as a token device or a smart card;
:* something you are, such as a biometric.
 

== Logging==
Audit trails are automatically enabled with the default installation of X-Cart Payments. Users do not have the ability to disable or change the logging parameters of X-Cart Payments. X-Cart Payments log journal does not contain cardholder data. It is implemented at the source code level. The setting of an event log journal does not require any additional action from users.
The log files are created in the var/log/ directory. In X-Cart Payments 3.1, logs can be viewed via the X-Cart Payments admin back end. Make sure you restrict access to the log files by business need-to-know.
The following types of activity are logged:
:* All actions taken by any individual with root or administrative privileges.
:* Successes and failures of all individual accesses to application sections and functions.
:* Initialization of the audit logs.
:* User sign in and sign out.
 
Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to the files access.log and error.log.
Each log event includes:
:* Type of event;
:* Date and time of event;
:* Username and IP address;
:* Success or failure indication;
:* Action which led to the event;
:* Component which led to the event.
 
There is also a meta-log which contains information about other log files being created.
Make sure you have a system-level auditing software properly configured to monitor users' activity on the server. This software should:
:* warn on a checksum change of any of X-Cart Payments source code files except for the log file and the database files;
:* record any file writing operations related to X-Cart Payments files.
 

==Communication==
LAN channel or other available connection method can be used as a communication channel.
X-Cart Payments payment application supports the following data formats:
{| class="wikitable" width=90%
|-
| scope="col" style="width: 20%;"| '''Protocol'''
| scope="col" style="width: 70%;"| HTTP protocol (RFC 2616: HTTP/1.1) is used for data transfer between client and server
|- style="vertical-align:top;"
| '''Data transmission method'''
| Only encrypted cardholder data (RSA 2048 and AES 256) is transferred. RAW POST method is used for data transmission - (data stream is transmitted in the body of the request that is sent from client to server)
|- style="vertical-align:top;"
| '''Data format'''
| Data is transmitted in XML format (Extensible Markup Language (XML) 1.0) or in plain text using POST query via HTTPS
|- style="vertical-align:top;"
| '''Port'''
| X-Cart Payments payment application uses ports 80, 443
|-
|}
 
'''Network traffic encryption''' 
X-Cart Payments uses encryption, such as TLS or IPSEC, for:
:* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
:* providing remote web-based access to the application.
 
If you use some tools to remotely access the application, you should encrypt all the communication using such technologies as TLS or IPSEC.
 
As per PCI DSS requirement, cardholder data must never be sent unencrypted by email, and X-Cart Payments does meet this requirement never sending cardholder data by email or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.
 
'''Enable TLS''' 
TLS protects data that is transmitted between a browser and your web server. It is critical that you have TLS enabled on your web server, and one of the first steps you should take after the installation is to enable TLS.
:* Your web server must be configured to use TLS v1.2 protocols with strong encryption (128-bit or longer key is required).
:* You will need to have a certificate issued for your web domain. Read guidelines on installing Comodo's Instant TLS certificates.
 
If a web server does not have TLS enabled, X-Cart Payments will not function.
X-Cart Payments does not support remote administrative access. Strong encryption must be used for remote access to the server.
The connection of servers with X-Cart Payments payment application to the Internet must be protected by a firewall. In X-Cart Payments configurations involving more than one server, server connections should take place in network segments separated from the Internet via stateful inspection firewalls.
 
'''Wireless communications''' 
If you use wireless networking to access X-Cart Payments, it is your responsibility to ensure your wireless security configuration follows the PCI DSS requirements.
:* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
:* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
:* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
:* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
::* Use with a minimum 104-bit encryption key and 24 bit-initialization value.
::* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS.
::* Rotate shared WEP keys quarterly (or automatically if the technology permits).
::* Rotate shared WEP keys whenever there are changes in personnel with access to keys.
::* Restrict access based on media access code (MAC) address.
::* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.
 
'''Remote access''' 
X-Cart Payments provides web-based access using two-factor authentication based on one-time codes. Detailed information can be found on the [[X-Payments:Two-factor_authentication | X-Payments:Two-factor authentication]] page.
If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:
:* Change the default settings in the remote access software (for example, change the default passwords and use unique passwords for each customer).
:* Allow connections only from specific (known) IP/MAC addresses.
:* Use strong authentication or complex passwords for logins.
:* Enable encrypted data transmission.
:* Enable account lockout after a certain number of failed login attempts.
:* Configure the system so a remote user must establish a Virtual Private Network ("VPN") connection via a firewall before access is allowed.
:* Enable any logging or auditing functions.
:* Restrict access to customer passwords to authorized reseller/integrator personnel.
:* Establish customer passwords according to PCI DSS requirements.
Qualiteam does not provide software updates via remote access on an automated basis.
 

==Hardware and software==
The following requirements must be met for X-Cart Payments payment application self-service terminals: 
'''Operating System''' 
Linux Ubuntu 16 or later, Linux Debian 6.0 or later, Linux CentOS 6 or later 
'''DBMS''' 
My SQL 5.6 or later 
'''Software''' 
PHP 5.5 or later 
Apache 2.4 or later
 

==Product versioning methodology==
{| class="wikitable" width=90%
|-
! scope="col" style="width: 15%;"| '''Version number changes'''
! scope="col" style="width: 45%;"| '''Software changes'''
! scope="col" style="width: 15%;"| '''Description'''
! scope="col" style="width: 15%;"| '''PA-DSS changes'''
|- style="vertical-align:top;"
| Version number does not change
| Change of the software name Change of the vendor name
| Changes not related to the software development process
| Administrative
|- style="vertical-align:top;"
| Increment of the minor version number to reflect a change not affecting the certification. For example, change of the version number from 1.0.5 to 1.0.6 (for the certification of 1.0.x)
| - Changes to the user interface - Changes to the database schema - Changes to supported payment gateway integrations / Addition of new payment gateway integrations
| Changes that have no impact on the PA-DSS requirements compliance or Payment Application security
| No Impact
|- style="vertical-align:top;"
| Increment of the second version number. For example, change of the version number from 1.1.* to 1.2.*
| Software changes satisfy the following conditions: - Fewer than 4 sections of the standard (from 1 to 12) involved; - Fewer than a half of all the requirements of the standard (sections 1 to 12) involved; - Less than a half of the software functions (or code) modified; - Changes implemented for compatibility with the updated versions of previously tested OS, DBMS and third party software products. - Addition/removal of supported payment processors. - Recompilation of the source code using a new compiler or different compiler settings. - Changes of the software versioning policy. - Changes of the software not related to security.
| - Changes in the software affecting payment card data mechanisms. - Changes addressing the identified vulnerabilities of the application. - Changes related to the completion of the annual cycle of development (if there are other changes).
| Low Impact
|- style="vertical-align:top;"
| Increment of the first version number. For example, change of the version number from 1.0.* to 2.0.*
| Software changes satisfy the following conditions: - 4 or more sections of the standard (from 1 to 12) involved; - More than a half of all the requirements of the standard (sections 1 to 12) involved; - More than a half of the software functions (or code) modified; - Addition of new supported platforms/OS versions.
| Major changes in the software architecture, global alterations of code
| High Impact
|}
 
The release of each new version is accompanied with a notification to all the application users (agents), which indicates the new application version number and a list of main changes in the new version.
 

==New patches and updates delivery==

New patches, updates, installation instructions and MD5 checksum files are delivered via secure HelpDesk system located at https://secure.x-cart.com using "File Area" section in users accounts there.
We send newsletters about new patches and updates originating from x-cart.com domain name via verified and well-known email delivery system.

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:Getting started

2017-09-25T07:58:39Z

Alex Mulin:

<noinclude>{{XP_manual_TOC}}</noinclude>

'''To begin accepting payments with X-Payments''':

# [[X-Payments:Installation | Install]] X-Payments.{{Note1 | Note: Installation of X-Payment is not needed if you are using the [https://www.x-payments.com/ X-Payments Hosted] solution.}}
# Log in to the X-Payments back end. X-Payments 3: Before you can log in as administrator, you need to set up a method for two-factor user authentication. For details, see [[X-Payments:Two-factor_authentication | Two-factor authentication (X-Payments 3)]]. X-Payments 2.2 and earlier: To log in as administrator, you will need PIN codes. For instructions on logging in to the X-Payments admin back end, watch the video: <youtube>uaIC0wjgBjQ</youtube> For more information on PIN codes in X-Payments, see [[X-Payments:Managing PIN codes | Managing PIN codes (X-Payments 2.2 and earlier)]].
# Go to the '[[X-Payments:General_settings | General settings]]' page and adjust the general settings and preferences for your X-Payments installation.
# On the '[[X-Payments:User_manual#Payment_Configurations | Payment Configurations]]' page, configure and enable one or more payment modules you want to use.
# On the '[[X-Payments:User_manual#Online_Stores | Online Stores]]' page, add your 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 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).
# Open the details of your store for viewing and copy or make note of the connection details needed to connect the store to X-Payments: the configuration bundle, store ID and a set of encryption keys.
# Connect your store to X-Payments. For manuals of X-Payments connectors, see: [[Template:XP_connector_manuals|XP connector manuals]].
# To be able to use 3D-Secure payer authentication service (Verified by VISA, MasterCard Secure Code), [[X-Payments:3D-Secure_settings | configure CardinalCommerce module]] in X-Payments.
# If you are going to grant access to the X-Payments back end to other users, go to the '[[X-Payments:Managing_users | Users]]' section and [[X-Payments:Managing_users | create new user accounts]]. {{Note1|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.}}
# If you are going to store cardholder data, generate [[X-Payments:Encryption_keys | cardholder data encryption keys]].

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

[[Category:X-Payments User Manual]]

X-Payments:PA-DSS implementation guide for X-Cart Payments 3

2017-07-19T12:36:46Z

Alex Mulin: /* Product versioning methodology */

==Introduction==
The purpose of this PA-DSS Implementation Guide is to inform employees of organizations using the X-Cart Payments payment application by Qualiteam Software Limited about the methods and means of protection of account data in the X-Cart Payments software.
 
The methods include the need for compliance with the information security standards in the payment card industry developed by the international payment systems Visa and MasterCard - Payment Card Industry Data Security Standard (PCI DSS) and Payment Application Data Security Standard (PA-DSS). For additional information about PCI DSS, please visit the [https://www.pcisecuritystandards.org/ Official PCI Security Standards Council Site].
 
The document provides instructions on how to implement the application in a PCI DSS compliant manner.
 
Full product name - X-Cart Payments. 
Product version - 3.1.x.
 
Any servers used to run the X-Cart Payments payment application must be configured according to this PA-DSS Implementation Guide.
 
This PA-DSS Implementation Guide should be updated:
:* at least annually;
:* after changes in the payment application (if required);
:* after changes in the PCI DSS and PA-DSS standards.
 
The updated Version of the PA-DSS Implementation Guide has to be sent to all the merchants using X-Cart Payments.
 
The history of changes to the X-Cart Payments PA-DSS Implementation Guide is provided in the table below.
 
'''Table.1. X-Cart Payments PA-DSS Implementation Guide history of changes''' 
{| class="wikitable" width=90%
|-
! scope="col" style="width: 10%;"| '''Author'''
! scope="col" style="width: 10%;"| '''Date'''
! scope="col" style="width: 10%;"| '''Number'''
! scope="col" style="width: 60%;"| '''Change description'''
|- style="vertical-align:top;"
| Alex Mulin
| 05/17/2016
| 01
| The original version of the document, designed to meet the requirements of PCI DSS version 3.1 and PA DSS version 3.1
|-
| Alex Mulin
| 05/17/2017
| 02
| The original version of the document, designed to meet the requirements of PCI DSS version 3.2 and PA DSS version 3.2
|-
|}
 

==Data protection==
The PCI DSS and PA-DSS standards prohibit storage of sensitive authentication data (after authorization) or cardholder data in cleartext. 
Cardholder data includes:
:* Primary Account Number (PAN)
:* Cardholder Name
:* Expiration Date
:* Service Code
 
Sensitive authentication data (SAD) includes:
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
 
X-Cart Payments has the ability to store parts of cardholder data temporarily to perform 3D Secure verification and certain types of transactions for some of the integrated payment processors. During storage, cardholder data is encrypted using RSA 2048 algorithm and AES 256 for key encryption. When its storage period is over, the data is removed automatically via "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.
 
X-Cart Payments may not be configured to store permanently in the database the following types of data:
:* Full PAN
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature.
 
The payment application masks PAN on display (except for the moment when the user enters the card number).
X-Cart Payments can display masked PAN on the "Payment details" pages and in the "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. The same data (partially masked with asterisks) may be passed via the API to the integrated software products. X-Cart Payments does not have the ability to display full PAN anywhere, and there are no settings that can change this behavior of the user interface.
 

==Data Collected while Testing==
Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:
# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever choose to collect credit card information to troubleshoot a problem that a customer of yours is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access.
#* Only collect a limited amount of data (no more than is needed to solve the problem).
#* Sensitive authentication data must be encrypted during storage. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Sensitive authentication data must be securely deleted immediately after use.
To prevent uncontrolled storage of cardholder data (for example, in case of operating system failure), it is recommended to disable the swap file or move it to a specially prepared encrypted partition.
 
==Authentication and access==
The X-Cart Payments payment application has an only user type. This type cannot get access to payment card numbers and does not have any administrative privileges that may affect PA-DSS compliance.
There are no built-in/default user accounts in X-Cart Payments. You must carefully control access to X-Cart Payments. Follow these rules:
:* Restrict the number of employees who have access to X-Cart Payments to only those who have a business need.
:* Always provide unique usernames for each person who needs access.
:* Do not use system-default usernames and/or passwords.
:* Ensure that web server is run under a non-privileged user account and the application has access to the database from a limited privilege user account.
 
To set password lifetime:
# Log in to X-Cart Payments.
# Go to Settings -> General Settings.
# In the "User account password lifetime" field, enter the number of days for which the user account password needs to be valid. The maximum allowed password lifetime is 90 days.
The following related rules apply:
:* The minimum password length is 8 characters.
:* A password must contain both numbers and lower- and uppercase characters.
:* The last 4 passwords must be unique.
:* A user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password.
:* A user is logged off after an inactivity period of 15 minutes.
 
PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:
:* For your Web hosting account administration area (Web hosting account where your online store is hosted);
:* For FTP access to the Web server;
:* For Remote Desktop Connection to the Web server (if available);
:* To connect to the MySQL server that contains your store data.
 
Linux authentication mechanism is used for login in the servers with running X-Cart Payments.
Accounts for access to the operating system are managed by the Linux administrator.
For Linux operating system accounts, you must configure the following attributes of the password policy:
:* use personal accounts, do not use any group, shared, or generic accounts and passwords;
:* changes to user passwords at least once every 90 days;
:* require a minimum length of at least seven characters;
:* contain both numeric and alphabetic characters;
:* do not use last four passwords used previously;
:* block account after six invalid logon attempts (minimum 30 minutes or until an administrator enables the user ID).
 
Two-factor authentication must be used for remote access to the operating system. The authentication methods, also known as factors, are:
:* something you know, such as a password or a passphrase;
:* something you have, such as a token device or a smart card;
:* something you are, such as a biometric.
 

== Logging==
Audit trails are automatically enabled with the default installation of X-Cart Payments. Users do not have the ability to disable or change the logging parameters of X-Cart Payments. X-Cart Payments log journal does not contain cardholder data. It is implemented at the source code level. The setting of an event log journal does not require any additional action from users.
The log files are created in the var/log/ directory. In X-Cart Payments 3.1, logs can be viewed via the X-Cart Payments admin back end. Make sure you restrict access to the log files by business need-to-know.
The following types of activity are logged:
:* All actions taken by any individual with root or administrative privileges.
:* Successes and failures of all individual accesses to application sections and functions.
:* Initialization of the audit logs.
:* User sign in and sign out.
 
Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to the files access.log and error.log.
Each log event includes:
:* Type of event;
:* Date and time of event;
:* Username and IP address;
:* Success or failure indication;
:* Action which led to the event;
:* Component which led to the event.
 
There is also a meta-log which contains information about other log files being created.
Make sure you have a system-level auditing software properly configured to monitor users' activity on the server. This software should:
:* warn on a checksum change of any of X-Cart Payments source code files except for the log file and the database files;
:* record any file writing operations related to X-Cart Payments files.
 

==Communication==
LAN channel or other available connection method can be used as a communication channel.
X-Cart Payments payment application supports the following data formats:
{| class="wikitable" width=90%
|-
| scope="col" style="width: 20%;"| '''Protocol'''
| scope="col" style="width: 70%;"| HTTP protocol (RFC 2616: HTTP/1.1) is used for data transfer between client and server
|- style="vertical-align:top;"
| '''Data transmission method'''
| Only encrypted cardholder data (RSA 2048 and AES 256) is transferred. RAW POST method is used for data transmission - (data stream is transmitted in the body of the request that is sent from client to server)
|- style="vertical-align:top;"
| '''Data format'''
| Data is transmitted in XML format (Extensible Markup Language (XML) 1.0) or in plain text using POST query via HTTPS
|- style="vertical-align:top;"
| '''Port'''
| X-Cart Payments payment application uses ports 80, 443
|-
|}
 
'''Network traffic encryption''' 
X-Cart Payments uses encryption, such as TLS or IPSEC, for:
:* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
:* providing remote web-based access to the application.
 
If you use some tools to remotely access the application, you should encrypt all the communication using such technologies as TLS or IPSEC.
 
As per PCI DSS requirement, cardholder data must never be sent unencrypted by email, and X-Cart Payments does meet this requirement never sending cardholder data by email or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.
 
'''Enable TLS''' 
TLS protects data that is transmitted between a browser and your web server. It is critical that you have TLS enabled on your web server, and one of the first steps you should take after the installation is to enable TLS.
:* Your web server must be configured to use TLS v1.1 or v1.2 protocols with strong encryption (128-bit or longer key is required).
:* You will need to have a certificate issued for your web domain. Read guidelines on installing Comodo's Instant TLS certificates.
 
If a web server does not have TLS enabled, X-Cart Payments will not function.
X-Cart Payments does not support remote administrative access. Strong encryption must be used for remote access to the server.
The connection of servers with X-Cart Payments payment application to the Internet must be protected by a firewall. In X-Cart Payments configurations involving more than one server, server connections should take place in network segments separated from the Internet via stateful inspection firewalls.
 
'''Wireless communications''' 
If you use wireless networking to access X-Cart Payments, it is your responsibility to ensure your wireless security configuration follows the PCI DSS requirements.
:* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
:* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
:* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
:* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
::* Use with a minimum 104-bit encryption key and 24 bit-initialization value.
::* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS.
::* Rotate shared WEP keys quarterly (or automatically if the technology permits).
::* Rotate shared WEP keys whenever there are changes in personnel with access to keys.
::* Restrict access based on media access code (MAC) address.
::* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.
 
'''Remote access''' 
X-Cart Payments provides web-based access using two-factor authentication based on one-time codes. Detailed information can be found on the [[X-Payments:Two-factor_authentication | X-Payments:Two-factor authentication]] page.
If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:
:* Change the default settings in the remote access software (for example, change the default passwords and use unique passwords for each customer).
:* Allow connections only from specific (known) IP/MAC addresses.
:* Use strong authentication or complex passwords for logins.
:* Enable encrypted data transmission.
:* Enable account lockout after a certain number of failed login attempts.
:* Configure the system so a remote user must establish a Virtual Private Network ("VPN") connection via a firewall before access is allowed.
:* Enable any logging or auditing functions.
:* Restrict access to customer passwords to authorized reseller/integrator personnel.
:* Establish customer passwords according to PCI DSS requirements.
Qualiteam does not provide software updates via remote access on an automated basis.
 

==Hardware and software==
The following requirements must be met for X-Cart Payments payment application self-service terminals: 
'''Operating System''' 
Linux Ubuntu 16 or later, Linux Debian 6.0 or later, Linux CentOS 6 or later 
'''DBMS''' 
My SQL 5.6 or later 
'''Software''' 
PHP 5.5 or later 
Apache 2.4 or later
 

==Product versioning methodology==
{| class="wikitable" width=90%
|-
! scope="col" style="width: 15%;"| '''Version number changes'''
! scope="col" style="width: 45%;"| '''Software changes'''
! scope="col" style="width: 15%;"| '''Description'''
! scope="col" style="width: 15%;"| '''PA-DSS changes'''
|- style="vertical-align:top;"
| Version number does not change
| Change of the software name Change of the vendor name
| Changes not related to the software development process
| Administrative
|- style="vertical-align:top;"
| Increment of the minor version number to reflect a change not affecting the certification. For example, change of the version number from 1.0.5 to 1.0.6 (for the certification of 1.0.x)
| - Changes to the user interface - Changes to the database schema - Changes to supported payment gateway integrations / Addition of new payment gateway integrations
| Changes that have no impact on the PA-DSS requirements compliance or Payment Application security
| No Impact
|- style="vertical-align:top;"
| Increment of the second version number. For example, change of the version number from 1.1.* to 1.2.*
| Software changes satisfy the following conditions: - Fewer than 4 sections of the standard (from 1 to 12) involved; - Fewer than a half of all the requirements of the standard (sections 1 to 12) involved; - Less than a half of the software functions (or code) modified; - Changes implemented for compatibility with the updated versions of previously tested OS, DBMS and third party software products. - Addition/removal of supported payment processors. - Recompilation of the source code using a new compiler or different compiler settings. - Changes of the software versioning policy. - Changes of the software not related to security.
| - Changes in the software affecting payment card data mechanisms. - Changes addressing the identified vulnerabilities of the application. - Changes related to the completion of the annual cycle of development (if there are other changes).
| Low Impact
|- style="vertical-align:top;"
| Increment of the first version number. For example, change of the version number from 1.0.* to 2.0.*
| Software changes satisfy the following conditions: - 4 or more sections of the standard (from 1 to 12) involved; - More than a half of all the requirements of the standard (sections 1 to 12) involved; - More than a half of the software functions (or code) modified; - Addition of new supported platforms/OS versions.
| Major changes in the software architecture, global alterations of code
| High Impact
|}
 
The release of each new version is accompanied with a notification to all the application users (agents), which indicates the new application version number and a list of main changes in the new version.
 

==New patches and updates delivery==

New patches, updates, installation instructions and MD5 checksum files are delivered via secure HelpDesk system located at https://secure.x-cart.com using "File Area" section in users accounts there.
We send newsletters about new patches and updates originating from x-cart.com domain name via verified and well-known email delivery system.

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PA-DSS implementation guide for X-Cart Payments 3

2017-07-19T12:18:38Z

Alex Mulin: /* Logging */

==Introduction==
The purpose of this PA-DSS Implementation Guide is to inform employees of organizations using the X-Cart Payments payment application by Qualiteam Software Limited about the methods and means of protection of account data in the X-Cart Payments software.
 
The methods include the need for compliance with the information security standards in the payment card industry developed by the international payment systems Visa and MasterCard - Payment Card Industry Data Security Standard (PCI DSS) and Payment Application Data Security Standard (PA-DSS). For additional information about PCI DSS, please visit the [https://www.pcisecuritystandards.org/ Official PCI Security Standards Council Site].
 
The document provides instructions on how to implement the application in a PCI DSS compliant manner.
 
Full product name - X-Cart Payments. 
Product version - 3.1.x.
 
Any servers used to run the X-Cart Payments payment application must be configured according to this PA-DSS Implementation Guide.
 
This PA-DSS Implementation Guide should be updated:
:* at least annually;
:* after changes in the payment application (if required);
:* after changes in the PCI DSS and PA-DSS standards.
 
The updated Version of the PA-DSS Implementation Guide has to be sent to all the merchants using X-Cart Payments.
 
The history of changes to the X-Cart Payments PA-DSS Implementation Guide is provided in the table below.
 
'''Table.1. X-Cart Payments PA-DSS Implementation Guide history of changes''' 
{| class="wikitable" width=90%
|-
! scope="col" style="width: 10%;"| '''Author'''
! scope="col" style="width: 10%;"| '''Date'''
! scope="col" style="width: 10%;"| '''Number'''
! scope="col" style="width: 60%;"| '''Change description'''
|- style="vertical-align:top;"
| Alex Mulin
| 05/17/2016
| 01
| The original version of the document, designed to meet the requirements of PCI DSS version 3.1 and PA DSS version 3.1
|-
| Alex Mulin
| 05/17/2017
| 02
| The original version of the document, designed to meet the requirements of PCI DSS version 3.2 and PA DSS version 3.2
|-
|}
 

==Data protection==
The PCI DSS and PA-DSS standards prohibit storage of sensitive authentication data (after authorization) or cardholder data in cleartext. 
Cardholder data includes:
:* Primary Account Number (PAN)
:* Cardholder Name
:* Expiration Date
:* Service Code
 
Sensitive authentication data (SAD) includes:
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
 
X-Cart Payments has the ability to store parts of cardholder data temporarily to perform 3D Secure verification and certain types of transactions for some of the integrated payment processors. During storage, cardholder data is encrypted using RSA 2048 algorithm and AES 256 for key encryption. When its storage period is over, the data is removed automatically via "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.
 
X-Cart Payments may not be configured to store permanently in the database the following types of data:
:* Full PAN
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature.
 
The payment application masks PAN on display (except for the moment when the user enters the card number).
X-Cart Payments can display masked PAN on the "Payment details" pages and in the "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. The same data (partially masked with asterisks) may be passed via the API to the integrated software products. X-Cart Payments does not have the ability to display full PAN anywhere, and there are no settings that can change this behavior of the user interface.
 

==Data Collected while Testing==
Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:
# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever choose to collect credit card information to troubleshoot a problem that a customer of yours is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access.
#* Only collect a limited amount of data (no more than is needed to solve the problem).
#* Sensitive authentication data must be encrypted during storage. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Sensitive authentication data must be securely deleted immediately after use.
To prevent uncontrolled storage of cardholder data (for example, in case of operating system failure), it is recommended to disable the swap file or move it to a specially prepared encrypted partition.
 
==Authentication and access==
The X-Cart Payments payment application has an only user type. This type cannot get access to payment card numbers and does not have any administrative privileges that may affect PA-DSS compliance.
There are no built-in/default user accounts in X-Cart Payments. You must carefully control access to X-Cart Payments. Follow these rules:
:* Restrict the number of employees who have access to X-Cart Payments to only those who have a business need.
:* Always provide unique usernames for each person who needs access.
:* Do not use system-default usernames and/or passwords.
:* Ensure that web server is run under a non-privileged user account and the application has access to the database from a limited privilege user account.
 
To set password lifetime:
# Log in to X-Cart Payments.
# Go to Settings -> General Settings.
# In the "User account password lifetime" field, enter the number of days for which the user account password needs to be valid. The maximum allowed password lifetime is 90 days.
The following related rules apply:
:* The minimum password length is 8 characters.
:* A password must contain both numbers and lower- and uppercase characters.
:* The last 4 passwords must be unique.
:* A user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password.
:* A user is logged off after an inactivity period of 15 minutes.
 
PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:
:* For your Web hosting account administration area (Web hosting account where your online store is hosted);
:* For FTP access to the Web server;
:* For Remote Desktop Connection to the Web server (if available);
:* To connect to the MySQL server that contains your store data.
 
Linux authentication mechanism is used for login in the servers with running X-Cart Payments.
Accounts for access to the operating system are managed by the Linux administrator.
For Linux operating system accounts, you must configure the following attributes of the password policy:
:* use personal accounts, do not use any group, shared, or generic accounts and passwords;
:* changes to user passwords at least once every 90 days;
:* require a minimum length of at least seven characters;
:* contain both numeric and alphabetic characters;
:* do not use last four passwords used previously;
:* block account after six invalid logon attempts (minimum 30 minutes or until an administrator enables the user ID).
 
Two-factor authentication must be used for remote access to the operating system. The authentication methods, also known as factors, are:
:* something you know, such as a password or a passphrase;
:* something you have, such as a token device or a smart card;
:* something you are, such as a biometric.
 

== Logging==
Audit trails are automatically enabled with the default installation of X-Cart Payments. Users do not have the ability to disable or change the logging parameters of X-Cart Payments. X-Cart Payments log journal does not contain cardholder data. It is implemented at the source code level. The setting of an event log journal does not require any additional action from users.
The log files are created in the var/log/ directory. In X-Cart Payments 3.1, logs can be viewed via the X-Cart Payments admin back end. Make sure you restrict access to the log files by business need-to-know.
The following types of activity are logged:
:* All actions taken by any individual with root or administrative privileges.
:* Successes and failures of all individual accesses to application sections and functions.
:* Initialization of the audit logs.
:* User sign in and sign out.
 
Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to the files access.log and error.log.
Each log event includes:
:* Type of event;
:* Date and time of event;
:* Username and IP address;
:* Success or failure indication;
:* Action which led to the event;
:* Component which led to the event.
 
There is also a meta-log which contains information about other log files being created.
Make sure you have a system-level auditing software properly configured to monitor users' activity on the server. This software should:
:* warn on a checksum change of any of X-Cart Payments source code files except for the log file and the database files;
:* record any file writing operations related to X-Cart Payments files.
 

==Communication==
LAN channel or other available connection method can be used as a communication channel.
X-Cart Payments payment application supports the following data formats:
{| class="wikitable" width=90%
|-
| scope="col" style="width: 20%;"| '''Protocol'''
| scope="col" style="width: 70%;"| HTTP protocol (RFC 2616: HTTP/1.1) is used for data transfer between client and server
|- style="vertical-align:top;"
| '''Data transmission method'''
| Only encrypted cardholder data (RSA 2048 and AES 256) is transferred. RAW POST method is used for data transmission - (data stream is transmitted in the body of the request that is sent from client to server)
|- style="vertical-align:top;"
| '''Data format'''
| Data is transmitted in XML format (Extensible Markup Language (XML) 1.0) or in plain text using POST query via HTTPS
|- style="vertical-align:top;"
| '''Port'''
| X-Cart Payments payment application uses ports 80, 443
|-
|}
 
'''Network traffic encryption''' 
X-Cart Payments uses encryption, such as TLS or IPSEC, for:
:* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
:* providing remote web-based access to the application.
 
If you use some tools to remotely access the application, you should encrypt all the communication using such technologies as TLS or IPSEC.
 
As per PCI DSS requirement, cardholder data must never be sent unencrypted by email, and X-Cart Payments does meet this requirement never sending cardholder data by email or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.
 
'''Enable TLS''' 
TLS protects data that is transmitted between a browser and your web server. It is critical that you have TLS enabled on your web server, and one of the first steps you should take after the installation is to enable TLS.
:* Your web server must be configured to use TLS v1.1 or v1.2 protocols with strong encryption (128-bit or longer key is required).
:* You will need to have a certificate issued for your web domain. Read guidelines on installing Comodo's Instant TLS certificates.
 
If a web server does not have TLS enabled, X-Cart Payments will not function.
X-Cart Payments does not support remote administrative access. Strong encryption must be used for remote access to the server.
The connection of servers with X-Cart Payments payment application to the Internet must be protected by a firewall. In X-Cart Payments configurations involving more than one server, server connections should take place in network segments separated from the Internet via stateful inspection firewalls.
 
'''Wireless communications''' 
If you use wireless networking to access X-Cart Payments, it is your responsibility to ensure your wireless security configuration follows the PCI DSS requirements.
:* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
:* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
:* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
:* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
::* Use with a minimum 104-bit encryption key and 24 bit-initialization value.
::* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS.
::* Rotate shared WEP keys quarterly (or automatically if the technology permits).
::* Rotate shared WEP keys whenever there are changes in personnel with access to keys.
::* Restrict access based on media access code (MAC) address.
::* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.
 
'''Remote access''' 
X-Cart Payments provides web-based access using two-factor authentication based on one-time codes. Detailed information can be found on the [[X-Payments:Two-factor_authentication | X-Payments:Two-factor authentication]] page.
If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:
:* Change the default settings in the remote access software (for example, change the default passwords and use unique passwords for each customer).
:* Allow connections only from specific (known) IP/MAC addresses.
:* Use strong authentication or complex passwords for logins.
:* Enable encrypted data transmission.
:* Enable account lockout after a certain number of failed login attempts.
:* Configure the system so a remote user must establish a Virtual Private Network ("VPN") connection via a firewall before access is allowed.
:* Enable any logging or auditing functions.
:* Restrict access to customer passwords to authorized reseller/integrator personnel.
:* Establish customer passwords according to PCI DSS requirements.
Qualiteam does not provide software updates via remote access on an automated basis.
 

==Hardware and software==
The following requirements must be met for X-Cart Payments payment application self-service terminals: 
'''Operating System''' 
Linux Ubuntu 16 or later, Linux Debian 6.0 or later, Linux CentOS 6 or later 
'''DBMS''' 
My SQL 5.6 or later 
'''Software''' 
PHP 5.5 or later 
Apache 2.4 or later
 

==Product versioning methodology==
{| class="wikitable" width=90%
|-
! scope="col" style="width: 15%;"| '''Version number changes'''
! scope="col" style="width: 45%;"| '''Software changes'''
! scope="col" style="width: 15%;"| '''Description'''
! scope="col" style="width: 15%;"| '''PA-DSS changes'''
|- style="vertical-align:top;"
| Version number does not change
| Change of the software name Change of the vendor name
| Changes not related to the software development process
| Administrative
|- style="vertical-align:top;"
| Increment of the minor version number to reflect a change not affecting the certification. For example, change of the version number from 1.0.5 to 1.0.6 (for the certification of 1.0.x)
| - Changes to the user interface - Changes to the database schema - Changes to supported payment gateway integrations / Addition of new payment gateway integrations
| Changes that have no impact on the PA-DSS requirements compliance or Payment Application security
| No Impact
|- style="vertical-align:top;"
| Increment of the second version number. For example, change of the version number from 1.1.* to 1.2.*
| Software changes satisfy the following conditions: - Fewer than 4 sections of the standard (from 1 to 12) involved; - Fewer than a half of all the requirements of the standard (sections 1 to 12) involved; - Less than a half of the software functions (or code) modified; - Changes implemented for compatibility with the updated versions of previously tested OS, DBMS and third party software products. - Addition/removal of supported payment processors. - Recompilation of the source code using a new compiler or different compiler settings. - Changes of the software versioning policy. - Changes of the software not related to security.
| - Changes in the software affecting payment card data mechanisms. - Changes addressing the identified vulnerabilities of the application. - Changes related to the completion of the annual cycle of development (if there are other changes).
| Low Impact
|- style="vertical-align:top;"
| Increment of the first version number. For example, change of the version number from 1.0.* to 2.0.*
| Software changes satisfy the following conditions: - 4 or more sections of the standard (from 1 to 12) involved; - More than a half of all the requirements of the standard (sections 1 to 12) involved; - More than a half of the software functions (or code) modified; - Addition of new supported platforms/OS versions.
| Major changes in the software architecture, global alterations of code
| High Impact
|}
 
The release of each new version is accompanied with a notification to all the application users (agents), which indicates the new application version number and a list of main changes in the new version.
 

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PA-DSS implementation guide for X-Cart Payments 3

2017-07-19T12:18:00Z

Alex Mulin:

==Introduction==
The purpose of this PA-DSS Implementation Guide is to inform employees of organizations using the X-Cart Payments payment application by Qualiteam Software Limited about the methods and means of protection of account data in the X-Cart Payments software.
 
The methods include the need for compliance with the information security standards in the payment card industry developed by the international payment systems Visa and MasterCard - Payment Card Industry Data Security Standard (PCI DSS) and Payment Application Data Security Standard (PA-DSS). For additional information about PCI DSS, please visit the [https://www.pcisecuritystandards.org/ Official PCI Security Standards Council Site].
 
The document provides instructions on how to implement the application in a PCI DSS compliant manner.
 
Full product name - X-Cart Payments. 
Product version - 3.1.x.
 
Any servers used to run the X-Cart Payments payment application must be configured according to this PA-DSS Implementation Guide.
 
This PA-DSS Implementation Guide should be updated:
:* at least annually;
:* after changes in the payment application (if required);
:* after changes in the PCI DSS and PA-DSS standards.
 
The updated Version of the PA-DSS Implementation Guide has to be sent to all the merchants using X-Cart Payments.
 
The history of changes to the X-Cart Payments PA-DSS Implementation Guide is provided in the table below.
 
'''Table.1. X-Cart Payments PA-DSS Implementation Guide history of changes''' 
{| class="wikitable" width=90%
|-
! scope="col" style="width: 10%;"| '''Author'''
! scope="col" style="width: 10%;"| '''Date'''
! scope="col" style="width: 10%;"| '''Number'''
! scope="col" style="width: 60%;"| '''Change description'''
|- style="vertical-align:top;"
| Alex Mulin
| 05/17/2016
| 01
| The original version of the document, designed to meet the requirements of PCI DSS version 3.1 and PA DSS version 3.1
|-
| Alex Mulin
| 05/17/2017
| 02
| The original version of the document, designed to meet the requirements of PCI DSS version 3.2 and PA DSS version 3.2
|-
|}
 

==Data protection==
The PCI DSS and PA-DSS standards prohibit storage of sensitive authentication data (after authorization) or cardholder data in cleartext. 
Cardholder data includes:
:* Primary Account Number (PAN)
:* Cardholder Name
:* Expiration Date
:* Service Code
 
Sensitive authentication data (SAD) includes:
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
 
X-Cart Payments has the ability to store parts of cardholder data temporarily to perform 3D Secure verification and certain types of transactions for some of the integrated payment processors. During storage, cardholder data is encrypted using RSA 2048 algorithm and AES 256 for key encryption. When its storage period is over, the data is removed automatically via "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.
 
X-Cart Payments may not be configured to store permanently in the database the following types of data:
:* Full PAN
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature.
 
The payment application masks PAN on display (except for the moment when the user enters the card number).
X-Cart Payments can display masked PAN on the "Payment details" pages and in the "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. The same data (partially masked with asterisks) may be passed via the API to the integrated software products. X-Cart Payments does not have the ability to display full PAN anywhere, and there are no settings that can change this behavior of the user interface.
 

==Data Collected while Testing==
Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:
# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever choose to collect credit card information to troubleshoot a problem that a customer of yours is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access.
#* Only collect a limited amount of data (no more than is needed to solve the problem).
#* Sensitive authentication data must be encrypted during storage. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Sensitive authentication data must be securely deleted immediately after use.
To prevent uncontrolled storage of cardholder data (for example, in case of operating system failure), it is recommended to disable the swap file or move it to a specially prepared encrypted partition.
 
==Authentication and access==
The X-Cart Payments payment application has an only user type. This type cannot get access to payment card numbers and does not have any administrative privileges that may affect PA-DSS compliance.
There are no built-in/default user accounts in X-Cart Payments. You must carefully control access to X-Cart Payments. Follow these rules:
:* Restrict the number of employees who have access to X-Cart Payments to only those who have a business need.
:* Always provide unique usernames for each person who needs access.
:* Do not use system-default usernames and/or passwords.
:* Ensure that web server is run under a non-privileged user account and the application has access to the database from a limited privilege user account.
 
To set password lifetime:
# Log in to X-Cart Payments.
# Go to Settings -> General Settings.
# In the "User account password lifetime" field, enter the number of days for which the user account password needs to be valid. The maximum allowed password lifetime is 90 days.
The following related rules apply:
:* The minimum password length is 8 characters.
:* A password must contain both numbers and lower- and uppercase characters.
:* The last 4 passwords must be unique.
:* A user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password.
:* A user is logged off after an inactivity period of 15 minutes.
 
PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:
:* For your Web hosting account administration area (Web hosting account where your online store is hosted);
:* For FTP access to the Web server;
:* For Remote Desktop Connection to the Web server (if available);
:* To connect to the MySQL server that contains your store data.
 
Linux authentication mechanism is used for login in the servers with running X-Cart Payments.
Accounts for access to the operating system are managed by the Linux administrator.
For Linux operating system accounts, you must configure the following attributes of the password policy:
:* use personal accounts, do not use any group, shared, or generic accounts and passwords;
:* changes to user passwords at least once every 90 days;
:* require a minimum length of at least seven characters;
:* contain both numeric and alphabetic characters;
:* do not use last four passwords used previously;
:* block account after six invalid logon attempts (minimum 30 minutes or until an administrator enables the user ID).
 
Two-factor authentication must be used for remote access to the operating system. The authentication methods, also known as factors, are:
:* something you know, such as a password or a passphrase;
:* something you have, such as a token device or a smart card;
:* something you are, such as a biometric.
 

== Logging==
Audit trails are automatically enabled with the default installation of X-Cart Payments. Users do not have the ability to disable or change the logging parameters of X-Cart Payments. X-Cart Payments log journal does not contain cardholder data. It is implemented at the source code level. The setting of an event log journal does not require any additional action from users.
The log files are created in the var/log/ directory. In X-Cart Payments 3.0, logs can be viewed via the X-Cart Payments admin back end. Make sure you restrict access to the log files by business need-to-know.
The following types of activity are logged:
:* All actions taken by any individual with root or administrative privileges.
:* Successes and failures of all individual accesses to application sections and functions.
:* Initialization of the audit logs.
:* User sign in and sign out.
 
Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to the files access.log and error.log.
Each log event includes:
:* Type of event;
:* Date and time of event;
:* Username and IP address;
:* Success or failure indication;
:* Action which led to the event;
:* Component which led to the event.
 
There is also a meta-log which contains information about other log files being created.
Make sure you have a system-level auditing software properly configured to monitor users' activity on the server. This software should:
:* warn on a checksum change of any of X-Cart Payments source code files except for the log file and the database files;
:* record any file writing operations related to X-Cart Payments files.
 

==Communication==
LAN channel or other available connection method can be used as a communication channel.
X-Cart Payments payment application supports the following data formats:
{| class="wikitable" width=90%
|-
| scope="col" style="width: 20%;"| '''Protocol'''
| scope="col" style="width: 70%;"| HTTP protocol (RFC 2616: HTTP/1.1) is used for data transfer between client and server
|- style="vertical-align:top;"
| '''Data transmission method'''
| Only encrypted cardholder data (RSA 2048 and AES 256) is transferred. RAW POST method is used for data transmission - (data stream is transmitted in the body of the request that is sent from client to server)
|- style="vertical-align:top;"
| '''Data format'''
| Data is transmitted in XML format (Extensible Markup Language (XML) 1.0) or in plain text using POST query via HTTPS
|- style="vertical-align:top;"
| '''Port'''
| X-Cart Payments payment application uses ports 80, 443
|-
|}
 
'''Network traffic encryption''' 
X-Cart Payments uses encryption, such as TLS or IPSEC, for:
:* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
:* providing remote web-based access to the application.
 
If you use some tools to remotely access the application, you should encrypt all the communication using such technologies as TLS or IPSEC.
 
As per PCI DSS requirement, cardholder data must never be sent unencrypted by email, and X-Cart Payments does meet this requirement never sending cardholder data by email or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.
 
'''Enable TLS''' 
TLS protects data that is transmitted between a browser and your web server. It is critical that you have TLS enabled on your web server, and one of the first steps you should take after the installation is to enable TLS.
:* Your web server must be configured to use TLS v1.1 or v1.2 protocols with strong encryption (128-bit or longer key is required).
:* You will need to have a certificate issued for your web domain. Read guidelines on installing Comodo's Instant TLS certificates.
 
If a web server does not have TLS enabled, X-Cart Payments will not function.
X-Cart Payments does not support remote administrative access. Strong encryption must be used for remote access to the server.
The connection of servers with X-Cart Payments payment application to the Internet must be protected by a firewall. In X-Cart Payments configurations involving more than one server, server connections should take place in network segments separated from the Internet via stateful inspection firewalls.
 
'''Wireless communications''' 
If you use wireless networking to access X-Cart Payments, it is your responsibility to ensure your wireless security configuration follows the PCI DSS requirements.
:* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
:* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
:* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
:* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
::* Use with a minimum 104-bit encryption key and 24 bit-initialization value.
::* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS.
::* Rotate shared WEP keys quarterly (or automatically if the technology permits).
::* Rotate shared WEP keys whenever there are changes in personnel with access to keys.
::* Restrict access based on media access code (MAC) address.
::* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.
 
'''Remote access''' 
X-Cart Payments provides web-based access using two-factor authentication based on one-time codes. Detailed information can be found on the [[X-Payments:Two-factor_authentication | X-Payments:Two-factor authentication]] page.
If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:
:* Change the default settings in the remote access software (for example, change the default passwords and use unique passwords for each customer).
:* Allow connections only from specific (known) IP/MAC addresses.
:* Use strong authentication or complex passwords for logins.
:* Enable encrypted data transmission.
:* Enable account lockout after a certain number of failed login attempts.
:* Configure the system so a remote user must establish a Virtual Private Network ("VPN") connection via a firewall before access is allowed.
:* Enable any logging or auditing functions.
:* Restrict access to customer passwords to authorized reseller/integrator personnel.
:* Establish customer passwords according to PCI DSS requirements.
Qualiteam does not provide software updates via remote access on an automated basis.
 

==Hardware and software==
The following requirements must be met for X-Cart Payments payment application self-service terminals: 
'''Operating System''' 
Linux Ubuntu 16 or later, Linux Debian 6.0 or later, Linux CentOS 6 or later 
'''DBMS''' 
My SQL 5.6 or later 
'''Software''' 
PHP 5.5 or later 
Apache 2.4 or later
 

==Product versioning methodology==
{| class="wikitable" width=90%
|-
! scope="col" style="width: 15%;"| '''Version number changes'''
! scope="col" style="width: 45%;"| '''Software changes'''
! scope="col" style="width: 15%;"| '''Description'''
! scope="col" style="width: 15%;"| '''PA-DSS changes'''
|- style="vertical-align:top;"
| Version number does not change
| Change of the software name Change of the vendor name
| Changes not related to the software development process
| Administrative
|- style="vertical-align:top;"
| Increment of the minor version number to reflect a change not affecting the certification. For example, change of the version number from 1.0.5 to 1.0.6 (for the certification of 1.0.x)
| - Changes to the user interface - Changes to the database schema - Changes to supported payment gateway integrations / Addition of new payment gateway integrations
| Changes that have no impact on the PA-DSS requirements compliance or Payment Application security
| No Impact
|- style="vertical-align:top;"
| Increment of the second version number. For example, change of the version number from 1.1.* to 1.2.*
| Software changes satisfy the following conditions: - Fewer than 4 sections of the standard (from 1 to 12) involved; - Fewer than a half of all the requirements of the standard (sections 1 to 12) involved; - Less than a half of the software functions (or code) modified; - Changes implemented for compatibility with the updated versions of previously tested OS, DBMS and third party software products. - Addition/removal of supported payment processors. - Recompilation of the source code using a new compiler or different compiler settings. - Changes of the software versioning policy. - Changes of the software not related to security.
| - Changes in the software affecting payment card data mechanisms. - Changes addressing the identified vulnerabilities of the application. - Changes related to the completion of the annual cycle of development (if there are other changes).
| Low Impact
|- style="vertical-align:top;"
| Increment of the first version number. For example, change of the version number from 1.0.* to 2.0.*
| Software changes satisfy the following conditions: - 4 or more sections of the standard (from 1 to 12) involved; - More than a half of all the requirements of the standard (sections 1 to 12) involved; - More than a half of the software functions (or code) modified; - Addition of new supported platforms/OS versions.
| Major changes in the software architecture, global alterations of code
| High Impact
|}
 
The release of each new version is accompanied with a notification to all the application users (agents), which indicates the new application version number and a list of main changes in the new version.
 

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:X-Payments-Hosted-FAQ

2017-05-31T09:24:54Z

Alex Mulin: /* What do I need to put as "Callback IP"? */

===What do I need to put as "Callback IP"?===

If you use the X-Payments Hosted solution at "*.x-checkout.com" domain you should use IP address '''98.142.211.162''' (if your account is based on X-Payments v1.x or v2.x) or '''104.200.146.25''' (if X-Payments v3.x).

If you use X-Payments Hosted at "*.xpayments.com" domain you need to specify '''52.36.122.200'''.

===How to configure an FTP client to connect to the yourdomain.x-checkout.com to access skins and logs?===

X-Payments 3.x does not support FTP connections. You can use XP 3.x admin back-end to access skins and logs in this version.

The instructions below are valid only for X-Payments versions 2.x and earlier.

To establish an FTP connection, you should use the details from the email received when your account was created:

:* host: yourdomain.x-checkout.com 
:* user: skins@yourdomain.x-checkout.com 
:* password: the one that you've received 

Please make sure that the "Explicit FTP over TLS" mode is used. This is required because plain text authentication is not allowed for PCI compliance.

Instructions for FileZilla FTP Client:

# Start FileZilla
# Go to File -> Site Manager
# Click New site
# Enter the connection settings:
#* Host: yourdomain.x-checkout.com 
#* Port: leave blank 
#* Protocol: FTP - File Transfer Protocol 
#* Encryption: Require explict FTP over TLS 
#* Logon type: Normal 
#* user: skins@yourdomain.x-checkout.com 
#* password: the one that you've received [[File:Filezilla.png]] 
# Click the Connect button

[[Category:X-Payments User Manual]]

X-Payments:X-Payments-Hosted-FAQ

2017-05-31T08:26:18Z

Alex Mulin: /* What do I need to put as "Callback IP"? */

===What do I need to put as "Callback IP"?===

If you use the X-Payments Hosted solution at "*.x-checkout.com" domain you should use IP address '''98.142.211.162''' if your account is based on X-Payments v1.x or v2.x or '''104.200.146.25''' if X-Payments v3.x
If you use X-Payments Hosted at "*.xpayments.com" domain you need to specify '''52.36.122.200'''.

===How to configure an FTP client to connect to the yourdomain.x-checkout.com to access skins and logs?===

X-Payments 3.x does not support FTP connections. You can use XP 3.x admin back-end to access skins and logs in this version.

The instructions below are valid only for X-Payments versions 2.x and earlier.

To establish an FTP connection, you should use the details from the email received when your account was created:

:* host: yourdomain.x-checkout.com 
:* user: skins@yourdomain.x-checkout.com 
:* password: the one that you've received 

Please make sure that the "Explicit FTP over TLS" mode is used. This is required because plain text authentication is not allowed for PCI compliance.

Instructions for FileZilla FTP Client:

# Start FileZilla
# Go to File -> Site Manager
# Click New site
# Enter the connection settings:
#* Host: yourdomain.x-checkout.com 
#* Port: leave blank 
#* Protocol: FTP - File Transfer Protocol 
#* Encryption: Require explict FTP over TLS 
#* Logon type: Normal 
#* user: skins@yourdomain.x-checkout.com 
#* password: the one that you've received [[File:Filezilla.png]] 
# Click the Connect button

[[Category:X-Payments User Manual]]

Blog

2017-04-26T12:34:22Z

Alex Mulin: Created page with "X-Payments blog"

X-Payments blog

X-Payments:X-Payments-Hosted-FAQ

2017-04-20T13:25:53Z

Alex Mulin: /* How to configure an FTP client to connect to the yourdomain.x-checkout.com to access skins and logs? */

===What do I need to put as "Callback IP"?===

If you use the X-Payments Hosted solution at "*.x-checkout.com" domain you should use IP address '''98.142.211.162''' if your account is based on X-Payments v1.x or v2.x or '''104.200.146.25''' if X-Payments v3.x
If you use X-Payments Hosted at "*.xpayments.com" domain you need to specify 52.36.122.200.

===How to configure an FTP client to connect to the yourdomain.x-checkout.com to access skins and logs?===

X-Payments 3.x does not support FTP connections. You can use XP 3.x admin back-end to access skins and logs in this version.

The instructions below are valid only for X-Payments versions 2.x and earlier.

To establish an FTP connection, you should use the details from the email received when your account was created:

:* host: yourdomain.x-checkout.com 
:* user: skins@yourdomain.x-checkout.com 
:* password: the one that you've received 

Please make sure that the "Explicit FTP over TLS" mode is used. This is required because plain text authentication is not allowed for PCI compliance.

Instructions for FileZilla FTP Client:

# Start FileZilla
# Go to File -> Site Manager
# Click New site
# Enter the connection settings:
#* Host: yourdomain.x-checkout.com 
#* Port: leave blank 
#* Protocol: FTP - File Transfer Protocol 
#* Encryption: Require explict FTP over TLS 
#* Logon type: Normal 
#* user: skins@yourdomain.x-checkout.com 
#* password: the one that you've received [[File:Filezilla.png]] 
# Click the Connect button

[[Category:X-Payments User Manual]]

X-Payments:X-Payments-Hosted-FAQ

2017-04-20T13:22:52Z

Alex Mulin:

===What do I need to put as "Callback IP"?===

If you use the X-Payments Hosted solution at "*.x-checkout.com" domain you should use IP address '''98.142.211.162''' if your account is based on X-Payments v1.x or v2.x or '''104.200.146.25''' if X-Payments v3.x
If you use X-Payments Hosted at "*.xpayments.com" domain you need to specify 52.36.122.200.

===How to configure an FTP client to connect to the yourdomain.x-checkout.com to access skins and logs?===

X-Payments 3.x does not support FTP connections. The instructions below are valid only for X-Payments versions 2.x and earlier.

To establish an FTP connection, you should use the details from the email received when your account was created:

:* host: yourdomain.x-checkout.com 
:* user: skins@yourdomain.x-checkout.com 
:* password: the one that you've received 

Please make sure that the "Explicit FTP over TLS" mode is used. This is required because plain text authentication is not allowed for PCI compliance.

Instructions for FileZilla FTP Client:

# Start FileZilla
# Go to File -> Site Manager
# Click New site
# Enter the connection settings:
#* Host: yourdomain.x-checkout.com 
#* Port: leave blank 
#* Protocol: FTP - File Transfer Protocol 
#* Encryption: Require explict FTP over TLS 
#* Logon type: Normal 
#* user: skins@yourdomain.x-checkout.com 
#* password: the one that you've received [[File:Filezilla.png]] 
# Click the Connect button

[[Category:X-Payments User Manual]]

X-Payments:How It Works

2016-12-20T11:04:13Z

Alex “Ambal” Mulin:

<noinclude>{{XP_manual_TOC}}</noinclude>

==X-Payments flow via diagram==
:[[File:XP-diagram.png|700px|border]]

===API Call===

1) Store initiates an API call to X-Payments to create a payment (Created payments can be [[X-Payments:User_manual#Viewing_Payments|viewed]] on the 'Payments' page in X-Payments back end). At this step store sends to X-Payments all information about the customer (billing and shipping address) and the products being purchased (product quantities and cost). In addition to that, store instructs X-Payments as to which payment configuration should be used.

2) X-Payments validates this initial request from the store: checks whether the requested [[X-Payments:User_manual#Payment_Configurations|payment configuration]] is [[X-Payments:Managing store connections#Editing Online Store Details|active]], whether the payment currency passed on to X-Payments by the store matches the currency specified in the respective payment configuration in X-Payments, and makes some other internal checks; for instance, a check is conducted to ensure that the template files for the page where customers enter cardholder data have not been modified without approval by X-Payments admin. If everything is fine, X-Payments returns a [[X-Payments:API#Response_specification | payment "token"]] to the store (The token serves as a temporary identifier of the payment in X-Payments; it is generated as a result of the API call and is removed after the customer is redirected back to the store when the payment is completed). If a problem is detected, no token is sent to the store, and an internal error is generated in X-Payments. Detailed information about such errors can be found in the X-Payments and X-Cart logs: 
* X-Payments: See the <xpay-dir>/var/log/api/YYYY-MM-DD/ directory
* X-Cart: See the <xcart-dir>/var/log/x-errors_xpay_connector-YYMMDD.php file

===Payment===

3) Customer is redirected to the X-Payments secure page where the form for entering credit card details is located. If the iframe is used, this redirect is not visible to customer, as the form is embedded into the checkout page.

4) Customer enters credit card details and submits the form. These details are sent to the payment gateway along with other data previously received by X-Payments (address details, products being purchased, etc).

5) Payment gateway operates with the bank to charge the card (or authorize the funds in case of an "auth only" transaction) and sends back to X-Payments the information about the transaction.

The log of communication between X-Payments and the payment gateway can be found in the <xpay-dir>/var/log/payment/YYYY-MM-DD/ directory.

===Callback from gateway (PayPal) to X-Payments===

6) Some payment gateways also send back to X-Payments an additional "callback" request. This "callback" request provides detailed information about the transaction and also helps to validate/confirm the transaction. Currently only PayPal Payments PRO operates in X-Payments in such a way. As an additional protection, X-Payments allows you to specify the IP addresses from which the gateway's callback requests can be received. Provided with a list of trusted Call-back IPs for PayPal, X-Payments will only accept "callback" requests coming from PayPal's server and ignore all other requests coming from anywhere else, should such requests be made. The list of PayPal's IP addresses can be found here: https://ppmts.custhelp.com/app/answers/detail/a_id/92
If you wish to use this additional protection, you can enter the necessary IP addresses into [[X-Payments:Configuring_PayPal_payment_modules_in_X-Payments#PayPalPaymentsProPayPalAPIconfsettings|PayPal payment configuration settings]] in X-Payments back end.

The log of payment gateway callback request processing is saved to the <xpay-dir>/var/log/callback/YYYY-MM-DD/ directory.

===Invoice===

7) Customer is redirected back to the store where the Invoice page is displayed.
If the transaction is declined by the payment gateway for some reason, the error page is displayed. Additional information about the reasons of the transaction being declined can be found in the X-Payments admin back end on the 'Payment details' page.

===Callback from X-Payments to the store===

8) Detailed information about the payment is sent to the store via a "callback" request.
The same functionality ("callback" requests) is used to notify the store if the payment has been changed via X-Payments admin back end; for example, if a secondary transaction took place ('Capture' or 'Void' for an authorized transaction, 'Refund' for a charge).

X-Cart allows additional protection for callback requests from X-Payments: thus you can specify the IP addresses for X-Payments callbacks in X-Payments connector module settings: http://help.x-cart.com/index.php?title=X-Cart:X-Payments_Connector. X-Cart will accept only those callback requests that come from the specified IP addresses, others will be ignored.

'''Important''': On some server configurations the IP address from which the callback request comes may not match the IP of the server where X-Payments is installed as illustrated below:

:[[File:XP-diagram1.png|700px|border]]

Even if X-Payments is installed on the 172.18.0.3 IP address, and is accessible via web by it, the outgoing request is received from the "proxy" of 172.18.0.0. So, it is recommended to verify the IP address for outgoing HTTPS connections with your hosting provider.

{{Note|If you use the '''X-Payments Hosted''' plan, you should use IP address '''98.142.211.162''' if your X-Payments account is v1.x or v2.x based or '''104.200.146.25''' if v3.x based.}}

The log of the X-Payments callback requests processing is saved to the following locations: 
* X-Cart: See the <xcart-dir>/var/log/x-errors_xpay_connector-YYMMDD.php file if any error occurred.
* X-Payments: See the <xpay-dir>/var/log/payment/YYYY-MM-DD/ directory for the initial Authorize or Sale (Authorize and Capture at the same time or Auto settle) transaction and <xpay-dir>/var/log/admin/YYYY-MM-DD/ directory for the secondary Capture, Void or Refund transaction.

[[Category:X-Payments User Manual]]

X-Payments:FAQ

2016-11-22T10:15:14Z

Alex “Ambal” Mulin: /* How to enable the use of TLS/SSL SMTP */

<noinclude>{{Template:XP manual TOC}}</noinclude>
==General==

===What is the X-Cart Payments service?===

X-Cart Payments is a SaaS (Software as a Service) solution allowing online merchants to use "on-site" or "merchant-hosted" credit card payment methods, like "Authorize.Net AIM", "SagePay - Direct integration", "FirstData Global Gateway - API", "PayPal Payments Pro - Direct Payment", and [[X-Payments:User_manual#Appendix_A._Supported_payment_gateways | many others]] in their integrated shopping carts.

The service includes:
* An account on a PCI DSS compliant web-hosting;
* An SSL certificate;
* A pre-installed and configured X-Payments application.

X-Payments (aka X-Cart Payments) is a PA-DSS validated application, a secure bridge between integrated shopping cart software and payment gateways. The application is hosted on a reliable and PCI DSS compliant web-hosting and is secured with SSL. It helps merchants to facilitate their overall PCI DSS compliance and to accept credit card payments securely.

Besides, X-Cart Payments makes it possible to accept credit card payments right on the checkout page in X-Cart (using the so-called [http://help.x-cart.com/index.php?title=X-Cart:IFrame_One-Step_Checkout_for_X-Payments iFrame One-Step Checkout] feature), while still providing a PCI DSS compliant payment solution for merchants. In other words, customers can pay without ever leaving your website and being redirected to the payment gateway site, in contrast to "off-site" payment methods like "PayPal Payments Standard", "Authorize.Net SIM", "SagePay - Form integration", "FirstData Global Gateway - Connect", etc. This can reassure customers and increase the conversion rates eventually, according to a [http://www.getelastic.com/single-vs-two-page-checkout/ research conducted by Getelastic.com].

Read more about X-Cart Payments on our website:
* http://www.x-cart.com/extensions/modules/xpayments.html
* http://www.x-cart.com/blog/new-xpayments-plans-introduced.html

===Which shopping cart software is compatible with X-Payments?===

X-Payments provides a [[X-Payments:API | web-based API]] allowing your store to submit or retrieve data. The shopping cart software you use for your store must support this API, which means you have to get an appropriate connector mod.

See the following pages for more info:

* [https://www.x-payments.com/help/X-Payments:Managing_store_connections#Connecting_an_Online_store How to connect an online store with X-Payments]
* [[X-Payments:API | X-Payments:API]]
* [http://help.x-cart.com/index.php?title=X-Cart:X-Payments_Connector X-Payments Connector]

===How can I obtain an X-Payments license===

X-Payments can be purchased at [http://www.x-cart.com/xpayments-pricing.html X-Cart website].

===How many stores can be connected to a single X-Payments installation?===

See details at [http://www.x-cart.com/xpayments-pricing.html X-Payments plans page]

===Can I transfer my X-Payments license and the software to a third party?===

It is possible for paid X-Payments downloadable licenses, but you need to get our written consent according to the terms and conditions of the [http://www.qtmsoft.com/xpayments-la.html license agreement].

==Installation and configuration==

===Why did you include PHP 5.3.0 into the '''X-Payments system''' '''requirements'''? It's relatively new, and many hosts aren't running it yet.===

According to PCI DSS '''Requirements''' (paragraph 6.1),

''>> 6.1 Ensure that all system components and software have the latest vendor-supplied security patches installed. Install critical security patches within one month of release.''

For PHP "the latest vendor-supplied security patches" means "the latest PHP version", because they do not supply patches. When we started to develop X-Payments, there were two stable versions of PHP available: 5.2.10 and 5.3.0. By the summer of 2010, the time PCI DSS compliance becomes a must, PHP 5.3.x will probably be as widely spread as 5.2.x now. That is why we decided to use some nice improvements of PHP 5.3.0.

===Can you tell me exactly what it is in v5.3.0 that's so necessary for X-Payments?===

The PHP development team has [http://www.php.net/archive/2010.php#id2010-12-16-1 announced] the end of support for PHP 5.2; therefore, 5.3 is going to be the earliest PHP version out there. We have used the newest features available in PHP 5.3 to make our software more current and eliminate the need to design and then certify it all over. Thus, PHP 5.3 features a more appropriate implementation of the Singleton pattern and allows to implement widget operations in the viewer using <tt>__invoke</tt>. It also offers numerous other functions that are handy but not available in PHP older than 5.3; for instance, array_replace, array_replace_recursive, etc.

===Can X-Payments be set up together with old [http://help.x-cart.com/index.php?title=X-Cart:Subscriptions Subscriptions] add-on module to automatically bill subscribers on a regular basis?===

No, it cannot. X-Cart's old [http://help.x-cart.com/index.php?title=X-Cart:Subscriptions Subscriptions] module is not compatible with X-Payments, and it is not PCI complaint.
The proper way is to use the new X-Payments Subscriptions module for [http://www.x-cart.com/extensions/modules/xpayments_subscriptions.html X-Cart 4] and [http://www.x-cart.com/extensions/addons/x-payments-subscriptions-and-installements.html X-Cart 5.]

===Why is it not possible to use blank database passwords in X-Payments configuration? That's not a problem for a production copy, but my test system doesn't use passwords usually===

According to PA-DSS '''requirements''' (paragraph 3.2),

''>> 3.2 Access to PCs, servers, and databases with payment applications must require a unique user ID and secure authentication.''

This means that a password must be used to access the database as well. X-Payments doesn't have a test mode, and all the '''requirements''' are checked on the fly as if it were a production copy. X-Payments won't start until all the '''requirements''' are met. That is how we guarantee that the software meets PA-DSS '''requirements'''. If there were a test mode, we would have to add another level of checking, and each such level decreases the security of the software "in the field". That is why we decided to go without some cool features but keep the high level of security.

===Can X-Payments be installed on server where my shopping cart software is hosted or do I need a separate web-server?===

Both options are allowed. X-Payments can be set up either together with your shopping cart software provided it is run in a separate PCI compliant hosting space/account or on a separate server (X-Payments uses SSL connection to exchange data with your store).

===Can X-Payments be installed on a shared hosting?===

Yes, provided that a separate account is used to host X-Payments. No other software must be installed and run under this account.

===Can I configure X-Payments to allow my customers to enter their billing address when entering their credit card data?===

No, you cannot. To edit the billing address, a customer has to go back to the store and edit the billing address in the customer profile at the store.

===How do I create a different skin for the page where customers enter their cardholder data?===

To create a different template for the page where your customers enter their 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 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.

===Is it possible to configure X-Payments to have my sales processed manually?===

No, it is not possible since X-Payments does not allow storing credit card numbers.

===How can I manually decrypt the LinkPoint key, which is returned encrypted by default?===

Use the '''openssl''' program in the command line:

<pre>
openssl rsa -in oldkey.pem -out newkey.pem
</pre>

* <tt>oldkey.pem</tt> - name of the encrypted key file provided by LinkPoint
* <tt>newkey.pem</tt> - name of the unencrypted key file to be uploaded to the server

{{Note1|Notes: 
1. When prompted to enter a password, enter the one you have received from Link Point. If you are prompted to enter a password again, just press '''Enter''' to leave the output key with no password. 
 
2. Be sure to set secure permissions on that file once you upload it (generally, the secure permissions are "600"). 
 
3. Be sure to remove the unencrypted key from your local PC.}}

===My payment method does not appear in the list after a successful import. What should I do?===

Chances are you want to use PayPal as your payment method. If this is so, you need to [index.php?title=X-Payments:PayPal follow a few additional steps] to get PayPal to work with X-Payments.

===I'm executing the cron.php script in a browser, but nothing happens===

If the script is run not in the command line interface (like in a browser in our case), its execution is interrupted due to security reasons.

To run the script successfully, execute it from the command line and use a PHP interpreter version 5.3.0 or better. You can use SSH access to execute the script.

===I need cron.php to send me emails when cronjobs are executed===

If you use Enterprise/Downloadable X-Payments, and your hosting can send emails every time an X-Payments job is executed, you can add a certain code to crontab settings for X-Payments cron.php to make cron send you emails; for example:

cd /home/checkout/public_html/ && /usr/bin/php-cli cron.php; echo "X-Payments Cron Job was launched";

Moreover, you can email the results of cron jobs execution to yourself by making a line like the following:

cd /home/checkout/public_html/ && /usr/bin/php-cli cron.php; cat /var/log/cron/YYYY-MM-DD/errors.php;

Just be sure to replace YYYY-MM-DD with a code that defines the current date on your server.

===I'm the admin and my account got locked===

This could happen when a user exceeds the allowed number of unsuccessful access attempts. The account is automatically locked for the period of time specified in the 'General settings' section.

If this is the case, you should wait until the specified dangerous activity blocking period passes, and try to sign in again.

By default, X-Payments limits the number of unsuccessful login attempts to the maximum of 6 and does not allow new login attempts for 30 minutes (this is controlled via Settings -> General settings -> Dangerous activity blocking period).

===I lost my password. What do I need to do?===

# Go to <pre>https://<your_xp_domain_name>/admin.php?target=login</pre>
# Click the 'Forgot password' link on the login page. An email message will be sent to you with a link containing your profile confirmation token.
# Follow the link to reset the password.

If the profile confirmation token has expired for some reason (e.g. you missed the email message and did not click the link in time), and you cannot set a new password for your account, just use the 'Forgot password' link on the login page again.

===Where can I find my X-Payments logs?===

X-Payments logs and X-Cart logs related to X-Payments can be found as follows:

On the X-Payments end: See the <xpay-dir>/var/log/ directory. If you are using an X-Payment Hosted account, you can see this folder as "var/log" in your X-Payments FTP account.

On the X-Cart 4 end: See the <xcart-dir>/var/log/x-errors_xpay_connector-YYMMDD.php files

===How to increase PayPal Payflow Pro "TIMEOUT" value===

In the file <xpay_dir>/lib/XPay/Module/PaypalWPPPEDirectPayment.php, locate the line # 249:

<source>
$bouncerData->setTimeout(45);
</source>

and change 45 to some other value in seconds (a number between 30..60 is recommended)

===How to enable the use of TLS/SSL SMTP===

In the file <xpdir>/config/config.ini.php, locate the line:

host="smtp.yourmailservice.com"

and replace it with the following:

host="ssl://smtp.yourmailservice.com"

===How to configure Elavon Converge/Virtual Merchant - Merchant Provided Form===

Suggested X-Payments settings:

* set Initial transaction to auth & capture
* merchantID is the same as elavon "accountID"
* get the userid from elavon
* get the PIN from elavon

Then setup myvirtualmerchant settings:

terminal > advanced > system setup

* Use HTTP Referrers [ unchecked ]
* Auto Pend HTTP Transactions [x]
* Auto Settlement [x]

EVERYTHING else is empty

PS:
Many thanks to [https://forum.x-cart.com/showpost.php?p=366912&postcount=4 carpeperdiem for sharing]!

==X-Payments Hosted FAQ==

{{X-Payments:X-Payments-Hosted-FAQ}}

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

[[Category:X-Payments User Manual]]

X-Payments:System requirements for X-Payments 3

2016-10-21T13:07:06Z

Alex “Ambal” Mulin: /* PHP configuration */

<noinclude>{{XP_manual_TOC}}</noinclude>

For hassle-free installation and performance of X-Payments, your server must meet the following requirements:
 
==Operating system==
A Unix-based operating system (Linux, FreeBSD, etc)
 
==PHP configuration==

'''PHP version:'''

: PHP v 5.5.30 or later (versions 7.0.3 or later are recommended)

'''php.ini settings:'''

:Mandatory:

:* safe_mode = off;
:* magic_quotes_sybase = off;
:* sql.safe_mode = off;
:* ini_set = on;
:* memory_limit >= 16M;

:Recommended:

:* disable_functions = NULL
:* max_execution_time >= 30;
:* memory_limit >= 32M;
:* max_input_time >= 30;
:* sendmail_from = username@example.com; (An email address that service email messages will be sent from)
:* precision = 14 (the default value set in the php.ini file).

'''PHP extensions:'''

:* Core;
:* PCRE;
:* HASH;
:* PDO with the MySQL driver;
:::'''''Important note about PDO extension:''''' X-Payments requires the PDO extension, as well as the MySQL PDO driver, to be installed as a shared module. In other words your php.ini file needs to be updated so that the PDO extensions will be loaded automatically when PHP runs: 
::::extension=php_pdo.so 
::::extension=php_pdo_mysql.so 
:::X-Payments will not install if you use a different PHP configuration (i.e. when PHP is compiled with the necessary PDO extensions like '--enable-pdo=shared' and '--with-pdo-mysql=shared'). In this case, please change the configuration as advised above (install both extensions as a shared module).
:::See also: http://php.net/manual/en/pdo.installation.php
:* mcrypt (To encrypt general data through the AES encryption algorithm);
:* XML DOM (To parse XML data);
:* cURL (To send secure HTTPS requests; cURL version 7.39.0 or better is recommended);
:* OpenSSL (To encrypt cardholder's data and API requests);
:* SOAP (Required for the Firstdata e4 payment gateway);
:* Reflection;
:* SimpleXML;
:* calendar;
:* ctype;
:* date;
:* fileinfo;
:* filter;
:* gd;
:* json;
:* libxml;
:* mbstring;
:* pcre;
:* posix;
:* spl;
:* standard;
:* xmlwriter.

'''Miscellaneous:'''
:* The crontab on the server where X-Payments is installed must be configured to periodically run the script cron.php (needed for data cleaning tasks and subscriptions). For more info, see [[X-Payments:Installation#XPCronPhp|Running the cron.php script]].
:* Use SMTP server (with SMTP Authentication option enabled) instead the PHP function mail() to send email;
:* Allow the PHP function fsockopen to ensure correct performance of SMTP mailer.

{{Note|If you need detailed help on PHP configuration settings, please refer to http://www.php.net .}}
 

==MySQL configuration==

'''MySQL version:'''

:* MySQL versions 5.6 or later (5.7 is recommended).

'''MySQL user privileges:'''

:Basic level privileges

:* select_priv;
:* insert_priv;
:* update_priv;
:* delete_priv;
:* lock_tables_priv;
:* index_priv;

:Privileges for the software installation and upgrade

:* create_priv;
:* drop_priv;
:* alter_priv.

'''MySQL user limitations:'''

:* MAX_QUESTIONS - no limitations;
:* MAX_UPDATES - no limitations;
:* MAX_QUERIES_PER_HOUR - no limitations;
:* MAX_USER_CONNECTIONS - no limitations.
:* max_allowed_packet - from 8 MB to 16 MB (recommended);
:* wait_timeout - from 7200 to 28800 (recommended).

'''InnoDB:'''
:* Must be enabled. Make sure there is no "skip-innodb" in my.cnf.
 
==Apache configuration==

Apache is the recommended web server for X-Payments. The settings described below refer to Apache only.

'''Distributed configuration file:'''

:* AccessFileName .htaccess; (The filename must always be .htaccess);
:* AllowOverride = ALL; (You must have sufficient permissions to change the settings of the web directory through the .htaccess file).

'''PHP running mode:'''

:If PHP interpreter is compiled as CGI, it must have the --enable-force-cgi-redirect option (without --enable-discard-path) enabled. This allows you to avoid the trouble with setting 755 permissions on PHP scripts and registering #!/usr/bin/php.

'''Apache modules:'''

:Mandatory

:* mod_dir; (For correct operation of DirectoryIndex)
:* mod_access; (For correct operation of Deny From All and Allow From All)
:* mod_auth; (For correct HTTP authentication)

:Recommended

:* mod_expires; (To setup file caching)
:* mod_gzip / mod_deflate. (For page compression)
 
==HTTPS settings==

HTTPS must be enabled.
 
==Secure Shell access==

For some operations, you will need to have secure shell access to the server where X-Payments is installed. These operations include:

:* [[X-Payments:Codebook_regeneration|Codebook regeneration]]
:* [[X-Payments:User_manual#Managing_PIN-codes|PIN-codes generation]]

If shell access is not allowed, the necessary actions can be performed with the help of the PHP shell_exec() function. You'll need to create a script shell.php like the following:

<pre>
<?php

$cmd = 'SHELL COMMAND';

echo shell_exec $cmd . '2>&1';

?>
</pre>
(Be sure to replace SHELL COMMAND with the actual command that needs to be executed).

Upload this script onto the server where X-Payments is installed and allow it in the <xp-dir>/.htaccess file by adding the following lines:

<pre>
<Files ~ "shell.php">
Order deny,allow
Allow from all
</Files>
</pre>

Then open this file in the web browser.

{{Note1|'''Important''': Right after the operation has been completed, remove the shell.php file and restore the original <xp-dir>/.htaccess file.}}
 

==System parameters==

'''Network settings:'''

:* X-Payments must use the IPv4 protocol;
:* Outgoing TCP connections must be opened to ports 25, 80 and 443;
:* External domains must be allowed at both system and PHP levels, that is the PHP functions gethostbyaddr and gethostbyname must work without any limitations;
:* Domains hosted on a localhost server must be resolved to an external IP address if the server is behind NAT.

'''Disk space:'''

:* 15 MB for a fresh application installation;
:* From 5 MB for the database. Exact amount of disk space required for the database depends on the number of transactions.
 
==Shopping cart software==

Your shopping cart software must support [[X-Payments:API]]. This can be achieved by installing an appropriate X-Payments connector. 
More info about the connectors is available here: 
{{XP_connector_manuals}}
<noinclude>{{pdf_single}}</noinclude>

[[Category:X-Payments User Manual]]

X-Payments:FAQ

2016-08-22T10:32:18Z

Alex “Ambal” Mulin: /* Which shopping cart software is compatible with X-Payments? */

<noinclude>{{Template:XP manual TOC}}</noinclude>
==General==

===What is X-Cart Payments service?===

X-Cart Payments is a SaaS (Software as a Service) allowing on-line merchants to use "on-site" or "merchant-hosted" credit card payment methods, like "Authorize.Net AIM", "SagePay - Direct integration", "FirstData Global Gateway - API", "PayPal Payments Pro - Direct Payment", and [[X-Payments:User_manual#Appendix_A._Supported_payment_gateways | more others]] in their integrated shopping carts.

The service includes:
* Account on a PCI DSS compliant web-hosting
* SSL certificate
* Pre-installed and configured X-Payments application

X-Payments (aka X-Cart Payments) is a PA-DSS validated application, a secure bridge between integrated shopping cart software and payment gateways. The application is hosted on a reliable and PCI DSS compliant web-hosting and secured with SSL. It helps merchants to facilitate their overall PCI DSS compliance and to accept credit card payments securely.

Besides, X-Cart Payments makes it possible to accept credit card payments right on X-Cart checkout page (using so called [http://help.x-cart.com/index.php?title=X-Cart:IFrame_One-Step_Checkout_for_X-Payments iFrame One-Step Checkout] feature), while still providing a PCI DSS compliant payment solution for merchants. In other words, customers can pay without ever leaving your web-site and being redirected to the payment gateway site, as comparing to the "off-site" payment methods like "PayPal Payments Standard", "Authorize.Net SIM", "SagePay - Form integration", "FirstData Global Gateway - Connect", etc. This can reassure customers and increase conversion rates eventually, according to a [http://www.getelastic.com/single-vs-two-page-checkout/ research conducted by Getelastic.com].

Read more about X-Cart Payments at our web-site:
* http://www.x-cart.com/extensions/modules/xpayments.html
* http://www.x-cart.com/blog/new-xpayments-plans-introduced.html

===Which shopping cart software is compatible with X-Payments?===

X-Payments provides [[X-Payments:API | web-based API]] allowing your store to submit or retrieve data. The shopping cart software you use for your store must support this API thus you have to get an appropriate connector mod.

See the following pages for more info:

* [https://www.x-payments.com/help/X-Payments:Managing_store_connections#Connecting_an_Online_store How to connect an online store with X-Payments]
* [[X-Payments:API | X-Payments:API]]
* [http://help.x-cart.com/index.php?title=X-Cart:X-Payments_Connector X-Payments Connector]

===How can I obtain X-Payments license===

X-Payments can be purchased at [http://www.x-cart.com/xpayments-pricing.html X-Cart website].

===How many stores can be connected to a single X-Payments installation?===

See details at [http://www.x-cart.com/xpayments-pricing.html X-Payments plans page]

===Can I transfer my X-Payments license and the software to a third party?===

It is possible for paid X-Payments downloadable licenses, but you need to get our written consent according to the terms and conditions of the [http://www.qtmsoft.com/xpayments-la.html license agreement].

==Installation and configuration ==

===Why did you include PHP 5.3.0 into the '''X-Payments system''' '''requirements'''? It's relatively new, and many hosts aren't running it yet.===

According to PCI DSS '''Requirements''' (paragraph 6.1),

''>> 6.1 Ensure that all system components and software have the latest vendor-supplied security patches installed. Install critical security patches within one month of release.''

For PHP "the latest vendor-supplied security patches" means "the latest PHP version", because they do not supply patches. When we started to develop X-Payments, there were two stable versions of PHP available: 5.2.10 and 5.3.0. By summer 2010, the time PCI DSS compliance becomes a must, PHP 5.3.x will probably be as widely spread as 5.2.x now. That is why we decided to use some nice improvements of PHP 5.3.0.

===Can you tell me exactly what it is in v5.3.0 that's so necessary for X-Payments?===

The PHP development team has [http://www.php.net/archive/2010.php#id2010-12-16-1 announced] the end of support for PHP 5.2; therefore, 5.3 is going to be the earliest PHP version out there. We have used the newest features available in PHP 5.3 to make our software more current and eliminate the need to design and then certify it all over. Thus, PHP 5.3 features a more appropriate implementation of the Singleton pattern and allows to implement widget operations in the viewer using <tt>__invoke</tt>. It also offers numerous other functions that are handy but not available in PHP older than 5.3; for instance, array_replace, array_replace_recursive, etc.

===Can X-Payments be set up together with old [http://help.x-cart.com/index.php?title=X-Cart:Subscriptions Subscriptions] add-on module to automatically bill subscribers on a regular basis?===

No, it can't. X-Cart's old [http://help.x-cart.com/index.php?title=X-Cart:Subscriptions Subscriptions] module is not compatible with X-Payments and it is not PCI complaint.
The right way is to use new X-Payments Subscriptions module for [http://www.x-cart.com/extensions/modules/xpayments_subscriptions.html X-Cart 4] and [http://www.x-cart.com/extensions/addons/x-payments-subscriptions-and-installements.html X-Cart 5.]

===Why is it not possible to use blank database passwords in X-Payments configuration? That's not a problem for a production copy, but my test system doesn't use passwords usually===

According to PA-DSS '''requirements''' (paragraph 3.2),

''>> 3.2 Access to PCs, servers, and databases with payment applications must require a unique user ID and secure authentication.''

This means that a password must be used to access the database as well. X-Payments doesn't have a test mode, and all the '''requirements''' are checked on the fly as if it were a production copy. X-Payments won't start until all the '''requirements''' are met. That is how we guarantee that the software meets PA-DSS '''requirements'''. If there were a test mode, we would have to add another level of checking, and each such level decreases the security of software "in the field". That is why we decided to go without some cool features, but keep high security level.

===Can X-Payments be installed on server where my shopping cart software is hosted or do I need a separate web-server?===

Both options are allowed. X-Payments can be set up either together with your shopping cart software provided it is run in a separate PCI compliant hosting space/account or on a separate server (X-Payments uses SSL connection to exchange data with your store).

===Can X-Payments be installed on a shared hosting?===

Yes, provided that a separate account is used for hosting X-Payments. No other software must be installed and run under this account.

===Can I configure X-Payments to allow my customers enter their billing address when entering their credit card data?===

No, you cannot. To edit the billing address, a customer should go back to the store and edit the billing address in the customer profile at the store.

===How do I create a different skin for the page where customers enter cardholder data?===

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.

===Is it possible to configure X-Payments to have my sales processed manually?===

No, it's not possible since X-Payments does not allow storing credit card numbers.

===How can I manually decrypt the LinkPoint key, returned encrypted by default?===

Use the '''openssl''' program in the command line:

<pre>
openssl rsa -in oldkey.pem -out newkey.pem
</pre>

* <tt>oldkey.pem</tt> - name of the encrypted key file provided by LinkPoint
* <tt>newkey.pem</tt> - name of the unencrypted key file to be uploaded to the server

{{Note1|Notes: 
1. When prompted to enter a password, enter the one you have received from Link Point. If you are prompted to enter a password again, just press '''Enter''' to leave the output key with no password. 
 
2. Be sure to set secure permissions on that file once you upload it (generally, secure permissions are "600"). 
 
3. Be sure to remove the unencrypted key from your local PC.}}

===My payment method does not appear in the list after successful import. What should I do?===

Chances are you want to use PayPal as your payment method. If this is so, you need to [index.php?title=X-Payments:PayPal follow a few additional steps] to get PayPal to work with X-Payments.

===I'm executing the cron.php script in a browser, but nothing happens===

In case the script is run not in the command line interface (like in a browser in our case), its execution is interrupted due to security reasons.

To run the script successfully, execute it from the command line and use PHP interpreter version 5.3.0 or above. You can use SSH access to execute the script.

===I need cron.php to send me emails when cronjobs are executed===

If you use Enterprise/Downloadable X-Payments and your hosting can send emails every time X-Payments job is executed you can add certain code to crontab settings for X-Payments cron.php to make cron send you emails, e.g.

cd /home/checkout/public_html/ && /usr/bin/php-cli cron.php; echo "X-Payments Cron Job was launched";

Moreover, you email yourself results of cron jobs execution by making a line like

cd /home/checkout/public_html/ && /usr/bin/php-cli cron.php; cat /var/log/cron/YYYY-MM-DD/errors.php;

Just subscritute YYYY-MM-DD with a code that defines current date on your server.

===I'm the admin and my account got locked===

This could happen when a user exceeds the allowed number of unsuccessful access attempts. The account is automatically locked for the period of time specified in the 'General settings' section.

If this is the case, you should wait until the specified dangerous activity blocking period passes, and try to sign in again.

By default, X-Payments limits number of unsuccessful login attempts by 6 max and does not allow new login attempts for 30 minutes (this is controlled at Settings -> General settings -> Dangerous activity blocking period).

===I lost my password. What do I need to do?===

* Go to <pre>https://<your_xp_domain_name>/admin.php?target=login</pre>
* click the 'Forgot password' link on the login page
* you'll receive a new email containing link with the profile confirmation token
* follow it to set the password

If the profile confirmation token is expired for some reason (e.g. you missed the email message and didn't click the link in time) and you cannot set the password to your account, just use the 'Forgot password' link again to set up the password.

===Where can I find X-Payments logs?===

X-Payments logs and X-Cart logs related to X-Payments are located at

At X-Payments side: See the <xpay-dir>/var/log/ directory. If you are using an X-Payment Hosted account you can see this folder as "var/log" in your X-Payments FTP account.

At X-Cart 4 side: See the <xcart-dir>/var/log/x-errors_xpay_connector-YYMMDD.php files

===How to increase PayPal Payflow Pro "TIMEOUT" value===

In file <xpay_dir>/lib/XPay/Module/PaypalWPPPEDirectPayment.php in line # 249:

<source>
$bouncerData->setTimeout(45);
</source>

change 45 to some value in seconds (a number between 30..60 is recommended)

===How to enable use of TLS/SSL SMTP===

In <xpdir>/config/config.ini.php file instead of:

host="smtp.yourmailservice.com"

make as below:

host="ssl://smtp.yourmailservice.com"

==X-Payments Hosted FAQ==

{{X-Payments:X-Payments-Hosted-FAQ}}

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

[[Category:X-Payments User Manual]]

X-Payments:PA-DSS implementation guide for X-Cart Payments 3

2016-07-01T13:40:04Z

Alex “Ambal” Mulin: /* Hardware and software */

==Introduction==
The purpose of this PA-DSS Implementation Guide is to inform employees of organizations using the X-Cart Payments payment application by Qualiteam Software Limited about the methods and means of protection of account data in the X-Cart Payments software.
 
The methods include the need for compliance with the information security standards in the payment card industry developed by the international payment systems Visa and MasterCard - Payment Card Industry Data Security Standard (PCI DSS) and Payment Application Data Security Standard (PA-DSS). For additional information about PCI DSS, please visit the [https://www.pcisecuritystandards.org/ Official PCI Security Standards Council Site].
 
The document provides instructions on how to implement the application in a PCI DSS compliant manner.
 
Full product name - X-Cart Payments. 
Product version - 3.0.x.
 
Any servers used to run the X-Cart Payments payment application must be configured according to this PA-DSS Implementation Guide.
 
This PA-DSS Implementation Guide should be updated:
:* at least annually;
:* after changes in the payment application (if required);
:* after changes in the PCI DSS and PA-DSS standards.
 
The updated Version of the PA-DSS Implementation Guide has to be sent to all the merchants using X-Cart Payments.
 
The history of changes to the X-Cart Payments PA-DSS Implementation Guide is provided in the table below.
 
'''Table.1. X-Cart Payments PA-DSS Implementation Guide history of changes''' 
{| class="wikitable" width=90%
|-
! scope="col" style="width: 10%;"| '''Author'''
! scope="col" style="width: 10%;"| '''Date'''
! scope="col" style="width: 10%;"| '''Number'''
! scope="col" style="width: 60%;"| '''Change description'''
|- style="vertical-align:top;"
|
| 05/17/2016
| 01
| The original version of the document, designed to meet the requirements of PCI DSS version 3.1 and PA DSS version 3.1
|-
|}
 

==Data protection==
The PCI DSS and PA-DSS standards prohibit storage of sensitive authentication data (after authorization) or cardholder data in cleartext. 
Cardholder data includes:
:* Primary Account Number (PAN)
:* Cardholder Name
:* Expiration Date
:* Service Code
 
Sensitive authentication data (SAD) includes:
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
 
X-Cart Payments has the ability to store parts of cardholder data temporarily to perform 3D Secure verification and certain types of transactions for some of the integrated payment processors. During storage, cardholder data is encrypted using RSA 2048 algorithm and AES 256 for key encryption. When its storage period is over, the data is removed automatically via "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.
 
X-Cart Payments may not be configured to store permanently in the database the following types of data:
:* Full PAN
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature.
 
The payment application masks PAN on display (except for the moment when the user enters the card number).
X-Cart Payments can display masked PAN on the "Payment details" pages and in the "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. The same data (partially masked with asterisks) may be passed via the API to the integrated software products. X-Cart Payments does not have the ability to display full PAN anywhere, and there are no settings that can change this behavior of the user interface.
 

==Data Collected while Testing==
Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:
# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever choose to collect credit card information to troubleshoot a problem that a customer of yours is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access.
#* Only collect a limited amount of data (no more than is needed to solve the problem).
#* Sensitive authentication data must be encrypted during storage. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Sensitive authentication data must be securely deleted immediately after use.
To prevent uncontrolled storage of cardholder data (for example, in case of operating system failure), it is recommended to disable the swap file or move it to a specially prepared encrypted partition.
 
==Authentication and access==
The X-Cart Payments payment application has an only user type. This type cannot get access to payment card numbers and does not have any administrative privileges that may affect PA-DSS compliance.
There are no built-in/default user accounts in X-Cart Payments. You must carefully control access to X-Cart Payments. Follow these rules:
:* Restrict the number of employees who have access to X-Cart Payments to only those who have a business need.
:* Always provide unique usernames for each person who needs access.
:* Do not use system-default usernames and/or passwords.
:* Ensure that web server is run under a non-privileged user account and the application has access to the database from a limited privilege user account.
 
To set password lifetime:
# Log in to X-Cart Payments.
# Go to Settings -> General Settings.
# In the "User account password lifetime" field, enter the number of days for which the user account password needs to be valid. The maximum allowed password lifetime is 90 days.
The following related rules apply:
:* The minimum password length is 8 characters.
:* A password must contain both numbers and lower- and uppercase characters.
:* The last 4 passwords must be unique.
:* A user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password.
:* A user is logged off after an inactivity period of 15 minutes.
 
PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:
:* For your Web hosting account administration area (Web hosting account where your online store is hosted);
:* For FTP access to the Web server;
:* For Remote Desktop Connection to the Web server (if available);
:* To connect to the MySQL server that contains your store data.
 
Linux authentication mechanism is used for login in the servers with running X-Cart Payments.
Accounts for access to the operating system are managed by the Linux administrator.
For Linux operating system accounts, you must configure the following attributes of the password policy:
:* use personal accounts, do not use any group, shared, or generic accounts and passwords;
:* changes to user passwords at least once every 90 days;
:* require a minimum length of at least seven characters;
:* contain both numeric and alphabetic characters;
:* do not use last four passwords used previously;
:* block account after six invalid logon attempts (minimum 30 minutes or until an administrator enables the user ID).
 
Two-factor authentication must be used for remote access to the operating system. The authentication methods, also known as factors, are:
:* something you know, such as a password or a passphrase;
:* something you have, such as a token device or a smart card;
:* something you are, such as a biometric.
 

== Logging==
Audit trails are automatically enabled with the default installation of X-Cart Payments. Users do not have the ability to disable or change the logging parameters of X-Cart Payments. X-Cart Payments log journal does not contain cardholder data. It is implemented at the source code level. The setting of an event log journal does not require any additional action from users.
The log files are created in the var/log/ directory. In X-Cart Payments 3.0, logs can be viewed via the X-Cart Payments admin back end. Make sure you restrict access to the log files by business need-to-know.
The following types of activity are logged:
:* All actions taken by any individual with root or administrative privileges.
:* Successes and failures of all individual accesses to application sections and functions.
:* Initialization of the audit logs.
:* User sign in and sign out.
 
Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to the files access.log and error.log.
Each log event includes:
:* Type of event;
:* Date and time of event;
:* Username and IP address;
:* Success or failure indication;
:* Action which led to the event;
:* Component which led to the event.
 
There is also a meta-log which contains information about other log files being created.
Make sure you have a system-level auditing software properly configured to monitor users' activity on the server. This software should:
:* warn on a checksum change of any of X-Cart Payments source code files except for the log file and the database files;
:* record any file writing operations related to X-Cart Payments files.
 

==Communication==
LAN channel or other available connection method can be used as a communication channel.
X-Cart Payments payment application supports the following data formats:
{| class="wikitable" width=90%
|-
| scope="col" style="width: 20%;"| '''Protocol'''
| scope="col" style="width: 70%;"| HTTP protocol (RFC 2616: HTTP/1.1) is used for data transfer between client and server
|- style="vertical-align:top;"
| '''Data transmission method'''
| Only encrypted cardholder data (RSA 2048 and AES 256) is transferred. RAW POST method is used for data transmission - (data stream is transmitted in the body of the request that is sent from client to server)
|- style="vertical-align:top;"
| '''Data format'''
| Data is transmitted in XML format (Extensible Markup Language (XML) 1.0) or in plain text using POST query via HTTPS
|- style="vertical-align:top;"
| '''Port'''
| X-Cart Payments payment application uses ports 80, 443
|-
|}
 
'''Network traffic encryption''' 
X-Cart Payments uses encryption, such as TLS or IPSEC, for:
:* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
:* providing remote web-based access to the application.
 
If you use some tools to remotely access the application, you should encrypt all the communication using such technologies as TLS or IPSEC.
 
As per PCI DSS requirement, cardholder data must never be sent unencrypted by email, and X-Cart Payments does meet this requirement never sending cardholder data by email or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.
 
'''Enable TLS''' 
TLS protects data that is transmitted between a browser and your web server. It is critical that you have TLS enabled on your web server, and one of the first steps you should take after the installation is to enable TLS.
:* Your web server must be configured to use TLS v1.1 or v1.2 protocols with strong encryption (128-bit or longer key is required).
:* You will need to have a certificate issued for your web domain. Read guidelines on installing Comodo's Instant TLS certificates.
 
If a web server does not have TLS enabled, X-Cart Payments will not function.
X-Cart Payments does not support remote administrative access. Strong encryption must be used for remote access to the server.
The connection of servers with X-Cart Payments payment application to the Internet must be protected by a firewall. In X-Cart Payments configurations involving more than one server, server connections should take place in network segments separated from the Internet via stateful inspection firewalls.
 
'''Wireless communications''' 
If you use wireless networking to access X-Cart Payments, it is your responsibility to ensure your wireless security configuration follows the PCI DSS requirements.
:* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
:* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
:* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
:* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
::* Use with a minimum 104-bit encryption key and 24 bit-initialization value.
::* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS.
::* Rotate shared WEP keys quarterly (or automatically if the technology permits).
::* Rotate shared WEP keys whenever there are changes in personnel with access to keys.
::* Restrict access based on media access code (MAC) address.
::* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.
 
'''Remote access''' 
X-Cart Payments provides web-based access using two-factor authentication based on one-time codes. Detailed information can be found on the [[X-Payments:Two-factor_authentication | X-Payments:Two-factor authentication]] page.
If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:
:* Change the default settings in the remote access software (for example, change the default passwords and use unique passwords for each customer).
:* Allow connections only from specific (known) IP/MAC addresses.
:* Use strong authentication or complex passwords for logins.
:* Enable encrypted data transmission.
:* Enable account lockout after a certain number of failed login attempts.
:* Configure the system so a remote user must establish a Virtual Private Network ("VPN") connection via a firewall before access is allowed.
:* Enable any logging or auditing functions.
:* Restrict access to customer passwords to authorized reseller/integrator personnel.
:* Establish customer passwords according to PCI DSS requirements.
Qualiteam does not provide software updates via remote access on an automated basis.
 

==Hardware and software==
The following requirements must be met for X-Cart Payments payment application self-service terminals: 
'''Operating System''' 
Linux Ubuntu 16 or later, Linux Debian 6.0 or later, Linux CentOS 6 or later 
'''DBMS''' 
My SQL 5.6 or later 
'''Software''' 
PHP 5.5 or later 
Apache 2.4 or later
 

==Product versioning methodology==
{| class="wikitable" width=90%
|-
! scope="col" style="width: 15%;"| '''Version number changes'''
! scope="col" style="width: 45%;"| '''Software changes'''
! scope="col" style="width: 15%;"| '''Description'''
! scope="col" style="width: 15%;"| '''PA-DSS changes'''
|- style="vertical-align:top;"
| Version number does not change
| Change of the software name Change of the vendor name
| Changes not related to the software development process
| Administrative
|- style="vertical-align:top;"
| Increment of the minor version number to reflect a change not affecting the certification. For example, change of the version number from 1.0.5 to 1.0.6 (for the certification of 1.0.x)
| - Changes to the user interface - Changes to the database schema - Changes to supported payment gateway integrations / Addition of new payment gateway integrations
| Changes that have no impact on the PA-DSS requirements compliance or Payment Application security
| No Impact
|- style="vertical-align:top;"
| Increment of the second version number. For example, change of the version number from 1.1.* to 1.2.*
| Software changes satisfy the following conditions: - Fewer than 4 sections of the standard (from 1 to 12) involved; - Fewer than a half of all the requirements of the standard (sections 1 to 12) involved; - Less than a half of the software functions (or code) modified; - Changes implemented for compatibility with the updated versions of previously tested OS, DBMS and third party software products. - Addition/removal of supported payment processors. - Recompilation of the source code using a new compiler or different compiler settings. - Changes of the software versioning policy. - Changes of the software not related to security.
| - Changes in the software affecting payment card data mechanisms. - Changes addressing the identified vulnerabilities of the application. - Changes related to the completion of the annual cycle of development (if there are other changes).
| Low Impact
|- style="vertical-align:top;"
| Increment of the first version number. For example, change of the version number from 1.0.* to 2.0.*
| Software changes satisfy the following conditions: - 4 or more sections of the standard (from 1 to 12) involved; - More than a half of all the requirements of the standard (sections 1 to 12) involved; - More than a half of the software functions (or code) modified; - Addition of new supported platforms/OS versions.
| Major changes in the software architecture, global alterations of code
| High Impact
|}
 
The release of each new version is accompanied with a notification to all the application users (agents), which indicates the new application version number and a list of main changes in the new version.
 

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PA-DSS implementation guide for X-Cart Payments 3

2016-05-30T08:32:54Z

Alex “Ambal” Mulin: /* Communication */

==Introduction==
The purpose of this PA-DSS Implementation Guide is to inform employees of organizations using the X-Cart Payments payment application by Qualiteam Software Limited about the methods and means of protection of account data in the X-Cart Payments software.
 
The methods include the need for compliance with the information security standards in the payment card industry developed by the international payment systems Visa and MasterCard – Payment Card Industry Data Security Standard (PCI DSS) and Payment Application Data Security Standard (PA-DSS). For additional information about PCI DSS, please visit the [https://www.pcisecuritystandards.org/ Official PCI Security Standards Council Site].
 
The document provides instructions on how to implement the application in a PCI DSS compliant manner.
 
Full product name – X-Cart Payments. 
Product version – 3.0.х.
 
Any servers used to run the X-Cart Payments payment application must be configured according to this PA-DSS Implementation Guide.
 
This PA-DSS Implementation Guide should be updated:
:* at least annually;
:* after changes in the payment application (if required);
:* after changes in the PCI DSS and PA-DSS standards.
 
The updated Version of the PA-DSS Implementation Guide has to be sent to all the merchants using X-Cart Payments.
 
The history of changes to the X-Cart Payments PA-DSS Implementation Guide is provided in the table below.
 
'''Table.1. X-Cart Payments PA-DSS Implementation Guide history of changes''' 
{| class="wikitable" width=90%
|-
! scope="col" style="width: 10%;"| '''Author'''
! scope="col" style="width: 10%;"| '''Date'''
! scope="col" style="width: 10%;"| '''Number'''
! scope="col" style="width: 60%;"| '''Change description'''
|- style="vertical-align:top;"
|
| 05/17/2016
| 01
| The original version of the document, designed to meet the requirements of PCI DSS version 3.1 and PA DSS version 3.1
|-
|}
 

==Data protection==
The PCI DSS and PA-DSS standards prohibit storage of sensitive authentication data (after authorization) or cardholder data in cleartext. 
Cardholder data includes:
:* Primary Account Number (PAN)
:* Cardholder Name
:* Expiration Date
:* Service Code
 
Sensitive authentication data (SAD) includes:
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
 
X-Cart Payments has the ability to store parts of cardholder data temporarily to perform 3D Secure verification and certain types of transactions for some of the integrated payment processors. During storage, cardholder data is encrypted using RSA 2048 algorithm and AES 256 for key encryption. When its storage period is over, the data is removed automatically via "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.
 
X-Cart Payments may not be configured to store permanently in the database the following types of data:
:* Full PAN
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature.
 
The payment application masks PAN on display (except for the moment when the user enters the card number).
X-Cart Payments can display masked PAN on the "Payment details" pages and in the "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. The same data (partially masked with asterisks) may be passed via the API to the integrated software products. X-Cart Payments does not have the ability to display full PAN anywhere, and there are no settings that can change this behavior of the user interface.
 

==Data Collected while Testing==
Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:
# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever choose to collect credit card information to troubleshoot a problem that a customer of yours is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access.
#* Only collect a limited amount of data (no more than is needed to solve the problem).
#* Sensitive authentication data must be encrypted during storage. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Sensitive authentication data must be securely deleted immediately after use.
To prevent uncontrolled storage of cardholder data (for example, in case of operating system failure), it is recommended to disable the swap file or move it to a specially prepared encrypted partition.
 
==Authentication and access==
The X-Cart Payments payment application has an only user type. This type cannot get access to payment card numbers and does not have any administrative privileges that may affect PA-DSS compliance.
There are no built-in/default user accounts in X-Cart Payments. You must carefully control access to X-Cart Payments. Follow these rules:
:* Restrict the number of employees who have access to X-Cart Payments to only those who have a business need.
:* Always provide unique usernames for each person who needs access.
:* Do not use system-default usernames and/or passwords.
:* Ensure that web server is run under a non-privileged user account and the application has access to the database from a limited privilege user account.
 
To set password lifetime:
# Log in to X-Cart Payments.
# Go to Settings -> General Settings.
# In the "User account password lifetime" field, enter the number of days for which the user account password needs to be valid. The maximum allowed password lifetime is 90 days.
The following related rules apply:
:* The minimum password length is 8 characters.
:* A password must contain both numbers and lower- and uppercase characters.
:* The last 4 passwords must be unique.
:* A user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password.
:* A user is logged off after an inactivity period of 15 minutes.
 
PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:
:* For your Web hosting account administration area (Web hosting account where your online store is hosted);
:* For FTP access to the Web server;
:* For Remote Desktop Connection to the Web server (if available);
:* To connect to the MySQL server that contains your store data.
 
Linux authentication mechanism is used for login in the servers with running X-Cart Payments.
Accounts for access to the operating system are managed by the Linux administrator.
For Linux operating system accounts, you must configure the following attributes of the password policy:
:* use personal accounts, do not use any group, shared, or generic accounts and passwords;
:* changes to user passwords at least once every 90 days;
:* require a minimum length of at least seven characters;
:* contain both numeric and alphabetic characters;
:* do not use last four passwords used previously;
:* block account after six invalid logon attempts (minimum 30 minutes or until an administrator enables the user ID).
 
Two-factor authentication must be used for remote access to the operating system. The authentication methods, also known as factors, are:
:* something you know, such as a password or a passphrase;
:* something you have, such as a token device or a smart card;
:* something you are, such as a biometric.
 

== Logging==
Audit trails are automatically enabled with the default installation of X-Cart Payments. Users do not have the ability to disable or change the logging parameters of X-Cart Payments. X-Cart Payments log journal does not contain cardholder data. It is implemented at the source code level. The setting of an event log journal does not require any additional action from users.
The log files are created in the var/log/ directory. In X-Cart Payments 3.0, logs can be viewed via the X-Cart Payments admin back end. Make sure you restrict access to the log files by business need-to-know.
The following types of activity are logged:
:* All actions taken by any individual with root or administrative privileges.
:* Successes and failures of all individual accesses to application sections and functions.
:* Initialization of the audit logs.
:* User sign in and sign out.
 
Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to the files access.log and error.log.
Each log event includes:
:* Type of event;
:* Date and time of event;
:* Username and IP address;
:* Success or failure indication;
:* Action which led to the event;
:* Component which led to the event.
 
There is also a meta-log which contains information about other log files being created.
Make sure you have a system-level auditing software properly configured to monitor users' activity on the server. This software should:
:* warn on a checksum change of any of X-Cart Payments source code files except for the log file and the database files;
:* record any file writing operations related to X-Cart Payments files.
 

==Communication==
LAN channel or other available connection method can be used as a communication channel.
X-Cart Payments payment application supports the following data formats:
{| class="wikitable" width=90%
|-
| scope="col" style="width: 20%;"| '''Protocol'''
| scope="col" style="width: 70%;"| HTTP protocol (RFC 2616: HTTP/1.1) is used for data transfer between client and server
|- style="vertical-align:top;"
| '''Data transmission method'''
| Only encrypted cardholder data (RSA 2048 and AES 256) is transferred. RAW POST method is used for data transmission – (data stream is transmitted in the body of the request that is sent from client to server)
|- style="vertical-align:top;"
| '''Data format'''
| Data is transmitted in XML format (Extensible Markup Language (XML) 1.0) or in plain text using POST query via HTTPS
|- style="vertical-align:top;"
| '''Port'''
| X-Cart Payments payment application uses ports 80, 443
|-
|}
 
'''Network traffic encryption''' 
X-Cart Payments uses encryption, such as TLS or IPSEC, for:
:* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
:* providing remote web-based access to the application.
 
If you use some tools to remotely access the application, you should encrypt all the communication using such technologies as TLS or IPSEC.
 
As per PCI DSS requirement, cardholder data must never be sent unencrypted by email, and X-Cart Payments does meet this requirement never sending cardholder data by email or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.
 
'''Enable TLS''' 
TLS protects data that is transmitted between a browser and your web server. It is critical that you have TLS enabled on your web server, and one of the first steps you should take after the installation is to enable TLS.
:* Your web server must be configured to use TLS v1.1 or v1.2 protocols with strong encryption (128-bit or longer key is required).
:* You will need to have a certificate issued for your web domain. Read guidelines on installing Comodo's Instant TLS certificates.
 
If a web server does not have TLS enabled, X-Cart Payments will not function.
X-Cart Payments does not support remote administrative access. Strong encryption must be used for remote access to the server.
The connection of servers with X-Cart Payments payment application to the Internet must be protected by a firewall. In X-Cart Payments configurations involving more than one server, server connections should take place in network segments separated from the Internet via stateful inspection firewalls.
 
'''Wireless communications''' 
If you use wireless networking to access X-Cart Payments, it is your responsibility to ensure your wireless security configuration follows the PCI DSS requirements.
:* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
:* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
:* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
:* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
::* Use with a minimum 104-bit encryption key and 24 bit-initialization value.
::* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS.
::* Rotate shared WEP keys quarterly (or automatically if the technology permits).
::* Rotate shared WEP keys whenever there are changes in personnel with access to keys.
::* Restrict access based on media access code (MAC) address.
::* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.
 
'''Remote access''' 
X-Cart Payments provides web-based access using two-factor authentication based on one-time codes. Detailed information can be found on the [[X-Payments:Two-factor_authentication | X-Payments:Two-factor authentication]] page.
If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:
:* Change the default settings in the remote access software (for example, change the default passwords and use unique passwords for each customer).
:* Allow connections only from specific (known) IP/MAC addresses.
:* Use strong authentication or complex passwords for logins.
:* Enable encrypted data transmission.
:* Enable account lockout after a certain number of failed login attempts.
:* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed.
:* Enable any logging or auditing functions.
:* Restrict access to customer passwords to authorized reseller/integrator personnel.
:* Establish customer passwords according to PCI DSS requirements.
Qualiteam does not provide software updates via remote access on an automated basis.
 

==Hardware and software==
The following requirements must be met for X-Cart Payments payment application self-service terminals: 
'''Operating System''' 
Linux Ubuntu 16 or later 
'''DBMS''' 
My SQL 5.6 or later 
'''Software''' 
PHP 5.5 or later 
Apache 2.4 or later
 
==Product versioning methodology==
{| class="wikitable" width=90%
|-
! scope="col" style="width: 15%;"| '''Version number changes'''
! scope="col" style="width: 45%;"| '''Software changes'''
! scope="col" style="width: 15%;"| '''Description'''
! scope="col" style="width: 15%;"| '''PA-DSS changes'''
|- style="vertical-align:top;"
| Version number does not change
| Change of the software name Change of the vendor name
| Changes not related to the software development process
| Administrative
|- style="vertical-align:top;"
| Increment of the minor version number to reflect a change not affecting the certification. For example, change of the version number from 1.0.5 to 1.0.6 (for the certification of 1.0.x)
| - Changes to the user interface - Changes to the database schema - Changes to supported payment gateway integrations / Addition of new payment gateway integrations
| Сhanges that have no impact on the PA-DSS requirements compliance or Payment Application security
| No Impact
|- style="vertical-align:top;"
| Increment of the second version number. For example, change of the version number from 1.1.* to 1.2.*
| Software changes satisfy the following conditions: - Fewer than 4 sections of the standard (from 1 to 12) involved; - Fewer than a half of all the requirements of the standard (sections 1 to 12) involved; - Less than a half of the software functions (or code) modified; - Changes implemented for compatibility with the updated versions of previously tested OS, DBMS and third party software products. - Addition/removal of supported payment processors. - Recompilation of the source code using a new compiler or different compiler settings. - Changes of the software versioning policy. - Changes of the software not related to security.
| - Changes in the software affecting payment card data mechanisms. - Changes addressing the identified vulnerabilities of the application. - Changes related to the completion of the annual cycle of development (if there are other changes).
| Low Impact
|- style="vertical-align:top;"
| Increment of the first version number. For example, change of the version number from 1.0.* to 2.0.*
| Software changes satisfy the following conditions: - 4 or more sections of the standard (from 1 to 12) involved; - More than a half of all the requirements of the standard (sections 1 to 12) involved; - More than a half of the software functions (or code) modified; - Addition of new supported platforms/OS versions.
| Major changes in the software architecture, global alterations of code
| High Impact
|}
 
The release of each new version is accompanied with a notification to all the application users (agents), which indicates the new application version number and a list of main changes in the new version.
 

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PA-DSS implementation guide for X-Cart Payments 3

2016-05-26T09:46:02Z

Alex “Ambal” Mulin: /* Communication */

==Introduction==
The purpose of this PA-DSS Implementation Guide is to inform employees of organizations using the X-Cart Payments payment application by Qualiteam Software Limited about the methods and means of protection of account data in the X-Cart Payments software.
 
The methods include the need for compliance with the information security standards in the payment card industry developed by the international payment systems Visa and MasterCard – Payment Card Industry Data Security Standard (PCI DSS) and Payment Application Data Security Standard (PA-DSS). For additional information about PCI DSS, please visit the [https://www.pcisecuritystandards.org/ Official PCI Security Standards Council Site].
 
The document provides instructions on how to implement the application in a PCI DSS compliant manner.
 
Full product name – X-Cart Payments. 
Product version – 3.0.х.
 
Any servers used to run the X-Cart Payments payment application must be configured according to this PA-DSS Implementation Guide.
 
This PA-DSS Implementation Guide should be updated:
:* at least annually;
:* after changes in the payment application (if required);
:* after changes in the PCI DSS and PA-DSS standards.
 
The updated Version of the PA-DSS Implementation Guide has to be sent to all the merchants using X-Cart Payments.
 
The history of changes to the X-Cart Payments PA-DSS Implementation Guide is provided in the table below.
 
'''Table.1. X-Cart Payments PA-DSS Implementation Guide history of changes''' 
{| class="wikitable" width=90%
|-
! scope="col" style="width: 10%;"| '''Author'''
! scope="col" style="width: 10%;"| '''Date'''
! scope="col" style="width: 10%;"| '''Number'''
! scope="col" style="width: 60%;"| '''Change description'''
|- style="vertical-align:top;"
|
| 05/17/2016
| 01
| The original version of the document, designed to meet the requirements of PCI DSS version 3.1 and PA DSS version 3.1
|-
|}
 

==Data protection==
The PCI DSS and PA-DSS standards prohibit storage of sensitive authentication data (after authorization) or cardholder data in cleartext. 
Cardholder data includes:
:* Primary Account Number (PAN)
:* Cardholder Name
:* Expiration Date
:* Service Code
 
Sensitive authentication data (SAD) includes:
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
 
X-Cart Payments has the ability to store parts of cardholder data temporarily to perform 3D Secure verification and certain types of transactions for some of the integrated payment processors. During storage, cardholder data is encrypted using RSA 2048 algorithm and AES 256 for key encryption. When its storage period is over, the data is removed automatically via "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.
 
X-Cart Payments may not be configured to store permanently in the database the following types of data:
:* Full PAN
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature.
 
The payment application masks PAN on display (except for the moment when the user enters the card number).
X-Cart Payments can display masked PAN on the "Payment details" pages and in the "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. The same data (partially masked with asterisks) may be passed via the API to the integrated software products. X-Cart Payments does not have the ability to display full PAN anywhere, and there are no settings that can change this behavior of the user interface.
 

==Data Collected while Testing==
Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:
# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever choose to collect credit card information to troubleshoot a problem that a customer of yours is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access.
#* Only collect a limited amount of data (no more than is needed to solve the problem).
#* Sensitive authentication data must be encrypted during storage. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Sensitive authentication data must be securely deleted immediately after use.
To prevent uncontrolled storage of cardholder data (for example, in case of operating system failure), it is recommended to disable the swap file or move it to a specially prepared encrypted partition.
 
==Authentication and access==
The X-Cart Payments payment application has an only user type. This type cannot get access to payment card numbers and does not have any administrative privileges that may affect PA-DSS compliance.
There are no built-in/default user accounts in X-Cart Payments. You must carefully control access to X-Cart Payments. Follow these rules:
:* Restrict the number of employees who have access to X-Cart Payments to only those who have a business need.
:* Always provide unique usernames for each person who needs access.
:* Do not use system-default usernames and/or passwords.
:* Ensure that web server is run under a non-privileged user account and the application has access to the database from a limited privilege user account.
 
To set password lifetime:
# Log in to X-Cart Payments.
# Go to Settings -> General Settings.
# In the "User account password lifetime" field, enter the number of days for which the user account password needs to be valid. The maximum allowed password lifetime is 90 days.
The following related rules apply:
:* The minimum password length is 8 characters.
:* A password must contain both numbers and lower- and uppercase characters.
:* The last 4 passwords must be unique.
:* A user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password.
:* A user is logged off after an inactivity period of 15 minutes.
 
PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:
:* For your Web hosting account administration area (Web hosting account where your online store is hosted);
:* For FTP access to the Web server;
:* For Remote Desktop Connection to the Web server (if available);
:* To connect to the MySQL server that contains your store data.
 
Linux authentication mechanism is used for login in the servers with running X-Cart Payments.
Accounts for access to the operating system are managed by the Linux administrator.
For Linux operating system accounts, you must configure the following attributes of the password policy:
:* use personal accounts, do not use any group, shared, or generic accounts and passwords;
:* changes to user passwords at least once every 90 days;
:* require a minimum length of at least seven characters;
:* contain both numeric and alphabetic characters;
:* do not use last four passwords used previously;
:* block account after six invalid logon attempts (minimum 30 minutes or until an administrator enables the user ID).
 
Two-factor authentication must be used for remote access to the operating system. The authentication methods, also known as factors, are:
:* something you know, such as a password or a passphrase;
:* something you have, such as a token device or a smart card;
:* something you are, such as a biometric.
 

== Logging==
Audit trails are automatically enabled with the default installation of X-Cart Payments. Users do not have the ability to disable or change the logging parameters of X-Cart Payments. X-Cart Payments log journal does not contain cardholder data. It is implemented at the source code level. The setting of an event log journal does not require any additional action from users.
The log files are created in the var/log/ directory. In X-Cart Payments 3.0, logs can be viewed via the X-Cart Payments admin back end. Make sure you restrict access to the log files by business need-to-know.
The following types of activity are logged:
:* All actions taken by any individual with root or administrative privileges.
:* Successes and failures of all individual accesses to application sections and functions.
:* Initialization of the audit logs.
:* User sign in and sign out.
 
Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to the files access.log and error.log.
Each log event includes:
:* Type of event;
:* Date and time of event;
:* Username and IP address;
:* Success or failure indication;
:* Action which led to the event;
:* Component which led to the event.
 
There is also a meta-log which contains information about other log files being created.
Make sure you have a system-level auditing software properly configured to monitor users' activity on the server. This software should:
:* warn on a checksum change of any of X-Cart Payments source code files except for the log file and the database files;
:* record any file writing operations related to X-Cart Payments files.
 

==Communication==
LAN channel or other available connection method can be used as a communication channel.
X-Cart Payments payment application supports the following data formats:
{| class="wikitable" width=90%
|-
| scope="col" style="width: 20%;"| '''Protocol'''
| scope="col" style="width: 70%;"| HTTP protocol (RFC 2616: HTTP/1.1) is used for data transfer between client and server
|- style="vertical-align:top;"
| '''Data transmission method'''
| Only encrypted cardholder data (RSA 2048 and AES 256) is transferred. RAW POST method is used for data transmission – (data stream is transmitted in the body of the request that is sent from client to server)
|- style="vertical-align:top;"
| '''Data format'''
| Data is transmitted in XML format (Extensible Markup Language (XML) 1.0)
|- style="vertical-align:top;"
| '''Port'''
| X-Cart Payments payment application uses ports 80, 443
|-
|}
 
'''Network traffic encryption''' 
X-Cart Payments uses encryption, such as TLS or IPSEC, for:
:* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
:* providing remote web-based access to the application.
 
If you use some tools to remotely access the application, you should encrypt all the communication using such technologies as TLS or IPSEC.
 
As per PCI DSS requirement, cardholder data must never be sent unencrypted by email, and X-Cart Payments does meet this requirement never sending cardholder data by email or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.
 
'''Enable TLS''' 
TLS protects data that is transmitted between a browser and your web server. It is critical that you have TLS enabled on your web server, and one of the first steps you should take after the installation is to enable TLS.
:* Your web server must be configured to use TLS v1.1 or v1.2 protocols with strong encryption (128-bit or longer key is required).
:* You will need to have a certificate issued for your web domain. Read guidelines on installing Comodo's Instant TLS certificates.
 
If a web server does not have TLS enabled, X-Cart Payments will not function.
X-Cart Payments does not support remote administrative access. Strong encryption must be used for remote access to the server.
The connection of servers with X-Cart Payments payment application to the Internet must be protected by a firewall. In X-Cart Payments configurations involving more than one server, server connections should take place in network segments separated from the Internet via stateful inspection firewalls.
 
'''Wireless communications''' 
If you use wireless networking to access X-Cart Payments, it is your responsibility to ensure your wireless security configuration follows the PCI DSS requirements.
:* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
:* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
:* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
:* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
::* Use with a minimum 104-bit encryption key and 24 bit-initialization value.
::* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS.
::* Rotate shared WEP keys quarterly (or automatically if the technology permits).
::* Rotate shared WEP keys whenever there are changes in personnel with access to keys.
::* Restrict access based on media access code (MAC) address.
::* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.
 
'''Remote access''' 
X-Cart Payments provides web-based access using two-factor authentication based on one-time codes. Detailed information can be found on the [[X-Payments:Two-factor_authentication | X-Payments:Two-factor authentication]] page.
If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:
:* Change the default settings in the remote access software (for example, change the default passwords and use unique passwords for each customer).
:* Allow connections only from specific (known) IP/MAC addresses.
:* Use strong authentication or complex passwords for logins.
:* Enable encrypted data transmission.
:* Enable account lockout after a certain number of failed login attempts.
:* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed.
:* Enable any logging or auditing functions.
:* Restrict access to customer passwords to authorized reseller/integrator personnel.
:* Establish customer passwords according to PCI DSS requirements.
Qualiteam does not provide software updates via remote access on an automated basis.
 

==Hardware and software==
The following requirements must be met for X-Cart Payments payment application self-service terminals: 
'''Operating System''' 
Linux Ubuntu 16 or later 
'''DBMS''' 
My SQL 5.6 or later 
'''Software''' 
PHP 5.5 or later 
Apache 2.4 or later
 
==Product versioning methodology==
{| class="wikitable" width=90%
|-
! scope="col" style="width: 15%;"| '''Version number changes'''
! scope="col" style="width: 45%;"| '''Software changes'''
! scope="col" style="width: 15%;"| '''Description'''
! scope="col" style="width: 15%;"| '''PA-DSS changes'''
|- style="vertical-align:top;"
| Version number does not change
| Change of the software name Change of the vendor name
| Changes not related to the software development process
| Administrative
|- style="vertical-align:top;"
| Increment of the minor version number to reflect a change not affecting the certification. For example, change of the version number from 1.0.5 to 1.0.6 (for the certification of 1.0.x)
| - Changes to the user interface - Changes to the database schema - Changes to supported payment gateway integrations / Addition of new payment gateway integrations
| Сhanges that have no impact on the PA-DSS requirements compliance or Payment Application security
| No Impact
|- style="vertical-align:top;"
| Increment of the second version number. For example, change of the version number from 1.1.* to 1.2.*
| Software changes satisfy the following conditions: - Fewer than 4 sections of the standard (from 1 to 12) involved; - Fewer than a half of all the requirements of the standard (sections 1 to 12) involved; - Less than a half of the software functions (or code) modified; - Changes implemented for compatibility with the updated versions of previously tested OS, DBMS and third party software products. - Addition/removal of supported payment processors. - Recompilation of the source code using a new compiler or different compiler settings. - Changes of the software versioning policy. - Changes of the software not related to security.
| - Changes in the software affecting payment card data mechanisms. - Changes addressing the identified vulnerabilities of the application. - Changes related to the completion of the annual cycle of development (if there are other changes).
| Low Impact
|- style="vertical-align:top;"
| Increment of the first version number. For example, change of the version number from 1.0.* to 2.0.*
| Software changes satisfy the following conditions: - 4 or more sections of the standard (from 1 to 12) involved; - More than a half of all the requirements of the standard (sections 1 to 12) involved; - More than a half of the software functions (or code) modified; - Addition of new supported platforms/OS versions.
| Major changes in the software architecture, global alterations of code
| High Impact
|}
 
The release of each new version is accompanied with a notification to all the application users (agents), which indicates the new application version number and a list of main changes in the new version.
 

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PA-DSS implementation guide for X-Cart Payments 3

2016-05-26T09:44:17Z

Alex “Ambal” Mulin: /* Communication */

==Introduction==
The purpose of this PA-DSS Implementation Guide is to inform employees of organizations using the X-Cart Payments payment application by Qualiteam Software Limited about the methods and means of protection of account data in the X-Cart Payments software.
 
The methods include the need for compliance with the information security standards in the payment card industry developed by the international payment systems Visa and MasterCard – Payment Card Industry Data Security Standard (PCI DSS) and Payment Application Data Security Standard (PA-DSS). For additional information about PCI DSS, please visit the [https://www.pcisecuritystandards.org/ Official PCI Security Standards Council Site].
 
The document provides instructions on how to implement the application in a PCI DSS compliant manner.
 
Full product name – X-Cart Payments. 
Product version – 3.0.х.
 
Any servers used to run the X-Cart Payments payment application must be configured according to this PA-DSS Implementation Guide.
 
This PA-DSS Implementation Guide should be updated:
:* at least annually;
:* after changes in the payment application (if required);
:* after changes in the PCI DSS and PA-DSS standards.
 
The updated Version of the PA-DSS Implementation Guide has to be sent to all the merchants using X-Cart Payments.
 
The history of changes to the X-Cart Payments PA-DSS Implementation Guide is provided in the table below.
 
'''Table.1. X-Cart Payments PA-DSS Implementation Guide history of changes''' 
{| class="wikitable" width=90%
|-
! scope="col" style="width: 10%;"| '''Author'''
! scope="col" style="width: 10%;"| '''Date'''
! scope="col" style="width: 10%;"| '''Number'''
! scope="col" style="width: 60%;"| '''Change description'''
|- style="vertical-align:top;"
|
| 05/17/2016
| 01
| The original version of the document, designed to meet the requirements of PCI DSS version 3.1 and PA DSS version 3.1
|-
|}
 

==Data protection==
The PCI DSS and PA-DSS standards prohibit storage of sensitive authentication data (after authorization) or cardholder data in cleartext. 
Cardholder data includes:
:* Primary Account Number (PAN)
:* Cardholder Name
:* Expiration Date
:* Service Code
 
Sensitive authentication data (SAD) includes:
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
 
X-Cart Payments has the ability to store parts of cardholder data temporarily to perform 3D Secure verification and certain types of transactions for some of the integrated payment processors. During storage, cardholder data is encrypted using RSA 2048 algorithm and AES 256 for key encryption. When its storage period is over, the data is removed automatically via "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.
 
X-Cart Payments may not be configured to store permanently in the database the following types of data:
:* Full PAN
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature.
 
The payment application masks PAN on display (except for the moment when the user enters the card number).
X-Cart Payments can display masked PAN on the "Payment details" pages and in the "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. The same data (partially masked with asterisks) may be passed via the API to the integrated software products. X-Cart Payments does not have the ability to display full PAN anywhere, and there are no settings that can change this behavior of the user interface.
 

==Data Collected while Testing==
Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:
# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever choose to collect credit card information to troubleshoot a problem that a customer of yours is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access.
#* Only collect a limited amount of data (no more than is needed to solve the problem).
#* Sensitive authentication data must be encrypted during storage. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Sensitive authentication data must be securely deleted immediately after use.
To prevent uncontrolled storage of cardholder data (for example, in case of operating system failure), it is recommended to disable the swap file or move it to a specially prepared encrypted partition.
 
==Authentication and access==
The X-Cart Payments payment application has an only user type. This type cannot get access to payment card numbers and does not have any administrative privileges that may affect PA-DSS compliance.
There are no built-in/default user accounts in X-Cart Payments. You must carefully control access to X-Cart Payments. Follow these rules:
:* Restrict the number of employees who have access to X-Cart Payments to only those who have a business need.
:* Always provide unique usernames for each person who needs access.
:* Do not use system-default usernames and/or passwords.
:* Ensure that web server is run under a non-privileged user account and the application has access to the database from a limited privilege user account.
 
To set password lifetime:
# Log in to X-Cart Payments.
# Go to Settings -> General Settings.
# In the "User account password lifetime" field, enter the number of days for which the user account password needs to be valid. The maximum allowed password lifetime is 90 days.
The following related rules apply:
:* The minimum password length is 8 characters.
:* A password must contain both numbers and lower- and uppercase characters.
:* The last 4 passwords must be unique.
:* A user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password.
:* A user is logged off after an inactivity period of 15 minutes.
 
PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:
:* For your Web hosting account administration area (Web hosting account where your online store is hosted);
:* For FTP access to the Web server;
:* For Remote Desktop Connection to the Web server (if available);
:* To connect to the MySQL server that contains your store data.
 
Linux authentication mechanism is used for login in the servers with running X-Cart Payments.
Accounts for access to the operating system are managed by the Linux administrator.
For Linux operating system accounts, you must configure the following attributes of the password policy:
:* use personal accounts, do not use any group, shared, or generic accounts and passwords;
:* changes to user passwords at least once every 90 days;
:* require a minimum length of at least seven characters;
:* contain both numeric and alphabetic characters;
:* do not use last four passwords used previously;
:* block account after six invalid logon attempts (minimum 30 minutes or until an administrator enables the user ID).
 
Two-factor authentication must be used for remote access to the operating system. The authentication methods, also known as factors, are:
:* something you know, such as a password or a passphrase;
:* something you have, such as a token device or a smart card;
:* something you are, such as a biometric.
 

== Logging==
Audit trails are automatically enabled with the default installation of X-Cart Payments. Users do not have the ability to disable or change the logging parameters of X-Cart Payments. X-Cart Payments log journal does not contain cardholder data. It is implemented at the source code level. The setting of an event log journal does not require any additional action from users.
The log files are created in the var/log/ directory. In X-Cart Payments 3.0, logs can be viewed via the X-Cart Payments admin back end. Make sure you restrict access to the log files by business need-to-know.
The following types of activity are logged:
:* All actions taken by any individual with root or administrative privileges.
:* Successes and failures of all individual accesses to application sections and functions.
:* Initialization of the audit logs.
:* User sign in and sign out.
 
Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to the files access.log and error.log.
Each log event includes:
:* Type of event;
:* Date and time of event;
:* Username and IP address;
:* Success or failure indication;
:* Action which led to the event;
:* Component which led to the event.
 
There is also a meta-log which contains information about other log files being created.
Make sure you have a system-level auditing software properly configured to monitor users' activity on the server. This software should:
:* warn on a checksum change of any of X-Cart Payments source code files except for the log file and the database files;
:* record any file writing operations related to X-Cart Payments files.
 

==Communication==
LAN channel or other available connection method can be used as a communication channel.
X-Cart Payments payment application supports the following data formats:
{| class="wikitable" width=90%
|-
| scope="col" style="width: 20%;"| '''Protocol'''
| scope="col" style="width: 70%;"| HTTP protocol (RFC 2616: HTTP/1.1) is used for data transfer between client and server
|- style="vertical-align:top;"
| '''Data transmission method'''
| Only encrypted cardholder data (RSA 2048 and AES 256) is transferred. RAW POST method is used for data transmission – (data stream is transmitted in the body of the request that is sent from client to server)
|- style="vertical-align:top;"
| '''Data format'''
| Data is transmitted in XML format (Extensible Markup Language (XML) 1.0)
|- style="vertical-align:top;"
| '''Port'''
| X-Cart Payments payment application uses ports 80, 443
|-
|}
 
'''Network traffic encryption''' 
X-Cart Payments uses encryption, such as TLS or IPSEC, for:
:* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
:* providing remote web-based access to the application.
 
If you use some tools to remotely access the application, you should encrypt all the communication using such technologies as TLS or IPSEC.
 
As per PCI DSS requirement, cardholder data must never be sent unencrypted by email, and X-Cart Payments does meet this requirement never sending cardholder data by email or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.
 
'''Enable TLS''' 
TLS protects data that is transmitted between a browser and your web server. It is critical that you have TLS enabled on your web server, and one of the first steps you should take after the installation is to enable TLS.
:* Your web server must be configured to use TLS v1.1 or v1.2 protocols with strong encryption (128-bit or longer key is required).
:* You will need to have a certificate issued for your web domain. Read guidelines on installing Comodo's Instant TLS certificates.
 
If a web server does not have TLS enabled, X-Cart Payments will not function or will be notifying users depending on the allow_insecure_protocol parameter set in the config.ini.php file (disabled by default).
X-Cart Payments does not support remote administrative access. Strong encryption must be used for remote access to the server.
The connection of servers with X-Cart Payments payment application to the Internet must be protected by a firewall. In X-Cart Payments configurations involving more than one server, server connections should take place in network segments separated from the Internet via stateful inspection firewalls.
 
'''Wireless communications''' 
If you use wireless networking to access X-Cart Payments, it is your responsibility to ensure your wireless security configuration follows the PCI DSS requirements.
:* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
:* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
:* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
:* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
::* Use with a minimum 104-bit encryption key and 24 bit-initialization value.
::* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS.
::* Rotate shared WEP keys quarterly (or automatically if the technology permits).
::* Rotate shared WEP keys whenever there are changes in personnel with access to keys.
::* Restrict access based on media access code (MAC) address.
::* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.
 
'''Remote access''' 
X-Cart Payments provides web-based access using two-factor authentication based on one-time codes. Detailed information can be found on the [[X-Payments:Two-factor_authentication | X-Payments:Two-factor authentication]] page.
If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:
:* Change the default settings in the remote access software (for example, change the default passwords and use unique passwords for each customer).
:* Allow connections only from specific (known) IP/MAC addresses.
:* Use strong authentication or complex passwords for logins.
:* Enable encrypted data transmission.
:* Enable account lockout after a certain number of failed login attempts.
:* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed.
:* Enable any logging or auditing functions.
:* Restrict access to customer passwords to authorized reseller/integrator personnel.
:* Establish customer passwords according to PCI DSS requirements.
Qualiteam does not provide software updates via remote access on an automated basis.
 

==Hardware and software==
The following requirements must be met for X-Cart Payments payment application self-service terminals: 
'''Operating System''' 
Linux Ubuntu 16 or later 
'''DBMS''' 
My SQL 5.6 or later 
'''Software''' 
PHP 5.5 or later 
Apache 2.4 or later
 
==Product versioning methodology==
{| class="wikitable" width=90%
|-
! scope="col" style="width: 15%;"| '''Version number changes'''
! scope="col" style="width: 45%;"| '''Software changes'''
! scope="col" style="width: 15%;"| '''Description'''
! scope="col" style="width: 15%;"| '''PA-DSS changes'''
|- style="vertical-align:top;"
| Version number does not change
| Change of the software name Change of the vendor name
| Changes not related to the software development process
| Administrative
|- style="vertical-align:top;"
| Increment of the minor version number to reflect a change not affecting the certification. For example, change of the version number from 1.0.5 to 1.0.6 (for the certification of 1.0.x)
| - Changes to the user interface - Changes to the database schema - Changes to supported payment gateway integrations / Addition of new payment gateway integrations
| Сhanges that have no impact on the PA-DSS requirements compliance or Payment Application security
| No Impact
|- style="vertical-align:top;"
| Increment of the second version number. For example, change of the version number from 1.1.* to 1.2.*
| Software changes satisfy the following conditions: - Fewer than 4 sections of the standard (from 1 to 12) involved; - Fewer than a half of all the requirements of the standard (sections 1 to 12) involved; - Less than a half of the software functions (or code) modified; - Changes implemented for compatibility with the updated versions of previously tested OS, DBMS and third party software products. - Addition/removal of supported payment processors. - Recompilation of the source code using a new compiler or different compiler settings. - Changes of the software versioning policy. - Changes of the software not related to security.
| - Changes in the software affecting payment card data mechanisms. - Changes addressing the identified vulnerabilities of the application. - Changes related to the completion of the annual cycle of development (if there are other changes).
| Low Impact
|- style="vertical-align:top;"
| Increment of the first version number. For example, change of the version number from 1.0.* to 2.0.*
| Software changes satisfy the following conditions: - 4 or more sections of the standard (from 1 to 12) involved; - More than a half of all the requirements of the standard (sections 1 to 12) involved; - More than a half of the software functions (or code) modified; - Addition of new supported platforms/OS versions.
| Major changes in the software architecture, global alterations of code
| High Impact
|}
 
The release of each new version is accompanied with a notification to all the application users (agents), which indicates the new application version number and a list of main changes in the new version.
 

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PA-DSS implementation guide for X-Cart Payments 3

2016-05-26T09:40:40Z

Alex “Ambal” Mulin: /* Data protection */

==Introduction==
The purpose of this PA-DSS Implementation Guide is to inform employees of organizations using the X-Cart Payments payment application by Qualiteam Software Limited about the methods and means of protection of account data in the X-Cart Payments software.
 
The methods include the need for compliance with the information security standards in the payment card industry developed by the international payment systems Visa and MasterCard – Payment Card Industry Data Security Standard (PCI DSS) and Payment Application Data Security Standard (PA-DSS). For additional information about PCI DSS, please visit the [https://www.pcisecuritystandards.org/ Official PCI Security Standards Council Site].
 
The document provides instructions on how to implement the application in a PCI DSS compliant manner.
 
Full product name – X-Cart Payments. 
Product version – 3.0.х.
 
Any servers used to run the X-Cart Payments payment application must be configured according to this PA-DSS Implementation Guide.
 
This PA-DSS Implementation Guide should be updated:
:* at least annually;
:* after changes in the payment application (if required);
:* after changes in the PCI DSS and PA-DSS standards.
 
The updated Version of the PA-DSS Implementation Guide has to be sent to all the merchants using X-Cart Payments.
 
The history of changes to the X-Cart Payments PA-DSS Implementation Guide is provided in the table below.
 
'''Table.1. X-Cart Payments PA-DSS Implementation Guide history of changes''' 
{| class="wikitable" width=90%
|-
! scope="col" style="width: 10%;"| '''Author'''
! scope="col" style="width: 10%;"| '''Date'''
! scope="col" style="width: 10%;"| '''Number'''
! scope="col" style="width: 60%;"| '''Change description'''
|- style="vertical-align:top;"
|
| 05/17/2016
| 01
| The original version of the document, designed to meet the requirements of PCI DSS version 3.1 and PA DSS version 3.1
|-
|}
 

==Data protection==
The PCI DSS and PA-DSS standards prohibit storage of sensitive authentication data (after authorization) or cardholder data in cleartext. 
Cardholder data includes:
:* Primary Account Number (PAN)
:* Cardholder Name
:* Expiration Date
:* Service Code
 
Sensitive authentication data (SAD) includes:
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
 
X-Cart Payments has the ability to store parts of cardholder data temporarily to perform 3D Secure verification and certain types of transactions for some of the integrated payment processors. During storage, cardholder data is encrypted using RSA 2048 algorithm and AES 256 for key encryption. When its storage period is over, the data is removed automatically via "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.
 
X-Cart Payments may not be configured to store permanently in the database the following types of data:
:* Full PAN
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature.
 
The payment application masks PAN on display (except for the moment when the user enters the card number).
X-Cart Payments can display masked PAN on the "Payment details" pages and in the "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. The same data (partially masked with asterisks) may be passed via the API to the integrated software products. X-Cart Payments does not have the ability to display full PAN anywhere, and there are no settings that can change this behavior of the user interface.
 

==Data Collected while Testing==
Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:
# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever choose to collect credit card information to troubleshoot a problem that a customer of yours is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access.
#* Only collect a limited amount of data (no more than is needed to solve the problem).
#* Sensitive authentication data must be encrypted during storage. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Sensitive authentication data must be securely deleted immediately after use.
To prevent uncontrolled storage of cardholder data (for example, in case of operating system failure), it is recommended to disable the swap file or move it to a specially prepared encrypted partition.
 
==Authentication and access==
The X-Cart Payments payment application has an only user type. This type cannot get access to payment card numbers and does not have any administrative privileges that may affect PA-DSS compliance.
There are no built-in/default user accounts in X-Cart Payments. You must carefully control access to X-Cart Payments. Follow these rules:
:* Restrict the number of employees who have access to X-Cart Payments to only those who have a business need.
:* Always provide unique usernames for each person who needs access.
:* Do not use system-default usernames and/or passwords.
:* Ensure that web server is run under a non-privileged user account and the application has access to the database from a limited privilege user account.
 
To set password lifetime:
# Log in to X-Cart Payments.
# Go to Settings -> General Settings.
# In the "User account password lifetime" field, enter the number of days for which the user account password needs to be valid. The maximum allowed password lifetime is 90 days.
The following related rules apply:
:* The minimum password length is 8 characters.
:* A password must contain both numbers and lower- and uppercase characters.
:* The last 4 passwords must be unique.
:* A user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password.
:* A user is logged off after an inactivity period of 15 minutes.
 
PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:
:* For your Web hosting account administration area (Web hosting account where your online store is hosted);
:* For FTP access to the Web server;
:* For Remote Desktop Connection to the Web server (if available);
:* To connect to the MySQL server that contains your store data.
 
Linux authentication mechanism is used for login in the servers with running X-Cart Payments.
Accounts for access to the operating system are managed by the Linux administrator.
For Linux operating system accounts, you must configure the following attributes of the password policy:
:* use personal accounts, do not use any group, shared, or generic accounts and passwords;
:* changes to user passwords at least once every 90 days;
:* require a minimum length of at least seven characters;
:* contain both numeric and alphabetic characters;
:* do not use last four passwords used previously;
:* block account after six invalid logon attempts (minimum 30 minutes or until an administrator enables the user ID).
 
Two-factor authentication must be used for remote access to the operating system. The authentication methods, also known as factors, are:
:* something you know, such as a password or a passphrase;
:* something you have, such as a token device or a smart card;
:* something you are, such as a biometric.
 

== Logging==
Audit trails are automatically enabled with the default installation of X-Cart Payments. Users do not have the ability to disable or change the logging parameters of X-Cart Payments. X-Cart Payments log journal does not contain cardholder data. It is implemented at the source code level. The setting of an event log journal does not require any additional action from users.
The log files are created in the var/log/ directory. In X-Cart Payments 3.0, logs can be viewed via the X-Cart Payments admin back end. Make sure you restrict access to the log files by business need-to-know.
The following types of activity are logged:
:* All actions taken by any individual with root or administrative privileges.
:* Successes and failures of all individual accesses to application sections and functions.
:* Initialization of the audit logs.
:* User sign in and sign out.
 
Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to the files access.log and error.log.
Each log event includes:
:* Type of event;
:* Date and time of event;
:* Username and IP address;
:* Success or failure indication;
:* Action which led to the event;
:* Component which led to the event.
 
There is also a meta-log which contains information about other log files being created.
Make sure you have a system-level auditing software properly configured to monitor users' activity on the server. This software should:
:* warn on a checksum change of any of X-Cart Payments source code files except for the log file and the database files;
:* record any file writing operations related to X-Cart Payments files.
 

==Communication==
LAN channel or other available connection method can be used as a communication channel.
X-Cart Payments payment application supports the following data formats:
{| class="wikitable" width=90%
|-
| scope="col" style="width: 20%;"| '''Protocol'''
| scope="col" style="width: 70%;"| HTTP protocol (RFC 2616: HTTP/1.1) is used for data transfer between client and server
|- style="vertical-align:top;"
| '''Data transmission method'''
| Only encrypted cardholder data (RSA 2048 and AES 256) is transferred. RAW POST method is used for data transmission – (data stream is transmitted in the body of the request that is sent from client to server)
|- style="vertical-align:top;"
| '''Data format'''
| Data is transmitted in XML format (Extensible Markup Language (XML) 1.0)
|- style="vertical-align:top;"
| '''Port'''
| X-Cart Payments payment application uses ports 80, 123, 443
|-
|}
 
'''Network traffic encryption''' 
X-Cart Payments uses encryption, such as TLS or IPSEC, for:
:* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
:* providing remote web-based access to the application.
 
If you use some tools to remotely access the application, you should encrypt all the communication using such technologies as TLS or IPSEC.
 
As per PCI DSS requirement, cardholder data must never be sent unencrypted by email, and X-Cart Payments does meet this requirement never sending cardholder data by email or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.
 
'''Enable TLS''' 
TLS protects data that is transmitted between a browser and your web server. It is critical that you have TLS enabled on your web server, and one of the first steps you should take after the installation is to enable TLS.
:* Your web server must be configured to use TLS v1.1 or v1.2 protocols with strong encryption (128-bit or longer key is required).
:* You will need to have a certificate issued for your web domain. Read guidelines on installing Comodo's Instant TLS certificates.
 
If a web server does not have TLS enabled, X-Cart Payments will not function or will be notifying users depending on the allow_insecure_protocol parameter set in the config.ini.php file (disabled by default).
X-Cart Payments does not support remote administrative access. Strong encryption must be used for remote access to the server.
The connection of servers with X-Cart Payments payment application to the Internet must be protected by a firewall. In X-Cart Payments configurations involving more than one server, server connections should take place in network segments separated from the Internet via stateful inspection firewalls.
 
'''Wireless communications''' 
If you use wireless networking to access X-Cart Payments, it is your responsibility to ensure your wireless security configuration follows the PCI DSS requirements.
:* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
:* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
:* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
:* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
::* Use with a minimum 104-bit encryption key and 24 bit-initialization value.
::* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS.
::* Rotate shared WEP keys quarterly (or automatically if the technology permits).
::* Rotate shared WEP keys whenever there are changes in personnel with access to keys.
::* Restrict access based on media access code (MAC) address.
::* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.
 
'''Remote access''' 
X-Cart Payments provides web-based access using two-factor authentication based on one-time codes. Detailed information can be found on the [[X-Payments:Two-factor_authentication | X-Payments:Two-factor authentication]] page.
If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:
:* Change the default settings in the remote access software (for example, change the default passwords and use unique passwords for each customer).
:* Allow connections only from specific (known) IP/MAC addresses.
:* Use strong authentication or complex passwords for logins.
:* Enable encrypted data transmission.
:* Enable account lockout after a certain number of failed login attempts.
:* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed.
:* Enable any logging or auditing functions.
:* Restrict access to customer passwords to authorized reseller/integrator personnel.
:* Establish customer passwords according to PCI DSS requirements.
Qualiteam does not provide software updates via remote access on an automated basis.
 

==Hardware and software==
The following requirements must be met for X-Cart Payments payment application self-service terminals: 
'''Operating System''' 
Linux Ubuntu 16 or later 
'''DBMS''' 
My SQL 5.6 or later 
'''Software''' 
PHP 5.5 or later 
Apache 2.4 or later
 
==Product versioning methodology==
{| class="wikitable" width=90%
|-
! scope="col" style="width: 15%;"| '''Version number changes'''
! scope="col" style="width: 45%;"| '''Software changes'''
! scope="col" style="width: 15%;"| '''Description'''
! scope="col" style="width: 15%;"| '''PA-DSS changes'''
|- style="vertical-align:top;"
| Version number does not change
| Change of the software name Change of the vendor name
| Changes not related to the software development process
| Administrative
|- style="vertical-align:top;"
| Increment of the minor version number to reflect a change not affecting the certification. For example, change of the version number from 1.0.5 to 1.0.6 (for the certification of 1.0.x)
| - Changes to the user interface - Changes to the database schema - Changes to supported payment gateway integrations / Addition of new payment gateway integrations
| Сhanges that have no impact on the PA-DSS requirements compliance or Payment Application security
| No Impact
|- style="vertical-align:top;"
| Increment of the second version number. For example, change of the version number from 1.1.* to 1.2.*
| Software changes satisfy the following conditions: - Fewer than 4 sections of the standard (from 1 to 12) involved; - Fewer than a half of all the requirements of the standard (sections 1 to 12) involved; - Less than a half of the software functions (or code) modified; - Changes implemented for compatibility with the updated versions of previously tested OS, DBMS and third party software products. - Addition/removal of supported payment processors. - Recompilation of the source code using a new compiler or different compiler settings. - Changes of the software versioning policy. - Changes of the software not related to security.
| - Changes in the software affecting payment card data mechanisms. - Changes addressing the identified vulnerabilities of the application. - Changes related to the completion of the annual cycle of development (if there are other changes).
| Low Impact
|- style="vertical-align:top;"
| Increment of the first version number. For example, change of the version number from 1.0.* to 2.0.*
| Software changes satisfy the following conditions: - 4 or more sections of the standard (from 1 to 12) involved; - More than a half of all the requirements of the standard (sections 1 to 12) involved; - More than a half of the software functions (or code) modified; - Addition of new supported platforms/OS versions.
| Major changes in the software architecture, global alterations of code
| High Impact
|}
 
The release of each new version is accompanied with a notification to all the application users (agents), which indicates the new application version number and a list of main changes in the new version.
 

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PA-DSS implementation guide for X-Cart Payments 3

2016-05-26T09:25:12Z

Alex “Ambal” Mulin:

==Introduction==
The purpose of this PA-DSS Implementation Guide is to inform employees of organizations using the X-Cart Payments payment application by Qualiteam Software Limited about the methods and means of protection of account data in the X-Cart Payments software.
 
The methods include the need for compliance with the information security standards in the payment card industry developed by the international payment systems Visa and MasterCard – Payment Card Industry Data Security Standard (PCI DSS) and Payment Application Data Security Standard (PA-DSS). For additional information about PCI DSS, please visit the [https://www.pcisecuritystandards.org/ Official PCI Security Standards Council Site].
 
The document provides instructions on how to implement the application in a PCI DSS compliant manner.
 
Full product name – X-Cart Payments. 
Product version – 3.0.х.
 
Any servers used to run the X-Cart Payments payment application must be configured according to this PA-DSS Implementation Guide.
 
This PA-DSS Implementation Guide should be updated:
:* at least annually;
:* after changes in the payment application (if required);
:* after changes in the PCI DSS and PA-DSS standards.
 
The updated Version of the PA-DSS Implementation Guide has to be sent to all the merchants using X-Cart Payments.
 
The history of changes to the X-Cart Payments PA-DSS Implementation Guide is provided in the table below.
 
'''Table.1. X-Cart Payments PA-DSS Implementation Guide history of changes''' 
{| class="wikitable" width=90%
|-
! scope="col" style="width: 10%;"| '''Author'''
! scope="col" style="width: 10%;"| '''Date'''
! scope="col" style="width: 10%;"| '''Number'''
! scope="col" style="width: 60%;"| '''Change description'''
|- style="vertical-align:top;"
|
| 05/17/2016
| 01
| The original version of the document, designed to meet the requirements of PCI DSS version 3.1 and PA DSS version 3.1
|-
|}
 

==Data protection==
The PCI DSS and PA-DSS standards prohibit storage of sensitive authentication data (after authorization) or cardholder data in cleartext. 
Cardholder data includes:
:* Primary Account Number (PAN)
:* Cardholder Name
:* Expiration Date
:* Service Code
 
Sensitive authentication data (SAD) includes:
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
 
X-Cart Payments has the ability to store parts of cardholder data temporarily to perform 3D Secure verification and certain types of transactions for some of the integrated payment processors. During storage, cardholder data is encrypted using RSA 2056 algorithm and AES 256 for key encryption. When its storage period is over, the data is removed automatically via "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.
 
X-Cart Payments may not be configured to store permanently in the database the following types of data:
:* Full PAN
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature.
 
The payment application masks PAN on display (except for the moment when the user enters the card number).
X-Cart Payments can display masked PAN on the "Payment details" pages and in the "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. The same data (partially masked with asterisks) may be passed via the API to the integrated software products. X-Cart Payments does not have the ability to display full PAN anywhere, and there are no settings that can change this behavior of the user interface.
 

==Data Collected while Testing==
Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:
# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever choose to collect credit card information to troubleshoot a problem that a customer of yours is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access.
#* Only collect a limited amount of data (no more than is needed to solve the problem).
#* Sensitive authentication data must be encrypted during storage. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Sensitive authentication data must be securely deleted immediately after use.
To prevent uncontrolled storage of cardholder data (for example, in case of operating system failure), it is recommended to disable the swap file or move it to a specially prepared encrypted partition.
 
==Authentication and access==
The X-Cart Payments payment application has an only user type. This type cannot get access to payment card numbers and does not have any administrative privileges that may affect PA-DSS compliance.
There are no built-in/default user accounts in X-Cart Payments. You must carefully control access to X-Cart Payments. Follow these rules:
:* Restrict the number of employees who have access to X-Cart Payments to only those who have a business need.
:* Always provide unique usernames for each person who needs access.
:* Do not use system-default usernames and/or passwords.
:* Ensure that web server is run under a non-privileged user account and the application has access to the database from a limited privilege user account.
 
To set password lifetime:
# Log in to X-Cart Payments.
# Go to Settings -> General Settings.
# In the "User account password lifetime" field, enter the number of days for which the user account password needs to be valid. The maximum allowed password lifetime is 90 days.
The following related rules apply:
:* The minimum password length is 8 characters.
:* A password must contain both numbers and lower- and uppercase characters.
:* The last 4 passwords must be unique.
:* A user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password.
:* A user is logged off after an inactivity period of 15 minutes.
 
PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:
:* For your Web hosting account administration area (Web hosting account where your online store is hosted);
:* For FTP access to the Web server;
:* For Remote Desktop Connection to the Web server (if available);
:* To connect to the MySQL server that contains your store data.
 
Linux authentication mechanism is used for login in the servers with running X-Cart Payments.
Accounts for access to the operating system are managed by the Linux administrator.
For Linux operating system accounts, you must configure the following attributes of the password policy:
:* use personal accounts, do not use any group, shared, or generic accounts and passwords;
:* changes to user passwords at least once every 90 days;
:* require a minimum length of at least seven characters;
:* contain both numeric and alphabetic characters;
:* do not use last four passwords used previously;
:* block account after six invalid logon attempts (minimum 30 minutes or until an administrator enables the user ID).
 
Two-factor authentication must be used for remote access to the operating system. The authentication methods, also known as factors, are:
:* something you know, such as a password or a passphrase;
:* something you have, such as a token device or a smart card;
:* something you are, such as a biometric.
 

== Logging==
Audit trails are automatically enabled with the default installation of X-Cart Payments. Users do not have the ability to disable or change the logging parameters of X-Cart Payments. X-Cart Payments log journal does not contain cardholder data. It is implemented at the source code level. The setting of an event log journal does not require any additional action from users.
The log files are created in the var/log/ directory. In X-Cart Payments 3.0, logs can be viewed via the X-Cart Payments admin back end. Make sure you restrict access to the log files by business need-to-know.
The following types of activity are logged:
:* All actions taken by any individual with root or administrative privileges.
:* Successes and failures of all individual accesses to application sections and functions.
:* Initialization of the audit logs.
:* User sign in and sign out.
 
Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to the files access.log and error.log.
Each log event includes:
:* Type of event;
:* Date and time of event;
:* Username and IP address;
:* Success or failure indication;
:* Action which led to the event;
:* Component which led to the event.
 
There is also a meta-log which contains information about other log files being created.
Make sure you have a system-level auditing software properly configured to monitor users' activity on the server. This software should:
:* warn on a checksum change of any of X-Cart Payments source code files except for the log file and the database files;
:* record any file writing operations related to X-Cart Payments files.
 

==Communication==
LAN channel or other available connection method can be used as a communication channel.
X-Cart Payments payment application supports the following data formats:
{| class="wikitable" width=90%
|-
| scope="col" style="width: 20%;"| '''Protocol'''
| scope="col" style="width: 70%;"| HTTP protocol (RFC 2616: HTTP/1.1) is used for data transfer between client and server
|- style="vertical-align:top;"
| '''Data transmission method'''
| Only encrypted cardholder data (RSA 2048 and AES 256) is transferred. RAW POST method is used for data transmission – (data stream is transmitted in the body of the request that is sent from client to server)
|- style="vertical-align:top;"
| '''Data format'''
| Data is transmitted in XML format (Extensible Markup Language (XML) 1.0)
|- style="vertical-align:top;"
| '''Port'''
| X-Cart Payments payment application uses ports 80, 123, 443
|-
|}
 
'''Network traffic encryption''' 
X-Cart Payments uses encryption, such as TLS or IPSEC, for:
:* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
:* providing remote web-based access to the application.
 
If you use some tools to remotely access the application, you should encrypt all the communication using such technologies as TLS or IPSEC.
 
As per PCI DSS requirement, cardholder data must never be sent unencrypted by email, and X-Cart Payments does meet this requirement never sending cardholder data by email or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.
 
'''Enable TLS''' 
TLS protects data that is transmitted between a browser and your web server. It is critical that you have TLS enabled on your web server, and one of the first steps you should take after the installation is to enable TLS.
:* Your web server must be configured to use TLS v1.1 or v1.2 protocols with strong encryption (128-bit or longer key is required).
:* You will need to have a certificate issued for your web domain. Read guidelines on installing Comodo's Instant TLS certificates.
 
If a web server does not have TLS enabled, X-Cart Payments will not function or will be notifying users depending on the allow_insecure_protocol parameter set in the config.ini.php file (disabled by default).
X-Cart Payments does not support remote administrative access. Strong encryption must be used for remote access to the server.
The connection of servers with X-Cart Payments payment application to the Internet must be protected by a firewall. In X-Cart Payments configurations involving more than one server, server connections should take place in network segments separated from the Internet via stateful inspection firewalls.
 
'''Wireless communications''' 
If you use wireless networking to access X-Cart Payments, it is your responsibility to ensure your wireless security configuration follows the PCI DSS requirements.
:* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
:* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
:* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
:* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
::* Use with a minimum 104-bit encryption key and 24 bit-initialization value.
::* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS.
::* Rotate shared WEP keys quarterly (or automatically if the technology permits).
::* Rotate shared WEP keys whenever there are changes in personnel with access to keys.
::* Restrict access based on media access code (MAC) address.
::* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.
 
'''Remote access''' 
X-Cart Payments provides web-based access using two-factor authentication based on one-time codes. Detailed information can be found on the [[X-Payments:Two-factor_authentication | X-Payments:Two-factor authentication]] page.
If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:
:* Change the default settings in the remote access software (for example, change the default passwords and use unique passwords for each customer).
:* Allow connections only from specific (known) IP/MAC addresses.
:* Use strong authentication or complex passwords for logins.
:* Enable encrypted data transmission.
:* Enable account lockout after a certain number of failed login attempts.
:* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed.
:* Enable any logging or auditing functions.
:* Restrict access to customer passwords to authorized reseller/integrator personnel.
:* Establish customer passwords according to PCI DSS requirements.
Qualiteam does not provide software updates via remote access on an automated basis.
 

==Hardware and software==
The following requirements must be met for X-Cart Payments payment application self-service terminals: 
'''Operating System''' 
Linux Ubuntu 16 or later 
'''DBMS''' 
My SQL 5.6 or later 
'''Software''' 
PHP 5.5 or later 
Apache 2.4 or later
 
==Product versioning methodology==
{| class="wikitable" width=90%
|-
! scope="col" style="width: 15%;"| '''Version number changes'''
! scope="col" style="width: 45%;"| '''Software changes'''
! scope="col" style="width: 15%;"| '''Description'''
! scope="col" style="width: 15%;"| '''PA-DSS changes'''
|- style="vertical-align:top;"
| Version number does not change
| Change of the software name Change of the vendor name
| Changes not related to the software development process
| Administrative
|- style="vertical-align:top;"
| Increment of the minor version number to reflect a change not affecting the certification. For example, change of the version number from 1.0.5 to 1.0.6 (for the certification of 1.0.x)
| - Changes to the user interface - Changes to the database schema - Changes to supported payment gateway integrations / Addition of new payment gateway integrations
| Сhanges that have no impact on the PA-DSS requirements compliance or Payment Application security
| No Impact
|- style="vertical-align:top;"
| Increment of the second version number. For example, change of the version number from 1.1.* to 1.2.*
| Software changes satisfy the following conditions: - Fewer than 4 sections of the standard (from 1 to 12) involved; - Fewer than a half of all the requirements of the standard (sections 1 to 12) involved; - Less than a half of the software functions (or code) modified; - Changes implemented for compatibility with the updated versions of previously tested OS, DBMS and third party software products. - Addition/removal of supported payment processors. - Recompilation of the source code using a new compiler or different compiler settings. - Changes of the software versioning policy. - Changes of the software not related to security.
| - Changes in the software affecting payment card data mechanisms. - Changes addressing the identified vulnerabilities of the application. - Changes related to the completion of the annual cycle of development (if there are other changes).
| Low Impact
|- style="vertical-align:top;"
| Increment of the first version number. For example, change of the version number from 1.0.* to 2.0.*
| Software changes satisfy the following conditions: - 4 or more sections of the standard (from 1 to 12) involved; - More than a half of all the requirements of the standard (sections 1 to 12) involved; - More than a half of the software functions (or code) modified; - Addition of new supported platforms/OS versions.
| Major changes in the software architecture, global alterations of code
| High Impact
|}
 
The release of each new version is accompanied with a notification to all the application users (agents), which indicates the new application version number and a list of main changes in the new version.
 

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PA-DSS implementation guide for X-Cart Payments 3

2016-05-26T09:23:38Z

Alex “Ambal” Mulin:

==Introduction==
The purpose of this PA-DSS Implementation Guide is to inform employees of organizations using the X-Cart Payments payment application by Qualiteam Software Limited about the methods and means of protection of account data in the X-Cart Payments software.
 
The methods include the need for compliance with the information security standards in the payment card industry developed by the international payment systems Visa and MasterCard – Payment Card Industry Data Security Standard (PCI DSS) and Payment Application Data Security Standard (PA-DSS). For additional information about PCI DSS, please visit the [https://www.pcisecuritystandards.org/ Official PCI Security Standards Council Site].
 
The document provides instructions on how to implement the application in a PCI DSS compliant manner.
 
Full product name – X-Cart Payments. 
Product version – 3.0.х.
 
Any servers used to run the X-Cart Payments payment application must be configured according to this PA-DSS Implementation Guide.
 
This PA-DSS Implementation Guide should be updated:
:* at least annually;
:* after changes in the payment application (if required);
:* after changes in the PCI DSS and PA-DSS standards.
 
The updated Version of the PA-DSS Implementation Guide has to be sent to all the merchants using X-Cart Payments.
 
The history of changes to the X-Cart Payments PA-DSS Implementation Guide is provided in the table below.
 
'''Table.1. X-Cart Payments PA-DSS Implementation Guide history of changes''' 
{| class="wikitable" width=90%
|-
! scope="col" style="width: 10%;"| '''Author'''
! scope="col" style="width: 10%;"| '''Date'''
! scope="col" style="width: 10%;"| '''Number'''
! scope="col" style="width: 60%;"| '''Change description'''
|- style="vertical-align:top;"
|
| 05/17/2016
| 01
| The original version of the document, designed to meet the requirements of PCI DSS version 3.1 and PA DSS version 3.1
|-
|}
 

==Data protection==
The PCI DSS and PA-DSS standards prohibit storage of sensitive authentication data (after authorization) or cardholder data in cleartext. 
Cardholder data includes:
:* Primary Account Number (PAN)
:* Cardholder Name
:* Expiration Date
:* Service Code
 
Sensitive authentication data (SAD) includes:
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
 
X-Cart Payments has the ability to store parts of cardholder data temporarily to perform 3D Secure verification and certain types of transactions for some of the integrated payment processors. During storage, cardholder data is encrypted using RSA 2056 algorithm and AES 256 for key encryption. When its storage period is over, the data is removed automatically via "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.
 
X-Cart Payments may not be configured to store permanently in the database the following types of data:
:* Full PAN
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature.
 
The payment application masks PAN on display (except for the moment when the user enters the card number).
X-Cart Payments can display masked PAN on the "Payment details" pages and in the "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. The same data (partially masked with asterisks) may be passed via the API to the integrated software products. X-Cart Payments does not have the ability to display full PAN anywhere, and there are no settings that can change this behavior of the user interface.
 

==Data Collected while Testing==
Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:
# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever choose to collect credit card information to troubleshoot a problem that a customer of yours is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access.
#* Only collect a limited amount of data (no more than is needed to solve the problem).
#* Sensitive authentication data must be encrypted during storage. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Sensitive authentication data must be securely deleted immediately after use.
To prevent uncontrolled storage of cardholder data (for example, in case of operating system failure), it is recommended to disable the swap file or move it to a specially prepared encrypted partition.
 
==Authentication and access==
The X-Cart Payments payment application has an only user type. This type cannot get access to payment card numbers and does not have any administrative privileges that may affect PA-DSS compliance.
There are no built-in/default user accounts in X-Cart Payments. You must carefully control access to X-Cart Payments. Follow these rules:
:* Restrict the number of employees who have access to X-Cart Payments to only those who have a business need.
:* Always provide unique usernames for each person who needs access.
:* Do not use system-default usernames and/or passwords.
:* Ensure that web server is run under a non-privileged user account and the application has access to the database from a limited privilege user account.
 
To set password lifetime:
# Log in to X-Cart Payments.
# Go to Settings -> General Settings.
# In the "User account password lifetime" field, enter the number of days for which the user account password needs to be valid. The maximum allowed password lifetime is 90 days.
The following related rules apply:
:* The minimum password length is 8 characters.
:* A password must contain both numbers and lower- and uppercase characters.
:* The last 4 passwords must be unique.
:* A user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password.
:* A user is logged off after an inactivity period of 15 minutes.
 
PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:
:* For your Web hosting account administration area (Web hosting account where your online store is hosted);
:* For FTP access to the Web server;
:* For Remote Desktop Connection to the Web server (if available);
:* To connect to the MySQL server that contains your store data.
 
Linux authentication mechanism is used for login in the servers with running X-Payments.
Accounts for access to the operating system are managed by the Linux administrator.
For Linux operating system accounts, you must configure the following attributes of the password policy:
:* use personal accounts, do not use any group, shared, or generic accounts and passwords;
:* changes to user passwords at least once every 90 days;
:* require a minimum length of at least seven characters;
:* contain both numeric and alphabetic characters;
:* do not use last four passwords used previously;
:* block account after six invalid logon attempts (minimum 30 minutes or until an administrator enables the user ID).
 
Two-factor authentication must be used for remote access to the operating system. The authentication methods, also known as factors, are:
:* something you know, such as a password or a passphrase;
:* something you have, such as a token device or a smart card;
:* something you are, such as a biometric.
 

== Logging==
Audit trails are automatically enabled with the default installation of X-Payments. Users do not have the ability to disable or change the logging parameters of X-Cart Payments. X-Cart Payments log journal does not contain cardholder data. It is implemented at the source code level. The setting of an event log journal does not require any additional action from users.
The log files are created in the var/log/ directory. In X-Cart Payments 3.0, logs can be viewed via the X-Cart Payments admin back end. Make sure you restrict access to the log files by business need-to-know.
The following types of activity are logged:
:* All actions taken by any individual with root or administrative privileges.
:* Successes and failures of all individual accesses to application sections and functions.
:* Initialization of the audit logs.
:* User sign in and sign out.
 
Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to the files access.log and error.log.
Each log event includes:
:* Type of event;
:* Date and time of event;
:* Username and IP address;
:* Success or failure indication;
:* Action which led to the event;
:* Component which led to the event.
 
There is also a meta-log which contains information about other log files being created.
Make sure you have a system-level auditing software properly configured to monitor users' activity on the server. This software should:
:* warn on a checksum change of any of X-Cart Payments source code files except for the log file and the database files;
:* record any file writing operations related to X-Cart Payments files.
 

==Communication==
LAN channel or other available connection method can be used as a communication channel.
X-Cart Payments payment application supports the following data formats:
{| class="wikitable" width=90%
|-
| scope="col" style="width: 20%;"| '''Protocol'''
| scope="col" style="width: 70%;"| HTTP protocol (RFC 2616: HTTP/1.1) is used for data transfer between client and server
|- style="vertical-align:top;"
| '''Data transmission method'''
| Only encrypted cardholder data (RSA 2048 and AES 256) is transferred. RAW POST method is used for data transmission – (data stream is transmitted in the body of the request that is sent from client to server)
|- style="vertical-align:top;"
| '''Data format'''
| Data is transmitted in XML format (Extensible Markup Language (XML) 1.0)
|- style="vertical-align:top;"
| '''Port'''
| X-Cart Payments payment application uses ports 80, 123, 443
|-
|}
 
'''Network traffic encryption''' 
X-Cart Payments uses encryption, such as TLS or IPSEC, for:
:* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
:* providing remote web-based access to the application.
 
If you use some tools to remotely access the application, you should encrypt all the communication using such technologies as TLS or IPSEC.
 
As per PCI DSS requirement, cardholder data must never be sent unencrypted by email, and X-Cart Payments does meet this requirement never sending cardholder data by email or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.
 
'''Enable TLS''' 
TLS protects data that is transmitted between a browser and your web server. It is critical that you have TLS enabled on your web server, and one of the first steps you should take after the installation is to enable TLS.
:* Your web server must be configured to use TLS v1.1 or v1.2 protocols with strong encryption (128-bit or longer key is required).
:* You will need to have a certificate issued for your web domain. Read guidelines on installing Comodo's Instant TLS certificates.
 
If a web server does not have TLS enabled, X-Cart Payments will not function or will be notifying users depending on the allow_insecure_protocol parameter set in the config.ini.php file (disabled by default).
X-Cart Payments does not support remote administrative access. Strong encryption must be used for remote access to the server.
The connection of servers with X-Cart Payments payment application to the Internet must be protected by a firewall. In X-Cart Payments configurations involving more than one server, server connections should take place in network segments separated from the Internet via stateful inspection firewalls.
 
'''Wireless communications''' 
If you use wireless networking to access X-Cart Payments, it is your responsibility to ensure your wireless security configuration follows the PCI DSS requirements.
:* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
:* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
:* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
:* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
::* Use with a minimum 104-bit encryption key and 24 bit-initialization value.
::* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS.
::* Rotate shared WEP keys quarterly (or automatically if the technology permits).
::* Rotate shared WEP keys whenever there are changes in personnel with access to keys.
::* Restrict access based on media access code (MAC) address.
::* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.
 
'''Remote access''' 
X-Cart Payments provides web-based access using two-factor authentication based on one-time codes. Detailed information can be found on the [[X-Payments:Two-factor_authentication | X-Payments:Two-factor authentication]] page.
If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:
:* Change the default settings in the remote access software (for example, change the default passwords and use unique passwords for each customer).
:* Allow connections only from specific (known) IP/MAC addresses.
:* Use strong authentication or complex passwords for logins.
:* Enable encrypted data transmission.
:* Enable account lockout after a certain number of failed login attempts.
:* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed.
:* Enable any logging or auditing functions.
:* Restrict access to customer passwords to authorized reseller/integrator personnel.
:* Establish customer passwords according to PCI DSS requirements.
Qualiteam does not provide software updates via remote access on an automated basis.
 

==Hardware and software==
The following requirements must be met for X-Cart Payments payment application self-service terminals: 
'''Operating System''' 
Linux Ubuntu 16 or later 
'''DBMS''' 
My SQL 5.6 or later 
'''Software''' 
PHP 5.5 or later 
Apache 2.4 or later
 
==Product versioning methodology==
{| class="wikitable" width=90%
|-
! scope="col" style="width: 15%;"| '''Version number changes'''
! scope="col" style="width: 45%;"| '''Software changes'''
! scope="col" style="width: 15%;"| '''Description'''
! scope="col" style="width: 15%;"| '''PA-DSS changes'''
|- style="vertical-align:top;"
| Version number does not change
| Change of the software name Change of the vendor name
| Changes not related to the software development process
| Administrative
|- style="vertical-align:top;"
| Increment of the minor version number to reflect a change not affecting the certification. For example, change of the version number from 1.0.5 to 1.0.6 (for the certification of 1.0.x)
| - Changes to the user interface - Changes to the database schema - Changes to supported payment gateway integrations / Addition of new payment gateway integrations
| Сhanges that have no impact on the PA-DSS requirements compliance or Payment Application security
| No Impact
|- style="vertical-align:top;"
| Increment of the second version number. For example, change of the version number from 1.1.* to 1.2.*
| Software changes satisfy the following conditions: - Fewer than 4 sections of the standard (from 1 to 12) involved; - Fewer than a half of all the requirements of the standard (sections 1 to 12) involved; - Less than a half of the software functions (or code) modified; - Changes implemented for compatibility with the updated versions of previously tested OS, DBMS and third party software products. - Addition/removal of supported payment processors. - Recompilation of the source code using a new compiler or different compiler settings. - Changes of the software versioning policy. - Changes of the software not related to security.
| - Changes in the software affecting payment card data mechanisms. - Changes addressing the identified vulnerabilities of the application. - Changes related to the completion of the annual cycle of development (if there are other changes).
| Low Impact
|- style="vertical-align:top;"
| Increment of the first version number. For example, change of the version number from 1.0.* to 2.0.*
| Software changes satisfy the following conditions: - 4 or more sections of the standard (from 1 to 12) involved; - More than a half of all the requirements of the standard (sections 1 to 12) involved; - More than a half of the software functions (or code) modified; - Addition of new supported platforms/OS versions.
| Major changes in the software architecture, global alterations of code
| High Impact
|}
 
The release of each new version is accompanied with a notification to all the application users (agents), which indicates the new application version number and a list of main changes in the new version.
 

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PA-DSS implementation guide for X-Cart Payments 3

2016-05-26T09:17:58Z

Alex “Ambal” Mulin: /* Introduction */

==Introduction==
The purpose of this PA-DSS Implementation Guide is to inform employees of organizations using the X-Cart Payments payment application by Qualiteam Software Limited about the methods and means of protection of account data in the X-Cart Payments software.
 
The methods include the need for compliance with the information security standards in the payment card industry developed by the international payment systems Visa and MasterCard – Payment Card Industry Data Security Standard (PCI DSS) and Payment Application Data Security Standard (PA-DSS). For additional information about PCI DSS, please visit the [https://www.pcisecuritystandards.org/ Official PCI Security Standards Council Site].
 
The document provides instructions on how to implement the application in a PCI DSS compliant manner.
 
Full product name – X-Cart Payments. 
Product version – 3.0.х.
 
Any servers used to run the X-Cart Payments payment application must be configured according to this PA-DSS Implementation Guide.
 
This PA-DSS Implementation Guide should be updated:
:* at least annually;
:* after changes in the payment application (if required);
:* after changes in the PCI DSS and PA-DSS standards.
 
The updated Version of the PA-DSS Implementation Guide has to be sent to all the merchants using X-Cart Payments.
 
The history of changes to the X-Cart Payments PA-DSS Implementation Guide is provided in the table below.
 
'''Table.1. X-Cart Payments PA-DSS Implementation Guide history of changes''' 
{| class="wikitable" width=90%
|-
! scope="col" style="width: 10%;"| '''Author'''
! scope="col" style="width: 10%;"| '''Date'''
! scope="col" style="width: 10%;"| '''Number'''
! scope="col" style="width: 60%;"| '''Change description'''
|- style="vertical-align:top;"
|
| 05/17/2016
| 01
| The original version of the document, designed to meet the requirements of PCI DSS version 3.1 and PA DSS version 3.1
|-
|}
 

==Data protection==
The PCI DSS and PA-DSS standards prohibit storage of sensitive authentication data (after authorization) or cardholder data in cleartext. 
Cardholder data includes:
:* Primary Account Number (PAN)
:* Cardholder Name
:* Expiration Date
:* Service Code
 
Sensitive authentication data (SAD) includes:
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
 
X-Payments has the ability to store parts of cardholder data temporarily to perform 3D Secure verification and certain types of transactions for some of the integrated payment processors. During storage, cardholder data is encrypted using RSA 2056 algorithm and AES 256 for key encryption. When its storage period is over, the data is removed automatically via "cron" software that needs to be installed and configured to run X-Payments periodic tasks.
 
X-Payments may not be configured to store permanently in the database the following types of data:
:* Full PAN
:* Full track data (magnetic-stripe data or equivalent on a chip)
:* CAV2/CVC2/CVV2/CID
:* PINs/PIN blocks
Merchants and/or developers implementing X-Payments should not attempt to customize this as a feature.
 
The payment application masks PAN on display (except for the moment when the user enters the card number).
X-Payments can display masked PAN on the "Payment details" pages and in the "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. The same data (partially masked with asterisks) may be passed via the API to the integrated software products. X-Payments does not have the ability to display full PAN anywhere, and there are no settings that can change this behavior of the user interface.
 

==Data Collected while Testing==
Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:
# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever choose to collect credit card information to troubleshoot a problem that a customer of yours is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access.
#* Only collect a limited amount of data (no more than is needed to solve the problem).
#* Sensitive authentication data must be encrypted during storage. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Sensitive authentication data must be securely deleted immediately after use.
To prevent uncontrolled storage of cardholder data (for example, in case of operating system failure), it is recommended to disable the swap file or move it to a specially prepared encrypted partition.
 
==Authentication and access==
The X-Payments payment application has an only user type. This type cannot get access to payment card numbers and does not have any administrative privileges that may affect PA-DSS compliance.
There are no built-in/default user accounts in X-Payments. You must carefully control access to X-Payments. Follow these rules:
:* Restrict the number of employees who have access to X-Payments to only those who have a business need.
:* Always provide unique usernames for each person who needs access.
:* Do not use system-default usernames and/or passwords.
:* Ensure that web server is run under a non-privileged user account and the application has access to the database from a limited privilege user account.
 
To set password lifetime:
# Log in to X-Cart Payments.
# Go to Settings -> General Settings.
# In the "User account password lifetime" field, enter the number of days for which the user account password needs to be valid. The maximum allowed password lifetime is 90 days.
The following related rules apply:
:* The minimum password length is 8 characters.
:* A password must contain both numbers and lower- and uppercase characters.
:* The last 4 passwords must be unique.
:* A user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password.
:* A user is logged off after an inactivity period of 15 minutes.
 
PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:
:* For your Web hosting account administration area (Web hosting account where your online store is hosted);
:* For FTP access to the Web server;
:* For Remote Desktop Connection to the Web server (if available);
:* To connect to the MySQL server that contains your store data.
 
Linux authentication mechanism is used for login in the servers with running X-Payments.
Accounts for access to the operating system are managed by the Linux administrator.
For Linux operating system accounts, you must configure the following attributes of the password policy:
:* use personal accounts, do not use any group, shared, or generic accounts and passwords;
:* changes to user passwords at least once every 90 days;
:* require a minimum length of at least seven characters;
:* contain both numeric and alphabetic characters;
:* do not use last four passwords used previously;
:* block account after six invalid logon attempts (minimum 30 minutes or until an administrator enables the user ID).
 
Two-factor authentication must be used for remote access to the operating system. The authentication methods, also known as factors, are:
:* something you know, such as a password or a passphrase;
:* something you have, such as a token device or a smart card;
:* something you are, such as a biometric.
 

== Logging==
Audit trails are automatically enabled with the default installation of X-Payments. Users do not have the ability to disable or change the logging parameters of X-Payments. X-Payments log journal does not contain cardholder data. It is implemented at the source code level. The setting of an event log journal does not require any additional action from users.
The log files are created in the var/log/ directory. In X-Payments 3.0, logs can be viewed via the X-Payments admin back end. Make sure you restrict access to the log files by business need-to-know.
The following types of activity are logged:
:* All actions taken by any individual with root or administrative privileges.
:* Successes and failures of all individual accesses to application sections and functions.
:* Initialization of the audit logs.
:* User sign in and sign out.
 
Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to the files access.log and error.log.
Each log event includes:
:* Type of event;
:* Date and time of event;
:* Username and IP address;
:* Success or failure indication;
:* Action which led to the event;
:* Component which led to the event.
 
There is also a meta-log which contains information about other log files being created.
Make sure you have a system-level auditing software properly configured to monitor users' activity on the server. This software should:
:* warn on a checksum change of any of X-Cart Payments source code files except for the log file and the database files;
:* record any file writing operations related to X-Cart Payments files.
 

==Communication==
LAN channel or other available connection method can be used as a communication channel.
X-Payments payment application supports the following data formats:
{| class="wikitable" width=90%
|-
| scope="col" style="width: 20%;"| '''Protocol'''
| scope="col" style="width: 70%;"| HTTP protocol (RFC 2616: HTTP/1.1) is used for data transfer between client and server
|- style="vertical-align:top;"
| '''Data transmission method'''
| Only encrypted cardholder data (RSA 2048 and AES 256) is transferred. RAW POST method is used for data transmission – (data stream is transmitted in the body of the request that is sent from client to server)
|- style="vertical-align:top;"
| '''Data format'''
| Data is transmitted in XML format (Extensible Markup Language (XML) 1.0)
|- style="vertical-align:top;"
| '''Port'''
| X-Payments payment application uses ports 80, 123, 443
|-
|}
 
'''Network traffic encryption''' 
X-Payments uses encryption, such as TLS or IPSEC, for:
:* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
:* providing remote web-based access to the application.
 
If you use some tools to remotely access the application, you should encrypt all the communication using such technologies as TLS or IPSEC.
 
As per PCI DSS requirement, cardholder data must never be sent unencrypted by email, and X-Payments does meet this requirement never sending cardholder data by email or by IMs. Merchants and/or developers implementing X-Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.
 
'''Enable TLS''' 
TLS protects data that is transmitted between a browser and your web server. It is critical that you have TLS enabled on your web server, and one of the first steps you should take after the installation is to enable TLS.
:* Your web server must be configured to use TLS v1.1 or v1.2 protocols with strong encryption (128-bit or longer key is required).
:* You will need to have a certificate issued for your web domain. Read guidelines on installing Comodo's Instant TLS certificates.
 
If a web server does not have TLS enabled, X-Payments will not function or will be notifying users depending on the allow_insecure_protocol parameter set in the config.ini.php file (disabled by default).
X-Payments does not support remote administrative access. Strong encryption must be used for remote access to the server.
The connection of servers with X-Payments payment application to the Internet must be protected by a firewall. In X-Payments configurations involving more than one server, server connections should take place in network segments separated from the Internet via stateful inspection firewalls.
 
'''Wireless communications''' 
If you use wireless networking to access X-Payments, it is your responsibility to ensure your wireless security configuration follows the PCI DSS requirements.
:* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
:* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
:* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
:* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
::* Use with a minimum 104-bit encryption key and 24 bit-initialization value.
::* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS.
::* Rotate shared WEP keys quarterly (or automatically if the technology permits).
::* Rotate shared WEP keys whenever there are changes in personnel with access to keys.
::* Restrict access based on media access code (MAC) address.
::* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.
 
'''Remote access''' 
X-Cart Payments provides web-based access using two-factor authentication based on one-time codes. Detailed information can be found on the [[X-Payments:Two-factor_authentication | X-Payments:Two-factor authentication]] page.
If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:
:* Change the default settings in the remote access software (for example, change the default passwords and use unique passwords for each customer).
:* Allow connections only from specific (known) IP/MAC addresses.
:* Use strong authentication or complex passwords for logins.
:* Enable encrypted data transmission.
:* Enable account lockout after a certain number of failed login attempts.
:* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed.
:* Enable any logging or auditing functions.
:* Restrict access to customer passwords to authorized reseller/integrator personnel.
:* Establish customer passwords according to PCI DSS requirements.
Qualiteam does not provide software updates via remote access on an automated basis.
 

==Hardware and software==
The following requirements must be met for X-Payments payment application self-service terminals: 
'''Operating System''' 
Linux Ubuntu 16 or later 
'''DBMS''' 
My SQL 5.6 or later 
'''Software''' 
PHP 5.5 or later 
Apache 2.4 or later
 
==Product versioning methodology==
{| class="wikitable" width=90%
|-
! scope="col" style="width: 15%;"| '''Version number changes'''
! scope="col" style="width: 45%;"| '''Software changes'''
! scope="col" style="width: 15%;"| '''Description'''
! scope="col" style="width: 15%;"| '''PA-DSS changes'''
|- style="vertical-align:top;"
| Version number does not change
| Change of the software name Change of the vendor name
| Changes not related to the software development process
| Administrative
|- style="vertical-align:top;"
| Increment of the minor version number to reflect a change not affecting the certification. For example, change of the version number from 1.0.5 to 1.0.6 (for the certification of 1.0.x)
| - Changes to the user interface - Changes to the database schema - Changes to supported payment gateway integrations / Addition of new payment gateway integrations
| Сhanges that have no impact on the PA-DSS requirements compliance or Payment Application security
| No Impact
|- style="vertical-align:top;"
| Increment of the second version number. For example, change of the version number from 1.1.* to 1.2.*
| Software changes satisfy the following conditions: - Fewer than 4 sections of the standard (from 1 to 12) involved; - Fewer than a half of all the requirements of the standard (sections 1 to 12) involved; - Less than a half of the software functions (or code) modified; - Changes implemented for compatibility with the updated versions of previously tested OS, DBMS and third party software products. - Addition/removal of supported payment processors. - Recompilation of the source code using a new compiler or different compiler settings. - Changes of the software versioning policy. - Changes of the software not related to security.
| - Changes in the software affecting payment card data mechanisms. - Changes addressing the identified vulnerabilities of the application. - Changes related to the completion of the annual cycle of development (if there are other changes).
| Low Impact
|- style="vertical-align:top;"
| Increment of the first version number. For example, change of the version number from 1.0.* to 2.0.*
| Software changes satisfy the following conditions: - 4 or more sections of the standard (from 1 to 12) involved; - More than a half of all the requirements of the standard (sections 1 to 12) involved; - More than a half of the software functions (or code) modified; - Addition of new supported platforms/OS versions.
| Major changes in the software architecture, global alterations of code
| High Impact
|}
 
The release of each new version is accompanied with a notification to all the application users (agents), which indicates the new application version number and a list of main changes in the new version.
 

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:API

2016-05-25T10:29:00Z

Alex “Ambal” Mulin: /* API versions supported */

== API versions supported ==

'''API v1.1''': X-Payments 1.0.2-1.0.5 
'''API v1.2''': X-Payments 1.0.6, 2.0.0, 2.0.1 
'''API v1.3''': X-Payments 2.1.0, 2.1.1 
'''API v1.4''': X-Payments 2.1.2 (Nov 2014), 2.1.3 (Feb 2015) 
'''API v1.5''': X-Payments 2.2 (June 2015) 
'''API v1.6''': X-Payments 3.x (June 2016)

==Samples==

While we are doing an addition to our API docs I suggest to use function xpc_api_request from
X-Cart 4 file modules/XPayments_Connector/xpc_func.php as a sample.

Especially function xpc_request_test() to make a test call.

==API requests==

All API requests are made to the '''httрs://<xpayments_url>/api.php''' URL.
Only HTTPS protocol is used.
A request is an XML document that is encrypted using RSA method with a key generated by X-Payments.

'''Request/Response encryption'''

* Encryption method used: RSA;
* Key length: 2048 bit;
* A private key is created with a 32 character password;
* The password is generated randomly;
* The number of password characters varies from 33 to 127.

For each online store X-Payments generates 2 pairs of keys:

# a public and a private key to encrypt requests/responses from the online store to X-Payments;
# a public and a private key to encrypt requests/responses from X-Payments to the online store.

So when the online store sends a request to X-Payments, this request is encrypted using the public key from the first pair, X-Payments decrypts it using the private key of the first pair. Then X-Payments response is encrypted using the public key of the second pair, and the online store decrypts this response using the private key of the second pair.

To ensure full-featured two-way commumication between X-Payments and an online store, you need to copy tree values from the X-Payments interface:
:* Public key from the first pair (Online store → X-Payments),
:* Private key from the second pair (X-Payments → Online store),
:* Private key password,
and have them stored on the side of the online store by an appropriate X-Payments connector.

'''Encryption algorithm:'''

# An empty string is created for pre-prepared data.
# A 32-character salt-block is formed of random characters from 33 to 255.
# The length of the salt-block in bites is taken and transformed into a 12-character string by adding zeros before it.
# The salt-block length string and the salt-block are added to the pre-prepared data.
# MD5 digital signature is taken from the data. The signature is formed as a HEX (32-character string).
# The length of the digital signature in bites is taken and transformed into a 12-character string by adding zeros before it.
# The digital signature length string and the digital signature are added to the pre-prepared data.
# The length of the data string in bites is taken and transformed into a 12-character string by adding zeros before it.
# The data string length string and the data string are added to the pre-prepared data.
# The string of pre-prepared data is divided into 128 bite chunks.
# Each chunk is encrypted using a public key.
# Each chunk is encoded with base64.
# Chunks are glued together using a line feed character (0x0a).
# API prefix is added to the glued chunks.

===cURL as a means of sending requests===

Using libcurl v.7.10 and above is recommended.

TTL should be specified depending on the performance of the server where X-Payments is installed. The recommended value is 120 seconds.

It is recommended to use SSL v.3 and above.

===Data types===

Data types used:

* string - a UTF-8 string;
* email - an email address no longer than 255 characters;
* URL - a URL address no longer than 255 characters;
* currency - a floating point number denoting a certain sum of money. The mantissa size is the same as the payment currency mantissa size, but not longer than 3. All the exceeding characters will be truncated.
* integer - an integer number.

ISO 4217 Alpha-3 in the upper register is always used as the payment currency code.

ISO 639-1 Alpha-2 in the lower register is always used as the language code.

==Payment configurations list request==

Returns a list of payment configurations that are configured, enabled, and assigned to this online store/shopping cart.

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment_confs
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal get
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}
 

===Request example===

<pre>
<api_version>1.5</api_version>
<target>payment_confs</target>
<action>get</action>
</pre>
 

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | payment_module
| colspan="1" | container
| colspan="1" |
|-
| colspan="1" | payment_module/name
| colspan="1" | string
| colspan="1" | Name of the payment configuration, as set by the X-Payments admin
|-
| colspan="1" | payment_module/id
| colspan="1" | integer
| colspan="1" | Identifier of the payment configuration (autoincrement)
|-
| colspan="1" | payment_module/transactionTypes
| colspan="1" | container
| colspan="1" |
|-
| colspan="1" | payment_module/transactionTypes/sale
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Sale" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/auth
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Authorize only" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/capture
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Capture" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/capturePart
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows partial "Capture" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/captureMulti
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows multiple "Capture" operations ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/void
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Void" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/voidPart
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows partial "Void" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/voidMulti
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows multiple "Void" operations ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/refund
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Refund" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/refundPart
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows partial "Refund" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/refundMulti
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows multiple "Refund" operations ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/getInfo
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows to receive information from the payment gateway ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/accept
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Accept" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/decline
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Decline" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/test
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Test" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/authCaptureInfo
| colspan="1" | container
| colspan="1" |
|-
| colspan="1" | payment_module/authCaptureInfo/authExp
| colspan="1" | integer
| colspan="1" | How many days the transaction can stay in the Authorized status before being declined automatically
|-
| colspan="1" | payment_module/authCaptureInfo/captMinLimit
| colspan="1" | float
| colspan="1" | Minimum capture limit allowed by the payment gateway. Presented as a part of 1 (0 - no minimum limit, 0.2 - minimum 20% of authorized total, 0.5 - 50% of authorized total, etc.)
|-
| colspan="1" | payment_module/authCaptureInfo/captMaxLimit
| colspan="1" |
| colspan="1" | Maximum capture limit allowed by the payment gateway. Presented as a part of 1 (0 - no maximum limit, 0.5 - 50% of authorized total, 1 - 100% of authorized total, etc.)
|-
| colspan="1" | payment_module/moduleName
| colspan="1" | string
| colspan="1" | Default X-Payments name of the payment configuration
|-
| colspan="1" | payment_module/settingsHash
| colspan="1" | string
| colspan="1" | MD5 hash of the payment configuration settings
|-
| colspan="1" | payment_module/currency
| colspan="1" | string
| colspan="1" | 3-characters code of currency (ISO 4217). API v1.3 and later.
|-
| colspan="1" | payment_module/canSaveCards
| colspan="1" | string
| colspan="1" | Whether the payment configuration supports tokenization, i.e. customers' credit card can be saved on the payment gateway ("Y" - supports, "N" - doesn't support). API v1.3 and later.
|-
| colspan="1" | payment_module/class
| colspan="1" | string
| colspan="1" | Service field of the class name. It is unique for a payment module so it can be used to detect a certain payment gateway. E.g. XPay_Module_SagePayDirect for SagePay, XPay_Module_AuthorizeNet for Authorize.Net AIM, etc. API v1.4 and later.
|-
| colspan="1" | payment_module/isTestMode
| colspan="1" | string
| colspan="1" | Indicates if the payment configuration is configured in test mode ("Y" - test mode, "N" - live mode). API v1.4 and later.
|}
 

===Response example===

<pre>
<data>
<payment_module type="cell">
<name>First Data Global Gateway e4(SM) Web Service API</name>
<id>1</id>
<transactionTypes>
<sale>1</sale>
<auth>1</auth>
<capture>1</capture>
<capturePart>1</capturePart>
<captureMulti></captureMulti>
<void>1</void>
<voidPart></voidPart>
<voidMulti></voidMulti>
<refund>1</refund>
<refundPart>1</refundPart>
<refundMulti>1</refundMulti>
<getInfo></getInfo>
<accept></accept>
<decline></decline>
<test></test>
</transactionTypes>
<authCaptureInfo>
<authExp>30</authExp>
<captMinLimit>0</captMinLimit>
<captMaxLimit>1</captMaxLimit>
</authCaptureInfo>
<moduleName>First Data Payeezy Gateway (ex- Global Gateway e4)</moduleName>
<settingsHash>d41d8cd98f00b204e9800998ecf8427e</settingsHash>
<currency>USD</currency>
<canSaveCards>Y</canSaveCards>
<class>XPay_Module_FirstDataE4</class>
<isTestMode>Y</isTestMode>
</payment_module>
<payment_module type="cell">
<name>Chase Paymentech</name>
<id>2</id>
<transactionTypes>
<sale>1</sale>
<auth>1</auth>
<capture>1</capture>
<capturePart>1</capturePart>
<captureMulti></captureMulti>
<void>1</void>
<voidPart></voidPart>
<voidMulti></voidMulti>
<refund>1</refund>
<refundPart>1</refundPart>
<refundMulti></refundMulti>
<getInfo></getInfo>
<accept></accept>
<decline></decline>
<test></test>
</transactionTypes>
<authCaptureInfo>
<authExp>30</authExp>
<captMinLimit>0</captMinLimit>
<captMaxLimit>1</captMaxLimit>
</authCaptureInfo>
<moduleName>Chase Paymentech</moduleName>
<settingsHash>d41d8cd98f00b204e9800998ecf8427e</settingsHash>
<currency>USD</currency>
<canSaveCards>Y</canSaveCards>
<class>XPay_Module_Chase</class>
<isTestMode>Y</isTestMode>
</payment_module>
</data>
</pre>
 

==Test connection request==
Use this request to test the connection between the store and X-Payments. It can also help to detect the version of the X-Payments installation and the API version supported by X-Payments.

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal connect
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal test
|-
| colspan="1" | testCode
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Any string
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}
 

===Request example===

<pre>
<testCode>123</testCode>
<api_version>1.5</api_version>
<target>connect</target>
<action>test</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | hashCode
| colspan="1" | string
| colspan="1" | MD5 hash of the sent code
|-
| colspan="1" | error
| colspan="1" | string
| colspan="1" | Error code (if any)
|-
| colspan="1" | error_message
| colspan="1" | string
| colspan="1" | Error message
|-
| colspan="1" | is_error_message
| colspan="1" | string
| colspan="1" | Flag indicating the error message presence
|-
| colspan="1" | version
| colspan="1" | string
| colspan="1" | X-Payments version
|}
 

===Response example===

Example of a good response:
<pre>
<data>
<hashCode>202cb962ac59075b964b07152d234b70</hashCode>
<error></error>
<error_message></error_message>
<is_error_message></is_error_message>
<version>2.2.0</version>
</data>
</pre>

Example of a response with an error:
<pre>
<data>
<error>506</error>
<error_message>Your X-Payments connector module supports API version "1.9". This X-Payments supports the following API versions only: "1.1, 1.2, 1.3, 1.4, 1.5, 1.6".</error_message>
<is_error_message></is_error_message>
</data>
</pre>
 

==Payment initialisation request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal init
|-
| colspan="1" | confId
| colspan="1" | Y
| colspan="1" | integer
| colspan="1" | Payment module configuration ID
|-
| colspan="1" | refId
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Order ID in the online store
|-
| colspan="1" | returnUrl
| colspan="1" | Y
| colspan="1" | URL, 255
| colspan="1" | URL of the page to redirect the customer after payment
|-
| colspan="1" | callbackUrl
| colspan="1" | Y
| colspan="1" | URL, 255
| colspan="1" | URL to which X-Payments sends background requests with service information
|-
| colspan="1" | language
| colspan="1" | N
| colspan="1" | code of ISO 639-1 (Alpha-2)
| colspan="1" | Language code. If not specified - en
|-
| colspan="1" | cart
| colspan="1" | Y
| colspan="1" | container
| colspan="1" | A container with addresses description
|-
| colspan="1" | cart/billingAddress
| colspan="1" | Y
| colspan="1" | container
| colspan="1" | A container with the billing address description
|-
| colspan="1" | cart/billingAddress/firstname
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/lastname
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/company
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/address
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/city
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/state
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/country
| colspan="1" | Y
| colspan="1" | string, 2
| colspan="1" | ISO 3166-1 alpha-2 Country code https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
|-
| colspan="1" | cart/billingAddress/zipcode
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/email
| colspan="1" | Y
| colspan="1" | emai, 255l
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/phone
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/fax
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress
| colspan="1" | Y
| colspan="1" | container
| colspan="1" | A container with the shipping address description
|-
| colspan="1" | cart/shippingAddress/firstname
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/lastname
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/company
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/address
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/city
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/state
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/country
| colspan="1" | Y
| colspan="1" | string, 2
| colspan="1" | ISO 3166-1 alpha-2 Country code https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
|-
| colspan="1" | cart/shippingAddress/zipcode
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/email
| colspan="1" | Y
| colspan="1" | email, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/phone
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/fax
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/items
| colspan="1" | Y
| colspan="1" | container
| colspan="1" | A container with product description
|-
| colspan="1" | cart/items/sku
| colspan="1" | Y
| colspan="1" | string, 64
| colspan="1" | SKU (product code)
|-
| colspan="1" | cart/items/name
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" | Product name
|-
| colspan="1" | cart/items/price
| colspan="1" | Y
| colspan="1" | currency
| colspan="1" | Product item price
|-
| colspan="1" | cart/items/quantity
| colspan="1" | N
| colspan="1" | integer
| colspan="1" | Ordered number of products. If not specified - 1
|-
| colspan="1" | cart/login
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" | Unique customer ID in the online store (login, username, userid, etc.)
|-
| colspan="1" | cart/currency
| colspan="1" | N
| colspan="1" | string, 3
| colspan="1" | Payment currency code (ISO 4217 Alpha-3). If not specified, default payment configuration currency is used
|-
| colspan="1" | cart/shippingCost
| colspan="1" | -
| colspan="1" | currency
| colspan="1" | Shipping cost. By default - 0
|-
| colspan="1" | cart/taxCost
| colspan="1" | -
| colspan="1" | currency
| colspan="1" | Tax amount. By default - 0
|-
| colspan="1" | cart/discount
| colspan="1" | -
| colspan="1" | currency
| colspan="1" | Discount amount. By default - 0
|-
| colspan="1" | cart/totalCost
| colspan="1" | Y
| colspan="1" | currency
| colspan="1" | Total payment amount. Must equal to a sum of cart/items/price * cart/items/quantity + cart/shippingCost + cart/taxCost - cart/discount
|-
| colspan="1" | cart/description
| colspan="1" | -
| colspan="1" | string, 65536
| colspan="1" |
|-
| colspan="1" | cart/merchantEmail
| colspan="1" | Y
| colspan="1" | email, 255
| colspan="1" |
|-
| colspan="1" | cart/forceTransactionType
| colspan="1" | -
| colspan="1" | one of values: A or S or empty A - authorize S - sale
| colspan="1" | A flag of forced Sale or Authorize operation. Overrides the setting from the payment configuration. If the value is empty or the field is omitted, the operation is performed according to the payment configuration settings.
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|-
| colspan="1" | template (''supported by API 1.3 and later'')
| colspan="1" | N
| colspan="1" | string
| colspan="1" | The name of a template in X-Payments requested by the store. Forces the use of the specified template for the payment. If the string passed in this field does not match any template available in X-Payments, it will be ignored.
|-
| colspan="1" | saveCard (''supported by API 1.3 and later'')
| colspan="1" | N
| colspan="1" | string
| colspan="1" | Customer's choice at checkout (“Y” if customer would like to save the card)
|-
| colspan="1" | cart/kountCustomerUniq (''supported by API 1.6 and later'')
| colspan="1" | N
| colspan="1" | string, 32
| colspan="1" | This field is a unique customer identifier in the Kount system, which is send as a UNIQ field.
|}
 
'''List of template names in X-Payments 2.1.x (API v1.3)''':
:* '''default''': A template for the separate page. Used if the payment form is displayed on a separate page of your checkout process (not iframe).
:* '''fast''': Iframe for X-Cart 4 Fast Lane Checkout. Used for X-Cart 4 with the Fast Lane Checkout module. The payment form is displayed at the last step of the checkout process.
:* '''lite''': Iframe for X-Cart 4 One Page Checkout. Used for X-Cart 4 with the One Page Checkout module. The payment form is displayed in the payment section at checkout.
:* '''magento_iframe''': Iframe for Magento. Use this template for Magento and iframe.
:* '''mobile''': Template for mobile devices. Used with the X-Cart Mobile module.
:* '''xc5''': Iframe for X-Cart 5. Used for X-Cart 5 and iframe.

===Request example===

<pre>
<confId>8</confId>
<refId>1120</refId>
<cart>
<login>customer</login>
<billingAddress>
<firstname>John</firstname>
<lastname>Smith</lastname>
<address>10 Main street</address>
<city>Fillmore</city>
<state>UT</state>
<country>US</country>
<zipcode>84631</zipcode>
<company>IQ testing</company>
<email>bit-bucket@x-cart.com</email>
<phone>927348572</phone>
<fax></fax>
</billingAddress>
<shippingAddress>
<firstname>John</firstname>
<lastname>Smith</lastname>
<address>10 Main street</address>
<city>Fillmore</city>
<state>UT</state>
<country>US</country>
<zipcode>84631</zipcode>
<company>IQ testing</company>
<email>bit-bucket@x-cart.com</email>
<phone>927348572</phone>
<fax></fax>
</shippingAddress>
<items type="cell">
<sku>SKU17513</sku>
<name>Three Stone Princess Cut Diamond Ring</name>
<price>399.99</price>
<quantity>1</quantity>
</items>
<currency>USD</currency>
<shippingCost>15</shippingCost>
<taxCost>0</taxCost>
<discount>0</discount>
<totalCost>414.99</totalCost>
<description>Order(s) #1120</description>
<merchantEmail>bit-bucket@x-cart.com</merchantEmail>
<forceTransactionType></forceTransactionType>
</cart>
<returnUrl>https://example.com/xcart/payment/cc_xpc.php</returnUrl>
<callbackUrl>https://example.com/xcart/payment/cc_xpc.php</callbackUrl>
<language>ru</language>
<target>payment</target>
<action>init</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | token
| colspan="1" | string,32
| colspan="1" | Temporary payment token, expires immediately after the customer has submitted the cardholder data form
|-
| colspan="1" | txnId
| colspan="1" | string,32
| colspan="1" | A unique payment ID. Is used for all further requests to this payment through the API.
|}

===Response example===

<pre>
<data>
<token>41b2ef3b34698d4f6ed73151ae7307d2</token>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<error></error>
<error_message></error_message>
</data>
</pre>

==Redirecting a customer to the cardholder data entering page==

A POST form is created that sends data to the URL <XPayments_web_root>/payment.php; the form contains the following fields:

* target - has the value "main";
* token - uses the value from the token field received in the response to the payment initialisation request.

Request protocol - HTTPS 
The form must be sent by the POST method. All data must also be sent as POST variables.

==Payment information request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal get_info
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | refresh
| colspan="1" | N
| colspan="1" | 0 или 1
| colspan="1" | A flag specifying that the data in X-Payments must be overwritten by the data from the payment gateway. By default - 0
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<refresh>0</target>
<target>payment</target>
<action>get_info</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Payment status codes|Payment status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Human readable message containing the payment status
|-
| colspan="1" | isFraudStatus
| colspan="1" | 0 or 1
| colspan="1" | Means that the payment is blocked by the gateway, because the customer has not passed the gateway security check
|-
| colspan="1" | currency
| colspan="1" | string, 3
| colspan="1" | Payment currency code
|-
| colspan="1" | amount
| colspan="1" | currency
| colspan="1" | Payment total
|-
| colspan="1" | authorized
| colspan="1" | currency
| colspan="1" | Authorized payment total
|-
| colspan="1" | chargedAmount
| colspan="1" | currency
| colspan="1" | Charged payment total
|-
| colspan="1" | capturedAmount
| colspan="1" | currency
| colspan="1" | Captured amount of the authorized amount
|-
| colspan="1" | capturedAmountAvail
| colspan="1" | currency
| colspan="1" | Amount that is authorized and can be captured
|-
| colspan="1" | voidedAmount
| colspan="1" | currency
| colspan="1" | Amount that is authorized but voided
|-
| colspan="1" | voidedAmountAvail
| colspan="1" | currency
| colspan="1" | Amount that is authorized and can be voided
|-
| colspan="1" | refundedAmount
| colspan="1" | currency
| colspan="1" | Amount that can be refunded
|-
| colspan="1" | refundedAmountAvail
| colspan="1" | currency
| colspan="1" | Amount that can be refunded
|-
| colspan="1" | fraudAuthorized
| colspan="1" | currency
| colspan="1" | A part of the authorized amount that was blocked by the gateway because the customer had not passed the gateway security check
|-
| colspan="1" | fraudCharged
| colspan="1" | currency
| colspan="1" | A part of the charged amount that was blocked by the gateway because the customer had not passed the gateway security check
|-
| colspan="1" | authorizeInProgress
| colspan="1" | currency
| colspan="1" | A part of the authorized amount that is being handled by the gateway
|-
| colspan="1" | chargeInProgress
| colspan="1" | currency
| colspan="1" | A part of the charged amount that is being handled by the gateway
|-
| colspan="1" | transactionInProgress
| colspan="1" | 0 или 1
| colspan="1" | Are there any payment transactions handled by the gateway?
|-
| colspan="1" | capturedAmountAvailMin
| colspan="1" | currency
| colspan="1" | Minimum amount that can be captured from the authorized amount
|-
| colspan="1" | capturedAmountAvailGateway
| colspan="1" | currency
| colspan="1" | Amount that can be captured from the authorized amount through the gateway
|-
| colspan="1" | capturedAmountAvailMinGateway
| colspan="1" | currency
| colspan="1" | Minimum amount that can be captured from the authorized amount through the gateway
|-
| colspan="1" | voidedAmountAvailGateway
| colspan="1" | currency
| colspan="1" | Amount that can be voided from the authorized amount through the gateway
|-
| colspan="1" | refundedAmountAvailGateway
| colspan="1" | currency
| colspan="1" | Amount that can be refunded from the authorized amount through the gateway
|-
| colspan="1" | txnId
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | lastMessage
| colspan="1" | string, 65536
| colspan="1" | Last gateway message
|-
| colspan="1" | error
| colspan="1" | string, 128
| colspan="1" | Error code
|-
| colspan="1" | error_message
| colspan="1" | string, 65536
| colspan="1" | Error message
|}

{{Note|Fields ending in "Gateway" contain amounts that can be used in transactions through the gateway. For example, if a sum of $100 was authorized, and then a capture transaction was emulated for $100, the next refund operation will be available in the emulation mode only. The value of the refundedAmountAvailGateway field will be equal to 0.}}

===Response example===

<pre>
<data>
<status>2</status>
<message>Payment is authorized</message>
<isFraudStatus></isFraudStatus>
<currency>USD</currency>
<amount>414.99</amount>
<authorized>414.99</authorized>
<chargedAmount>0.00</chargedAmount>
<capturedAmount>0.00</capturedAmount>
<capturedAmountAvail>414.99</capturedAmountAvail>
<voidedAmount>0.00</voidedAmount>
<voidedAmountAvail>414.99</voidedAmountAvail>
<refundedAmount>0.00</refundedAmount>
<refundedAmountAvail>0.00</refundedAmountAvail>
<fraudAuthorized>0.00</fraudAuthorized>
<fraudCharged>0.00</fraudCharged>
<authorizeInProgress>0.00</authorizeInProgress>
<chargeInProgress>0.00</chargeInProgress>
<transactionInProgress></transactionInProgress>
<capturedAmountAvailMin>0.00</capturedAmountAvailMin>
<capturedAmountAvailGateway>414.99</capturedAmountAvailGateway>
<capturedAmountAvailMinGateway>0.00</capturedAmountAvailMinGateway>
<voidedAmountAvailGateway>414.99</voidedAmountAvailGateway>
<refundedAmountAvailGateway>0.00</refundedAmountAvailGateway>
<txnId>8e67e0da23ce7ed451b2c1adbbd7373c</txnId>
<lastMessage>Success</lastMessage>
<error></error>
<error_message></error_message>
</data>
</pre>

==Detailed payment and transaction information request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal get_additional_info
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | A unique payment ID received in the payment initialisation request response
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<target>payment</target>
<action>get_additional_info</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | payment
| colspan="1" | container
| colspan="1" | Payment information request response
|-
| colspan="1" | transactions
| colspan="1" | container
| colspan="1" | Transaction list
|-
| colspan="1" | transactions/date
| colspan="1" | integer, 11
| colspan="1" | Transaction date (Unix timestamp)
|-
| colspan="1" | transactions/action
| colspan="1" | string, 255
| colspan="1" | Transaction name
|-
| colspan="1" | transactions/status
| colspan="1" | string, 255
| colspan="1" | Transaction status
|-
| colspan="1" | transactions/message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|-
| colspan="1" | transactions/total
| colspan="1" | string, 32
| colspan="1" | Transaction amount and currency
|-
| colspan="1" | transactions/txnid
| colspan="1" | string, 255
| colspan="1" | Gateway transaction unique ID
|-
| colspan="1" | transactions/payment_status
| colspan="1" | string, 255
| colspan="1" | The payment status after the transaction
|-
| colspan="1" | transactions/fields
| colspan="1" | container
| colspan="1" | Transaction additional fields list
|-
| colspan="1" | transactions/fields/name
| colspan="1" | string, 255
| colspan="1" | Field name
|-
| colspan="1" | transactions/fields/name
| colspan="1" | string, 255
| colspan="1" | Field value
|-
| colspan="1" | payment/cardValidation (API 1.5 and later)
| colspan="1" | container
| colspan="1" | container for Address validation system (AVS)
|-
| colspan="1" | payment/cardValidation/avs_z (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Flag for AVS ZIP-code ("0" - unknown, "1" - matches, "2" - does not match)
|-
| colspan="1" | payment/cardValidation/avs_c (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Flag for AVS cardholder name ("0" - unknown, "1" - matches, "2" - does not match)
|-
| colspan="1" | payment/cardValidation/avs_a (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Flag for AVS street address ("0" - unknown, "1" - matches, "2" - does not match)
|-
| colspan="1" | payment/cardValidation/cvv (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Flag for CVV/CVV2/CVD ("0" - unknown, "1" - matches, "2" - does not match)
|-
| colspan="1" | payment/maskedCardData (API 1.5 and later)
| colspan="1" | container
| colspan="1" | container for Credit Card details (which are allowed to store and display by PA-DSS)
|-
| colspan="1" | payment/maskedCardData/first6 (API 1.5 and later)
| colspan="1" | string
| colspan="1" | First six digits of the credit card number
|-
| colspan="1" | payment/maskedCardData/last4 (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Last four digits of the credit card number
|-
| colspan="1" | payment/maskedCardData/type (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Credit card type: VISA, MC, AMEX, etc
|-
| colspan="1" | payment/maskedCardData/expire_month (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Credit card expiration month
|-
| colspan="1" | payment/maskedCardData/expire_year (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Credit card expiration year
|}

===Response example===

<pre>
<data>
<payment>
<status>2</status>
<message>Payment is authorized</message>
<isFraudStatus>1</isFraudStatus>
<currency>USD</currency>
<amount>10.61</amount>
<authorized>10.61</authorized>
<chargedAmount>0.00</chargedAmount>
<capturedAmount>0.00</capturedAmount>
<capturedAmountAvail>10.61</capturedAmountAvail>
<voidedAmount>0.00</voidedAmount>
<voidedAmountAvail>10.61</voidedAmountAvail>
<refundedAmount>0.00</refundedAmount>
<refundedAmountAvail>0.00</refundedAmountAvail>
<fraudAuthorized>0.00</fraudAuthorized>
<fraudCharged>0.00</fraudCharged>
<authorizeInProgress>0.00</authorizeInProgress>
<chargeInProgress>0.00</chargeInProgress>
<advinfo>
<Message></Message>
<Response code>1</Response>
<txn_id>6583</txn_id>
<Authorization number>ET154399</Authorization>
<AVS>5: Cardholder name incorrect, billing address and postal code match</AVS>
<Bank message>Approved</Bank>
<Bank response code>100</Bank>
<CVV2>M: CVV2 / CVC2/CVD Match.</CVV2>
<Processing status>Transaction Normal</Processing>
<Transarmor Token>8393008475641111</Transarmor>
<[Kount] 702650>Distance from Device to Billing > 1000km</[Kount] 702650>
<[Kount] 702656>Billing Country not equal to BIN Country (Visa/MC)</[Kount] 702656>
<[Kount] 702662>Billing Country not equal to Device Country</[Kount] 702662>
<[Kount] Auto>R</[Kount] Auto>
<[Kount] Errors></[Kount] Errors>
<[Kount] Score>26</[Kount] Score>
<[Kount] Transaction ID>3Z7903KDCTT0</[Kount] Transaction ID>
<[Kount] Warnings></[Kount] Warnings>
</advinfo>
<transactionInProgress></transactionInProgress>
<capturedAmountAvailMin>0.00</capturedAmountAvailMin>
<capturedAmountAvailGateway>10.61</capturedAmountAvailGateway>
<capturedAmountAvailMinGateway>0.00</capturedAmountAvailMinGateway>
<voidedAmountAvailGateway>10.61</voidedAmountAvailGateway>
<refundedAmountAvailGateway>0.00</refundedAmountAvailGateway>
<cardValidation>
<avs_z>1</avs_z>
<avs_c>2</avs_c>
<avs_a>1</avs_a>
<cvv>1</cvv>
</cardValidation>
<maskedCardData>
<first6>411111</first6>
<last4>1111</last4>
<type>VISA</type>
<expire_month>03</expire_month>
<expire_year>2020</expire_year>
</maskedCardData>
</payment>
<transactions type="cell">
<date>1438098759</date>
<action>Authorize</action>
<status>Success</status>
<message>Transaction Normal</message>
<total>10.61 USD</total>
<txnid>57629270</txnid>
<fields type="cell">
<name>Authorization number</name>
<value>ET154399</value>
</fields>
<fields type="cell">
<name>AVS</name>
<value>5: Cardholder name incorrect, billing address and postal code match</value>
</fields>
<fields type="cell">
<name>Bank message</name>
<value>Approved</value>
</fields>
<fields type="cell">
<name>Bank response code</name>
<value>100</value>
</fields>
<fields type="cell">
<name>CVV2</name>
<value>M: CVV2 / CVC2/CVD Match.</value>
</fields>
<fields type="cell">
<name>Processing status</name>
<value>Transaction Normal</value>
</fields>
<fields type="cell">
<name>Transarmor Token</name>
<value>8393008475641111</value>
</fields>
<fields type="cell">
<name>[Kount] 702650</name>
<value>Distance from Device to Billing > 1000km</value>
</fields>
<fields type="cell">
<name>[Kount] 702656</name>
<value>Billing Country not equal to BIN Country (Visa/MC)</value>
</fields>
<fields type="cell">
<name>[Kount] 702662</name>
<value>Billing Country not equal to Device Country</value>
</fields>
<fields type="cell">
<name>[Kount] Auto</name>
<value>R</value>
</fields>
<fields type="cell">
<name>[Kount] Score</name>
<value>26</value>
</fields>
<fields type="cell">
<name>[Kount] Transaction ID</name>
<value>3Z7903KDCTT0</value>
</fields>
<payment_status>Charged</payment_status>
</transactions>
<error></error>
<error_message></error_message>
<is_error_message></is_error_message>
<version>2.2.0</version>
</data>
</pre>

 
''The following pertains to API 1.5 and later:'' 
If the transaction was checked by Kount antifraud screening service, the "advinfo" and "tansaction/fields" containers contain information of kount results. The field names related to Kount start with the [Kount] prefix. The information can be extracted as follows:

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Description'''
|-
| colspan="1"| [Kount] %%%%%, where %%%%% is some number
| colspan="1"| triggered rule, the number is the number of this rule
|-
| colspan="1"| [Kount] Auto
| colspan="1"| The status of the transaction in Kount ("R" - review, "D" - declined, "A" - approved)
|-
| colspan="1"| [Kount] Errors
| colspan="1"| list of errors (if any)
|-
| colspan="1"| [Kount] Warnings:
| colspan="1"| list of warnings (if any)
|-
| colspan="1"| [Kount] Score
| colspan="1"| Risk score
|-
| colspan="1"| [Kount] Transaction ID
| colspan="1"| Transaction ID in Kount, can be used to display the direct link to the transaction in Kount, https://awc.test.kount.net/workflow/detail.html?id=%%%%%% for test mode or https://awc.kount.net/workflow/detail.html?id=%%%%%%, where %%%%% should be replaced with the transaction ID
|}
 

==Capture authorized transaction request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string,128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal capture
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | amount
| colspan="1" | N
| colspan="1" | currency
| colspan="1" | The amount to capture from the previously authorized transaction. By default equals the amount of the authorized transaction
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

=== Request example ===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<target>payment</target>
<action>capture</action>
</pre>

===Response example===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|}

Response example <pre><data>
<status>1</status>
<message>Success</message>
<error></error>
<error_message></error_message>
</data>
</pre>

==Void authorized transaction request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal void
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | amount
| colspan="1" | N
| colspan="1" | currency
| colspan="1" | Amount to void of the authorized transaction. By default equals to the amount of the authorized transaction
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<target>payment</target>
<action>void</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|}

===Response example===

<pre>
<data>
<status>1</status>
<message>Success</message>
<error></error>
<error_message></error_message>
</data>
</pre>

==Refund captured transaction request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal capture
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | amount
| colspan="1" | N
| colspan="1" | currency
| colspan="1" | Amount to be refunded to the customer of the previously captured transactions. By default equals to the amount of captured transactions
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre><txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<target>payment</target>
<action>refund</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|}

===Response example===

<pre><data>
<status>1</status>
<message>Success</message>
<error></error>
<error_message></error_message>
</data>
</pre>

==Blocked by gateway transaction accept request (Accept)==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal accept
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<target>payment</target>
<action>accept</action>
</pre>

===Response example===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|}

Response example <pre><data>
<status>1</status>
<message>Success</message>
<error></error>
<error_message></error_message>
</data>
</pre>

==Blocked by gateway transaction decline request (Decline)==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal decline
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<target>payment</target>
<action>decline</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|}

===Response example===

<pre>
<data>
<status>1</status>
<message>Success</message>
<error></error>
<error_message></error_message>
</data>
</pre>

==Charge again transaction request (Tokenization)==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal recharge
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID which references the token that will be used to identify the payment on the side of the payment gateway
|-
| colspan="1" | amount
| colspan="1" | Y
| colspan="1" | currency
| colspan="1" | The amount for which the "saved" card is to be charged using the token from the previous successful transaction
|-
| colspan="1" | description
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Description of the transaction
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|-
| colspan="1" | refId (supported by API 1.4 and later)
| colspan="1" | N
| colspan="1" | string, 128
| colspan="1" | Order ID in the online store
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<description>Recurring payment for the new issue of Playboy</description>
<target>payment</target>
<action>recharge</action>
<api_version>1.2</api_version>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | data
| colspan="1" | array
| colspan="1" |
|-
| colspan="1" | data[status]
| colspan="1" | integer
| colspan="1" | Status of the new payment (See [[#Payment status codes|Payment status codes]])
|-
| colspan="1" | data[transaction_id]
| colspan="1" | string
| colspan="1" | ID of the created payment for further references (capture/void/refund etc)
|-
| colspan="1" | data[error]
| colspan="1" | string
| colspan="1" |
|-
| colspan="1" | data[error_message]
| colspan="1" | string
| colspan="1" |
|-
| colspan="1" | data[is_error_message]
| colspan="1" | string
| colspan="1" |
|}
 

==Callback request with service payment information==

This is a background request that X-Payments sends to the store after a payment has been completed and it’s result (accepted, declined, etc) has been received from the payment gateway. The request is sent via HTTP POST to the callbackURL defined in the Payment initialisation request. Once this request has been sent, the customer is redirected back to the store.

===POSTed data===
{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Value'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | action
| colspan="1" | callback
| colspan="1" | fixed string
| colspan="1" | Identifies the callback request
|-
| colspan="1" | txnId
| colspan="1" | (mixed)
| colspan="1" | string (MD5 hash)
| colspan="1" | A unique ID of the payment on the side of X-Payments
|-
| colspan="1" | updateData
| colspan="1" | (mixed)
| colspan="1" | string
| colspan="1" | Encrypted response from X-Payments
|}

X-Payments does not expect a response from the store for this request; however, if the HTTP status of the response is not 200 OK, the request is considered failed, and a special notification is sent to the X-Payments admin. The store needs to decrypt the encrypted part of the response and update the order on its side accordingly. Once the updateData value has been decrypted, it is an XML document with the same structure as the [[X-Payments:API#Response_specification_2|response for Payment information request]].
 

==Check cart callback request==

After the customer has submitted credit card data, right before sending this data to the payment gateway, X-Payments connects to the store to verify the cart total and contents.

The HTTP POST request is sent to the '''callbackURL''' defined in the '''Payment initialisation request'''.

===POSTed data===
{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Value'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | action
| colspan="1" | check_cart
| colspan="1" | fixed string
| colspan="1" | Identifies the check-cart callback request
|-
| colspan="1" | txnId
| colspan="1" | (mixed)
| colspan="1" | string (MD5 hash)
| colspan="1" | A unique ID of the payment on the side of X-Payments
|-
| colspan="1" | refId
| colspan="1" | (mixed)
| colspan="1" | string
| colspan="1" | Order ID (or any other reference) in the online store
|}
 
As of API v1.3, the store must respond to this callback request. The response must be an encrypted XML document (i.e. the same way as for other communication between the store and X-Payments).

===Encrypted response for check-cart callback request===
{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | Y
| colspan="1" | fixed string
| colspan="1" | Should be “cart-changed” or "cart-not-changed"
|-
| colspan="1" | cart
| colspan="1" | Y
| colspan="1" | container
| colspan="1" | A container with cart/order description. See [[X-Payments:API#Request_specification|Payment initialisation request specification]] for details. This container must be included for "status = cart-changed" and is not necessary for "status = cart-not-changed"
|-
| colspan="1" | saveCard
| colspan="1" | N
| colspan="1" | string
| colspan="1" | Whether the customer has chosen to save their card for future use (“Y” if the customer would like to save the card)
|}
 

==Communication between X-Payments iframe and the store==

===Communication structure===
Communication between the online store (parent frame) and X-Payments (iframe) is implemented with the help of the javascript Window.postMessage method. Notifictions to both the sides represent stringified JSON formatted texts that consist of a service message (string) and an optional list of parameters:
:* '''height''': height of the iframe
:* '''error''': human readable message
:* '''type''': message type. X-Payments sends it as 2, which indicates that the online store should re-initialize the payment. In API v1.3 no other values are supported.

===Messages sent from the online store to X-Payments===
'''Submit payment form''' 
X-Payments’ iframe does not have a Submit button, so instead of it the payment form should be submitted from the parent window by any kind of “Submit order” or “Place order” button at checkout. At the same time, the special message '''submitPaymentForm''' with no parameters should be sent.
-----------------------------------------------------------
{
:::message: 'submitPaymentForm',
:::params: {}
}
-----------------------------------------------------------

 
===Messages sent from X-Payments to the online store===
'''Iframe is loaded and ready''' 
The message ready notifies the parent window that the payment form is ready. The actual height of the iframe is included in the parameters, so the parent window (checkout page) can perform the necessary adjustments.
-----------------------------------------------------------
{
:::message: 'ready',
:::params: {
::::::height: $(document).height()
:::}
}
-----------------------------------------------------------
 
'''Payment form submitted with an error''' 
The message '''paymentFormSubmitError''' with no parameters is sent in the case of any validation error. This may be the case, for example, if the customer’s credit card expiration date is in the past, or the credit card number does not match the card type (e.g. VISA, MasterCard), or when a required field has not been submitted (e.g. CVV2). Once the message '''paymentFormSubmitError''' with no parameters has been received, the store should not proceed to the next step of the checkout process, but should expect the payment form to be submitted again.
-----------------------------------------------------------
{
:::message: 'paymentFormSubmitError',
:::params: {}
}
-----------------------------------------------------------
 
'''Internal error''' 
The '''paymentFormSubmitError''' message with a special set of parameters is used to notify the store if something is wrong outside X-Payments, and X-Payments cannot do anything about it (for example, if the payment gateway has sent an unknown/unexpected piece of data).
-----------------------------------------------------------
{
:::message: 'paymentFormSubmitError',
:::params: {
::::::height: $(document).height(),
::::::error: 'Internal error',
::::::type: '2'
:::}
}
-----------------------------------------------------------
 
'''Session is expired''' 
For security reasons the length of the session is limited to 15 minutes. After this period the store has to re-initialize the payment. In this case X-Payments sends the '''paymentFormSubmitError''' message with the “Payment session expired” error.
-----------------------------------------------------------
{
:::message: 'paymentFormSubmitError',
:::params: {
::::::height: $(document).height(),
::::::error: 'Payment session expired',
::::::type: '2'
:::}
}
-----------------------------------------------------------
 
'''Payment form in Iframe is submitted''' (supported by API v1.4 and later) 
The message '''paymentFormSubmit''' notifies the parent window that the payment form has been submitted from the X-Payments side; for example, if a customer clicks the Enter key inside the iframe. Once the store receives this message, it should operate in the same way as though the customer has clicked the Place order button at checkout.
-----------------------------------------------------------
{
:::message: 'paymentFormSubmit',
:::params: {}
}

-----------------------------------------------------------
 

==Appendix A. Status codes.==

===Payment status codes===
: 1 - New
: 2 - Authorized
: 3 - Declined
: 4 - Charged
: 5 - Refunded
: 6 - Partially refunded

===Operation status codes===
: 0 - transaction failed
: 1 - transaction is successful
: 2 - transaction is successful and is duplicate

==See also==

* [http://lu53.crtdev.local/%7Emixon/google-cache-w.php?q=/index.php?title=X-Cart:X-Payments_Connector X-Cart:X-Payments Connector]

[[Category:X-Payments Developer Guide]]

X-Payments:API

2016-05-25T10:28:42Z

Alex “Ambal” Mulin: /* API versions supported */

== API versions supported ==

'''API v1.1''': X-Payments 1.0.2-1.0.5 
'''API v1.2''': X-Payments 1.0.6, 2.0.0, 2.0.1 
'''API v1.3''': X-Payments 2.1.0, 2.1.1 
'''API v1.4''': X-Payments 2.1.2 (Nov 2014), 2.1.3 (Feb 2015) 
'''API v1.5''': X-Payments 2.2 (June 2015) 
'''API v1.6''': X-Payments 3.x (June 2016) 

==Samples==

While we are doing an addition to our API docs I suggest to use function xpc_api_request from
X-Cart 4 file modules/XPayments_Connector/xpc_func.php as a sample.

Especially function xpc_request_test() to make a test call.

==API requests==

All API requests are made to the '''httрs://<xpayments_url>/api.php''' URL.
Only HTTPS protocol is used.
A request is an XML document that is encrypted using RSA method with a key generated by X-Payments.

'''Request/Response encryption'''

* Encryption method used: RSA;
* Key length: 2048 bit;
* A private key is created with a 32 character password;
* The password is generated randomly;
* The number of password characters varies from 33 to 127.

For each online store X-Payments generates 2 pairs of keys:

# a public and a private key to encrypt requests/responses from the online store to X-Payments;
# a public and a private key to encrypt requests/responses from X-Payments to the online store.

So when the online store sends a request to X-Payments, this request is encrypted using the public key from the first pair, X-Payments decrypts it using the private key of the first pair. Then X-Payments response is encrypted using the public key of the second pair, and the online store decrypts this response using the private key of the second pair.

To ensure full-featured two-way commumication between X-Payments and an online store, you need to copy tree values from the X-Payments interface:
:* Public key from the first pair (Online store → X-Payments),
:* Private key from the second pair (X-Payments → Online store),
:* Private key password,
and have them stored on the side of the online store by an appropriate X-Payments connector.

'''Encryption algorithm:'''

# An empty string is created for pre-prepared data.
# A 32-character salt-block is formed of random characters from 33 to 255.
# The length of the salt-block in bites is taken and transformed into a 12-character string by adding zeros before it.
# The salt-block length string and the salt-block are added to the pre-prepared data.
# MD5 digital signature is taken from the data. The signature is formed as a HEX (32-character string).
# The length of the digital signature in bites is taken and transformed into a 12-character string by adding zeros before it.
# The digital signature length string and the digital signature are added to the pre-prepared data.
# The length of the data string in bites is taken and transformed into a 12-character string by adding zeros before it.
# The data string length string and the data string are added to the pre-prepared data.
# The string of pre-prepared data is divided into 128 bite chunks.
# Each chunk is encrypted using a public key.
# Each chunk is encoded with base64.
# Chunks are glued together using a line feed character (0x0a).
# API prefix is added to the glued chunks.

===cURL as a means of sending requests===

Using libcurl v.7.10 and above is recommended.

TTL should be specified depending on the performance of the server where X-Payments is installed. The recommended value is 120 seconds.

It is recommended to use SSL v.3 and above.

===Data types===

Data types used:

* string - a UTF-8 string;
* email - an email address no longer than 255 characters;
* URL - a URL address no longer than 255 characters;
* currency - a floating point number denoting a certain sum of money. The mantissa size is the same as the payment currency mantissa size, but not longer than 3. All the exceeding characters will be truncated.
* integer - an integer number.

ISO 4217 Alpha-3 in the upper register is always used as the payment currency code.

ISO 639-1 Alpha-2 in the lower register is always used as the language code.

==Payment configurations list request==

Returns a list of payment configurations that are configured, enabled, and assigned to this online store/shopping cart.

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment_confs
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal get
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}
 

===Request example===

<pre>
<api_version>1.5</api_version>
<target>payment_confs</target>
<action>get</action>
</pre>
 

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | payment_module
| colspan="1" | container
| colspan="1" |
|-
| colspan="1" | payment_module/name
| colspan="1" | string
| colspan="1" | Name of the payment configuration, as set by the X-Payments admin
|-
| colspan="1" | payment_module/id
| colspan="1" | integer
| colspan="1" | Identifier of the payment configuration (autoincrement)
|-
| colspan="1" | payment_module/transactionTypes
| colspan="1" | container
| colspan="1" |
|-
| colspan="1" | payment_module/transactionTypes/sale
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Sale" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/auth
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Authorize only" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/capture
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Capture" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/capturePart
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows partial "Capture" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/captureMulti
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows multiple "Capture" operations ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/void
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Void" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/voidPart
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows partial "Void" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/voidMulti
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows multiple "Void" operations ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/refund
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Refund" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/refundPart
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows partial "Refund" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/refundMulti
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows multiple "Refund" operations ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/getInfo
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows to receive information from the payment gateway ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/accept
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Accept" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/decline
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Decline" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/test
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Test" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/authCaptureInfo
| colspan="1" | container
| colspan="1" |
|-
| colspan="1" | payment_module/authCaptureInfo/authExp
| colspan="1" | integer
| colspan="1" | How many days the transaction can stay in the Authorized status before being declined automatically
|-
| colspan="1" | payment_module/authCaptureInfo/captMinLimit
| colspan="1" | float
| colspan="1" | Minimum capture limit allowed by the payment gateway. Presented as a part of 1 (0 - no minimum limit, 0.2 - minimum 20% of authorized total, 0.5 - 50% of authorized total, etc.)
|-
| colspan="1" | payment_module/authCaptureInfo/captMaxLimit
| colspan="1" |
| colspan="1" | Maximum capture limit allowed by the payment gateway. Presented as a part of 1 (0 - no maximum limit, 0.5 - 50% of authorized total, 1 - 100% of authorized total, etc.)
|-
| colspan="1" | payment_module/moduleName
| colspan="1" | string
| colspan="1" | Default X-Payments name of the payment configuration
|-
| colspan="1" | payment_module/settingsHash
| colspan="1" | string
| colspan="1" | MD5 hash of the payment configuration settings
|-
| colspan="1" | payment_module/currency
| colspan="1" | string
| colspan="1" | 3-characters code of currency (ISO 4217). API v1.3 and later.
|-
| colspan="1" | payment_module/canSaveCards
| colspan="1" | string
| colspan="1" | Whether the payment configuration supports tokenization, i.e. customers' credit card can be saved on the payment gateway ("Y" - supports, "N" - doesn't support). API v1.3 and later.
|-
| colspan="1" | payment_module/class
| colspan="1" | string
| colspan="1" | Service field of the class name. It is unique for a payment module so it can be used to detect a certain payment gateway. E.g. XPay_Module_SagePayDirect for SagePay, XPay_Module_AuthorizeNet for Authorize.Net AIM, etc. API v1.4 and later.
|-
| colspan="1" | payment_module/isTestMode
| colspan="1" | string
| colspan="1" | Indicates if the payment configuration is configured in test mode ("Y" - test mode, "N" - live mode). API v1.4 and later.
|}
 

===Response example===

<pre>
<data>
<payment_module type="cell">
<name>First Data Global Gateway e4(SM) Web Service API</name>
<id>1</id>
<transactionTypes>
<sale>1</sale>
<auth>1</auth>
<capture>1</capture>
<capturePart>1</capturePart>
<captureMulti></captureMulti>
<void>1</void>
<voidPart></voidPart>
<voidMulti></voidMulti>
<refund>1</refund>
<refundPart>1</refundPart>
<refundMulti>1</refundMulti>
<getInfo></getInfo>
<accept></accept>
<decline></decline>
<test></test>
</transactionTypes>
<authCaptureInfo>
<authExp>30</authExp>
<captMinLimit>0</captMinLimit>
<captMaxLimit>1</captMaxLimit>
</authCaptureInfo>
<moduleName>First Data Payeezy Gateway (ex- Global Gateway e4)</moduleName>
<settingsHash>d41d8cd98f00b204e9800998ecf8427e</settingsHash>
<currency>USD</currency>
<canSaveCards>Y</canSaveCards>
<class>XPay_Module_FirstDataE4</class>
<isTestMode>Y</isTestMode>
</payment_module>
<payment_module type="cell">
<name>Chase Paymentech</name>
<id>2</id>
<transactionTypes>
<sale>1</sale>
<auth>1</auth>
<capture>1</capture>
<capturePart>1</capturePart>
<captureMulti></captureMulti>
<void>1</void>
<voidPart></voidPart>
<voidMulti></voidMulti>
<refund>1</refund>
<refundPart>1</refundPart>
<refundMulti></refundMulti>
<getInfo></getInfo>
<accept></accept>
<decline></decline>
<test></test>
</transactionTypes>
<authCaptureInfo>
<authExp>30</authExp>
<captMinLimit>0</captMinLimit>
<captMaxLimit>1</captMaxLimit>
</authCaptureInfo>
<moduleName>Chase Paymentech</moduleName>
<settingsHash>d41d8cd98f00b204e9800998ecf8427e</settingsHash>
<currency>USD</currency>
<canSaveCards>Y</canSaveCards>
<class>XPay_Module_Chase</class>
<isTestMode>Y</isTestMode>
</payment_module>
</data>
</pre>
 

==Test connection request==
Use this request to test the connection between the store and X-Payments. It can also help to detect the version of the X-Payments installation and the API version supported by X-Payments.

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal connect
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal test
|-
| colspan="1" | testCode
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Any string
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}
 

===Request example===

<pre>
<testCode>123</testCode>
<api_version>1.5</api_version>
<target>connect</target>
<action>test</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | hashCode
| colspan="1" | string
| colspan="1" | MD5 hash of the sent code
|-
| colspan="1" | error
| colspan="1" | string
| colspan="1" | Error code (if any)
|-
| colspan="1" | error_message
| colspan="1" | string
| colspan="1" | Error message
|-
| colspan="1" | is_error_message
| colspan="1" | string
| colspan="1" | Flag indicating the error message presence
|-
| colspan="1" | version
| colspan="1" | string
| colspan="1" | X-Payments version
|}
 

===Response example===

Example of a good response:
<pre>
<data>
<hashCode>202cb962ac59075b964b07152d234b70</hashCode>
<error></error>
<error_message></error_message>
<is_error_message></is_error_message>
<version>2.2.0</version>
</data>
</pre>

Example of a response with an error:
<pre>
<data>
<error>506</error>
<error_message>Your X-Payments connector module supports API version "1.9". This X-Payments supports the following API versions only: "1.1, 1.2, 1.3, 1.4, 1.5, 1.6".</error_message>
<is_error_message></is_error_message>
</data>
</pre>
 

==Payment initialisation request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal init
|-
| colspan="1" | confId
| colspan="1" | Y
| colspan="1" | integer
| colspan="1" | Payment module configuration ID
|-
| colspan="1" | refId
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Order ID in the online store
|-
| colspan="1" | returnUrl
| colspan="1" | Y
| colspan="1" | URL, 255
| colspan="1" | URL of the page to redirect the customer after payment
|-
| colspan="1" | callbackUrl
| colspan="1" | Y
| colspan="1" | URL, 255
| colspan="1" | URL to which X-Payments sends background requests with service information
|-
| colspan="1" | language
| colspan="1" | N
| colspan="1" | code of ISO 639-1 (Alpha-2)
| colspan="1" | Language code. If not specified - en
|-
| colspan="1" | cart
| colspan="1" | Y
| colspan="1" | container
| colspan="1" | A container with addresses description
|-
| colspan="1" | cart/billingAddress
| colspan="1" | Y
| colspan="1" | container
| colspan="1" | A container with the billing address description
|-
| colspan="1" | cart/billingAddress/firstname
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/lastname
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/company
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/address
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/city
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/state
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/country
| colspan="1" | Y
| colspan="1" | string, 2
| colspan="1" | ISO 3166-1 alpha-2 Country code https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
|-
| colspan="1" | cart/billingAddress/zipcode
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/email
| colspan="1" | Y
| colspan="1" | emai, 255l
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/phone
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/fax
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress
| colspan="1" | Y
| colspan="1" | container
| colspan="1" | A container with the shipping address description
|-
| colspan="1" | cart/shippingAddress/firstname
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/lastname
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/company
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/address
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/city
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/state
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/country
| colspan="1" | Y
| colspan="1" | string, 2
| colspan="1" | ISO 3166-1 alpha-2 Country code https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
|-
| colspan="1" | cart/shippingAddress/zipcode
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/email
| colspan="1" | Y
| colspan="1" | email, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/phone
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/fax
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/items
| colspan="1" | Y
| colspan="1" | container
| colspan="1" | A container with product description
|-
| colspan="1" | cart/items/sku
| colspan="1" | Y
| colspan="1" | string, 64
| colspan="1" | SKU (product code)
|-
| colspan="1" | cart/items/name
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" | Product name
|-
| colspan="1" | cart/items/price
| colspan="1" | Y
| colspan="1" | currency
| colspan="1" | Product item price
|-
| colspan="1" | cart/items/quantity
| colspan="1" | N
| colspan="1" | integer
| colspan="1" | Ordered number of products. If not specified - 1
|-
| colspan="1" | cart/login
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" | Unique customer ID in the online store (login, username, userid, etc.)
|-
| colspan="1" | cart/currency
| colspan="1" | N
| colspan="1" | string, 3
| colspan="1" | Payment currency code (ISO 4217 Alpha-3). If not specified, default payment configuration currency is used
|-
| colspan="1" | cart/shippingCost
| colspan="1" | -
| colspan="1" | currency
| colspan="1" | Shipping cost. By default - 0
|-
| colspan="1" | cart/taxCost
| colspan="1" | -
| colspan="1" | currency
| colspan="1" | Tax amount. By default - 0
|-
| colspan="1" | cart/discount
| colspan="1" | -
| colspan="1" | currency
| colspan="1" | Discount amount. By default - 0
|-
| colspan="1" | cart/totalCost
| colspan="1" | Y
| colspan="1" | currency
| colspan="1" | Total payment amount. Must equal to a sum of cart/items/price * cart/items/quantity + cart/shippingCost + cart/taxCost - cart/discount
|-
| colspan="1" | cart/description
| colspan="1" | -
| colspan="1" | string, 65536
| colspan="1" |
|-
| colspan="1" | cart/merchantEmail
| colspan="1" | Y
| colspan="1" | email, 255
| colspan="1" |
|-
| colspan="1" | cart/forceTransactionType
| colspan="1" | -
| colspan="1" | one of values: A or S or empty A - authorize S - sale
| colspan="1" | A flag of forced Sale or Authorize operation. Overrides the setting from the payment configuration. If the value is empty or the field is omitted, the operation is performed according to the payment configuration settings.
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|-
| colspan="1" | template (''supported by API 1.3 and later'')
| colspan="1" | N
| colspan="1" | string
| colspan="1" | The name of a template in X-Payments requested by the store. Forces the use of the specified template for the payment. If the string passed in this field does not match any template available in X-Payments, it will be ignored.
|-
| colspan="1" | saveCard (''supported by API 1.3 and later'')
| colspan="1" | N
| colspan="1" | string
| colspan="1" | Customer's choice at checkout (“Y” if customer would like to save the card)
|-
| colspan="1" | cart/kountCustomerUniq (''supported by API 1.6 and later'')
| colspan="1" | N
| colspan="1" | string, 32
| colspan="1" | This field is a unique customer identifier in the Kount system, which is send as a UNIQ field.
|}
 
'''List of template names in X-Payments 2.1.x (API v1.3)''':
:* '''default''': A template for the separate page. Used if the payment form is displayed on a separate page of your checkout process (not iframe).
:* '''fast''': Iframe for X-Cart 4 Fast Lane Checkout. Used for X-Cart 4 with the Fast Lane Checkout module. The payment form is displayed at the last step of the checkout process.
:* '''lite''': Iframe for X-Cart 4 One Page Checkout. Used for X-Cart 4 with the One Page Checkout module. The payment form is displayed in the payment section at checkout.
:* '''magento_iframe''': Iframe for Magento. Use this template for Magento and iframe.
:* '''mobile''': Template for mobile devices. Used with the X-Cart Mobile module.
:* '''xc5''': Iframe for X-Cart 5. Used for X-Cart 5 and iframe.

===Request example===

<pre>
<confId>8</confId>
<refId>1120</refId>
<cart>
<login>customer</login>
<billingAddress>
<firstname>John</firstname>
<lastname>Smith</lastname>
<address>10 Main street</address>
<city>Fillmore</city>
<state>UT</state>
<country>US</country>
<zipcode>84631</zipcode>
<company>IQ testing</company>
<email>bit-bucket@x-cart.com</email>
<phone>927348572</phone>
<fax></fax>
</billingAddress>
<shippingAddress>
<firstname>John</firstname>
<lastname>Smith</lastname>
<address>10 Main street</address>
<city>Fillmore</city>
<state>UT</state>
<country>US</country>
<zipcode>84631</zipcode>
<company>IQ testing</company>
<email>bit-bucket@x-cart.com</email>
<phone>927348572</phone>
<fax></fax>
</shippingAddress>
<items type="cell">
<sku>SKU17513</sku>
<name>Three Stone Princess Cut Diamond Ring</name>
<price>399.99</price>
<quantity>1</quantity>
</items>
<currency>USD</currency>
<shippingCost>15</shippingCost>
<taxCost>0</taxCost>
<discount>0</discount>
<totalCost>414.99</totalCost>
<description>Order(s) #1120</description>
<merchantEmail>bit-bucket@x-cart.com</merchantEmail>
<forceTransactionType></forceTransactionType>
</cart>
<returnUrl>https://example.com/xcart/payment/cc_xpc.php</returnUrl>
<callbackUrl>https://example.com/xcart/payment/cc_xpc.php</callbackUrl>
<language>ru</language>
<target>payment</target>
<action>init</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | token
| colspan="1" | string,32
| colspan="1" | Temporary payment token, expires immediately after the customer has submitted the cardholder data form
|-
| colspan="1" | txnId
| colspan="1" | string,32
| colspan="1" | A unique payment ID. Is used for all further requests to this payment through the API.
|}

===Response example===

<pre>
<data>
<token>41b2ef3b34698d4f6ed73151ae7307d2</token>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<error></error>
<error_message></error_message>
</data>
</pre>

==Redirecting a customer to the cardholder data entering page==

A POST form is created that sends data to the URL <XPayments_web_root>/payment.php; the form contains the following fields:

* target - has the value "main";
* token - uses the value from the token field received in the response to the payment initialisation request.

Request protocol - HTTPS 
The form must be sent by the POST method. All data must also be sent as POST variables.

==Payment information request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal get_info
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | refresh
| colspan="1" | N
| colspan="1" | 0 или 1
| colspan="1" | A flag specifying that the data in X-Payments must be overwritten by the data from the payment gateway. By default - 0
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<refresh>0</target>
<target>payment</target>
<action>get_info</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Payment status codes|Payment status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Human readable message containing the payment status
|-
| colspan="1" | isFraudStatus
| colspan="1" | 0 or 1
| colspan="1" | Means that the payment is blocked by the gateway, because the customer has not passed the gateway security check
|-
| colspan="1" | currency
| colspan="1" | string, 3
| colspan="1" | Payment currency code
|-
| colspan="1" | amount
| colspan="1" | currency
| colspan="1" | Payment total
|-
| colspan="1" | authorized
| colspan="1" | currency
| colspan="1" | Authorized payment total
|-
| colspan="1" | chargedAmount
| colspan="1" | currency
| colspan="1" | Charged payment total
|-
| colspan="1" | capturedAmount
| colspan="1" | currency
| colspan="1" | Captured amount of the authorized amount
|-
| colspan="1" | capturedAmountAvail
| colspan="1" | currency
| colspan="1" | Amount that is authorized and can be captured
|-
| colspan="1" | voidedAmount
| colspan="1" | currency
| colspan="1" | Amount that is authorized but voided
|-
| colspan="1" | voidedAmountAvail
| colspan="1" | currency
| colspan="1" | Amount that is authorized and can be voided
|-
| colspan="1" | refundedAmount
| colspan="1" | currency
| colspan="1" | Amount that can be refunded
|-
| colspan="1" | refundedAmountAvail
| colspan="1" | currency
| colspan="1" | Amount that can be refunded
|-
| colspan="1" | fraudAuthorized
| colspan="1" | currency
| colspan="1" | A part of the authorized amount that was blocked by the gateway because the customer had not passed the gateway security check
|-
| colspan="1" | fraudCharged
| colspan="1" | currency
| colspan="1" | A part of the charged amount that was blocked by the gateway because the customer had not passed the gateway security check
|-
| colspan="1" | authorizeInProgress
| colspan="1" | currency
| colspan="1" | A part of the authorized amount that is being handled by the gateway
|-
| colspan="1" | chargeInProgress
| colspan="1" | currency
| colspan="1" | A part of the charged amount that is being handled by the gateway
|-
| colspan="1" | transactionInProgress
| colspan="1" | 0 или 1
| colspan="1" | Are there any payment transactions handled by the gateway?
|-
| colspan="1" | capturedAmountAvailMin
| colspan="1" | currency
| colspan="1" | Minimum amount that can be captured from the authorized amount
|-
| colspan="1" | capturedAmountAvailGateway
| colspan="1" | currency
| colspan="1" | Amount that can be captured from the authorized amount through the gateway
|-
| colspan="1" | capturedAmountAvailMinGateway
| colspan="1" | currency
| colspan="1" | Minimum amount that can be captured from the authorized amount through the gateway
|-
| colspan="1" | voidedAmountAvailGateway
| colspan="1" | currency
| colspan="1" | Amount that can be voided from the authorized amount through the gateway
|-
| colspan="1" | refundedAmountAvailGateway
| colspan="1" | currency
| colspan="1" | Amount that can be refunded from the authorized amount through the gateway
|-
| colspan="1" | txnId
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | lastMessage
| colspan="1" | string, 65536
| colspan="1" | Last gateway message
|-
| colspan="1" | error
| colspan="1" | string, 128
| colspan="1" | Error code
|-
| colspan="1" | error_message
| colspan="1" | string, 65536
| colspan="1" | Error message
|}

{{Note|Fields ending in "Gateway" contain amounts that can be used in transactions through the gateway. For example, if a sum of $100 was authorized, and then a capture transaction was emulated for $100, the next refund operation will be available in the emulation mode only. The value of the refundedAmountAvailGateway field will be equal to 0.}}

===Response example===

<pre>
<data>
<status>2</status>
<message>Payment is authorized</message>
<isFraudStatus></isFraudStatus>
<currency>USD</currency>
<amount>414.99</amount>
<authorized>414.99</authorized>
<chargedAmount>0.00</chargedAmount>
<capturedAmount>0.00</capturedAmount>
<capturedAmountAvail>414.99</capturedAmountAvail>
<voidedAmount>0.00</voidedAmount>
<voidedAmountAvail>414.99</voidedAmountAvail>
<refundedAmount>0.00</refundedAmount>
<refundedAmountAvail>0.00</refundedAmountAvail>
<fraudAuthorized>0.00</fraudAuthorized>
<fraudCharged>0.00</fraudCharged>
<authorizeInProgress>0.00</authorizeInProgress>
<chargeInProgress>0.00</chargeInProgress>
<transactionInProgress></transactionInProgress>
<capturedAmountAvailMin>0.00</capturedAmountAvailMin>
<capturedAmountAvailGateway>414.99</capturedAmountAvailGateway>
<capturedAmountAvailMinGateway>0.00</capturedAmountAvailMinGateway>
<voidedAmountAvailGateway>414.99</voidedAmountAvailGateway>
<refundedAmountAvailGateway>0.00</refundedAmountAvailGateway>
<txnId>8e67e0da23ce7ed451b2c1adbbd7373c</txnId>
<lastMessage>Success</lastMessage>
<error></error>
<error_message></error_message>
</data>
</pre>

==Detailed payment and transaction information request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal get_additional_info
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | A unique payment ID received in the payment initialisation request response
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<target>payment</target>
<action>get_additional_info</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | payment
| colspan="1" | container
| colspan="1" | Payment information request response
|-
| colspan="1" | transactions
| colspan="1" | container
| colspan="1" | Transaction list
|-
| colspan="1" | transactions/date
| colspan="1" | integer, 11
| colspan="1" | Transaction date (Unix timestamp)
|-
| colspan="1" | transactions/action
| colspan="1" | string, 255
| colspan="1" | Transaction name
|-
| colspan="1" | transactions/status
| colspan="1" | string, 255
| colspan="1" | Transaction status
|-
| colspan="1" | transactions/message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|-
| colspan="1" | transactions/total
| colspan="1" | string, 32
| colspan="1" | Transaction amount and currency
|-
| colspan="1" | transactions/txnid
| colspan="1" | string, 255
| colspan="1" | Gateway transaction unique ID
|-
| colspan="1" | transactions/payment_status
| colspan="1" | string, 255
| colspan="1" | The payment status after the transaction
|-
| colspan="1" | transactions/fields
| colspan="1" | container
| colspan="1" | Transaction additional fields list
|-
| colspan="1" | transactions/fields/name
| colspan="1" | string, 255
| colspan="1" | Field name
|-
| colspan="1" | transactions/fields/name
| colspan="1" | string, 255
| colspan="1" | Field value
|-
| colspan="1" | payment/cardValidation (API 1.5 and later)
| colspan="1" | container
| colspan="1" | container for Address validation system (AVS)
|-
| colspan="1" | payment/cardValidation/avs_z (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Flag for AVS ZIP-code ("0" - unknown, "1" - matches, "2" - does not match)
|-
| colspan="1" | payment/cardValidation/avs_c (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Flag for AVS cardholder name ("0" - unknown, "1" - matches, "2" - does not match)
|-
| colspan="1" | payment/cardValidation/avs_a (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Flag for AVS street address ("0" - unknown, "1" - matches, "2" - does not match)
|-
| colspan="1" | payment/cardValidation/cvv (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Flag for CVV/CVV2/CVD ("0" - unknown, "1" - matches, "2" - does not match)
|-
| colspan="1" | payment/maskedCardData (API 1.5 and later)
| colspan="1" | container
| colspan="1" | container for Credit Card details (which are allowed to store and display by PA-DSS)
|-
| colspan="1" | payment/maskedCardData/first6 (API 1.5 and later)
| colspan="1" | string
| colspan="1" | First six digits of the credit card number
|-
| colspan="1" | payment/maskedCardData/last4 (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Last four digits of the credit card number
|-
| colspan="1" | payment/maskedCardData/type (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Credit card type: VISA, MC, AMEX, etc
|-
| colspan="1" | payment/maskedCardData/expire_month (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Credit card expiration month
|-
| colspan="1" | payment/maskedCardData/expire_year (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Credit card expiration year
|}

===Response example===

<pre>
<data>
<payment>
<status>2</status>
<message>Payment is authorized</message>
<isFraudStatus>1</isFraudStatus>
<currency>USD</currency>
<amount>10.61</amount>
<authorized>10.61</authorized>
<chargedAmount>0.00</chargedAmount>
<capturedAmount>0.00</capturedAmount>
<capturedAmountAvail>10.61</capturedAmountAvail>
<voidedAmount>0.00</voidedAmount>
<voidedAmountAvail>10.61</voidedAmountAvail>
<refundedAmount>0.00</refundedAmount>
<refundedAmountAvail>0.00</refundedAmountAvail>
<fraudAuthorized>0.00</fraudAuthorized>
<fraudCharged>0.00</fraudCharged>
<authorizeInProgress>0.00</authorizeInProgress>
<chargeInProgress>0.00</chargeInProgress>
<advinfo>
<Message></Message>
<Response code>1</Response>
<txn_id>6583</txn_id>
<Authorization number>ET154399</Authorization>
<AVS>5: Cardholder name incorrect, billing address and postal code match</AVS>
<Bank message>Approved</Bank>
<Bank response code>100</Bank>
<CVV2>M: CVV2 / CVC2/CVD Match.</CVV2>
<Processing status>Transaction Normal</Processing>
<Transarmor Token>8393008475641111</Transarmor>
<[Kount] 702650>Distance from Device to Billing > 1000km</[Kount] 702650>
<[Kount] 702656>Billing Country not equal to BIN Country (Visa/MC)</[Kount] 702656>
<[Kount] 702662>Billing Country not equal to Device Country</[Kount] 702662>
<[Kount] Auto>R</[Kount] Auto>
<[Kount] Errors></[Kount] Errors>
<[Kount] Score>26</[Kount] Score>
<[Kount] Transaction ID>3Z7903KDCTT0</[Kount] Transaction ID>
<[Kount] Warnings></[Kount] Warnings>
</advinfo>
<transactionInProgress></transactionInProgress>
<capturedAmountAvailMin>0.00</capturedAmountAvailMin>
<capturedAmountAvailGateway>10.61</capturedAmountAvailGateway>
<capturedAmountAvailMinGateway>0.00</capturedAmountAvailMinGateway>
<voidedAmountAvailGateway>10.61</voidedAmountAvailGateway>
<refundedAmountAvailGateway>0.00</refundedAmountAvailGateway>
<cardValidation>
<avs_z>1</avs_z>
<avs_c>2</avs_c>
<avs_a>1</avs_a>
<cvv>1</cvv>
</cardValidation>
<maskedCardData>
<first6>411111</first6>
<last4>1111</last4>
<type>VISA</type>
<expire_month>03</expire_month>
<expire_year>2020</expire_year>
</maskedCardData>
</payment>
<transactions type="cell">
<date>1438098759</date>
<action>Authorize</action>
<status>Success</status>
<message>Transaction Normal</message>
<total>10.61 USD</total>
<txnid>57629270</txnid>
<fields type="cell">
<name>Authorization number</name>
<value>ET154399</value>
</fields>
<fields type="cell">
<name>AVS</name>
<value>5: Cardholder name incorrect, billing address and postal code match</value>
</fields>
<fields type="cell">
<name>Bank message</name>
<value>Approved</value>
</fields>
<fields type="cell">
<name>Bank response code</name>
<value>100</value>
</fields>
<fields type="cell">
<name>CVV2</name>
<value>M: CVV2 / CVC2/CVD Match.</value>
</fields>
<fields type="cell">
<name>Processing status</name>
<value>Transaction Normal</value>
</fields>
<fields type="cell">
<name>Transarmor Token</name>
<value>8393008475641111</value>
</fields>
<fields type="cell">
<name>[Kount] 702650</name>
<value>Distance from Device to Billing > 1000km</value>
</fields>
<fields type="cell">
<name>[Kount] 702656</name>
<value>Billing Country not equal to BIN Country (Visa/MC)</value>
</fields>
<fields type="cell">
<name>[Kount] 702662</name>
<value>Billing Country not equal to Device Country</value>
</fields>
<fields type="cell">
<name>[Kount] Auto</name>
<value>R</value>
</fields>
<fields type="cell">
<name>[Kount] Score</name>
<value>26</value>
</fields>
<fields type="cell">
<name>[Kount] Transaction ID</name>
<value>3Z7903KDCTT0</value>
</fields>
<payment_status>Charged</payment_status>
</transactions>
<error></error>
<error_message></error_message>
<is_error_message></is_error_message>
<version>2.2.0</version>
</data>
</pre>

 
''The following pertains to API 1.5 and later:'' 
If the transaction was checked by Kount antifraud screening service, the "advinfo" and "tansaction/fields" containers contain information of kount results. The field names related to Kount start with the [Kount] prefix. The information can be extracted as follows:

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Description'''
|-
| colspan="1"| [Kount] %%%%%, where %%%%% is some number
| colspan="1"| triggered rule, the number is the number of this rule
|-
| colspan="1"| [Kount] Auto
| colspan="1"| The status of the transaction in Kount ("R" - review, "D" - declined, "A" - approved)
|-
| colspan="1"| [Kount] Errors
| colspan="1"| list of errors (if any)
|-
| colspan="1"| [Kount] Warnings:
| colspan="1"| list of warnings (if any)
|-
| colspan="1"| [Kount] Score
| colspan="1"| Risk score
|-
| colspan="1"| [Kount] Transaction ID
| colspan="1"| Transaction ID in Kount, can be used to display the direct link to the transaction in Kount, https://awc.test.kount.net/workflow/detail.html?id=%%%%%% for test mode or https://awc.kount.net/workflow/detail.html?id=%%%%%%, where %%%%% should be replaced with the transaction ID
|}
 

==Capture authorized transaction request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string,128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal capture
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | amount
| colspan="1" | N
| colspan="1" | currency
| colspan="1" | The amount to capture from the previously authorized transaction. By default equals the amount of the authorized transaction
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

=== Request example ===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<target>payment</target>
<action>capture</action>
</pre>

===Response example===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|}

Response example <pre><data>
<status>1</status>
<message>Success</message>
<error></error>
<error_message></error_message>
</data>
</pre>

==Void authorized transaction request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal void
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | amount
| colspan="1" | N
| colspan="1" | currency
| colspan="1" | Amount to void of the authorized transaction. By default equals to the amount of the authorized transaction
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<target>payment</target>
<action>void</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|}

===Response example===

<pre>
<data>
<status>1</status>
<message>Success</message>
<error></error>
<error_message></error_message>
</data>
</pre>

==Refund captured transaction request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal capture
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | amount
| colspan="1" | N
| colspan="1" | currency
| colspan="1" | Amount to be refunded to the customer of the previously captured transactions. By default equals to the amount of captured transactions
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre><txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<target>payment</target>
<action>refund</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|}

===Response example===

<pre><data>
<status>1</status>
<message>Success</message>
<error></error>
<error_message></error_message>
</data>
</pre>

==Blocked by gateway transaction accept request (Accept)==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal accept
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<target>payment</target>
<action>accept</action>
</pre>

===Response example===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|}

Response example <pre><data>
<status>1</status>
<message>Success</message>
<error></error>
<error_message></error_message>
</data>
</pre>

==Blocked by gateway transaction decline request (Decline)==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal decline
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<target>payment</target>
<action>decline</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|}

===Response example===

<pre>
<data>
<status>1</status>
<message>Success</message>
<error></error>
<error_message></error_message>
</data>
</pre>

==Charge again transaction request (Tokenization)==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal recharge
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID which references the token that will be used to identify the payment on the side of the payment gateway
|-
| colspan="1" | amount
| colspan="1" | Y
| colspan="1" | currency
| colspan="1" | The amount for which the "saved" card is to be charged using the token from the previous successful transaction
|-
| colspan="1" | description
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Description of the transaction
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|-
| colspan="1" | refId (supported by API 1.4 and later)
| colspan="1" | N
| colspan="1" | string, 128
| colspan="1" | Order ID in the online store
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<description>Recurring payment for the new issue of Playboy</description>
<target>payment</target>
<action>recharge</action>
<api_version>1.2</api_version>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | data
| colspan="1" | array
| colspan="1" |
|-
| colspan="1" | data[status]
| colspan="1" | integer
| colspan="1" | Status of the new payment (See [[#Payment status codes|Payment status codes]])
|-
| colspan="1" | data[transaction_id]
| colspan="1" | string
| colspan="1" | ID of the created payment for further references (capture/void/refund etc)
|-
| colspan="1" | data[error]
| colspan="1" | string
| colspan="1" |
|-
| colspan="1" | data[error_message]
| colspan="1" | string
| colspan="1" |
|-
| colspan="1" | data[is_error_message]
| colspan="1" | string
| colspan="1" |
|}
 

==Callback request with service payment information==

This is a background request that X-Payments sends to the store after a payment has been completed and it’s result (accepted, declined, etc) has been received from the payment gateway. The request is sent via HTTP POST to the callbackURL defined in the Payment initialisation request. Once this request has been sent, the customer is redirected back to the store.

===POSTed data===
{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Value'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | action
| colspan="1" | callback
| colspan="1" | fixed string
| colspan="1" | Identifies the callback request
|-
| colspan="1" | txnId
| colspan="1" | (mixed)
| colspan="1" | string (MD5 hash)
| colspan="1" | A unique ID of the payment on the side of X-Payments
|-
| colspan="1" | updateData
| colspan="1" | (mixed)
| colspan="1" | string
| colspan="1" | Encrypted response from X-Payments
|}

X-Payments does not expect a response from the store for this request; however, if the HTTP status of the response is not 200 OK, the request is considered failed, and a special notification is sent to the X-Payments admin. The store needs to decrypt the encrypted part of the response and update the order on its side accordingly. Once the updateData value has been decrypted, it is an XML document with the same structure as the [[X-Payments:API#Response_specification_2|response for Payment information request]].
 

==Check cart callback request==

After the customer has submitted credit card data, right before sending this data to the payment gateway, X-Payments connects to the store to verify the cart total and contents.

The HTTP POST request is sent to the '''callbackURL''' defined in the '''Payment initialisation request'''.

===POSTed data===
{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Value'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | action
| colspan="1" | check_cart
| colspan="1" | fixed string
| colspan="1" | Identifies the check-cart callback request
|-
| colspan="1" | txnId
| colspan="1" | (mixed)
| colspan="1" | string (MD5 hash)
| colspan="1" | A unique ID of the payment on the side of X-Payments
|-
| colspan="1" | refId
| colspan="1" | (mixed)
| colspan="1" | string
| colspan="1" | Order ID (or any other reference) in the online store
|}
 
As of API v1.3, the store must respond to this callback request. The response must be an encrypted XML document (i.e. the same way as for other communication between the store and X-Payments).

===Encrypted response for check-cart callback request===
{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | Y
| colspan="1" | fixed string
| colspan="1" | Should be “cart-changed” or "cart-not-changed"
|-
| colspan="1" | cart
| colspan="1" | Y
| colspan="1" | container
| colspan="1" | A container with cart/order description. See [[X-Payments:API#Request_specification|Payment initialisation request specification]] for details. This container must be included for "status = cart-changed" and is not necessary for "status = cart-not-changed"
|-
| colspan="1" | saveCard
| colspan="1" | N
| colspan="1" | string
| colspan="1" | Whether the customer has chosen to save their card for future use (“Y” if the customer would like to save the card)
|}
 

==Communication between X-Payments iframe and the store==

===Communication structure===
Communication between the online store (parent frame) and X-Payments (iframe) is implemented with the help of the javascript Window.postMessage method. Notifictions to both the sides represent stringified JSON formatted texts that consist of a service message (string) and an optional list of parameters:
:* '''height''': height of the iframe
:* '''error''': human readable message
:* '''type''': message type. X-Payments sends it as 2, which indicates that the online store should re-initialize the payment. In API v1.3 no other values are supported.

===Messages sent from the online store to X-Payments===
'''Submit payment form''' 
X-Payments’ iframe does not have a Submit button, so instead of it the payment form should be submitted from the parent window by any kind of “Submit order” or “Place order” button at checkout. At the same time, the special message '''submitPaymentForm''' with no parameters should be sent.
-----------------------------------------------------------
{
:::message: 'submitPaymentForm',
:::params: {}
}
-----------------------------------------------------------

 
===Messages sent from X-Payments to the online store===
'''Iframe is loaded and ready''' 
The message ready notifies the parent window that the payment form is ready. The actual height of the iframe is included in the parameters, so the parent window (checkout page) can perform the necessary adjustments.
-----------------------------------------------------------
{
:::message: 'ready',
:::params: {
::::::height: $(document).height()
:::}
}
-----------------------------------------------------------
 
'''Payment form submitted with an error''' 
The message '''paymentFormSubmitError''' with no parameters is sent in the case of any validation error. This may be the case, for example, if the customer’s credit card expiration date is in the past, or the credit card number does not match the card type (e.g. VISA, MasterCard), or when a required field has not been submitted (e.g. CVV2). Once the message '''paymentFormSubmitError''' with no parameters has been received, the store should not proceed to the next step of the checkout process, but should expect the payment form to be submitted again.
-----------------------------------------------------------
{
:::message: 'paymentFormSubmitError',
:::params: {}
}
-----------------------------------------------------------
 
'''Internal error''' 
The '''paymentFormSubmitError''' message with a special set of parameters is used to notify the store if something is wrong outside X-Payments, and X-Payments cannot do anything about it (for example, if the payment gateway has sent an unknown/unexpected piece of data).
-----------------------------------------------------------
{
:::message: 'paymentFormSubmitError',
:::params: {
::::::height: $(document).height(),
::::::error: 'Internal error',
::::::type: '2'
:::}
}
-----------------------------------------------------------
 
'''Session is expired''' 
For security reasons the length of the session is limited to 15 minutes. After this period the store has to re-initialize the payment. In this case X-Payments sends the '''paymentFormSubmitError''' message with the “Payment session expired” error.
-----------------------------------------------------------
{
:::message: 'paymentFormSubmitError',
:::params: {
::::::height: $(document).height(),
::::::error: 'Payment session expired',
::::::type: '2'
:::}
}
-----------------------------------------------------------
 
'''Payment form in Iframe is submitted''' (supported by API v1.4 and later) 
The message '''paymentFormSubmit''' notifies the parent window that the payment form has been submitted from the X-Payments side; for example, if a customer clicks the Enter key inside the iframe. Once the store receives this message, it should operate in the same way as though the customer has clicked the Place order button at checkout.
-----------------------------------------------------------
{
:::message: 'paymentFormSubmit',
:::params: {}
}

-----------------------------------------------------------
 

==Appendix A. Status codes.==

===Payment status codes===
: 1 - New
: 2 - Authorized
: 3 - Declined
: 4 - Charged
: 5 - Refunded
: 6 - Partially refunded

===Operation status codes===
: 0 - transaction failed
: 1 - transaction is successful
: 2 - transaction is successful and is duplicate

==See also==

* [http://lu53.crtdev.local/%7Emixon/google-cache-w.php?q=/index.php?title=X-Cart:X-Payments_Connector X-Cart:X-Payments Connector]

[[Category:X-Payments Developer Guide]]

X-Payments:Troubleshooting

2016-05-25T10:05:51Z

Alex “Ambal” Mulin: /* Sage Pay - Reason: 4020 : Information received from an Invalid IP address */

<noinclude>{{Template:XP manual TOC}}</noinclude>
==Troubleshooting==

===X-Payments 1.x installation process fails on a Windows server===
If X-Payments 1.x installation fails on a Windows server, try replacing the following line from install.php:
<pre>define('XP_DIR', rtrim(realpath(dirname(__FILE__)), XP_DS) . XP_DS);</pre>
with this line:
<pre>define('XP_DIR', rtrim(dirname(__FILE__), XP_DS) . XP_DS);</pre>

===Warning: require_once(/home/user/public_html/xpayments/lib/PDO.php)===

I am trying to install the X-Payments module but receive the following error on step 2 of the installation process:

Warning: require_once(/home/user/public_html/xpayments/lib/PDO.php) [function.require-once]: failed to open stream: No such file or directory in /home/user/public_html/xpayments/top.inc.PHP53.php on line 84

Fatal error: require_once() [function.require]: Failed opening required '/home/user/public_html/xpayments/lib/PDO.php' (include_path='.:/usr/lib/php:/usr/local/lib/php') in /home/user/public_html/xpayments/top.inc.PHP53.php on line 84

Solution:

It looks like the problem is related to the current PHP configuration on your server.

PHP is currently compiled with the necessary extensions:

'--enable-pdo=shared'
'--with-pdo-mysql=shared'
'--with-pdo-sqlite=shared'

However, X-Payments requires a bit different type of PHP configuration. PDO extension, as well as the MySQL PDO driver, needs to be installed as a shared module. In other words your php.ini file needs to be updated so that the PDO extensions will be loaded automatically when PHP runs:

extension=php_pdo.so
extension=php_pdo_mysql.so

See also:
* http://php.net/manual/en/pdo.installation.php

Please share this info with your server administrator and ask them to make the necessary changes in your PHP configuration.

===cron.php: X-Payments is using a non-secure protocol error===

I have tried everything to get the x payments cron.php working, but it is not working and we are getting this error:

ERROR [2012-25-06 12:23:01]
User: unknown; IP: unknown
Zone: Core
Code: NONSECURE_PROTOCOL (237)
X-Payments is using a non-secure protocol

Affected systems: Core/Defender.php file (60:assert); Application.php file (133:check); /home/user/public_html/xpayments/cron.php file (26:run)

Solution:

Wrong PHP binary is used to run cron.php script. You need to run cron.php using so called "CLI" version of PHP. Ask your hosting administrator to tell where PHP CLI is located on your server and configure cron to run cron.php script using PHP CLI version.

===Duplicate charges===

X-Payments v1.0.5 may have this issue under certain circumstances (iFrame checkout option aka "Lite interface" is enabled). Reason is that customers don't see an obvious sign that their payment is being processed after they entered their details and clicked "Submit" button so they click once again. This may create duplicate charges with some payment processors supported by X-Payments.

Solution:

Apply below patches to

1) front-end templates of your X-Payments:

[[File:Xp.105.diff]]

2) X-Cart connector:

[[File:Xc.454.diff]]

See how to apply patches at [http://help.x-cart.com/index.php?title=X-Cart:To_apply_a_patch_manually X-Cart:To apply a patch manually]

Note:
You do not need to apply the above patches if your X-Payments version is not v1.0.5 and if you do not use iFrame checkout provided by X-Payments.

===Empty or 404 page at Magento admin back-end===

If you see empty or 404 page at System -> Configuration -> X-Payments connector after installation do the following:

1) Clear cache:
System -> Cache Management

2) Logout and login admin area again

3) Then go to System -> Permissions -> Roles and click on "Administrators", then in a popup/new window click "Save Role".
That's it.

===My store background image does not carry over to X-Payments checkout area template===

'''Solution:'''

Make sure if the background image parameter in your X-Payments checkout skin is set as direct URL to your store image.

X-Payments checkout skin CSS file includes the following class used to display the header of integrated store pages:

#header .line1 .logo {
background: url("../../skin/artistictunes_car_tires/css/../images/custom/top_image1.jpg") no-repeat scroll left top #000000;
height: 240px;
margin-left: 0;
padding-top: 0;
position: relative;
width: auto;
}

For example, one of the possible solutions - modify the code of the generated CSS file, and change the default background image URL:

"../../skin/artistictunes_car_tires/css/../images/custom/top_image1.jpg"

to e.g. this one:

"https://yourshopdomain.com/xcart/skin/artistictunes_car_tires/images/custom/top_image1.jpg"

===X-Payments error (code: 843): Unallowed target===

This type of error may appear in X-Cart versions prior to 4.5.0.
You see below error message and X-Payments log file entry when using "Test connection" and "Request payment methods" buttons:

Error message:

<source>
- X-Payments error (code: 843): Unallowed target - ""
</source>

X-Payments log file entry:

<source>
-----------------------------------
ERROR [2013-11-05 00:11:49]
User: shopping cart (%%%%%%%%%%%); IP: %%%%%%%%%%%%
Zone: Model
Code: TARGET_UNALLOWED (843)
Unallowed target - ""
-----------------------------------
</source>

Solution:

Check if you have correct charset code specified in "Charset" field on X-Cart admin back-end -> Content -> Languages -> Your store language page.
See how to manage languages in X-Cart [[http://help.x-cart.com/index.php?title=X-Cart:Managing_Languages | here]].

===Sage Pay - Reason: 4020 : Information received from an Invalid IP address===

This is caused by a wrong IP for callbacks set in your Sage Pay account.

If you are using X-Payments Hosted plan (Basic, PRO or Multistore) you need to add the IP address '''98.142.211.162''' or '''104.200.145.25''' in your SagePay merchant backend on the Settings -> Valid IPs page.

If you are using a downloadable X-Payments license - you need to enter IP address of the server where your X-Payments copy is deployed. See [[X-Payments:How_It_Works#Callback_from_X-Payments_to_the_store | this article]] to understand X-Payments callbacks.

===No credit card form displayed when a customer pays===

====Error message at checkout instead of credit card form====

You've made a change in credit card form template at X-Payments side and now your checkout doesn't work?

This is the most probable situation with such type of errors during checkout via X-Payments. You've made a change in X-Payments credit card form and forgot to approve it at X-Payments admin back-end. As result X-Payments cannot process credit cards as it sees some changes in templates, but they are not approved by you, i.e. the admin user. Such approval process is implemented in X-Payments for security reasons. See also [[X-Payments:User_manual#Customizing_the_Interface]]

'''Solution:'''

Go into admin back-end dashboard and '''log in as the main admin user''' and check if it displays a warning about "Payment interface files have been modified" like below
[[File:Warning_customer_interface_changed.png]]

If yes, '''click "Approve" link''' in the warning text and everything is set now.

====No payment methods are displayed in the X-Payments connector settings====

So you deployed the configuration bundle copied from the X-Payments dashboard but do not see any payment methods in X-Cart on the X-Payments connector settings page. 
Your checkout via X-Payments does not work either.

'''Solution:'''
Make sure the online store is enabled in the X-Payments Admin back end and has at least one payment method enabled for it.

[[File:Xp_admin_backend.png|border|668px|]]

====CyberSource Internal Error====

Do you use CyberSource and get "Internal Error" on the checkout page along with below error within the X-Payments error log?

<source>

ERROR [2012-13-12 17:27:17]
User: unknown; IP: 68.184.224.121
Zone: Transport
Code: FILE_NOT_ACCESSIBLE (109)
File "Path/to/the/cybersource/security/key/txt/file" does not exist or is not readable

</source>

Solution:

Make sure you specified the right **server** path to the Cybersource key file on the [[X-Payments:CyberSourceSOAP | "CyberSource SOAP toolkit API" configuration page]], and it is readable by HTTP daemon on your X-Payments server.

====You use Hosted X-Payments plans and run out of bandwidth====

Congratulations! Your amount of transactions is impressive indeed! Most likely you used all bandwidth we provide for X-Payments Hosted accounts.

'''Solution''':

Please contact us using your HelpDesk account regarding the issue and we will consult you how to increase your bandwidth. Also, you should consider either upgrading to larger X-Payments Hosted plan or using X-Payments downloadable license that you can host yourself.

====You use Hosted X-Payments plans and run out of disk space====

One more reason for Hosted X-Payments plans can be you've run out of disk space we provide with every plan - check X-Payments folder at your X-Payments Hosted account (see [[X-Payments:X-Payments-Hosted-FAQ]]).

'''Solution:'''

Download logs files from your X-Payments Hosted account (see [[X-Payments:FAQ#Where_can_I_find_X-Payments_logs.3F]]) and remove them at X-Payments server to clear up some space.

====Your integrated shopping cart does not pass all customer profile fields to X-Payments correctly====

E.g. in X-Cart you can configure some vital for X-Payments customer profile fields (e.g. zipcode, address, email) as optional and your customers can miss them and do not fill in them with data during checkout. Thus X-Cart passes empty values for those data fields and X-Payments fails to process a transaction. X-Payments connector usually shows below warning

[[File:Warning_profile_fields_XP_connector.png]]

'''Solution:'''

Either make such customer profile fields mandatory for checkout in your cart or customize your cart connector for X-Payments to pass non-empty values if they should not be mandatory for your checkout routine and customers can leave such profile fields empty.

====PayPal PRO integration does not work in X-Cart 4.x====

You followed [http://help.x-cart.com/index.php?title=X-Cart:Adding_and_enabling_PayPal_payment_methods_in_X-Cart Adding and enabling PayPal payment methods in X-Cart] and [[X-Payments:Configuring_PayPal_payment_modules_in_X-Payments]], made sure all configuration settings are set correctly, but PayPal PRO still does not work for you and you see "Internal error" message when you use X-Payments in iFrame mode or see "Internal error (The merchantEmail is missing or incorrect)" error message when X-Payments is configured as a separate page in your X-Cart checkout routine.

'''Solution:'''

PayPal module in X-Cart v4.x refers to "orders department email address" at General settings/Company options/Company emails section. You need to have a valid email address in that setting to fix the issue.

====X-Cart isn't Synchronizing PayPal Payments PRO payment methods from X-Payments====

Trying to update payment processor on the back end of the store in the X-Payments Connector. In the backend of the X-Payments Admin, there is a new payment method enabled- PayPal Payments Pro. Virtual Merchant will no longer be used. See screenshot in the attachment.

On the backend of the site, once I try to Synchronize Payment Methods, the screen quickly shows options available to sync the new payment method. I have options to "set orders for..." then the options quickly disappear. There is a screenshot attached.

So with that, once I try to synchronize, the system won't allow me. The old payment method still remains (although it hasn't been deleted in the X-Payment Admin Backend) but the new method SHOULD appear once they are synchronized, showing TWO payment methods on the backend of the store, with the option for me to enable either one.

'''Solution:'''

X-Cart 4 have some restrictions of PayPal usage, so that you need to first add PayPal Pro methods inside X-Cart and configure them using the same credentials like in X-Payments. Re-sync methods after that and you'll see the PayPal.

====There are connection problems between your shopping cart and X-Payments at the time when a customer pays====

Your cart cannot connect to X-Payments some times and your customers see "Internal error" displayed.

'''Solution:'''

Make sure your cart server can connect to X-Payments server at all times (especially during your site high load times of a day).

==="Callback to online store is failed" notification and now all credit card transactions are failing===

You receive below notifications from X-Payments

<source>
"Callback to online store is failed. This notification has been sent by X-Payments installation at 'www.mysite.com'"
</source>

and now all credit card transactions are failing and the credit card fields for secure checkout on your website are missing.

'''Solution:'''

Most likely you regenerated [[X-Payments:Encryption_keys | encryption codes in X-Payments]] but neglected to update the information in X-Cart, hence the credit card fields are not loading when the customer is attempting to use a credit card for payment.

To remedy this go into X-Payments, 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 [http://help.x-cart.com/index.php?title=X-Cart:X-Payments_Connector#Configuring_X-Payments_Connector Configuring X-Payments Connector]).

===Fatal error: Access to undeclared static property: XPay_Model_Base_Module::$this===

You started to see error messages like below instead of working X-Payments.

<source>
Fatal error: Access to undeclared static property: XPay_Model_Base_Module::$this in /xxxxxxxxxxx/lib/XPay/Model/Base/Module.php on line 153
or
Fatal error: Access to undeclared static property: XPay_Model_Base_Module::$this in /xxxxxxxxxxx/lib/XPay/Model/Base/Module.php on line 131
</source>

'''Solution:'''

It is due to updating PHP to v 5.4.

To fix the problem, in lines 131 and 153 of

<xpayments_dir>/lib/XPay/Model/Base/Module.php

change

<source>
self::$this->
</source>

to

<source>
$this->
</source>

===My X-Payments doesn't store customers credit cards/X-Payments subscriptions module doesn't work===

So "Store credit card" functionality or X-Payments Subscriptions module doesn't work in your shopping cart despite of you integrated it with X-Payments?

'''Solution:'''

# Make sure you use X-Payments v2.x because X-Payments v1.x doesn't support this functionality.
# Make sure you use a payment gateway that supports so called "tokenization" in X-Payments v2.x - see the list of such payment gateways at [[X-Payments:Supported_payment_gateways]]. They have "+" in "Tokenization" column. "-" means tokenization is not supported for a payment gateway.
# So you do use X-Payments v2.x and a payment gateway that supports tokenization in X-Payments? Please make sure tokenization functionality is enabled for your payment gateway account at payment gateway side. Sometimes payment gateways call it differently, e.g. "vault", "Transformer", etc. If you are not sure - contact your payment gateway to enable tokenization for your payment gateway.

===Customer CC expires in 2022 - X-Payments stops at 2020===

We just had a customer call in. He could not check out because our X-Payments payment page would not allow him to enter the expiration year of 2022 for his credit card. Our X-Payments only goes up to 2020.

'''Solution:'''

You need to change YEAR_RANGE from 7 to 10 for example in file lib/XPay/View/Payment/Main.php

// Years list range

const YEAR_RANGE = 7

===White screen or HTTP 500 Internal server error instead of admin dashboard===

You see white screen after logging in X-Payments admin dashboard.

'''Solution:'''

Some PHP packages contain a bug that causes "White screen" or HTTP 500 Internal server error when PHP operates with the database via PDO. If you experience such issue contact your hosting support referring to:

https://bugs.php.net/bug.php?id=60825
https://bugs.php.net/bug.php?id=53716

===Magento: cannot test module connection or payment methods cannot be imported===

You copied all configuration data from X-Payments properly but in Magento admin you see below message when you click "Test module" button
Test transaction failed. Please check the X-Payment Connector settings and try again. If all options is ok review your X-Payments settings and make sure you have properly defined shopping cart properties.

Or a message that payment methods cannot be imported when you click "Request payment methods" button.

'''Solution:'''

Possible reason - you do not have a valid SSL certificate installed for your X-Payments. Self-signed SSL cannot pass libCurl validation and thus prevent connection between Magento and X-Payments, too. You need to install a valid SSL certificate at X-Payments server.

'''NOTE:''' users of our hosted X-Payments plans are safe since we provide SSL by default.

===Google Chrome v41.0.2272.76 detects X-Payments v2.1 credit card form as a mobile site on desktops===

After the update of the Google Chrome web browser to version 41.0.2272.76, the credit card form provided to your site by X-Payments v2.1 may be displayed incorrectly for Google Chrome users.
The problem behind this is that the value of the user-agent header sent by Chrome has changed, which causes X-Payments to identify the browser as running on a mobile device, even when, if fact, it is running on a PC. The result is that the credit card form is corrupted like on these screen shots:

- http://awesomescreenshot.com/0724kkas56
- http://awesomescreenshot.com/04f4kkaq18

'''Solution:'''

To fix the issue, you need to update the Mobile Detect library in your X-Payments installation so the list of supported user agents is relevant. For that you should replace the file
<xpayments-dir>/lib/MobileDetect.php with this one: https://drive.google.com/file/d/0B6p7sehSZL8_QUN6VmRVMHpxaFE/view?usp=sharing (should be done via SFTP, SSH, Control panel, etc.)

If you find it difficult to apply the changes yourself please contact our Tech Support team using https://secure.x-cart.com.

===Trouble with credit card logos in iFrame template for X-Cart 5===

You use X-Cart 5 integrated with X-Payments v2.x and see credit card logos displayed like [https://drive.google.com/a/x-cart.com/file/d/0B6p7sehSZL8_T1kyQ0RCNS1nWDA/view?usp=sharing this in checkout] using Mac Safari or iPad.

'''Solution'''

Replace files fast.css and xc5.css in folder <x-pay_dir>/public/templates/ with these:

https://drive.google.com/a/x-cart.com/folderview?id=0B6p7sehSZL8_OUVTeUtCUkFjY2M&usp=sharing

===My entire shop is run in an iFrame and X-Payments does not display "Pay" button===

There is a special code in X-Payments that hides "Pay" button if it the payment form is shown inside iframe.
In your case the whole store is placed inside iframe and that triggers the special code.
Easiest workaround which will not affect other stores connected to the X-Payments is to edit the template file css (I presume you use default.css) and where

<pre>
div.content div.buttonRow {
margin: 35px auto;
width: 400px;
}
</pre>

you should add

<pre>
display: block !important;
</pre>

e.g. after correction that code will look like

<pre>
div.content div.buttonRow {
margin: 35px auto;
width: 400px;
display: block !important;
}
</pre>

Do not forget to approve the changes in the admin back-end afterwards.

===X-Payments credit card form does not fit properly on Android tablet screen when used in iFrame in X-Cart 4 OPC===

X-Payments credit card form is displayed as shown on [https://drive.google.com/file/d/0B6p7sehSZL8_ZDhac2JNVWxlQ1E/view?usp=sharing this screen shot].

The reason is X-Cart 4 OPC shows desktop version of the site checkout while X-Payments shows mobile checkout template which is wider than needed for XC4 desktop OPC.

'''Solution'''

Apply [https://drive.google.com/file/d/0B6p7sehSZL8_c0JmYjhaRi1ITEE/view?usp=sharing this patch] to X-Payments connector files in your X-Cart 4.
 

===How to test payments via PayPal in X-Payments===

There is a list of credit card numbers in the PayPal guides which many people assume can be used when processing credit card transactions through PayPal. However, many of these card numbers have been blocked from PayPal system in one fashion or another (e.g. delay processing a lot so integrated software like X-Cart or Magento just fails to place a test transaction), so general advice is "don't use those card numbers".

In general, when testing credit card transactions with PayPal as the processor, it is recommended using a randomized credit card number. The number
must have a valid BIN, a valid check digit, and must be the correct length for the card type, but aside from that, the card number can be random.
You can get such random test credit card numbers at http://getcreditcardnumbers.com

==="The TxnID field is missing or incorrect" message after upgrading to a new connector version in Magento===

If after upgrading Magento connector to a new version and placing a new order you see an error message "The txnID field is missing or incorrect" instead of successful "Thank you for your order" page you need to clean/purge Magento's cache in your shop in the admin back-end. Consult with Magento user manual how to do that.

===Browser warning about wrong SSL certificate pops up===

If your browser shows a pop-up with warning about SSL certificate every time you test a transaction via X-Payments - this means your store installation has self-made/dummy SSL certificate. It is fine during testing, but you need to upgrade it to a real SSL certificate when your site goes live.
During testing just add that SSL certificate to exclusions in your browser in order not to see that warning every time you place a test transaction via X-Payments. This won't help you to hide that message from your shoppers though. The warning is not shown by a browser if a real SSL certificate is used.

==="X-Payments tried to notify the store about updates in payment but failed" notification===

You receive notifications that say "X-Payments tried to notify the store about updates in payment but failed ...".

They mean X-Payments callback requests have failed because of timeout or because your online shop site is not reachable by X-Payments.

In the 1st case the store didn't respond within 15 seconds coded by default in X-Payments, but the logs from the side of the store for these requests say, that the requests were received and processed with no errors. It means, that communication between the store and X-Payments actually works, but it takes to long for the store to respond. As a quick solution for this very reason it is recommended to increase the timeout limits in your X-Payments installation:
If X-Payments 2.x - in file lib/XPay/Model/Payment.php by changing "15" in a line of code that looks like to a bigger value (max 60):

<pre>
$requestData->setTimeout(15);
</pre>

If X-Payments 3.x - in file config/config.ini.php in section [callback] change value of wait_timeout param:

<pre>
[callback]

; Wait timeout for callback requests to the shopping cart (in seconds)
wait_timeout=15
</pre>

If you do not have access to your X-Payments installation code - contact vendors of the software by posting them a technical support ticket via https://secure.x-cart.com.

But the right solution is to figure out why your web site does not respond to X-Payments callbacks within 15 seconds.

In the 2nd case it might be firewall blocking X-Payments callback requests or your web shop was down for some time.

==="No Payment Methods Available" message shown to a customer===

A customer cannot place an order as he/she is displayed a message "No Payment Methods Available" at checkout and at the same time you see an error message "Data validation error, node "request": String length ("266342") exceeds the maximum allowed length for this node - "100000" in X-Payments error log file.

'''Reason'''

A shopper added too many line items (different products) to his/her cart ("too many" - e.g. over a thousand) and as result data passed to X-Payments exceeds amount it is configured to accept for security reasons.

'''Solution'''

1) a customer should divide his order in several with less number of line items and process them one by one.

2) if you face to this issue too often you can increase amount of data allowed to be processed by X-Payments by changing value of constant REQUEST_MAX_LENGTH in X-Payments file lib/XPay/Transport/Request/Api.php, but we do not recommend to large value there for security reasons.

===Payflow PRO currency issue===

'''NOTE''': do not confuse this with PayPal Payments PRO (PayFlow API)! There is PayFlow PRO integration, too. We are talking about PayFlow PRO here.

You need to process payments via PayFlow PRO in other currency than USD, but there is no way to change it. You configured integrated cart in e.g. CAD but X-Payments passes data to PayFlow PRO as USD. This is caused by features of PayFlow PRO API - no exact requirements about passing currency type to PayFlow PRO - sometimes it can be passed as "CUR", sometimes as "CU", etc depending on payment processor you have configured at PayFlow PRO back-end.

'''Solution'''

1) Switch to PayPal Payments Pro (Payflow API) integration instead of PayFlow PRO in X-Payments.

or

2) change code of X-Payments as follows:
in file lib/XPay/Module/PayflowPro.php find function

<pre>
private function getInitRequestBody(XPay_Transport_GatewayRequest $request)
</pre>

In the function find lines

<pre>
...
$fields = array(
'TRXTYPE' => XPay_Model_PaymentTransaction::SALE == $request->action ? 'S' : 'A',
'AMT' => $this->preparePrice($request->payment->get('total')),
'TAXAMT' => $this->preparePrice($additionalData->get('tax_cost')),
...
</pre>

and add a line of code

<pre>
'CURRENCY' => $request->payment->get('currency'),
</pre>

to get something like

<pre>
'TRXTYPE' => XPay_Model_PaymentTransaction::SALE == $request->action ? 'S' : 'A',
'CURRENCY' => $request->payment->get('currency'),
'AMT' => $this->preparePrice($request->payment->get('total')),
'TAXAMT' => $this->preparePrice($additionalData->get('tax_cost')),
</pre>

The above tweak will work if "PayPal" is configured as the gateway in your PayFlow PRO account.

For others you should directly specify currency in format required by payment gateway.

E.g.
<pre>
'CURRENCY' => 'USD',
</pre>

===X-Cart 5 and Exception message: Shopping cart server returned wrong HTTP headers for callback.===

You use X-Cart 5 and see below error message or error log entry at X-Cart 5 side:

<pre>
Failed to send "check_cart" callback to the store "mydomain.com"
Url: https://www.example.com/cart.php?target=callback&action=callback&xpcBackReference=ABCDEFGHIJKL
Exception message: Shopping cart server returned wrong HTTP headers for callback.
</pre>

'''Solution''':

Most likely you try to test X-Payments with X-Cart 5 storefront closed. If so, in X-Cart 5 file etc/config.php find below piece of code:

<pre>
[storefront_options]
; Do not close target=callback for payments if storefront is closed
callback_opened = Off
</pre>

and change "Off" to "On" there.

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

[[Category:X-Payments User Manual]]

X-Payments:X-Payments-Hosted-FAQ

2016-05-25T10:00:01Z

Alex “Ambal” Mulin: /* What do I need to put as "Callback IP"? */

===What do I need to put as "Callback IP"?===

If you use the X-Payments Hosted solution you should use IP address '''98.142.211.162''' if your account is based on X-Payments v1.x or v2.x or '''104.200.145.25''' if X-Payments v3.x

===How to configure FTP client to connect to the yourdomain.x-checkout.com to access skins and logs?===

You should use the details from the email received when your account was created:

:* host: yourdomain.x-checkout.com 
:* user: skins@yourdomain.x-checkout.com 
:* password: the one that you've received 

Please make sure that the "Explicit FTP over TLS" mode is used. This is required because plain text authentication is not allowed for PCI compliance.

Instructions for FileZilla FTP Client:

# Start FileZilla
# Go to File -> Site Manager
# Click New site
# Enter the connection settings:
#* Host: yourdomain.x-checkout.com 
#* Port: leave blank 
#* Protocol: FTP - File Transfer Protocol 
#* Encryption: Require explict FTP over TLS 
#* Logon type: Normal 
#* user: skins@yourdomain.x-checkout.com 
#* password: the one that you've received [[File:Filezilla.png]] 
# Click the Connect button

[[Category:X-Payments User Manual]]

X-Payments:X-Payments-Hosted-FAQ

2016-05-25T09:59:33Z

Alex “Ambal” Mulin: /* What do I need to put as "Callback IP"? */

===What do I need to put as "Callback IP"?===

If you use the X-Payments Hosted solution you should use IP address 98.142.211.162 if your account is based on X-Payments v1.x or v2.x or 104.200.145.25 if X-Payments v3.x

===How to configure FTP client to connect to the yourdomain.x-checkout.com to access skins and logs?===

You should use the details from the email received when your account was created:

:* host: yourdomain.x-checkout.com 
:* user: skins@yourdomain.x-checkout.com 
:* password: the one that you've received 

Please make sure that the "Explicit FTP over TLS" mode is used. This is required because plain text authentication is not allowed for PCI compliance.

Instructions for FileZilla FTP Client:

# Start FileZilla
# Go to File -> Site Manager
# Click New site
# Enter the connection settings:
#* Host: yourdomain.x-checkout.com 
#* Port: leave blank 
#* Protocol: FTP - File Transfer Protocol 
#* Encryption: Require explict FTP over TLS 
#* Logon type: Normal 
#* user: skins@yourdomain.x-checkout.com 
#* password: the one that you've received [[File:Filezilla.png]] 
# Click the Connect button

[[Category:X-Payments User Manual]]

X-Payments:How It Works

2016-05-25T08:53:24Z

Alex “Ambal” Mulin:

<noinclude>{{XP_manual_TOC}}</noinclude>

==X-Payments flow via diagram==
:[[File:XP-diagram.png|700px|border]]

===API Call===

1) Store initiates an API call to X-Payments to create a payment (Created payments can be [[X-Payments:User_manual#Viewing_Payments|viewed]] on the 'Payments' page in X-Payments back end). At this step store sends to X-Payments all information about the customer (billing and shipping address) and the products being purchased (product quantities and cost). In addition to that, store instructs X-Payments as to which payment configuration should be used.

2) X-Payments validates this initial request from the store: checks whether the requested [[X-Payments:User_manual#Payment_Configurations|payment configuration]] is [[X-Payments:Managing store connections#Editing Online Store Details|active]], whether the payment currency passed on to X-Payments by the store matches the currency specified in the respective payment configuration in X-Payments, and makes some other internal checks; for instance, a check is conducted to ensure that the template files for the page where customers enter cardholder data have not been modified without approval by X-Payments admin. If everything is fine, X-Payments returns a [[X-Payments:API#Response_specification | payment "token"]] to the store (The token serves as a temporary identifier of the payment in X-Payments; it is generated as a result of the API call and is removed after the customer is redirected back to the store when the payment is completed). If a problem is detected, no token is sent to the store, and an internal error is generated in X-Payments. Detailed information about such errors can be found in the X-Payments and X-Cart logs: 
* X-Payments: See the <xpay-dir>/var/log/api/YYYY-MM-DD/ directory
* X-Cart: See the <xcart-dir>/var/log/x-errors_xpay_connector-YYMMDD.php file

===Payment===

3) Customer is redirected to the X-Payments secure page where the form for entering credit card details is located. If the iframe is used, this redirect is not visible to customer, as the form is embedded into the checkout page.

4) Customer enters credit card details and submits the form. These details are sent to the payment gateway along with other data previously received by X-Payments (address details, products being purchased, etc).

5) Payment gateway operates with the bank to charge the card (or authorize the funds in case of an "auth only" transaction) and sends back to X-Payments the information about the transaction.

The log of communication between X-Payments and the payment gateway can be found in the <xpay-dir>/var/log/payment/YYYY-MM-DD/ directory.

===Callback from gateway (PayPal) to X-Payments===

6) Some payment gateways also send back to X-Payments an additional "callback" request. This "callback" request provides detailed information about the transaction and also helps to validate/confirm the transaction. Currently only PayPal Payments PRO operates in X-Payments in such a way. As an additional protection, X-Payments allows you to specify the IP addresses from which the gateway's callback requests can be received. Provided with a list of trusted Call-back IPs for PayPal, X-Payments will only accept "callback" requests coming from PayPal’s server and ignore all other requests coming from anywhere else, should such requests be made. The list of PayPal’s IP addresses can be found here: https://ppmts.custhelp.com/app/answers/detail/a_id/92
If you wish to use this additional protection, you can enter the necessary IP addresses into [[X-Payments:Configuring_PayPal_payment_modules_in_X-Payments#PayPalPaymentsProPayPalAPIconfsettings|PayPal payment configuration settings]] in X-Payments back end.

The log of payment gateway callback request processing is saved to the <xpay-dir>/var/log/callback/YYYY-MM-DD/ directory.

===Invoice===

7) Customer is redirected back to the store where the Invoice page is displayed.
If the transaction is declined by the payment gateway for some reason, the error page is displayed. Additional information about the reasons of the transaction being declined can be found in the X-Payments admin back end on the 'Payment details' page.

===Callback from X-Payments to the store===

8) Detailed information about the payment is sent to the store via a "callback" request.
The same functionality ("callback" requests) is used to notify the store if the payment has been changed via X-Payments admin back end; for example, if a secondary transaction took place ('Capture' or 'Void' for an authorized transaction, 'Refund' for a charge).

X-Cart allows additional protection for callback requests from X-Payments: thus you can specify the IP addresses for X-Payments callbacks in X-Payments connector module settings: http://help.x-cart.com/index.php?title=X-Cart:X-Payments_Connector. X-Cart will accept only those callback requests that come from the specified IP addresses, others will be ignored.

'''Important''': On some server configurations the IP address from which the callback request comes may not match the IP of the server where X-Payments is installed as illustrated below:

:[[File:XP-diagram1.png|700px|border]]

Even if X-Payments is installed on the 172.18.0.3 IP address, and is accessible via web by it, the outgoing request is received from the "proxy" of 172.18.0.0. So, it is recommended to verify the IP address for outgoing HTTPS connections with your hosting provider.

{{Note|If you use the '''X-Payments Hosted''' plan, you should use IP address '''98.142.211.162''' if your X-Payments account is v1.x or v2.x based or '''104.200.145.25''' if v3.x based.}}

The log of the X-Payments callback requests processing is saved to the following locations: 
* X-Cart: See the <xcart-dir>/var/log/x-errors_xpay_connector-YYMMDD.php file if any error occurred.
* X-Payments: See the <xpay-dir>/var/log/payment/YYYY-MM-DD/ directory for the initial Authorize or Sale (Authorize and Capture at the same time or Auto settle) transaction and <xpay-dir>/var/log/admin/YYYY-MM-DD/ directory for the secondary Capture, Void or Refund transaction.

[[Category:X-Payments User Manual]]

X-Payments:Troubleshooting

2016-05-05T12:49:52Z

Alex “Ambal” Mulin: /* "X-Payments tried to notify the store about updates in payment but failed" notification */

<noinclude>{{Template:XP manual TOC}}</noinclude>
==Troubleshooting==

===X-Payments 1.x installation process fails on a Windows server===
If X-Payments 1.x installation fails on a Windows server, try replacing the following line from install.php:
<pre>define('XP_DIR', rtrim(realpath(dirname(__FILE__)), XP_DS) . XP_DS);</pre>
with this line:
<pre>define('XP_DIR', rtrim(dirname(__FILE__), XP_DS) . XP_DS);</pre>

===Warning: require_once(/home/user/public_html/xpayments/lib/PDO.php)===

I am trying to install the X-Payments module but receive the following error on step 2 of the installation process:

Warning: require_once(/home/user/public_html/xpayments/lib/PDO.php) [function.require-once]: failed to open stream: No such file or directory in /home/user/public_html/xpayments/top.inc.PHP53.php on line 84

Fatal error: require_once() [function.require]: Failed opening required '/home/user/public_html/xpayments/lib/PDO.php' (include_path='.:/usr/lib/php:/usr/local/lib/php') in /home/user/public_html/xpayments/top.inc.PHP53.php on line 84

Solution:

It looks like the problem is related to the current PHP configuration on your server.

PHP is currently compiled with the necessary extensions:

'--enable-pdo=shared'
'--with-pdo-mysql=shared'
'--with-pdo-sqlite=shared'

However, X-Payments requires a bit different type of PHP configuration. PDO extension, as well as the MySQL PDO driver, needs to be installed as a shared module. In other words your php.ini file needs to be updated so that the PDO extensions will be loaded automatically when PHP runs:

extension=php_pdo.so
extension=php_pdo_mysql.so

See also:
* http://php.net/manual/en/pdo.installation.php

Please share this info with your server administrator and ask them to make the necessary changes in your PHP configuration.

===cron.php: X-Payments is using a non-secure protocol error===

I have tried everything to get the x payments cron.php working, but it is not working and we are getting this error:

ERROR [2012-25-06 12:23:01]
User: unknown; IP: unknown
Zone: Core
Code: NONSECURE_PROTOCOL (237)
X-Payments is using a non-secure protocol

Affected systems: Core/Defender.php file (60:assert); Application.php file (133:check); /home/user/public_html/xpayments/cron.php file (26:run)

Solution:

Wrong PHP binary is used to run cron.php script. You need to run cron.php using so called "CLI" version of PHP. Ask your hosting administrator to tell where PHP CLI is located on your server and configure cron to run cron.php script using PHP CLI version.

===Duplicate charges===

X-Payments v1.0.5 may have this issue under certain circumstances (iFrame checkout option aka "Lite interface" is enabled). Reason is that customers don't see an obvious sign that their payment is being processed after they entered their details and clicked "Submit" button so they click once again. This may create duplicate charges with some payment processors supported by X-Payments.

Solution:

Apply below patches to

1) front-end templates of your X-Payments:

[[File:Xp.105.diff]]

2) X-Cart connector:

[[File:Xc.454.diff]]

See how to apply patches at [http://help.x-cart.com/index.php?title=X-Cart:To_apply_a_patch_manually X-Cart:To apply a patch manually]

Note:
You do not need to apply the above patches if your X-Payments version is not v1.0.5 and if you do not use iFrame checkout provided by X-Payments.

===Empty or 404 page at Magento admin back-end===

If you see empty or 404 page at System -> Configuration -> X-Payments connector after installation do the following:

1) Clear cache:
System -> Cache Management

2) Logout and login admin area again

3) Then go to System -> Permissions -> Roles and click on "Administrators", then in a popup/new window click "Save Role".
That's it.

===My store background image does not carry over to X-Payments checkout area template===

'''Solution:'''

Make sure if the background image parameter in your X-Payments checkout skin is set as direct URL to your store image.

X-Payments checkout skin CSS file includes the following class used to display the header of integrated store pages:

#header .line1 .logo {
background: url("../../skin/artistictunes_car_tires/css/../images/custom/top_image1.jpg") no-repeat scroll left top #000000;
height: 240px;
margin-left: 0;
padding-top: 0;
position: relative;
width: auto;
}

For example, one of the possible solutions - modify the code of the generated CSS file, and change the default background image URL:

"../../skin/artistictunes_car_tires/css/../images/custom/top_image1.jpg"

to e.g. this one:

"https://yourshopdomain.com/xcart/skin/artistictunes_car_tires/images/custom/top_image1.jpg"

===X-Payments error (code: 843): Unallowed target===

This type of error may appear in X-Cart versions prior to 4.5.0.
You see below error message and X-Payments log file entry when using "Test connection" and "Request payment methods" buttons:

Error message:

<source>
- X-Payments error (code: 843): Unallowed target - ""
</source>

X-Payments log file entry:

<source>
-----------------------------------
ERROR [2013-11-05 00:11:49]
User: shopping cart (%%%%%%%%%%%); IP: %%%%%%%%%%%%
Zone: Model
Code: TARGET_UNALLOWED (843)
Unallowed target - ""
-----------------------------------
</source>

Solution:

Check if you have correct charset code specified in "Charset" field on X-Cart admin back-end -> Content -> Languages -> Your store language page.
See how to manage languages in X-Cart [[http://help.x-cart.com/index.php?title=X-Cart:Managing_Languages | here]].

===Sage Pay - Reason: 4020 : Information received from an Invalid IP address===

This is caused by a wrong IP for callbacks set in your Sage Pay account.

If you are using X-Payments Hosted plan (Basic, PRO or Multistore) you need to add the IP address of 98.142.211.162 in your SagePay merchant backend on the Settings -> Valid IPs page.

If you are using a downloadable X-Payments license - you need to enter IP address of the server where your X-Payments copy is deployed. See [[X-Payments:How_It_Works#Callback_from_X-Payments_to_the_store | this article]] to understand X-Payments callbacks.

===No credit card form displayed when a customer pays===

====Error message at checkout instead of credit card form====

You've made a change in credit card form template at X-Payments side and now your checkout doesn't work?

This is the most probable situation with such type of errors during checkout via X-Payments. You've made a change in X-Payments credit card form and forgot to approve it at X-Payments admin back-end. As result X-Payments cannot process credit cards as it sees some changes in templates, but they are not approved by you, i.e. the admin user. Such approval process is implemented in X-Payments for security reasons. See also [[X-Payments:User_manual#Customizing_the_Interface]]

'''Solution:'''

Go into admin back-end dashboard and '''log in as the main admin user''' and check if it displays a warning about "Payment interface files have been modified" like below
[[File:Warning_customer_interface_changed.png]]

If yes, '''click "Approve" link''' in the warning text and everything is set now.

====No payment methods are displayed in the X-Payments connector settings====

So you deployed the configuration bundle copied from the X-Payments dashboard but do not see any payment methods in X-Cart on the X-Payments connector settings page. 
Your checkout via X-Payments does not work either.

'''Solution:'''
Make sure the online store is enabled in the X-Payments Admin back end and has at least one payment method enabled for it.

[[File:Xp_admin_backend.png|border|668px|]]

====CyberSource Internal Error====

Do you use CyberSource and get "Internal Error" on the checkout page along with below error within the X-Payments error log?

<source>

ERROR [2012-13-12 17:27:17]
User: unknown; IP: 68.184.224.121
Zone: Transport
Code: FILE_NOT_ACCESSIBLE (109)
File "Path/to/the/cybersource/security/key/txt/file" does not exist or is not readable

</source>

Solution:

Make sure you specified the right **server** path to the Cybersource key file on the [[X-Payments:CyberSourceSOAP | "CyberSource SOAP toolkit API" configuration page]], and it is readable by HTTP daemon on your X-Payments server.

====You use Hosted X-Payments plans and run out of bandwidth====

Congratulations! Your amount of transactions is impressive indeed! Most likely you used all bandwidth we provide for X-Payments Hosted accounts.

'''Solution''':

Please contact us using your HelpDesk account regarding the issue and we will consult you how to increase your bandwidth. Also, you should consider either upgrading to larger X-Payments Hosted plan or using X-Payments downloadable license that you can host yourself.

====You use Hosted X-Payments plans and run out of disk space====

One more reason for Hosted X-Payments plans can be you've run out of disk space we provide with every plan - check X-Payments folder at your X-Payments Hosted account (see [[X-Payments:X-Payments-Hosted-FAQ]]).

'''Solution:'''

Download logs files from your X-Payments Hosted account (see [[X-Payments:FAQ#Where_can_I_find_X-Payments_logs.3F]]) and remove them at X-Payments server to clear up some space.

====Your integrated shopping cart does not pass all customer profile fields to X-Payments correctly====

E.g. in X-Cart you can configure some vital for X-Payments customer profile fields (e.g. zipcode, address, email) as optional and your customers can miss them and do not fill in them with data during checkout. Thus X-Cart passes empty values for those data fields and X-Payments fails to process a transaction. X-Payments connector usually shows below warning

[[File:Warning_profile_fields_XP_connector.png]]

'''Solution:'''

Either make such customer profile fields mandatory for checkout in your cart or customize your cart connector for X-Payments to pass non-empty values if they should not be mandatory for your checkout routine and customers can leave such profile fields empty.

====PayPal PRO integration does not work in X-Cart 4.x====

You followed [http://help.x-cart.com/index.php?title=X-Cart:Adding_and_enabling_PayPal_payment_methods_in_X-Cart Adding and enabling PayPal payment methods in X-Cart] and [[X-Payments:Configuring_PayPal_payment_modules_in_X-Payments]], made sure all configuration settings are set correctly, but PayPal PRO still does not work for you and you see "Internal error" message when you use X-Payments in iFrame mode or see "Internal error (The merchantEmail is missing or incorrect)" error message when X-Payments is configured as a separate page in your X-Cart checkout routine.

'''Solution:'''

PayPal module in X-Cart v4.x refers to "orders department email address" at General settings/Company options/Company emails section. You need to have a valid email address in that setting to fix the issue.

====X-Cart isn't Synchronizing PayPal Payments PRO payment methods from X-Payments====

Trying to update payment processor on the back end of the store in the X-Payments Connector. In the backend of the X-Payments Admin, there is a new payment method enabled- PayPal Payments Pro. Virtual Merchant will no longer be used. See screenshot in the attachment.

On the backend of the site, once I try to Synchronize Payment Methods, the screen quickly shows options available to sync the new payment method. I have options to "set orders for..." then the options quickly disappear. There is a screenshot attached.

So with that, once I try to synchronize, the system won't allow me. The old payment method still remains (although it hasn't been deleted in the X-Payment Admin Backend) but the new method SHOULD appear once they are synchronized, showing TWO payment methods on the backend of the store, with the option for me to enable either one.

'''Solution:'''

X-Cart 4 have some restrictions of PayPal usage, so that you need to first add PayPal Pro methods inside X-Cart and configure them using the same credentials like in X-Payments. Re-sync methods after that and you'll see the PayPal.

====There are connection problems between your shopping cart and X-Payments at the time when a customer pays====

Your cart cannot connect to X-Payments some times and your customers see "Internal error" displayed.

'''Solution:'''

Make sure your cart server can connect to X-Payments server at all times (especially during your site high load times of a day).

==="Callback to online store is failed" notification and now all credit card transactions are failing===

You receive below notifications from X-Payments

<source>
"Callback to online store is failed. This notification has been sent by X-Payments installation at 'www.mysite.com'"
</source>

and now all credit card transactions are failing and the credit card fields for secure checkout on your website are missing.

'''Solution:'''

Most likely you regenerated [[X-Payments:Encryption_keys | encryption codes in X-Payments]] but neglected to update the information in X-Cart, hence the credit card fields are not loading when the customer is attempting to use a credit card for payment.

To remedy this go into X-Payments, 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 [http://help.x-cart.com/index.php?title=X-Cart:X-Payments_Connector#Configuring_X-Payments_Connector Configuring X-Payments Connector]).

===Fatal error: Access to undeclared static property: XPay_Model_Base_Module::$this===

You started to see error messages like below instead of working X-Payments.

<source>
Fatal error: Access to undeclared static property: XPay_Model_Base_Module::$this in /xxxxxxxxxxx/lib/XPay/Model/Base/Module.php on line 153
or
Fatal error: Access to undeclared static property: XPay_Model_Base_Module::$this in /xxxxxxxxxxx/lib/XPay/Model/Base/Module.php on line 131
</source>

'''Solution:'''

It is due to updating PHP to v 5.4.

To fix the problem, in lines 131 and 153 of

<xpayments_dir>/lib/XPay/Model/Base/Module.php

change

<source>
self::$this->
</source>

to

<source>
$this->
</source>

===My X-Payments doesn't store customers credit cards/X-Payments subscriptions module doesn't work===

So "Store credit card" functionality or X-Payments Subscriptions module doesn't work in your shopping cart despite of you integrated it with X-Payments?

'''Solution:'''

# Make sure you use X-Payments v2.x because X-Payments v1.x doesn't support this functionality.
# Make sure you use a payment gateway that supports so called "tokenization" in X-Payments v2.x - see the list of such payment gateways at [[X-Payments:Supported_payment_gateways]]. They have "+" in "Tokenization" column. "-" means tokenization is not supported for a payment gateway.
# So you do use X-Payments v2.x and a payment gateway that supports tokenization in X-Payments? Please make sure tokenization functionality is enabled for your payment gateway account at payment gateway side. Sometimes payment gateways call it differently, e.g. "vault", "Transformer", etc. If you are not sure - contact your payment gateway to enable tokenization for your payment gateway.

===Customer CC expires in 2022 - X-Payments stops at 2020===

We just had a customer call in. He could not check out because our X-Payments payment page would not allow him to enter the expiration year of 2022 for his credit card. Our X-Payments only goes up to 2020.

'''Solution:'''

You need to change YEAR_RANGE from 7 to 10 for example in file lib/XPay/View/Payment/Main.php

// Years list range

const YEAR_RANGE = 7

===White screen or HTTP 500 Internal server error instead of admin dashboard===

You see white screen after logging in X-Payments admin dashboard.

'''Solution:'''

Some PHP packages contain a bug that causes "White screen" or HTTP 500 Internal server error when PHP operates with the database via PDO. If you experience such issue contact your hosting support referring to:

https://bugs.php.net/bug.php?id=60825
https://bugs.php.net/bug.php?id=53716

===Magento: cannot test module connection or payment methods cannot be imported===

You copied all configuration data from X-Payments properly but in Magento admin you see below message when you click "Test module" button
Test transaction failed. Please check the X-Payment Connector settings and try again. If all options is ok review your X-Payments settings and make sure you have properly defined shopping cart properties.

Or a message that payment methods cannot be imported when you click "Request payment methods" button.

'''Solution:'''

Possible reason - you do not have a valid SSL certificate installed for your X-Payments. Self-signed SSL cannot pass libCurl validation and thus prevent connection between Magento and X-Payments, too. You need to install a valid SSL certificate at X-Payments server.

'''NOTE:''' users of our hosted X-Payments plans are safe since we provide SSL by default.

===Google Chrome v41.0.2272.76 detects X-Payments v2.1 credit card form as a mobile site on desktops===

After the update of the Google Chrome web browser to version 41.0.2272.76, the credit card form provided to your site by X-Payments v2.1 may be displayed incorrectly for Google Chrome users.
The problem behind this is that the value of the user-agent header sent by Chrome has changed, which causes X-Payments to identify the browser as running on a mobile device, even when, if fact, it is running on a PC. The result is that the credit card form is corrupted like on these screen shots:

- http://awesomescreenshot.com/0724kkas56
- http://awesomescreenshot.com/04f4kkaq18

'''Solution:'''

To fix the issue, you need to update the Mobile Detect library in your X-Payments installation so the list of supported user agents is relevant. For that you should replace the file
<xpayments-dir>/lib/MobileDetect.php with this one: https://drive.google.com/file/d/0B6p7sehSZL8_QUN6VmRVMHpxaFE/view?usp=sharing (should be done via SFTP, SSH, Control panel, etc.)

If you find it difficult to apply the changes yourself please contact our Tech Support team using https://secure.x-cart.com.

===Trouble with credit card logos in iFrame template for X-Cart 5===

You use X-Cart 5 integrated with X-Payments v2.x and see credit card logos displayed like [https://drive.google.com/a/x-cart.com/file/d/0B6p7sehSZL8_T1kyQ0RCNS1nWDA/view?usp=sharing this in checkout] using Mac Safari or iPad.

'''Solution'''

Replace files fast.css and xc5.css in folder <x-pay_dir>/public/templates/ with these:

https://drive.google.com/a/x-cart.com/folderview?id=0B6p7sehSZL8_OUVTeUtCUkFjY2M&usp=sharing

===My entire shop is run in an iFrame and X-Payments does not display "Pay" button===

There is a special code in X-Payments that hides "Pay" button if it the payment form is shown inside iframe.
In your case the whole store is placed inside iframe and that triggers the special code.
Easiest workaround which will not affect other stores connected to the X-Payments is to edit the template file css (I presume you use default.css) and where

<pre>
div.content div.buttonRow {
margin: 35px auto;
width: 400px;
}
</pre>

you should add

<pre>
display: block !important;
</pre>

e.g. after correction that code will look like

<pre>
div.content div.buttonRow {
margin: 35px auto;
width: 400px;
display: block !important;
}
</pre>

Do not forget to approve the changes in the admin back-end afterwards.

===X-Payments credit card form does not fit properly on Android tablet screen when used in iFrame in X-Cart 4 OPC===

X-Payments credit card form is displayed as shown on [https://drive.google.com/file/d/0B6p7sehSZL8_ZDhac2JNVWxlQ1E/view?usp=sharing this screen shot].

The reason is X-Cart 4 OPC shows desktop version of the site checkout while X-Payments shows mobile checkout template which is wider than needed for XC4 desktop OPC.

'''Solution'''

Apply [https://drive.google.com/file/d/0B6p7sehSZL8_c0JmYjhaRi1ITEE/view?usp=sharing this patch] to X-Payments connector files in your X-Cart 4.
 

===How to test payments via PayPal in X-Payments===

There is a list of credit card numbers in the PayPal guides which many people assume can be used when processing credit card transactions through PayPal. However, many of these card numbers have been blocked from PayPal system in one fashion or another (e.g. delay processing a lot so integrated software like X-Cart or Magento just fails to place a test transaction), so general advice is "don't use those card numbers".

In general, when testing credit card transactions with PayPal as the processor, it is recommended using a randomized credit card number. The number
must have a valid BIN, a valid check digit, and must be the correct length for the card type, but aside from that, the card number can be random.
You can get such random test credit card numbers at http://getcreditcardnumbers.com

==="The TxnID field is missing or incorrect" message after upgrading to a new connector version in Magento===

If after upgrading Magento connector to a new version and placing a new order you see an error message "The txnID field is missing or incorrect" instead of successful "Thank you for your order" page you need to clean/purge Magento's cache in your shop in the admin back-end. Consult with Magento user manual how to do that.

===Browser warning about wrong SSL certificate pops up===

If your browser shows a pop-up with warning about SSL certificate every time you test a transaction via X-Payments - this means your store installation has self-made/dummy SSL certificate. It is fine during testing, but you need to upgrade it to a real SSL certificate when your site goes live.
During testing just add that SSL certificate to exclusions in your browser in order not to see that warning every time you place a test transaction via X-Payments. This won't help you to hide that message from your shoppers though. The warning is not shown by a browser if a real SSL certificate is used.

==="X-Payments tried to notify the store about updates in payment but failed" notification===

You receive notifications that say "X-Payments tried to notify the store about updates in payment but failed ...".

They mean X-Payments callback requests have failed because of timeout or because your online shop site is not reachable by X-Payments.

In the 1st case the store didn't respond within 15 seconds coded by default in X-Payments, but the logs from the side of the store for these requests say, that the requests were received and processed with no errors. It means, that communication between the store and X-Payments actually works, but it takes to long for the store to respond. As a quick solution for this very reason it is recommended to increase the timeout limits in your X-Payments installation:
If X-Payments 2.x - in file lib/XPay/Model/Payment.php by changing "15" in a line of code that looks like to a bigger value (max 60):

<pre>
$requestData->setTimeout(15);
</pre>

If X-Payments 3.x - in file config/config.ini.php in section [callback] change value of wait_timeout param:

<pre>
[callback]

; Wait timeout for callback requests to the shopping cart (in seconds)
wait_timeout=15
</pre>

If you do not have access to your X-Payments installation code - contact vendors of the software by posting them a technical support ticket via https://secure.x-cart.com.

But the right solution is to figure out why your web site does not respond to X-Payments callbacks within 15 seconds.

In the 2nd case it might be firewall blocking X-Payments callback requests or your web shop was down for some time.

==="No Payment Methods Available" message shown to a customer===

A customer cannot place an order as he/she is displayed a message "No Payment Methods Available" at checkout and at the same time you see an error message "Data validation error, node "request": String length ("266342") exceeds the maximum allowed length for this node - "100000" in X-Payments error log file.

'''Reason'''

A shopper added too many line items (different products) to his/her cart ("too many" - e.g. over a thousand) and as result data passed to X-Payments exceeds amount it is configured to accept for security reasons.

'''Solution'''

1) a customer should divide his order in several with less number of line items and process them one by one.

2) if you face to this issue too often you can increase amount of data allowed to be processed by X-Payments by changing value of constant REQUEST_MAX_LENGTH in X-Payments file lib/XPay/Transport/Request/Api.php, but we do not recommend to large value there for security reasons.

===Payflow PRO currency issue===

'''NOTE''': do not confuse this with PayPal Payments PRO (PayFlow API)! There is PayFlow PRO integration, too. We are talking about PayFlow PRO here.

You need to process payments via PayFlow PRO in other currency than USD, but there is no way to change it. You configured integrated cart in e.g. CAD but X-Payments passes data to PayFlow PRO as USD. This is caused by features of PayFlow PRO API - no exact requirements about passing currency type to PayFlow PRO - sometimes it can be passed as "CUR", sometimes as "CU", etc depending on payment processor you have configured at PayFlow PRO back-end.

'''Solution'''

1) Switch to PayPal Payments Pro (Payflow API) integration instead of PayFlow PRO in X-Payments.

or

2) change code of X-Payments as follows:
in file lib/XPay/Module/PayflowPro.php find function

<pre>
private function getInitRequestBody(XPay_Transport_GatewayRequest $request)
</pre>

In the function find lines

<pre>
...
$fields = array(
'TRXTYPE' => XPay_Model_PaymentTransaction::SALE == $request->action ? 'S' : 'A',
'AMT' => $this->preparePrice($request->payment->get('total')),
'TAXAMT' => $this->preparePrice($additionalData->get('tax_cost')),
...
</pre>

and add a line of code

<pre>
'CURRENCY' => $request->payment->get('currency'),
</pre>

to get something like

<pre>
'TRXTYPE' => XPay_Model_PaymentTransaction::SALE == $request->action ? 'S' : 'A',
'CURRENCY' => $request->payment->get('currency'),
'AMT' => $this->preparePrice($request->payment->get('total')),
'TAXAMT' => $this->preparePrice($additionalData->get('tax_cost')),
</pre>

The above tweak will work if "PayPal" is configured as the gateway in your PayFlow PRO account.

For others you should directly specify currency in format required by payment gateway.

E.g.
<pre>
'CURRENCY' => 'USD',
</pre>

===X-Cart 5 and Exception message: Shopping cart server returned wrong HTTP headers for callback.===

You use X-Cart 5 and see below error message or error log entry at X-Cart 5 side:

<pre>
Failed to send "check_cart" callback to the store "mydomain.com"
Url: https://www.example.com/cart.php?target=callback&action=callback&xpcBackReference=ABCDEFGHIJKL
Exception message: Shopping cart server returned wrong HTTP headers for callback.
</pre>

'''Solution''':

Most likely you try to test X-Payments with X-Cart 5 storefront closed. If so, in X-Cart 5 file etc/config.php find below piece of code:

<pre>
[storefront_options]
; Do not close target=callback for payments if storefront is closed
callback_opened = Off
</pre>

and change "Off" to "On" there.

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

[[Category:X-Payments User Manual]]

X-Payments:Troubleshooting

2016-05-05T12:49:22Z

Alex “Ambal” Mulin: /* "X-Payments tried to notify the store about updates in payment but failed" notification */

<noinclude>{{Template:XP manual TOC}}</noinclude>
==Troubleshooting==

===X-Payments 1.x installation process fails on a Windows server===
If X-Payments 1.x installation fails on a Windows server, try replacing the following line from install.php:
<pre>define('XP_DIR', rtrim(realpath(dirname(__FILE__)), XP_DS) . XP_DS);</pre>
with this line:
<pre>define('XP_DIR', rtrim(dirname(__FILE__), XP_DS) . XP_DS);</pre>

===Warning: require_once(/home/user/public_html/xpayments/lib/PDO.php)===

I am trying to install the X-Payments module but receive the following error on step 2 of the installation process:

Warning: require_once(/home/user/public_html/xpayments/lib/PDO.php) [function.require-once]: failed to open stream: No such file or directory in /home/user/public_html/xpayments/top.inc.PHP53.php on line 84

Fatal error: require_once() [function.require]: Failed opening required '/home/user/public_html/xpayments/lib/PDO.php' (include_path='.:/usr/lib/php:/usr/local/lib/php') in /home/user/public_html/xpayments/top.inc.PHP53.php on line 84

Solution:

It looks like the problem is related to the current PHP configuration on your server.

PHP is currently compiled with the necessary extensions:

'--enable-pdo=shared'
'--with-pdo-mysql=shared'
'--with-pdo-sqlite=shared'

However, X-Payments requires a bit different type of PHP configuration. PDO extension, as well as the MySQL PDO driver, needs to be installed as a shared module. In other words your php.ini file needs to be updated so that the PDO extensions will be loaded automatically when PHP runs:

extension=php_pdo.so
extension=php_pdo_mysql.so

See also:
* http://php.net/manual/en/pdo.installation.php

Please share this info with your server administrator and ask them to make the necessary changes in your PHP configuration.

===cron.php: X-Payments is using a non-secure protocol error===

I have tried everything to get the x payments cron.php working, but it is not working and we are getting this error:

ERROR [2012-25-06 12:23:01]
User: unknown; IP: unknown
Zone: Core
Code: NONSECURE_PROTOCOL (237)
X-Payments is using a non-secure protocol

Affected systems: Core/Defender.php file (60:assert); Application.php file (133:check); /home/user/public_html/xpayments/cron.php file (26:run)

Solution:

Wrong PHP binary is used to run cron.php script. You need to run cron.php using so called "CLI" version of PHP. Ask your hosting administrator to tell where PHP CLI is located on your server and configure cron to run cron.php script using PHP CLI version.

===Duplicate charges===

X-Payments v1.0.5 may have this issue under certain circumstances (iFrame checkout option aka "Lite interface" is enabled). Reason is that customers don't see an obvious sign that their payment is being processed after they entered their details and clicked "Submit" button so they click once again. This may create duplicate charges with some payment processors supported by X-Payments.

Solution:

Apply below patches to

1) front-end templates of your X-Payments:

[[File:Xp.105.diff]]

2) X-Cart connector:

[[File:Xc.454.diff]]

See how to apply patches at [http://help.x-cart.com/index.php?title=X-Cart:To_apply_a_patch_manually X-Cart:To apply a patch manually]

Note:
You do not need to apply the above patches if your X-Payments version is not v1.0.5 and if you do not use iFrame checkout provided by X-Payments.

===Empty or 404 page at Magento admin back-end===

If you see empty or 404 page at System -> Configuration -> X-Payments connector after installation do the following:

1) Clear cache:
System -> Cache Management

2) Logout and login admin area again

3) Then go to System -> Permissions -> Roles and click on "Administrators", then in a popup/new window click "Save Role".
That's it.

===My store background image does not carry over to X-Payments checkout area template===

'''Solution:'''

Make sure if the background image parameter in your X-Payments checkout skin is set as direct URL to your store image.

X-Payments checkout skin CSS file includes the following class used to display the header of integrated store pages:

#header .line1 .logo {
background: url("../../skin/artistictunes_car_tires/css/../images/custom/top_image1.jpg") no-repeat scroll left top #000000;
height: 240px;
margin-left: 0;
padding-top: 0;
position: relative;
width: auto;
}

For example, one of the possible solutions - modify the code of the generated CSS file, and change the default background image URL:

"../../skin/artistictunes_car_tires/css/../images/custom/top_image1.jpg"

to e.g. this one:

"https://yourshopdomain.com/xcart/skin/artistictunes_car_tires/images/custom/top_image1.jpg"

===X-Payments error (code: 843): Unallowed target===

This type of error may appear in X-Cart versions prior to 4.5.0.
You see below error message and X-Payments log file entry when using "Test connection" and "Request payment methods" buttons:

Error message:

<source>
- X-Payments error (code: 843): Unallowed target - ""
</source>

X-Payments log file entry:

<source>
-----------------------------------
ERROR [2013-11-05 00:11:49]
User: shopping cart (%%%%%%%%%%%); IP: %%%%%%%%%%%%
Zone: Model
Code: TARGET_UNALLOWED (843)
Unallowed target - ""
-----------------------------------
</source>

Solution:

Check if you have correct charset code specified in "Charset" field on X-Cart admin back-end -> Content -> Languages -> Your store language page.
See how to manage languages in X-Cart [[http://help.x-cart.com/index.php?title=X-Cart:Managing_Languages | here]].

===Sage Pay - Reason: 4020 : Information received from an Invalid IP address===

This is caused by a wrong IP for callbacks set in your Sage Pay account.

If you are using X-Payments Hosted plan (Basic, PRO or Multistore) you need to add the IP address of 98.142.211.162 in your SagePay merchant backend on the Settings -> Valid IPs page.

If you are using a downloadable X-Payments license - you need to enter IP address of the server where your X-Payments copy is deployed. See [[X-Payments:How_It_Works#Callback_from_X-Payments_to_the_store | this article]] to understand X-Payments callbacks.

===No credit card form displayed when a customer pays===

====Error message at checkout instead of credit card form====

You've made a change in credit card form template at X-Payments side and now your checkout doesn't work?

This is the most probable situation with such type of errors during checkout via X-Payments. You've made a change in X-Payments credit card form and forgot to approve it at X-Payments admin back-end. As result X-Payments cannot process credit cards as it sees some changes in templates, but they are not approved by you, i.e. the admin user. Such approval process is implemented in X-Payments for security reasons. See also [[X-Payments:User_manual#Customizing_the_Interface]]

'''Solution:'''

Go into admin back-end dashboard and '''log in as the main admin user''' and check if it displays a warning about "Payment interface files have been modified" like below
[[File:Warning_customer_interface_changed.png]]

If yes, '''click "Approve" link''' in the warning text and everything is set now.

====No payment methods are displayed in the X-Payments connector settings====

So you deployed the configuration bundle copied from the X-Payments dashboard but do not see any payment methods in X-Cart on the X-Payments connector settings page. 
Your checkout via X-Payments does not work either.

'''Solution:'''
Make sure the online store is enabled in the X-Payments Admin back end and has at least one payment method enabled for it.

[[File:Xp_admin_backend.png|border|668px|]]

====CyberSource Internal Error====

Do you use CyberSource and get "Internal Error" on the checkout page along with below error within the X-Payments error log?

<source>

ERROR [2012-13-12 17:27:17]
User: unknown; IP: 68.184.224.121
Zone: Transport
Code: FILE_NOT_ACCESSIBLE (109)
File "Path/to/the/cybersource/security/key/txt/file" does not exist or is not readable

</source>

Solution:

Make sure you specified the right **server** path to the Cybersource key file on the [[X-Payments:CyberSourceSOAP | "CyberSource SOAP toolkit API" configuration page]], and it is readable by HTTP daemon on your X-Payments server.

====You use Hosted X-Payments plans and run out of bandwidth====

Congratulations! Your amount of transactions is impressive indeed! Most likely you used all bandwidth we provide for X-Payments Hosted accounts.

'''Solution''':

Please contact us using your HelpDesk account regarding the issue and we will consult you how to increase your bandwidth. Also, you should consider either upgrading to larger X-Payments Hosted plan or using X-Payments downloadable license that you can host yourself.

====You use Hosted X-Payments plans and run out of disk space====

One more reason for Hosted X-Payments plans can be you've run out of disk space we provide with every plan - check X-Payments folder at your X-Payments Hosted account (see [[X-Payments:X-Payments-Hosted-FAQ]]).

'''Solution:'''

Download logs files from your X-Payments Hosted account (see [[X-Payments:FAQ#Where_can_I_find_X-Payments_logs.3F]]) and remove them at X-Payments server to clear up some space.

====Your integrated shopping cart does not pass all customer profile fields to X-Payments correctly====

E.g. in X-Cart you can configure some vital for X-Payments customer profile fields (e.g. zipcode, address, email) as optional and your customers can miss them and do not fill in them with data during checkout. Thus X-Cart passes empty values for those data fields and X-Payments fails to process a transaction. X-Payments connector usually shows below warning

[[File:Warning_profile_fields_XP_connector.png]]

'''Solution:'''

Either make such customer profile fields mandatory for checkout in your cart or customize your cart connector for X-Payments to pass non-empty values if they should not be mandatory for your checkout routine and customers can leave such profile fields empty.

====PayPal PRO integration does not work in X-Cart 4.x====

You followed [http://help.x-cart.com/index.php?title=X-Cart:Adding_and_enabling_PayPal_payment_methods_in_X-Cart Adding and enabling PayPal payment methods in X-Cart] and [[X-Payments:Configuring_PayPal_payment_modules_in_X-Payments]], made sure all configuration settings are set correctly, but PayPal PRO still does not work for you and you see "Internal error" message when you use X-Payments in iFrame mode or see "Internal error (The merchantEmail is missing or incorrect)" error message when X-Payments is configured as a separate page in your X-Cart checkout routine.

'''Solution:'''

PayPal module in X-Cart v4.x refers to "orders department email address" at General settings/Company options/Company emails section. You need to have a valid email address in that setting to fix the issue.

====X-Cart isn't Synchronizing PayPal Payments PRO payment methods from X-Payments====

Trying to update payment processor on the back end of the store in the X-Payments Connector. In the backend of the X-Payments Admin, there is a new payment method enabled- PayPal Payments Pro. Virtual Merchant will no longer be used. See screenshot in the attachment.

On the backend of the site, once I try to Synchronize Payment Methods, the screen quickly shows options available to sync the new payment method. I have options to "set orders for..." then the options quickly disappear. There is a screenshot attached.

So with that, once I try to synchronize, the system won't allow me. The old payment method still remains (although it hasn't been deleted in the X-Payment Admin Backend) but the new method SHOULD appear once they are synchronized, showing TWO payment methods on the backend of the store, with the option for me to enable either one.

'''Solution:'''

X-Cart 4 have some restrictions of PayPal usage, so that you need to first add PayPal Pro methods inside X-Cart and configure them using the same credentials like in X-Payments. Re-sync methods after that and you'll see the PayPal.

====There are connection problems between your shopping cart and X-Payments at the time when a customer pays====

Your cart cannot connect to X-Payments some times and your customers see "Internal error" displayed.

'''Solution:'''

Make sure your cart server can connect to X-Payments server at all times (especially during your site high load times of a day).

==="Callback to online store is failed" notification and now all credit card transactions are failing===

You receive below notifications from X-Payments

<source>
"Callback to online store is failed. This notification has been sent by X-Payments installation at 'www.mysite.com'"
</source>

and now all credit card transactions are failing and the credit card fields for secure checkout on your website are missing.

'''Solution:'''

Most likely you regenerated [[X-Payments:Encryption_keys | encryption codes in X-Payments]] but neglected to update the information in X-Cart, hence the credit card fields are not loading when the customer is attempting to use a credit card for payment.

To remedy this go into X-Payments, 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 [http://help.x-cart.com/index.php?title=X-Cart:X-Payments_Connector#Configuring_X-Payments_Connector Configuring X-Payments Connector]).

===Fatal error: Access to undeclared static property: XPay_Model_Base_Module::$this===

You started to see error messages like below instead of working X-Payments.

<source>
Fatal error: Access to undeclared static property: XPay_Model_Base_Module::$this in /xxxxxxxxxxx/lib/XPay/Model/Base/Module.php on line 153
or
Fatal error: Access to undeclared static property: XPay_Model_Base_Module::$this in /xxxxxxxxxxx/lib/XPay/Model/Base/Module.php on line 131
</source>

'''Solution:'''

It is due to updating PHP to v 5.4.

To fix the problem, in lines 131 and 153 of

<xpayments_dir>/lib/XPay/Model/Base/Module.php

change

<source>
self::$this->
</source>

to

<source>
$this->
</source>

===My X-Payments doesn't store customers credit cards/X-Payments subscriptions module doesn't work===

So "Store credit card" functionality or X-Payments Subscriptions module doesn't work in your shopping cart despite of you integrated it with X-Payments?

'''Solution:'''

# Make sure you use X-Payments v2.x because X-Payments v1.x doesn't support this functionality.
# Make sure you use a payment gateway that supports so called "tokenization" in X-Payments v2.x - see the list of such payment gateways at [[X-Payments:Supported_payment_gateways]]. They have "+" in "Tokenization" column. "-" means tokenization is not supported for a payment gateway.
# So you do use X-Payments v2.x and a payment gateway that supports tokenization in X-Payments? Please make sure tokenization functionality is enabled for your payment gateway account at payment gateway side. Sometimes payment gateways call it differently, e.g. "vault", "Transformer", etc. If you are not sure - contact your payment gateway to enable tokenization for your payment gateway.

===Customer CC expires in 2022 - X-Payments stops at 2020===

We just had a customer call in. He could not check out because our X-Payments payment page would not allow him to enter the expiration year of 2022 for his credit card. Our X-Payments only goes up to 2020.

'''Solution:'''

You need to change YEAR_RANGE from 7 to 10 for example in file lib/XPay/View/Payment/Main.php

// Years list range

const YEAR_RANGE = 7

===White screen or HTTP 500 Internal server error instead of admin dashboard===

You see white screen after logging in X-Payments admin dashboard.

'''Solution:'''

Some PHP packages contain a bug that causes "White screen" or HTTP 500 Internal server error when PHP operates with the database via PDO. If you experience such issue contact your hosting support referring to:

https://bugs.php.net/bug.php?id=60825
https://bugs.php.net/bug.php?id=53716

===Magento: cannot test module connection or payment methods cannot be imported===

You copied all configuration data from X-Payments properly but in Magento admin you see below message when you click "Test module" button
Test transaction failed. Please check the X-Payment Connector settings and try again. If all options is ok review your X-Payments settings and make sure you have properly defined shopping cart properties.

Or a message that payment methods cannot be imported when you click "Request payment methods" button.

'''Solution:'''

Possible reason - you do not have a valid SSL certificate installed for your X-Payments. Self-signed SSL cannot pass libCurl validation and thus prevent connection between Magento and X-Payments, too. You need to install a valid SSL certificate at X-Payments server.

'''NOTE:''' users of our hosted X-Payments plans are safe since we provide SSL by default.

===Google Chrome v41.0.2272.76 detects X-Payments v2.1 credit card form as a mobile site on desktops===

After the update of the Google Chrome web browser to version 41.0.2272.76, the credit card form provided to your site by X-Payments v2.1 may be displayed incorrectly for Google Chrome users.
The problem behind this is that the value of the user-agent header sent by Chrome has changed, which causes X-Payments to identify the browser as running on a mobile device, even when, if fact, it is running on a PC. The result is that the credit card form is corrupted like on these screen shots:

- http://awesomescreenshot.com/0724kkas56
- http://awesomescreenshot.com/04f4kkaq18

'''Solution:'''

To fix the issue, you need to update the Mobile Detect library in your X-Payments installation so the list of supported user agents is relevant. For that you should replace the file
<xpayments-dir>/lib/MobileDetect.php with this one: https://drive.google.com/file/d/0B6p7sehSZL8_QUN6VmRVMHpxaFE/view?usp=sharing (should be done via SFTP, SSH, Control panel, etc.)

If you find it difficult to apply the changes yourself please contact our Tech Support team using https://secure.x-cart.com.

===Trouble with credit card logos in iFrame template for X-Cart 5===

You use X-Cart 5 integrated with X-Payments v2.x and see credit card logos displayed like [https://drive.google.com/a/x-cart.com/file/d/0B6p7sehSZL8_T1kyQ0RCNS1nWDA/view?usp=sharing this in checkout] using Mac Safari or iPad.

'''Solution'''

Replace files fast.css and xc5.css in folder <x-pay_dir>/public/templates/ with these:

https://drive.google.com/a/x-cart.com/folderview?id=0B6p7sehSZL8_OUVTeUtCUkFjY2M&usp=sharing

===My entire shop is run in an iFrame and X-Payments does not display "Pay" button===

There is a special code in X-Payments that hides "Pay" button if it the payment form is shown inside iframe.
In your case the whole store is placed inside iframe and that triggers the special code.
Easiest workaround which will not affect other stores connected to the X-Payments is to edit the template file css (I presume you use default.css) and where

<pre>
div.content div.buttonRow {
margin: 35px auto;
width: 400px;
}
</pre>

you should add

<pre>
display: block !important;
</pre>

e.g. after correction that code will look like

<pre>
div.content div.buttonRow {
margin: 35px auto;
width: 400px;
display: block !important;
}
</pre>

Do not forget to approve the changes in the admin back-end afterwards.

===X-Payments credit card form does not fit properly on Android tablet screen when used in iFrame in X-Cart 4 OPC===

X-Payments credit card form is displayed as shown on [https://drive.google.com/file/d/0B6p7sehSZL8_ZDhac2JNVWxlQ1E/view?usp=sharing this screen shot].

The reason is X-Cart 4 OPC shows desktop version of the site checkout while X-Payments shows mobile checkout template which is wider than needed for XC4 desktop OPC.

'''Solution'''

Apply [https://drive.google.com/file/d/0B6p7sehSZL8_c0JmYjhaRi1ITEE/view?usp=sharing this patch] to X-Payments connector files in your X-Cart 4.
 

===How to test payments via PayPal in X-Payments===

There is a list of credit card numbers in the PayPal guides which many people assume can be used when processing credit card transactions through PayPal. However, many of these card numbers have been blocked from PayPal system in one fashion or another (e.g. delay processing a lot so integrated software like X-Cart or Magento just fails to place a test transaction), so general advice is "don't use those card numbers".

In general, when testing credit card transactions with PayPal as the processor, it is recommended using a randomized credit card number. The number
must have a valid BIN, a valid check digit, and must be the correct length for the card type, but aside from that, the card number can be random.
You can get such random test credit card numbers at http://getcreditcardnumbers.com

==="The TxnID field is missing or incorrect" message after upgrading to a new connector version in Magento===

If after upgrading Magento connector to a new version and placing a new order you see an error message "The txnID field is missing or incorrect" instead of successful "Thank you for your order" page you need to clean/purge Magento's cache in your shop in the admin back-end. Consult with Magento user manual how to do that.

===Browser warning about wrong SSL certificate pops up===

If your browser shows a pop-up with warning about SSL certificate every time you test a transaction via X-Payments - this means your store installation has self-made/dummy SSL certificate. It is fine during testing, but you need to upgrade it to a real SSL certificate when your site goes live.
During testing just add that SSL certificate to exclusions in your browser in order not to see that warning every time you place a test transaction via X-Payments. This won't help you to hide that message from your shoppers though. The warning is not shown by a browser if a real SSL certificate is used.

==="X-Payments tried to notify the store about updates in payment but failed" notification===

You receive notifications that say "X-Payments tried to notify the store about updates in payment but failed ...".

They mean X-Payments callback requests have failed because of timeout or because your online shop site is not reachable by X-Payments.

In the 1st case the store didn't respond within 15 seconds coded by default in X-Payments, but the logs from the side of the store for these requests say, that the requests were received and processed with no errors. It means, that communication between the store and X-Payments actually works, but it takes to long for the store to respond. As a quick solution for this very reason it is recommended to increase the timeout limits in your X-Payments installation:
If X-Payments 2.x - in file lib/XPay/Model/Payment.php by changing "15" in a line of code that looks like to a bigger value (max 60):
<code>
$requestData->setTimeout(15);
</code>

If X-Payments 3.x - in file config/config.ini.php in section [callback] change value of wait_timeout param:
<code>
[callback]

; Wait timeout for callback requests to the shopping cart (in seconds)
wait_timeout=15
</code>

If you do not have access to your X-Payments installation code - contact vendors of the software by posting them a technical support ticket via https://secure.x-cart.com.

But the right solution is to figure out why your web site does not respond to X-Payments callbacks within 15 seconds.

In the 2nd case it might be firewall blocking X-Payments callback requests or your web shop was down for some time.

==="No Payment Methods Available" message shown to a customer===

A customer cannot place an order as he/she is displayed a message "No Payment Methods Available" at checkout and at the same time you see an error message "Data validation error, node "request": String length ("266342") exceeds the maximum allowed length for this node - "100000" in X-Payments error log file.

'''Reason'''

A shopper added too many line items (different products) to his/her cart ("too many" - e.g. over a thousand) and as result data passed to X-Payments exceeds amount it is configured to accept for security reasons.

'''Solution'''

1) a customer should divide his order in several with less number of line items and process them one by one.

2) if you face to this issue too often you can increase amount of data allowed to be processed by X-Payments by changing value of constant REQUEST_MAX_LENGTH in X-Payments file lib/XPay/Transport/Request/Api.php, but we do not recommend to large value there for security reasons.

===Payflow PRO currency issue===

'''NOTE''': do not confuse this with PayPal Payments PRO (PayFlow API)! There is PayFlow PRO integration, too. We are talking about PayFlow PRO here.

You need to process payments via PayFlow PRO in other currency than USD, but there is no way to change it. You configured integrated cart in e.g. CAD but X-Payments passes data to PayFlow PRO as USD. This is caused by features of PayFlow PRO API - no exact requirements about passing currency type to PayFlow PRO - sometimes it can be passed as "CUR", sometimes as "CU", etc depending on payment processor you have configured at PayFlow PRO back-end.

'''Solution'''

1) Switch to PayPal Payments Pro (Payflow API) integration instead of PayFlow PRO in X-Payments.

or

2) change code of X-Payments as follows:
in file lib/XPay/Module/PayflowPro.php find function

<pre>
private function getInitRequestBody(XPay_Transport_GatewayRequest $request)
</pre>

In the function find lines

<pre>
...
$fields = array(
'TRXTYPE' => XPay_Model_PaymentTransaction::SALE == $request->action ? 'S' : 'A',
'AMT' => $this->preparePrice($request->payment->get('total')),
'TAXAMT' => $this->preparePrice($additionalData->get('tax_cost')),
...
</pre>

and add a line of code

<pre>
'CURRENCY' => $request->payment->get('currency'),
</pre>

to get something like

<pre>
'TRXTYPE' => XPay_Model_PaymentTransaction::SALE == $request->action ? 'S' : 'A',
'CURRENCY' => $request->payment->get('currency'),
'AMT' => $this->preparePrice($request->payment->get('total')),
'TAXAMT' => $this->preparePrice($additionalData->get('tax_cost')),
</pre>

The above tweak will work if "PayPal" is configured as the gateway in your PayFlow PRO account.

For others you should directly specify currency in format required by payment gateway.

E.g.
<pre>
'CURRENCY' => 'USD',
</pre>

===X-Cart 5 and Exception message: Shopping cart server returned wrong HTTP headers for callback.===

You use X-Cart 5 and see below error message or error log entry at X-Cart 5 side:

<pre>
Failed to send "check_cart" callback to the store "mydomain.com"
Url: https://www.example.com/cart.php?target=callback&action=callback&xpcBackReference=ABCDEFGHIJKL
Exception message: Shopping cart server returned wrong HTTP headers for callback.
</pre>

'''Solution''':

Most likely you try to test X-Payments with X-Cart 5 storefront closed. If so, in X-Cart 5 file etc/config.php find below piece of code:

<pre>
[storefront_options]
; Do not close target=callback for payments if storefront is closed
callback_opened = Off
</pre>

and change "Off" to "On" there.

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

[[Category:X-Payments User Manual]]

X-Payments:Troubleshooting

2016-05-05T12:48:56Z

Alex “Ambal” Mulin: /* "X-Payments tried to notify the store about updates in payment but failed" notification */

<noinclude>{{Template:XP manual TOC}}</noinclude>
==Troubleshooting==

===X-Payments 1.x installation process fails on a Windows server===
If X-Payments 1.x installation fails on a Windows server, try replacing the following line from install.php:
<pre>define('XP_DIR', rtrim(realpath(dirname(__FILE__)), XP_DS) . XP_DS);</pre>
with this line:
<pre>define('XP_DIR', rtrim(dirname(__FILE__), XP_DS) . XP_DS);</pre>

===Warning: require_once(/home/user/public_html/xpayments/lib/PDO.php)===

I am trying to install the X-Payments module but receive the following error on step 2 of the installation process:

Warning: require_once(/home/user/public_html/xpayments/lib/PDO.php) [function.require-once]: failed to open stream: No such file or directory in /home/user/public_html/xpayments/top.inc.PHP53.php on line 84

Fatal error: require_once() [function.require]: Failed opening required '/home/user/public_html/xpayments/lib/PDO.php' (include_path='.:/usr/lib/php:/usr/local/lib/php') in /home/user/public_html/xpayments/top.inc.PHP53.php on line 84

Solution:

It looks like the problem is related to the current PHP configuration on your server.

PHP is currently compiled with the necessary extensions:

'--enable-pdo=shared'
'--with-pdo-mysql=shared'
'--with-pdo-sqlite=shared'

However, X-Payments requires a bit different type of PHP configuration. PDO extension, as well as the MySQL PDO driver, needs to be installed as a shared module. In other words your php.ini file needs to be updated so that the PDO extensions will be loaded automatically when PHP runs:

extension=php_pdo.so
extension=php_pdo_mysql.so

See also:
* http://php.net/manual/en/pdo.installation.php

Please share this info with your server administrator and ask them to make the necessary changes in your PHP configuration.

===cron.php: X-Payments is using a non-secure protocol error===

I have tried everything to get the x payments cron.php working, but it is not working and we are getting this error:

ERROR [2012-25-06 12:23:01]
User: unknown; IP: unknown
Zone: Core
Code: NONSECURE_PROTOCOL (237)
X-Payments is using a non-secure protocol

Affected systems: Core/Defender.php file (60:assert); Application.php file (133:check); /home/user/public_html/xpayments/cron.php file (26:run)

Solution:

Wrong PHP binary is used to run cron.php script. You need to run cron.php using so called "CLI" version of PHP. Ask your hosting administrator to tell where PHP CLI is located on your server and configure cron to run cron.php script using PHP CLI version.

===Duplicate charges===

X-Payments v1.0.5 may have this issue under certain circumstances (iFrame checkout option aka "Lite interface" is enabled). Reason is that customers don't see an obvious sign that their payment is being processed after they entered their details and clicked "Submit" button so they click once again. This may create duplicate charges with some payment processors supported by X-Payments.

Solution:

Apply below patches to

1) front-end templates of your X-Payments:

[[File:Xp.105.diff]]

2) X-Cart connector:

[[File:Xc.454.diff]]

See how to apply patches at [http://help.x-cart.com/index.php?title=X-Cart:To_apply_a_patch_manually X-Cart:To apply a patch manually]

Note:
You do not need to apply the above patches if your X-Payments version is not v1.0.5 and if you do not use iFrame checkout provided by X-Payments.

===Empty or 404 page at Magento admin back-end===

If you see empty or 404 page at System -> Configuration -> X-Payments connector after installation do the following:

1) Clear cache:
System -> Cache Management

2) Logout and login admin area again

3) Then go to System -> Permissions -> Roles and click on "Administrators", then in a popup/new window click "Save Role".
That's it.

===My store background image does not carry over to X-Payments checkout area template===

'''Solution:'''

Make sure if the background image parameter in your X-Payments checkout skin is set as direct URL to your store image.

X-Payments checkout skin CSS file includes the following class used to display the header of integrated store pages:

#header .line1 .logo {
background: url("../../skin/artistictunes_car_tires/css/../images/custom/top_image1.jpg") no-repeat scroll left top #000000;
height: 240px;
margin-left: 0;
padding-top: 0;
position: relative;
width: auto;
}

For example, one of the possible solutions - modify the code of the generated CSS file, and change the default background image URL:

"../../skin/artistictunes_car_tires/css/../images/custom/top_image1.jpg"

to e.g. this one:

"https://yourshopdomain.com/xcart/skin/artistictunes_car_tires/images/custom/top_image1.jpg"

===X-Payments error (code: 843): Unallowed target===

This type of error may appear in X-Cart versions prior to 4.5.0.
You see below error message and X-Payments log file entry when using "Test connection" and "Request payment methods" buttons:

Error message:

<source>
- X-Payments error (code: 843): Unallowed target - ""
</source>

X-Payments log file entry:

<source>
-----------------------------------
ERROR [2013-11-05 00:11:49]
User: shopping cart (%%%%%%%%%%%); IP: %%%%%%%%%%%%
Zone: Model
Code: TARGET_UNALLOWED (843)
Unallowed target - ""
-----------------------------------
</source>

Solution:

Check if you have correct charset code specified in "Charset" field on X-Cart admin back-end -> Content -> Languages -> Your store language page.
See how to manage languages in X-Cart [[http://help.x-cart.com/index.php?title=X-Cart:Managing_Languages | here]].

===Sage Pay - Reason: 4020 : Information received from an Invalid IP address===

This is caused by a wrong IP for callbacks set in your Sage Pay account.

If you are using X-Payments Hosted plan (Basic, PRO or Multistore) you need to add the IP address of 98.142.211.162 in your SagePay merchant backend on the Settings -> Valid IPs page.

If you are using a downloadable X-Payments license - you need to enter IP address of the server where your X-Payments copy is deployed. See [[X-Payments:How_It_Works#Callback_from_X-Payments_to_the_store | this article]] to understand X-Payments callbacks.

===No credit card form displayed when a customer pays===

====Error message at checkout instead of credit card form====

You've made a change in credit card form template at X-Payments side and now your checkout doesn't work?

This is the most probable situation with such type of errors during checkout via X-Payments. You've made a change in X-Payments credit card form and forgot to approve it at X-Payments admin back-end. As result X-Payments cannot process credit cards as it sees some changes in templates, but they are not approved by you, i.e. the admin user. Such approval process is implemented in X-Payments for security reasons. See also [[X-Payments:User_manual#Customizing_the_Interface]]

'''Solution:'''

Go into admin back-end dashboard and '''log in as the main admin user''' and check if it displays a warning about "Payment interface files have been modified" like below
[[File:Warning_customer_interface_changed.png]]

If yes, '''click "Approve" link''' in the warning text and everything is set now.

====No payment methods are displayed in the X-Payments connector settings====

So you deployed the configuration bundle copied from the X-Payments dashboard but do not see any payment methods in X-Cart on the X-Payments connector settings page. 
Your checkout via X-Payments does not work either.

'''Solution:'''
Make sure the online store is enabled in the X-Payments Admin back end and has at least one payment method enabled for it.

[[File:Xp_admin_backend.png|border|668px|]]

====CyberSource Internal Error====

Do you use CyberSource and get "Internal Error" on the checkout page along with below error within the X-Payments error log?

<source>

ERROR [2012-13-12 17:27:17]
User: unknown; IP: 68.184.224.121
Zone: Transport
Code: FILE_NOT_ACCESSIBLE (109)
File "Path/to/the/cybersource/security/key/txt/file" does not exist or is not readable

</source>

Solution:

Make sure you specified the right **server** path to the Cybersource key file on the [[X-Payments:CyberSourceSOAP | "CyberSource SOAP toolkit API" configuration page]], and it is readable by HTTP daemon on your X-Payments server.

====You use Hosted X-Payments plans and run out of bandwidth====

Congratulations! Your amount of transactions is impressive indeed! Most likely you used all bandwidth we provide for X-Payments Hosted accounts.

'''Solution''':

Please contact us using your HelpDesk account regarding the issue and we will consult you how to increase your bandwidth. Also, you should consider either upgrading to larger X-Payments Hosted plan or using X-Payments downloadable license that you can host yourself.

====You use Hosted X-Payments plans and run out of disk space====

One more reason for Hosted X-Payments plans can be you've run out of disk space we provide with every plan - check X-Payments folder at your X-Payments Hosted account (see [[X-Payments:X-Payments-Hosted-FAQ]]).

'''Solution:'''

Download logs files from your X-Payments Hosted account (see [[X-Payments:FAQ#Where_can_I_find_X-Payments_logs.3F]]) and remove them at X-Payments server to clear up some space.

====Your integrated shopping cart does not pass all customer profile fields to X-Payments correctly====

E.g. in X-Cart you can configure some vital for X-Payments customer profile fields (e.g. zipcode, address, email) as optional and your customers can miss them and do not fill in them with data during checkout. Thus X-Cart passes empty values for those data fields and X-Payments fails to process a transaction. X-Payments connector usually shows below warning

[[File:Warning_profile_fields_XP_connector.png]]

'''Solution:'''

Either make such customer profile fields mandatory for checkout in your cart or customize your cart connector for X-Payments to pass non-empty values if they should not be mandatory for your checkout routine and customers can leave such profile fields empty.

====PayPal PRO integration does not work in X-Cart 4.x====

You followed [http://help.x-cart.com/index.php?title=X-Cart:Adding_and_enabling_PayPal_payment_methods_in_X-Cart Adding and enabling PayPal payment methods in X-Cart] and [[X-Payments:Configuring_PayPal_payment_modules_in_X-Payments]], made sure all configuration settings are set correctly, but PayPal PRO still does not work for you and you see "Internal error" message when you use X-Payments in iFrame mode or see "Internal error (The merchantEmail is missing or incorrect)" error message when X-Payments is configured as a separate page in your X-Cart checkout routine.

'''Solution:'''

PayPal module in X-Cart v4.x refers to "orders department email address" at General settings/Company options/Company emails section. You need to have a valid email address in that setting to fix the issue.

====X-Cart isn't Synchronizing PayPal Payments PRO payment methods from X-Payments====

Trying to update payment processor on the back end of the store in the X-Payments Connector. In the backend of the X-Payments Admin, there is a new payment method enabled- PayPal Payments Pro. Virtual Merchant will no longer be used. See screenshot in the attachment.

On the backend of the site, once I try to Synchronize Payment Methods, the screen quickly shows options available to sync the new payment method. I have options to "set orders for..." then the options quickly disappear. There is a screenshot attached.

So with that, once I try to synchronize, the system won't allow me. The old payment method still remains (although it hasn't been deleted in the X-Payment Admin Backend) but the new method SHOULD appear once they are synchronized, showing TWO payment methods on the backend of the store, with the option for me to enable either one.

'''Solution:'''

X-Cart 4 have some restrictions of PayPal usage, so that you need to first add PayPal Pro methods inside X-Cart and configure them using the same credentials like in X-Payments. Re-sync methods after that and you'll see the PayPal.

====There are connection problems between your shopping cart and X-Payments at the time when a customer pays====

Your cart cannot connect to X-Payments some times and your customers see "Internal error" displayed.

'''Solution:'''

Make sure your cart server can connect to X-Payments server at all times (especially during your site high load times of a day).

==="Callback to online store is failed" notification and now all credit card transactions are failing===

You receive below notifications from X-Payments

<source>
"Callback to online store is failed. This notification has been sent by X-Payments installation at 'www.mysite.com'"
</source>

and now all credit card transactions are failing and the credit card fields for secure checkout on your website are missing.

'''Solution:'''

Most likely you regenerated [[X-Payments:Encryption_keys | encryption codes in X-Payments]] but neglected to update the information in X-Cart, hence the credit card fields are not loading when the customer is attempting to use a credit card for payment.

To remedy this go into X-Payments, 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 [http://help.x-cart.com/index.php?title=X-Cart:X-Payments_Connector#Configuring_X-Payments_Connector Configuring X-Payments Connector]).

===Fatal error: Access to undeclared static property: XPay_Model_Base_Module::$this===

You started to see error messages like below instead of working X-Payments.

<source>
Fatal error: Access to undeclared static property: XPay_Model_Base_Module::$this in /xxxxxxxxxxx/lib/XPay/Model/Base/Module.php on line 153
or
Fatal error: Access to undeclared static property: XPay_Model_Base_Module::$this in /xxxxxxxxxxx/lib/XPay/Model/Base/Module.php on line 131
</source>

'''Solution:'''

It is due to updating PHP to v 5.4.

To fix the problem, in lines 131 and 153 of

<xpayments_dir>/lib/XPay/Model/Base/Module.php

change

<source>
self::$this->
</source>

to

<source>
$this->
</source>

===My X-Payments doesn't store customers credit cards/X-Payments subscriptions module doesn't work===

So "Store credit card" functionality or X-Payments Subscriptions module doesn't work in your shopping cart despite of you integrated it with X-Payments?

'''Solution:'''

# Make sure you use X-Payments v2.x because X-Payments v1.x doesn't support this functionality.
# Make sure you use a payment gateway that supports so called "tokenization" in X-Payments v2.x - see the list of such payment gateways at [[X-Payments:Supported_payment_gateways]]. They have "+" in "Tokenization" column. "-" means tokenization is not supported for a payment gateway.
# So you do use X-Payments v2.x and a payment gateway that supports tokenization in X-Payments? Please make sure tokenization functionality is enabled for your payment gateway account at payment gateway side. Sometimes payment gateways call it differently, e.g. "vault", "Transformer", etc. If you are not sure - contact your payment gateway to enable tokenization for your payment gateway.

===Customer CC expires in 2022 - X-Payments stops at 2020===

We just had a customer call in. He could not check out because our X-Payments payment page would not allow him to enter the expiration year of 2022 for his credit card. Our X-Payments only goes up to 2020.

'''Solution:'''

You need to change YEAR_RANGE from 7 to 10 for example in file lib/XPay/View/Payment/Main.php

// Years list range

const YEAR_RANGE = 7

===White screen or HTTP 500 Internal server error instead of admin dashboard===

You see white screen after logging in X-Payments admin dashboard.

'''Solution:'''

Some PHP packages contain a bug that causes "White screen" or HTTP 500 Internal server error when PHP operates with the database via PDO. If you experience such issue contact your hosting support referring to:

https://bugs.php.net/bug.php?id=60825
https://bugs.php.net/bug.php?id=53716

===Magento: cannot test module connection or payment methods cannot be imported===

You copied all configuration data from X-Payments properly but in Magento admin you see below message when you click "Test module" button
Test transaction failed. Please check the X-Payment Connector settings and try again. If all options is ok review your X-Payments settings and make sure you have properly defined shopping cart properties.

Or a message that payment methods cannot be imported when you click "Request payment methods" button.

'''Solution:'''

Possible reason - you do not have a valid SSL certificate installed for your X-Payments. Self-signed SSL cannot pass libCurl validation and thus prevent connection between Magento and X-Payments, too. You need to install a valid SSL certificate at X-Payments server.

'''NOTE:''' users of our hosted X-Payments plans are safe since we provide SSL by default.

===Google Chrome v41.0.2272.76 detects X-Payments v2.1 credit card form as a mobile site on desktops===

After the update of the Google Chrome web browser to version 41.0.2272.76, the credit card form provided to your site by X-Payments v2.1 may be displayed incorrectly for Google Chrome users.
The problem behind this is that the value of the user-agent header sent by Chrome has changed, which causes X-Payments to identify the browser as running on a mobile device, even when, if fact, it is running on a PC. The result is that the credit card form is corrupted like on these screen shots:

- http://awesomescreenshot.com/0724kkas56
- http://awesomescreenshot.com/04f4kkaq18

'''Solution:'''

To fix the issue, you need to update the Mobile Detect library in your X-Payments installation so the list of supported user agents is relevant. For that you should replace the file
<xpayments-dir>/lib/MobileDetect.php with this one: https://drive.google.com/file/d/0B6p7sehSZL8_QUN6VmRVMHpxaFE/view?usp=sharing (should be done via SFTP, SSH, Control panel, etc.)

If you find it difficult to apply the changes yourself please contact our Tech Support team using https://secure.x-cart.com.

===Trouble with credit card logos in iFrame template for X-Cart 5===

You use X-Cart 5 integrated with X-Payments v2.x and see credit card logos displayed like [https://drive.google.com/a/x-cart.com/file/d/0B6p7sehSZL8_T1kyQ0RCNS1nWDA/view?usp=sharing this in checkout] using Mac Safari or iPad.

'''Solution'''

Replace files fast.css and xc5.css in folder <x-pay_dir>/public/templates/ with these:

https://drive.google.com/a/x-cart.com/folderview?id=0B6p7sehSZL8_OUVTeUtCUkFjY2M&usp=sharing

===My entire shop is run in an iFrame and X-Payments does not display "Pay" button===

There is a special code in X-Payments that hides "Pay" button if it the payment form is shown inside iframe.
In your case the whole store is placed inside iframe and that triggers the special code.
Easiest workaround which will not affect other stores connected to the X-Payments is to edit the template file css (I presume you use default.css) and where

<pre>
div.content div.buttonRow {
margin: 35px auto;
width: 400px;
}
</pre>

you should add

<pre>
display: block !important;
</pre>

e.g. after correction that code will look like

<pre>
div.content div.buttonRow {
margin: 35px auto;
width: 400px;
display: block !important;
}
</pre>

Do not forget to approve the changes in the admin back-end afterwards.

===X-Payments credit card form does not fit properly on Android tablet screen when used in iFrame in X-Cart 4 OPC===

X-Payments credit card form is displayed as shown on [https://drive.google.com/file/d/0B6p7sehSZL8_ZDhac2JNVWxlQ1E/view?usp=sharing this screen shot].

The reason is X-Cart 4 OPC shows desktop version of the site checkout while X-Payments shows mobile checkout template which is wider than needed for XC4 desktop OPC.

'''Solution'''

Apply [https://drive.google.com/file/d/0B6p7sehSZL8_c0JmYjhaRi1ITEE/view?usp=sharing this patch] to X-Payments connector files in your X-Cart 4.
 

===How to test payments via PayPal in X-Payments===

There is a list of credit card numbers in the PayPal guides which many people assume can be used when processing credit card transactions through PayPal. However, many of these card numbers have been blocked from PayPal system in one fashion or another (e.g. delay processing a lot so integrated software like X-Cart or Magento just fails to place a test transaction), so general advice is "don't use those card numbers".

In general, when testing credit card transactions with PayPal as the processor, it is recommended using a randomized credit card number. The number
must have a valid BIN, a valid check digit, and must be the correct length for the card type, but aside from that, the card number can be random.
You can get such random test credit card numbers at http://getcreditcardnumbers.com

==="The TxnID field is missing or incorrect" message after upgrading to a new connector version in Magento===

If after upgrading Magento connector to a new version and placing a new order you see an error message "The txnID field is missing or incorrect" instead of successful "Thank you for your order" page you need to clean/purge Magento's cache in your shop in the admin back-end. Consult with Magento user manual how to do that.

===Browser warning about wrong SSL certificate pops up===

If your browser shows a pop-up with warning about SSL certificate every time you test a transaction via X-Payments - this means your store installation has self-made/dummy SSL certificate. It is fine during testing, but you need to upgrade it to a real SSL certificate when your site goes live.
During testing just add that SSL certificate to exclusions in your browser in order not to see that warning every time you place a test transaction via X-Payments. This won't help you to hide that message from your shoppers though. The warning is not shown by a browser if a real SSL certificate is used.

==="X-Payments tried to notify the store about updates in payment but failed" notification===

You receive notifications that say "X-Payments tried to notify the store about updates in payment but failed ...".

They mean X-Payments callback requests have failed because of timeout or because your online shop site is not reachable by X-Payments.

In the 1st case the store didn't respond within 15 seconds coded by default in X-Payments, but the logs from the side of the store for these requests say, that the requests were received and processed with no errors. It means, that communication between the store and X-Payments actually works, but it takes to long for the store to respond. As a quick solution for this very reason it is recommended to increase the timeout limits in your X-Payments installation:
If X-Payments 2.x - in file lib/XPay/Model/Payment.php by changing "15" in a line of code that looks like to a bigger value (max 60):

$requestData->setTimeout(15);

If X-Payments 3.x - in file config/config.ini.php in section [callback] change value of wait_timeout param:

[callback]

; Wait timeout for callback requests to the shopping cart (in seconds)
wait_timeout=15

If you do not have access to your X-Payments installation code - contact vendors of the software by posting them a technical support ticket via https://secure.x-cart.com.

But the right solution is to figure out why your web site does not respond to X-Payments callbacks within 15 seconds.

In the 2nd case it might be firewall blocking X-Payments callback requests or your web shop was down for some time.

==="No Payment Methods Available" message shown to a customer===

A customer cannot place an order as he/she is displayed a message "No Payment Methods Available" at checkout and at the same time you see an error message "Data validation error, node "request": String length ("266342") exceeds the maximum allowed length for this node - "100000" in X-Payments error log file.

'''Reason'''

A shopper added too many line items (different products) to his/her cart ("too many" - e.g. over a thousand) and as result data passed to X-Payments exceeds amount it is configured to accept for security reasons.

'''Solution'''

1) a customer should divide his order in several with less number of line items and process them one by one.

2) if you face to this issue too often you can increase amount of data allowed to be processed by X-Payments by changing value of constant REQUEST_MAX_LENGTH in X-Payments file lib/XPay/Transport/Request/Api.php, but we do not recommend to large value there for security reasons.

===Payflow PRO currency issue===

'''NOTE''': do not confuse this with PayPal Payments PRO (PayFlow API)! There is PayFlow PRO integration, too. We are talking about PayFlow PRO here.

You need to process payments via PayFlow PRO in other currency than USD, but there is no way to change it. You configured integrated cart in e.g. CAD but X-Payments passes data to PayFlow PRO as USD. This is caused by features of PayFlow PRO API - no exact requirements about passing currency type to PayFlow PRO - sometimes it can be passed as "CUR", sometimes as "CU", etc depending on payment processor you have configured at PayFlow PRO back-end.

'''Solution'''

1) Switch to PayPal Payments Pro (Payflow API) integration instead of PayFlow PRO in X-Payments.

or

2) change code of X-Payments as follows:
in file lib/XPay/Module/PayflowPro.php find function

<pre>
private function getInitRequestBody(XPay_Transport_GatewayRequest $request)
</pre>

In the function find lines

<pre>
...
$fields = array(
'TRXTYPE' => XPay_Model_PaymentTransaction::SALE == $request->action ? 'S' : 'A',
'AMT' => $this->preparePrice($request->payment->get('total')),
'TAXAMT' => $this->preparePrice($additionalData->get('tax_cost')),
...
</pre>

and add a line of code

<pre>
'CURRENCY' => $request->payment->get('currency'),
</pre>

to get something like

<pre>
'TRXTYPE' => XPay_Model_PaymentTransaction::SALE == $request->action ? 'S' : 'A',
'CURRENCY' => $request->payment->get('currency'),
'AMT' => $this->preparePrice($request->payment->get('total')),
'TAXAMT' => $this->preparePrice($additionalData->get('tax_cost')),
</pre>

The above tweak will work if "PayPal" is configured as the gateway in your PayFlow PRO account.

For others you should directly specify currency in format required by payment gateway.

E.g.
<pre>
'CURRENCY' => 'USD',
</pre>

===X-Cart 5 and Exception message: Shopping cart server returned wrong HTTP headers for callback.===

You use X-Cart 5 and see below error message or error log entry at X-Cart 5 side:

<pre>
Failed to send "check_cart" callback to the store "mydomain.com"
Url: https://www.example.com/cart.php?target=callback&action=callback&xpcBackReference=ABCDEFGHIJKL
Exception message: Shopping cart server returned wrong HTTP headers for callback.
</pre>

'''Solution''':

Most likely you try to test X-Payments with X-Cart 5 storefront closed. If so, in X-Cart 5 file etc/config.php find below piece of code:

<pre>
[storefront_options]
; Do not close target=callback for payments if storefront is closed
callback_opened = Off
</pre>

and change "Off" to "On" there.

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

[[Category:X-Payments User Manual]]

X-Payments:PCI DSS implementation guide for X-Payments 2.2

2016-04-26T12:30:42Z

Alex “Ambal” Mulin: /* X-Cart Payments versioning policy */

== Introduction ==

This guide covers '''X-Cart Payments''' 1.0, 2.0, 2.1, 2.2 and is intended for merchants and integrators who wish to implement the application in accordance with guidelines set by the PCI Data Security Standard (PCI DSS).

== X-Cart Payments versioning policy ==

X-Cart Payments version number must look like "X.Y.z" (e.g. 1.0.6, 2.0.1, 2.2.1, 3.0.0), where

* X - major release version number that gets incremented when high impact changes are introduced and certified under PA-DSS requirements;
* Y - minor release version number that gets incremented when low impact changes are added to X-Cart Payments package;
* Z - maintenance/bug-fix release version number that gets incremented when no impact and administrative changes are done to X-Cart Payments package.

See samples of changes below:

* High-impact - major update of core X-Cart Payments functions such as login routine, credit card processing inside X-Cart Payments.
* Low-impact - update of integration with newer versions of DBMS, OS and middleware whose older versions have been already verified, adding or removing payment processor integrations, re-compiling source code using new code compiler or new compiler settings, change to X-Cart Payments versioning policy, other changes not related to security of the application.
* No impact - UI changes, changes to DB schemes, report module updates, update or adding of new payment gateway.
* Administrative change - change of application name, change of software vendor name.

== PCI DSS ==

PCI DSS specifies 12 requirements broken into 6 groups for compliance that apply both to hardware and software parts of the system that is used to collect, store, transmit and process valuable credit card data as well as the human factor.

{| border
| Build and Maintain a Secure Network
|

* Requirement 1: Install and maintain a firewall configuration to protect cardholder data
* Requirement 2: Do not use vendor-supplied defaults for system passwords and other security parameters
|-
| Protect Cardholder Data
|

* Requirement 3: Protect stored cardholder data
* Requirement 4: Encrypt transmission of cardholder data across open, public networks
|-
| Maintain a Vulnerability Management Program
|

* Requirement 5: Use and regularly update anti-virus software
* Requirement 6: Develop and maintain secure systems and applications
|-
| Implement Strong Access Control Measures
|

* Requirement 7: Restrict access to cardholder data by business need-to-know
* Requirement 8: Assign a unique ID to each person with computer access
* Requirement 9: Restrict physical access to cardholder data
|-
| Regularly Monitor and Test Networks
|

* Requirement 10: Track and monitor all access to network resources and cardholder data
* Requirement 11: Regularly test security systems and processes
|-
| Maintain an Information Security Policy
|

* Requirement 12: Maintain a policy that addresses information security
|}

Specifically, relevant elements to an e-commerce business' PCI compliance status include:

* Properly using your payment application. For this purpose, carefully review the section below for information on how to use '''X-Cart Payments''' in a way that ensures PCI compliance.

* Using a PCI compliant Web hosting environment

* Using a PCI compliant payment provider

You can find and review the complete specification by visiting [https://www.pcisecuritystandards.org/ https://www.pcisecuritystandards.org/]

This guide is intended to help merchants implement the '''X-Cart Payments''' application in a way that is compliant with version 2.0 of the PCI DSS.

== Payment Card Industry Data Security Standard ('''PCI DSS''') ==

The Payment Card Industry Data Security Standard is a worldwide information security standard assembled by the major credit card vendors, including American Express, Discover Financial Services, JCB International, MasterCard Worldwide, and Visa, Inc. The standard was designed to help organizations involved in processing credit card payments online make their payment systems secure from cardholder data fraud.

'''X-Cart Payments''' has been designed and certified to meet all of the requirements of the '''PA-DSS''' version 2.0. This does not automatically make you, the merchant, PCI DSS compliant. To ensure PCI DSS compliance, it is necessary that you follow the recommendations and instructions provided in this guide.

For additional information about '''PCI DSS''' please visit the [https://www.pcisecuritystandards.org Official PCI Security Standards Council Site].

== Cardholder data storage==

'''X-Cart Payments''' has [[X-Payments:General_settings#Cardholder_Data | the ability to store parts of cardholder data temporarily]] for performing 3D Secure verification and certain types of transactions for some of the integrated payment processors. While stored cardholder data is encrypted using special [[X-Payments:Encryption_keys | cryptographic algorithm]]. The data is removed automatically when its storing period is over using "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.

'''X-Cart Payments''' can not be configured to store permanently in the database the following types of data:

* unmasked PAN
* PIN
* CVV
* magnetic stripe (track data)

Merchants and/or developers implementing '''X-Cart Payments''' should not attempt to customize this as a feature.

'''X-Cart Payments''' can display masked PAN on "Payment details" pages and in "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. '''X-Cart Payments''' does not have the ability to display full PAN anywhere and there are no settings that can change this behavior of the user interface.

==Configuring and using '''X-Cart Payments''' in PCI compliant manner ==

===Installation===

Follow the [[X-Payments:Installation | standard procedure]] for deployment of X-Cart Payments files to the web server.

{{Note1|Once installed, X-Cart Payments WILL NEVER: 
* store unmasked credit card numbers (PANs)
* send credit card data or any other information to Qualiteam for debug purposes}}

===Access control===

There are no built-in/default user accounts in '''X-Cart Payments'''.
You must carefully control access to '''X-Cart Payments'''. Follow these rules:

* Restrict the number of employees who have access to '''X-Cart Payments''' to only those who have a business need.
* Always provide unique usernames for each person who needs access.
* Do not use system-default usernames and/or passwords
* Web server must be run under a non-privileged user account. Application must access the database from a limited privilege user account.
* All default user accounts use secure authentication mechanisms and password policy settings that comply with all the standard requirements:
** user accounts inactive for more than 3 days are blocked
** password lifetime is set to 30 days

:: To set password lifetime:

::# Login to '''X-Cart Payments'''
::# Go to Settings -> General Settings
::# Enter the number of days the user account password will be valid for in the "User account password lifetime" field. The maximum allowed password lifetime is 90 days.

:* minimum password length is 8 characters
:* password must contain both lower and upper case characters and numbers
:* the last 4 passwords must be unique
:* user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password
:* user is logged off after inactivity period of 10 minutes

<div> Please note that changing default password policy settings will lead to breaking PCI DSS standard requirements.</div>

===Enabling SSL (Secure Socket Layer)===

SSL protects data that is transmitted between a browser and your web server. It is critical that you have SSL enabled on your web server, and this should be among the first steps taken after installation.

* Your web server must be configured to use TLS v1.2 protocols with strong encryption (128-bit or longer key is required)
* You will need to have a certificate issued for your web domain. Read [http://help.qtmsoft.com/index.php?title=Instant_SSL_certificate guidelines on installing Comodo's Instant SSL certificates].

If a web server does not have SSL enabled '''X-Cart Payments''' will not function or will be notifying users depending on '''allow_insecure_protocol''' parameter set in config.ini.php file (disabled by default).

===Data Collected while Testing===

Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:

# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever collect credit card information to troubleshoot a problem that one of your customers is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access
#* Only collect a limited amount of such data as needed to solve a specific problem
#* Sensitive authentication data must be encrypted while stored. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Such data must be securely deleted immediately after use.

===Encryption Key Management===

As part of your PA DSS v3.1 requirements, encryption key must be changed annually (changing every 90 days is recommended). You should also change the key any time an employee with access to the key leaves your company. Always replace the key if you know or suspect it has been compromised by any means.

To change the encryption keys:

# Log in to '''X-Cart Payments'''
# Go to Maintenance -> Encryption keys
# Click "Generate new keys"

===Use unique user IDs and secure authentication to access PCs, servers and databases ===

PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:

# For your Web hosting account administration area (Web hosting account where your online store is hosted)
# For FTP access to the Web server
# For Remote Desktop Connection to the Web server (if available)
# To connect to the MySQL server that contains your store data.

The passwords for the accounts mentioned above must also meet the following requirements:

* be at least 8 characters in length
* contain both numbers and letters in lower and upper case
* not coincide with any part of your email address
* not coincide with any of the last four passwords you have used
* have a lifetime of less than 90 days
* account lockout threshold must be set to 6.
* account lockout duration must be set to 30 minutes (or until unblocked by the administrator).
* user must be logged off after 15 minutes of inactivity

===Audit trails===

Audit trails are automatically enabled with the default installation of X-Cart Payments. There is no option to disable audit logging. The log files are created in the var/log/ directory. Make sure you restrict access to the log files by business need-to-know.

The following types of activity are logged:

* All actions taken by any individual with root or administrative privileges
* Successes and failures of all individual accesses to application sections and functions

* Initialization of the audit logs
* User sign in and sign out.

Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to files access.log and error.log.

Each log event includes:

* Type of event
* Date and time of event
* Username and IP address
* Success or failure indication
* Action which led to the event

* Component which led to the event

There is also a meta-log which contains information about other log files being created.

=== OS-level audit trails ===

Make sure you have a system-level auditing software properly configured to monitor users' activity on server. This software should:

* warn on a checksum change of any of X-Cart Payments source code files except of log file and database files
* record any file writing operations related to X-Cart Payments files

===Encrypting network traffic===

X-Cart Payments uses encryption, such as TLS or IPSEC, for:

* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
* providing remote web-based access to the application

If you use tools to remotely access the application, you should encrypt all communication using technologies such as TLS or IPSEC.

As per PCI DSS requirement 4.2, cardholder data should never be sent unencrypted by e-mail, and X-Cart Payments does meet this requirement '''never''' sending cardholder data by e-mail or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.

===Wireless communications===

If you use wireless networking to access '''X-Cart Payments''', it is your responsibility to ensure your wireless security con figuration follows the PCI DSS requirements.

* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
* Use with a minimum 104-bit encryption key and 24 bit-initialization value
* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS
* Rotate shared WEP keys quarterly (or automatically if the technology permits)
* Rotate shared WEP keys whenever there are changes in personnel with access to keys
* Restrict access based on media access cod e (MAC) address.
* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.

===Remote access===

X-Cart Payments provides web-based access using two-factor authentication based on one-time PIN codes. Detailed information can be found at [[X-Payments:Managing_PIN_codes | Managing PIN codes]] page.

If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:

* Change default settings in the remote access software (for example, change default passwords and use unique passwords for each customer)
* Allow connections only from specific (known) IP/MAC addresses
* Use strong authentication or complex passwords for logins
* Enable encrypted data transmission
* Enable account lockout after a certain number of failed login attempts
* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed
* Enable any logging or auditing functions
* Restrict access to customer passwords to authorized reseller/integrator personnel
* Establish customer passwords according to PCI DSS requirements 8.1, 8.2, 8.4, 8.5

Qualiteam does not provide software updates via remote access on an automated basis.

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PCI DSS implementation guide for X-Payments 2.2

2016-04-26T12:29:28Z

Alex “Ambal” Mulin: /* X-Cart Payments versioning policy */

== Introduction ==

This guide covers '''X-Cart Payments''' 1.0, 2.0, 2.1, 2.2 and is intended for merchants and integrators who wish to implement the application in accordance with guidelines set by the PCI Data Security Standard (PCI DSS).

== X-Cart Payments versioning policy ==

X-Cart Payments version number must look like "X.Y.z" (e.g. 1.0.6, 2.0.1, 2.2.1, 3.0.0), where

* X - major release version number that gets incremented when high impact changes are introduced and certified under PA-DSS requirements;
* Y - minor release version number that gets incremented when low impact changes are added to X-Cart Payments package;
* Z - maintenance/bug-fix release version number that gets incremented when no impact and administrative changes are done to X-Cart Payments package.

See samples of changes below:

High-impact - major update of core X-Cart Payments functions such as login routine, credit card processing inside X-Cart Payments.
Low-impact - update of integration with newer versions of DBMS, OS and middleware whose older versions have been already verified, adding or removing payment processor integrations, re-compiling source code using new code compiler or new compiler settings, change to X-Cart Payments versioning policy, other changes not related to security of the application.
No impact - UI changes, changes to DB schemes, report module updates, update or adding of new payment gateway

== PCI DSS ==

PCI DSS specifies 12 requirements broken into 6 groups for compliance that apply both to hardware and software parts of the system that is used to collect, store, transmit and process valuable credit card data as well as the human factor.

{| border
| Build and Maintain a Secure Network
|

* Requirement 1: Install and maintain a firewall configuration to protect cardholder data
* Requirement 2: Do not use vendor-supplied defaults for system passwords and other security parameters
|-
| Protect Cardholder Data
|

* Requirement 3: Protect stored cardholder data
* Requirement 4: Encrypt transmission of cardholder data across open, public networks
|-
| Maintain a Vulnerability Management Program
|

* Requirement 5: Use and regularly update anti-virus software
* Requirement 6: Develop and maintain secure systems and applications
|-
| Implement Strong Access Control Measures
|

* Requirement 7: Restrict access to cardholder data by business need-to-know
* Requirement 8: Assign a unique ID to each person with computer access
* Requirement 9: Restrict physical access to cardholder data
|-
| Regularly Monitor and Test Networks
|

* Requirement 10: Track and monitor all access to network resources and cardholder data
* Requirement 11: Regularly test security systems and processes
|-
| Maintain an Information Security Policy
|

* Requirement 12: Maintain a policy that addresses information security
|}

Specifically, relevant elements to an e-commerce business' PCI compliance status include:

* Properly using your payment application. For this purpose, carefully review the section below for information on how to use '''X-Cart Payments''' in a way that ensures PCI compliance.

* Using a PCI compliant Web hosting environment

* Using a PCI compliant payment provider

You can find and review the complete specification by visiting [https://www.pcisecuritystandards.org/ https://www.pcisecuritystandards.org/]

This guide is intended to help merchants implement the '''X-Cart Payments''' application in a way that is compliant with version 2.0 of the PCI DSS.

== Payment Card Industry Data Security Standard ('''PCI DSS''') ==

The Payment Card Industry Data Security Standard is a worldwide information security standard assembled by the major credit card vendors, including American Express, Discover Financial Services, JCB International, MasterCard Worldwide, and Visa, Inc. The standard was designed to help organizations involved in processing credit card payments online make their payment systems secure from cardholder data fraud.

'''X-Cart Payments''' has been designed and certified to meet all of the requirements of the '''PA-DSS''' version 2.0. This does not automatically make you, the merchant, PCI DSS compliant. To ensure PCI DSS compliance, it is necessary that you follow the recommendations and instructions provided in this guide.

For additional information about '''PCI DSS''' please visit the [https://www.pcisecuritystandards.org Official PCI Security Standards Council Site].

== Cardholder data storage==

'''X-Cart Payments''' has [[X-Payments:General_settings#Cardholder_Data | the ability to store parts of cardholder data temporarily]] for performing 3D Secure verification and certain types of transactions for some of the integrated payment processors. While stored cardholder data is encrypted using special [[X-Payments:Encryption_keys | cryptographic algorithm]]. The data is removed automatically when its storing period is over using "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.

'''X-Cart Payments''' can not be configured to store permanently in the database the following types of data:

* unmasked PAN
* PIN
* CVV
* magnetic stripe (track data)

Merchants and/or developers implementing '''X-Cart Payments''' should not attempt to customize this as a feature.

'''X-Cart Payments''' can display masked PAN on "Payment details" pages and in "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. '''X-Cart Payments''' does not have the ability to display full PAN anywhere and there are no settings that can change this behavior of the user interface.

==Configuring and using '''X-Cart Payments''' in PCI compliant manner ==

===Installation===

Follow the [[X-Payments:Installation | standard procedure]] for deployment of X-Cart Payments files to the web server.

{{Note1|Once installed, X-Cart Payments WILL NEVER: 
* store unmasked credit card numbers (PANs)
* send credit card data or any other information to Qualiteam for debug purposes}}

===Access control===

There are no built-in/default user accounts in '''X-Cart Payments'''.
You must carefully control access to '''X-Cart Payments'''. Follow these rules:

* Restrict the number of employees who have access to '''X-Cart Payments''' to only those who have a business need.
* Always provide unique usernames for each person who needs access.
* Do not use system-default usernames and/or passwords
* Web server must be run under a non-privileged user account. Application must access the database from a limited privilege user account.
* All default user accounts use secure authentication mechanisms and password policy settings that comply with all the standard requirements:
** user accounts inactive for more than 3 days are blocked
** password lifetime is set to 30 days

:: To set password lifetime:

::# Login to '''X-Cart Payments'''
::# Go to Settings -> General Settings
::# Enter the number of days the user account password will be valid for in the "User account password lifetime" field. The maximum allowed password lifetime is 90 days.

:* minimum password length is 8 characters
:* password must contain both lower and upper case characters and numbers
:* the last 4 passwords must be unique
:* user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password
:* user is logged off after inactivity period of 10 minutes

<div> Please note that changing default password policy settings will lead to breaking PCI DSS standard requirements.</div>

===Enabling SSL (Secure Socket Layer)===

SSL protects data that is transmitted between a browser and your web server. It is critical that you have SSL enabled on your web server, and this should be among the first steps taken after installation.

* Your web server must be configured to use TLS v1.2 protocols with strong encryption (128-bit or longer key is required)
* You will need to have a certificate issued for your web domain. Read [http://help.qtmsoft.com/index.php?title=Instant_SSL_certificate guidelines on installing Comodo's Instant SSL certificates].

If a web server does not have SSL enabled '''X-Cart Payments''' will not function or will be notifying users depending on '''allow_insecure_protocol''' parameter set in config.ini.php file (disabled by default).

===Data Collected while Testing===

Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:

# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever collect credit card information to troubleshoot a problem that one of your customers is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access
#* Only collect a limited amount of such data as needed to solve a specific problem
#* Sensitive authentication data must be encrypted while stored. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Such data must be securely deleted immediately after use.

===Encryption Key Management===

As part of your PA DSS v3.1 requirements, encryption key must be changed annually (changing every 90 days is recommended). You should also change the key any time an employee with access to the key leaves your company. Always replace the key if you know or suspect it has been compromised by any means.

To change the encryption keys:

# Log in to '''X-Cart Payments'''
# Go to Maintenance -> Encryption keys
# Click "Generate new keys"

===Use unique user IDs and secure authentication to access PCs, servers and databases ===

PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:

# For your Web hosting account administration area (Web hosting account where your online store is hosted)
# For FTP access to the Web server
# For Remote Desktop Connection to the Web server (if available)
# To connect to the MySQL server that contains your store data.

The passwords for the accounts mentioned above must also meet the following requirements:

* be at least 8 characters in length
* contain both numbers and letters in lower and upper case
* not coincide with any part of your email address
* not coincide with any of the last four passwords you have used
* have a lifetime of less than 90 days
* account lockout threshold must be set to 6.
* account lockout duration must be set to 30 minutes (or until unblocked by the administrator).
* user must be logged off after 15 minutes of inactivity

===Audit trails===

Audit trails are automatically enabled with the default installation of X-Cart Payments. There is no option to disable audit logging. The log files are created in the var/log/ directory. Make sure you restrict access to the log files by business need-to-know.

The following types of activity are logged:

* All actions taken by any individual with root or administrative privileges
* Successes and failures of all individual accesses to application sections and functions

* Initialization of the audit logs
* User sign in and sign out.

Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to files access.log and error.log.

Each log event includes:

* Type of event
* Date and time of event
* Username and IP address
* Success or failure indication
* Action which led to the event

* Component which led to the event

There is also a meta-log which contains information about other log files being created.

=== OS-level audit trails ===

Make sure you have a system-level auditing software properly configured to monitor users' activity on server. This software should:

* warn on a checksum change of any of X-Cart Payments source code files except of log file and database files
* record any file writing operations related to X-Cart Payments files

===Encrypting network traffic===

X-Cart Payments uses encryption, such as TLS or IPSEC, for:

* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
* providing remote web-based access to the application

If you use tools to remotely access the application, you should encrypt all communication using technologies such as TLS or IPSEC.

As per PCI DSS requirement 4.2, cardholder data should never be sent unencrypted by e-mail, and X-Cart Payments does meet this requirement '''never''' sending cardholder data by e-mail or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.

===Wireless communications===

If you use wireless networking to access '''X-Cart Payments''', it is your responsibility to ensure your wireless security con figuration follows the PCI DSS requirements.

* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
* Use with a minimum 104-bit encryption key and 24 bit-initialization value
* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS
* Rotate shared WEP keys quarterly (or automatically if the technology permits)
* Rotate shared WEP keys whenever there are changes in personnel with access to keys
* Restrict access based on media access cod e (MAC) address.
* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.

===Remote access===

X-Cart Payments provides web-based access using two-factor authentication based on one-time PIN codes. Detailed information can be found at [[X-Payments:Managing_PIN_codes | Managing PIN codes]] page.

If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:

* Change default settings in the remote access software (for example, change default passwords and use unique passwords for each customer)
* Allow connections only from specific (known) IP/MAC addresses
* Use strong authentication or complex passwords for logins
* Enable encrypted data transmission
* Enable account lockout after a certain number of failed login attempts
* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed
* Enable any logging or auditing functions
* Restrict access to customer passwords to authorized reseller/integrator personnel
* Establish customer passwords according to PCI DSS requirements 8.1, 8.2, 8.4, 8.5

Qualiteam does not provide software updates via remote access on an automated basis.

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:Supported payment gateways

2016-03-24T14:26:52Z

Alex “Ambal” Mulin:

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

{| class="wikitable" width=90%
|-
! scope="col" style="width: 15%;"| '''Payment service provider'''
! scope="col" style="width: 20%;"| '''Payment system'''
! scope="col" style="width: 6%;"| '''Sale'''
! scope="col" style="width: 6%;"| '''Auth'''
! scope="col" style="width: 10%;"| '''Capture'''
! scope="col" style="width: 6%;"| '''Void'''
! scope="col" style="width: 10%;"| '''Refund'''
! scope="col" style="width: 6%;"| '''Get status'''
! scope="col" style="width: 6%;"| '''Accept'''
! scope="col" style="width: 6%;"| '''Decline'''
! scope="col" style="width: 6%;"| '''Test'''
! scope="col" style="width: 6%;"| '''3D-Secure via Cardinal Commerce'''
! scope="col" style="width: 6%;"| '''Tokenization'''
|- style="vertical-align:top;"
| [http://www.paypal.com/ PayPal]
| PayFlow Pro
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|
| 3d Secure built in
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://www.paypal.com/ PayPal]
| PayPal Payments Pro (PayPal API)
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://www.paypal.com/ PayPal]
| PayPal Payments Pro (Payflow API)
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://www.anz.com/ Australia and New Zealand Banking Group Limited]
| ANZ eGate
| [[File:Check.svg|25px]]
|
|
|
|
|
|
|
|
|
|
|- style="vertical-align:top;"
| [http://paymentgateway.americanexpress.com/ American Express]
| American Express Web-Services API Integration
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
| [[File:Check.svg|25px]] + p, m
|
|
|
|
|
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://www.cybersource.com/ CyberSource Corporation]
| Authorize.Net AIM
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + m
|
|
|
|
| [[File:Check.svg|25px]]
|
|- style="vertical-align:top;"
| [http://www.cybersource.com/ CyberSource Corporation]
| Authorize.Net AIM XML
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
| [[File:Check.svg|25px]]
|
|- style="vertical-align:top;"
| [http://www.cybersource.com/ CyberSource Corporation]
| Authorize.Net CIM
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://www.beanstream.com/ Digital River, Inc.]
| Beanstream, a Digital River Company/FirstData Canada  
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
| [[File:Check.svg|25px]]
|
|- style="vertical-align:top;"
| [http://bluepay.com/xpayments-partner-page BluePay]
| BluePay  
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
|
|
|- style="vertical-align:top;"
| [https://www.braintreepayments.com/ Braintree, a division of PayPal, Inc.]
| Braintree
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
|
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://www.caledoncard.com/ Blue Pay Canada (ex. Caledon Computer Systems, Inc.)]
| Blue Pay Canada (ex. Caledon)
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
| [[File:Check.svg|25px]] + p, m
|
|
|
|
| [[File:Check.svg|25px]]
|
|- style="vertical-align:top;"
| [http://www.cardinalcommerce.com/ CardinalCommerce Corporation]
| Cardinal Commerce Centinel
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
|
|
|
|
| 3d Secure built in
|
|- style="vertical-align:top;"
| [http://www.chasepaymentech.com/ Chase Paymentech]
| Chase Paymentech  
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]] + p
|
|
|
|
|
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://www.cybersource.com/ CyberSource]
| CyberSource - SOAP toolkit API  
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://www.dibspayment.com/ DIBS Payment Services AB]
| DIBS
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
| [[File:Check.svg|25px]]
|
|- style="vertical-align:top;"
| [http://digitalriverpayments.co.uk/ Digital River, Inc.]
| Digital River World Payments / Beanstream
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
| [[File:Check.svg|25px]]
|
|- style="vertical-align:top;"
| [http://www.securepay.com.au/ SecurePay Pty Ltd]
| [http://www.directone.com.au/ DirectOne - Direct Interface]  
| [[File:Check.svg|25px]]
|
|
|
|
|
|
|
|
|
|
|- style="vertical-align:top;"
| [https://secure.5thdl.com Sparrow (ex. 5th Dimension Logisitics, LLC)]
| Sparrow (ex. 5th Dimension Gateway)
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
|
| [[File:Check.svg|25px]] + p
|
|
|
|
|
|
|- style="vertical-align:top;"
| [http://www.echo-inc.com/ Electronic Clearing House, Inc.]
| ECHO NVP
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|
| [[File:Check.svg|25px]]
|
|
|
|
|
| [[File:Check.svg|25px]]
|
|- style="vertical-align:top;"
| [http://www.elavon.com/ Elavon, Inc.]
| Elavon Converge
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|
|
|
|
| 3d Secure built in
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://www.barclaycardbusiness.co.uk/about_us.html Barclaycard Business]
| ePDQ MPI XML (Phased out)  
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
|
|
|- style="vertical-align:top;"
| [http://www.eprocessingnetwork.com/Info.html eProcessing Network, LLC]
| eProcessing Network - Transparent Database Engine
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|
|
|
|
|
|
|- style="vertical-align:top;"
| [http://www.moneris.com/ Moneris Solutions]
| eSELECTplus  
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
| [[File:Check.svg|25px]] + p, m
|
|
|
|
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://www.eway.com.au/Company/Company.aspx Web Active Corporation Pty Ltd]
| eWay Realtime Payments XML
| [[File:Check.svg|25px]]
|
|
|
| [[File:Check.svg|25px]]
|
|
|
|
|
|
|- style="vertical-align:top;"
| [http://www.globalpaymentsinc.com Global Payments, Inc]
| Global Iris/HSBC - RealAuth Remote
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|
|
|
|
| 3d Secure built in
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://www.goemerchant.com/ GoEmerchant, LLC]
| GoEmerchant - XML Gateway API
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
|
|
|- style="vertical-align:top;"
| [http://www.heidelpay.de Heidelberger Payment GmbH]
| HeidelPay
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
|
|
|
|
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://www.innovativegateway.com/ Intuit, Inc. Innovative Gateway]
| Innovative Gateway
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|
|
|
|
|
|
|
|
|
|- style="vertical-align:top;"
| [http://www.itransact.com/ iTransact, Inc.]
| iTransact XML  
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
|
|
|- style="vertical-align:top;"
| [http://www.firstdata.com/ First Data Corporation]
| First Data Payeezy Gateway (ex- Global Gateway e4)
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
|
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://www.merituspayment.com/ Meritus Payment Solutions]
| Meritus Web Host
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
|
| [[File:Check.svg|25px]] (works only in "Sale" mode, is disabled in "Auth only" mode)
|- style="vertical-align:top;"
| [http://www.netbilling.com/ Netbilling, Inc.]
| Netbilling - Direct Mode 3.1  
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
|
| [[File:Check.svg|25px]] + p, m
|
|
|
|
| [[File:Check.svg|25px]]
|
|- style="vertical-align:top;"
| [http://www.netregistry.com.au/ Netregistry Pty Ltd]
| NetRegistry  
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|
|
| [[File:Check.svg|25px]] + p, m
|
|
|
|
|
|
|- style="vertical-align:top;"
| [http://www.ogone.com/ Ingenico Payment Services (former Ogone)]
| Ingenico/Ogone/ePDQ e-Commerce
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
|
|
|- style="vertical-align:top;"
| [http://www.paygate.net/ PayGate]
| PayGate Korea  
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|
|
|
|
|
|
|- style="vertical-align:top;"
| [http://www.psigate.com/ Payment Services Interactive Gateway Inc.]
| PSiGate XML API
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
| [[File:Check.svg|25px]]
|
|- style="vertical-align:top;"
| [http://www.quantumgateway.com/ Quantum Services LLC]
| QuantumGateway - Transparent QGWdatabase Engine
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
| [[File:Check.svg|25px]]
|
|
|
|
|
|
|
|- style="vertical-align:top;"
| [http://www.quantumgateway.com/ Quantum Services LLC]
| QuantumGateway - XML Requester
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
|
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://payments.intuit.com/ Intuit Inc.]
| Intuit QuickBooks Payments  
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
|
|
|
|
|
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://www.realexpayments.com/ Realex Payments]
| Realex
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|
|
|
| 3d Secure built in
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://www.sagepay.com/ Sage Pay]
| Sage Pay Go - Direct Interface
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
| 3d Secure built in
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://www.securepay.com/ SecurePay.com Inc.]
| SecurePay USA  
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|
|
|
|
|
|
|
|- style="vertical-align:top;"
| [http://www.securepay.com.au/ SecurePay - A Business of Australia Post]
| SecurePay Australia
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|
|
|
|
|
|
|- style="vertical-align:top;"
| [https://www.simplify.com/commerce/ MasterCard]
| Simplify Commerce by MasterCard
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
|
| [[File:Check.svg|25px]]
|- style="vertical-align:top;"
| [http://www.skipjack.com/ Skipjack Financial Services, Inc.]
| SkipJack
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
|
|
|
|
|
|- style="vertical-align:top;"
| [http://www.usaepay.com/ GorCorp Inc.]
| USA ePay - Transaction Gateway API
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
|
|
|
|
| [[File:Check.svg|25px]]
|
|- style="vertical-align:top;"
| [http://www.elavon.com/ Elavon, Inc.]
| Virtual Merchant - Merchant Provided Form
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
|
|
|
|
|
|
|
|
|
|- style="vertical-align:top;"
| [http://www.plugnpay.com/ Plug and Pay Technologies]
| WebXpress
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
|
|
|
|
| [[File:Check.svg|25px]]
|
|- style="vertical-align:top;"
| [http://www.worldpay.com/ Worldpay]
| Worldpay Corporate Gateway - Direct Model
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p, m
|
|
|
|
| 3d Secure built in
|
|- style="vertical-align:top;"
| [http://www.worldpay.us/ WorldPay US, Inc.]
| WorldPay US  
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]]
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]] + p
| [[File:Check.svg|25px]] + p
|
|
|
|
|
| [[File:Check.svg|25px]]
|-
|}

[[Category:X-Payments User Manual]]

XPH:About

2016-02-10T11:13:25Z

Alex “Ambal” Mulin: /* Trademark policy */

<div style="background: #F7F7F7; border: 1px solid #999999; padding: 1em; ">
<big>
[[File:information.gif]] The goal of this website is to provide help on using X-Payments.

</big>
 
 
The list of Help resources available on X-Payments can be found on the [[Main_Page | Main Page]]. 
The following links provide some additional ways of browsing the site content that may be helpful:
* [[Special:Allpages/X-Payments:]] - Lists all pages in the X-Payments: namespace.
* [[Special:RecentChanges]] - Provides a list of recent changes.
 
{{Note1}} '''This website should not be used as a discussion board or support desk'''. Any support inquiries should be posted to Message board under your {{QA}}.
</div>

==Editorial guidelines==

* Please note that all help articles on X-Payments in this MediaWiki installation must be created in the "X-Payments" namespace. To achieve this, use "X-Payments" as a prefix when naming your pages. The correct format is "X-Payments:Name_of_page".

* Feel free to create and use [[:Category:Info templates|Templates]]

* Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software.

==Privacy policy==

See http://www.x-cart.com/privacy-policy.html

==Trademark policy==

See http://www.x-cart.com/trademark-policy.html

==API==

Read http://www.mediawiki.org/wiki/API on how to use MediaWiki API for retrieving data contained within this portal.

__NOTOC__

XPH:About

2016-02-10T11:13:12Z

Alex “Ambal” Mulin: /* Privacy policy */

<div style="background: #F7F7F7; border: 1px solid #999999; padding: 1em; ">
<big>
[[File:information.gif]] The goal of this website is to provide help on using X-Payments.

</big>
 
 
The list of Help resources available on X-Payments can be found on the [[Main_Page | Main Page]]. 
The following links provide some additional ways of browsing the site content that may be helpful:
* [[Special:Allpages/X-Payments:]] - Lists all pages in the X-Payments: namespace.
* [[Special:RecentChanges]] - Provides a list of recent changes.
 
{{Note1}} '''This website should not be used as a discussion board or support desk'''. Any support inquiries should be posted to Message board under your {{QA}}.
</div>

==Editorial guidelines==

* Please note that all help articles on X-Payments in this MediaWiki installation must be created in the "X-Payments" namespace. To achieve this, use "X-Payments" as a prefix when naming your pages. The correct format is "X-Payments:Name_of_page".

* Feel free to create and use [[:Category:Info templates|Templates]]

* Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software.

==Privacy policy==

See http://www.x-cart.com/privacy-policy.html

==Trademark policy==

See http://www.qtmsoft.com/trademark-policy.html

==API==

Read http://www.mediawiki.org/wiki/API on how to use MediaWiki API for retrieving data contained within this portal.

__NOTOC__

X-Payments:API

2015-12-18T09:05:07Z

Alex “Ambal” Mulin: /* Check cart callback request */

== API versions supported ==

'''API v1.1''': X-Payments 1.0.2-1.0.5 
'''API v1.2''': X-Payments 1.0.6, 2.0.0, 2.0.1 
'''API v1.3''': X-Payments 2.1.0, 2.1.1 
'''API v1.4''': X-Payments 2.1.2 (Nov 2014), 2.1.3 (Feb 2015) 
'''API v1.5''': X-Payments 2.2 (June 2015) 
'''API v1.6''': X-Payments 2.3 (planned) 

==API requests==

All API requests are made to the '''httрs://<xpayments_url>/api.php''' URL.
Only HTTPS protocol is used.
A request is an XML document that is encrypted using RSA method with a key generated by X-Payments.

'''Request/Response encryption'''

* Encryption method used: RSA;
* Key length: 2048 bit;
* A private key is created with a 32 character password;
* The password is generated randomly;
* The number of password characters varies from 33 to 127.

For each online store X-Payments generates 2 pairs of keys:

# a public and a private key to encrypt requests/responses from the online store to X-Payments;
# a public and a private key to encrypt requests/responses from X-Payments to the online store.

So when the online store sends a request to X-Payments, this request is encrypted using the public key from the first pair, X-Payments decrypts it using the private key of the first pair. Then X-Payments response is encrypted using the public key of the second pair, and the online store decrypts this response using the private key of the second pair.

To ensure full-featured two-way commumication between X-Payments and an online store, you need to copy tree values from the X-Payments interface:
:* Public key from the first pair (Online store → X-Payments),
:* Private key from the second pair (X-Payments → Online store),
:* Private key password,
and have them stored on the side of the online store by an appropriate X-Payments connector.

'''Encryption algorithm:'''

# An empty string is created for pre-prepared data.
# A 32-character salt-block is formed of random characters from 33 to 255.
# The length of the salt-block in bites is taken and transformed into a 12-character string by adding zeros before it.
# The salt-block length string and the salt-block are added to the pre-prepared data.
# MD5 digital signature is taken from the data. The signature is formed as a HEX (32-character string).
# The length of the digital signature in bites is taken and transformed into a 12-character string by adding zeros before it.
# The digital signature length string and the digital signature are added to the pre-prepared data.
# The length of the data string in bites is taken and transformed into a 12-character string by adding zeros before it.
# The data string length string and the data string are added to the pre-prepared data.
# The string of pre-prepared data is divided into 128 bite chunks.
# Each chunk is encrypted using a public key.
# Each chunk is encoded with base64.
# Chunks are glued together using a line feed character (0x0a).
# API prefix is added to the glued chunks.

===cURL as a means of sending requests===

Using libcurl v.7.10 and above is recommended.

TTL should be specified depending on the performance of the server where X-Payments is installed. The recommended value is 120 seconds.

It is recommended to use SSL v.3 and above.

===Data types===

Data types used:

* string - a UTF-8 string;
* email - an email address no longer than 255 characters;
* URL - a URL address no longer than 255 characters;
* currency - a floating point number denoting a certain sum of money. The mantissa size is the same as the payment currency mantissa size, but not longer than 3. All the exceeding characters will be truncated.
* integer - an integer number.

ISO 4217 Alpha-3 in the upper register is always used as the payment currency code.

ISO 639-1 Alpha-2 in the lower register is always used as the language code.

==Payment configurations list request==

Returns a list of payment configurations that are configured, enabled, and assigned to this online store/shopping cart.

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment_confs
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal get
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}
 

===Request example===

<pre>
<api_version>1.5</api_version>
<target>payment_confs</target>
<action>get</action>
</pre>
 

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | payment_module
| colspan="1" | container
| colspan="1" |
|-
| colspan="1" | payment_module/name
| colspan="1" | string
| colspan="1" | Name of the payment configuration, as set by the X-Payments admin
|-
| colspan="1" | payment_module/id
| colspan="1" | integer
| colspan="1" | Identifier of the payment configuration (autoincrement)
|-
| colspan="1" | payment_module/transactionTypes
| colspan="1" | container
| colspan="1" |
|-
| colspan="1" | payment_module/transactionTypes/sale
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Sale" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/auth
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Authorize only" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/capture
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Capture" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/capturePart
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows partial "Capture" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/captureMulti
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows multiple "Capture" operations ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/void
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Void" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/voidPart
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows partial "Void" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/voidMulti
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows multiple "Void" operations ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/refund
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Refund" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/refundPart
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows partial "Refund" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/refundMulti
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows multiple "Refund" operations ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/getInfo
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows to receive information from the payment gateway ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/accept
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Accept" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/decline
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Decline" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/transactionTypes/test
| colspan="1" | string
| colspan="1" | Whether the payment configuration allows "Test" operation ("1" - allows, "" empty - doesn't allow)
|-
| colspan="1" | payment_module/authCaptureInfo
| colspan="1" | container
| colspan="1" |
|-
| colspan="1" | payment_module/authCaptureInfo/authExp
| colspan="1" | integer
| colspan="1" | How many days the transaction can stay in the Authorized status before being declined automatically
|-
| colspan="1" | payment_module/authCaptureInfo/captMinLimit
| colspan="1" | float
| colspan="1" | Minimum capture limit allowed by the payment gateway. Presented as a part of 1 (0 - no minimum limit, 0.2 - minimum 20% of authorized total, 0.5 - 50% of authorized total, etc.)
|-
| colspan="1" | payment_module/authCaptureInfo/captMaxLimit
| colspan="1" |
| colspan="1" | Maximum capture limit allowed by the payment gateway. Presented as a part of 1 (0 - no maximum limit, 0.5 - 50% of authorized total, 1 - 100% of authorized total, etc.)
|-
| colspan="1" | payment_module/moduleName
| colspan="1" | string
| colspan="1" | Default X-Payments name of the payment configuration
|-
| colspan="1" | payment_module/settingsHash
| colspan="1" | string
| colspan="1" | MD5 hash of the payment configuration settings
|-
| colspan="1" | payment_module/currency
| colspan="1" | string
| colspan="1" | 3-characters code of currency (ISO 4217). API v1.3 and later.
|-
| colspan="1" | payment_module/canSaveCards
| colspan="1" | string
| colspan="1" | Whether the payment configuration supports tokenization, i.e. customers' credit card can be saved on the payment gateway ("Y" - supports, "N" - doesn't support). API v1.3 and later.
|-
| colspan="1" | payment_module/class
| colspan="1" | string
| colspan="1" | Service field of the class name. It is unique for a payment module so it can be used to detect a certain payment gateway. E.g. XPay_Module_SagePayDirect for SagePay, XPay_Module_AuthorizeNet for Authorize.Net AIM, etc. API v1.4 and later.
|-
| colspan="1" | payment_module/isTestMode
| colspan="1" | string
| colspan="1" | Indicates if the payment configuration is configured in test mode ("Y" - test mode, "N" - live mode). API v1.4 and later.
|}
 

===Response example===

<pre>
<data>
<payment_module type="cell">
<name>First Data Global Gateway e4(SM) Web Service API</name>
<id>1</id>
<transactionTypes>
<sale>1</sale>
<auth>1</auth>
<capture>1</capture>
<capturePart>1</capturePart>
<captureMulti></captureMulti>
<void>1</void>
<voidPart></voidPart>
<voidMulti></voidMulti>
<refund>1</refund>
<refundPart>1</refundPart>
<refundMulti>1</refundMulti>
<getInfo></getInfo>
<accept></accept>
<decline></decline>
<test></test>
</transactionTypes>
<authCaptureInfo>
<authExp>30</authExp>
<captMinLimit>0</captMinLimit>
<captMaxLimit>1</captMaxLimit>
</authCaptureInfo>
<moduleName>First Data Payeezy Gateway (ex- Global Gateway e4)</moduleName>
<settingsHash>d41d8cd98f00b204e9800998ecf8427e</settingsHash>
<currency>USD</currency>
<canSaveCards>Y</canSaveCards>
<class>XPay_Module_FirstDataE4</class>
<isTestMode>Y</isTestMode>
</payment_module>
<payment_module type="cell">
<name>Chase Paymentech</name>
<id>2</id>
<transactionTypes>
<sale>1</sale>
<auth>1</auth>
<capture>1</capture>
<capturePart>1</capturePart>
<captureMulti></captureMulti>
<void>1</void>
<voidPart></voidPart>
<voidMulti></voidMulti>
<refund>1</refund>
<refundPart>1</refundPart>
<refundMulti></refundMulti>
<getInfo></getInfo>
<accept></accept>
<decline></decline>
<test></test>
</transactionTypes>
<authCaptureInfo>
<authExp>30</authExp>
<captMinLimit>0</captMinLimit>
<captMaxLimit>1</captMaxLimit>
</authCaptureInfo>
<moduleName>Chase Paymentech</moduleName>
<settingsHash>d41d8cd98f00b204e9800998ecf8427e</settingsHash>
<currency>USD</currency>
<canSaveCards>Y</canSaveCards>
<class>XPay_Module_Chase</class>
<isTestMode>Y</isTestMode>
</payment_module>
</data>
</pre>
 

==Test connection request==
Use this request to test the connection between the store and X-Payments. It can also help to detect the version of the X-Payments installation and the API version supported by X-Payments.

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal connect
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal test
|-
| colspan="1" | testCode
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Any string
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}
 

===Request example===

<pre>
<testCode>123</testCode>
<api_version>1.5</api_version>
<target>connect</target>
<action>test</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | hashCode
| colspan="1" | string
| colspan="1" | MD5 hash of the sent code
|-
| colspan="1" | error
| colspan="1" | string
| colspan="1" | Error code (if any)
|-
| colspan="1" | error_message
| colspan="1" | string
| colspan="1" | Error message
|-
| colspan="1" | is_error_message
| colspan="1" | string
| colspan="1" | Flag indicating the error message presence
|-
| colspan="1" | version
| colspan="1" | string
| colspan="1" | X-Payments version
|}
 

===Response example===

Example of a good response:
<pre>
<data>
<hashCode>202cb962ac59075b964b07152d234b70</hashCode>
<error></error>
<error_message></error_message>
<is_error_message></is_error_message>
<version>2.2.0</version>
</data>
</pre>

Example of a response with an error:
<pre>
<data>
<error>506</error>
<error_message>Your X-Payments connector module supports API version "1.9". This X-Payments supports the following API versions only: "1.1, 1.2, 1.3, 1.4, 1.5, 1.6".</error_message>
<is_error_message></is_error_message>
</data>
</pre>
 

==Payment initialisation request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal init
|-
| colspan="1" | confId
| colspan="1" | Y
| colspan="1" | integer
| colspan="1" | Payment module configuration ID
|-
| colspan="1" | refId
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Order ID in the online store
|-
| colspan="1" | returnUrl
| colspan="1" | Y
| colspan="1" | URL, 255
| colspan="1" | URL of the page to redirect the customer after payment
|-
| colspan="1" | callbackUrl
| colspan="1" | Y
| colspan="1" | URL, 255
| colspan="1" | URL to which X-Payments sends background requests with service information
|-
| colspan="1" | language
| colspan="1" | N
| colspan="1" | code of ISO 639-1 (Alpha-2)
| colspan="1" | Language code. If not specified - en
|-
| colspan="1" | cart
| colspan="1" | Y
| colspan="1" | container
| colspan="1" | A container with addresses description
|-
| colspan="1" | cart/billingAddress
| colspan="1" | Y
| colspan="1" | container
| colspan="1" | A container with the billing address description
|-
| colspan="1" | cart/billingAddress/firstname
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/lastname
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/company
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/address
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/city
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/state
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/country
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/zipcode
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/email
| colspan="1" | Y
| colspan="1" | emai, 255l
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/phone
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/billingAddress/fax
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress
| colspan="1" | Y
| colspan="1" | container
| colspan="1" | A container with the shipping address description
|-
| colspan="1" | cart/shippingAddress/firstname
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/lastname
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/company
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/address
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/city
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/state
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/country
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/zipcode
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/email
| colspan="1" | Y
| colspan="1" | email, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/phone
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/shippingAddress/fax
| colspan="1" | N
| colspan="1" | string, 255
| colspan="1" |
|-
| colspan="1" | cart/items
| colspan="1" | Y
| colspan="1" | container
| colspan="1" | A container with product description
|-
| colspan="1" | cart/items/sku
| colspan="1" | Y
| colspan="1" | string, 64
| colspan="1" | SKU (product code)
|-
| colspan="1" | cart/items/name
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" | Product name
|-
| colspan="1" | cart/items/price
| colspan="1" | Y
| colspan="1" | currency
| colspan="1" | Product item price
|-
| colspan="1" | cart/items/quantity
| colspan="1" | N
| colspan="1" | integer
| colspan="1" | Ordered number of products. If not specified - 1
|-
| colspan="1" | cart/login
| colspan="1" | Y
| colspan="1" | string, 255
| colspan="1" | Unique customer ID in the online store (login, username, userid, etc.)
|-
| colspan="1" | cart/currency
| colspan="1" | N
| colspan="1" | string, 3
| colspan="1" | Payment currency code (ISO 4217 Alpha-3). If not specified, default payment configuration currency is used
|-
| colspan="1" | cart/shippingCost
| colspan="1" | -
| colspan="1" | currency
| colspan="1" | Shipping cost. By default - 0
|-
| colspan="1" | cart/taxCost
| colspan="1" | -
| colspan="1" | currency
| colspan="1" | Tax amount. By default - 0
|-
| colspan="1" | cart/discount
| colspan="1" | -
| colspan="1" | currency
| colspan="1" | Discount amount. By default - 0
|-
| colspan="1" | cart/totalCost
| colspan="1" | Y
| colspan="1" | currency
| colspan="1" | Total payment amount. Must equal to a sum of cart/items/price * cart/items/quantity + cart/shippingCost + cart/taxCost - cart/discount
|-
| colspan="1" | cart/description
| colspan="1" | -
| colspan="1" | string, 65536
| colspan="1" |
|-
| colspan="1" | cart/merchantEmail
| colspan="1" | Y
| colspan="1" | email, 255
| colspan="1" |
|-
| colspan="1" | cart/forceTransactionType
| colspan="1" | -
| colspan="1" | one of values: A or S or empty A - authorize S - sale
| colspan="1" | A flag of forced Sale or Authorize operation. Overrides the setting from the payment configuration. If the value is empty or the field is omitted, the operation is performed according to the payment configuration settings.
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|-
| colspan="1" | template (''supported by API 1.3 and later'')
| colspan="1" | N
| colspan="1" | string
| colspan="1" | The name of a template in X-Payments requested by the store. Forces the use of the specified template for the payment. If the string passed in this field does not match any template available in X-Payments, it will be ignored.
|-
| colspan="1" | saveCard (''supported by API 1.3 and later'')
| colspan="1" | N
| colspan="1" | string
| colspan="1" | Customer's choice at checkout (“Y” if customer would like to save the card)
|-
| colspan="1" | cart/kountCustomerUniq (''supported by API 1.6 and later'')
| colspan="1" | N
| colspan="1" | string, 32
| colspan="1" | This field is a unique customer identifier in the Kount system, which is send as a UNIQ field.
|}
 
'''List of template names in X-Payments 2.1.x (API v1.3)''':
:* '''default''': A template for the separate page. Used if the payment form is displayed on a separate page of your checkout process (not iframe).
:* '''fast''': Iframe for X-Cart 4 Fast Lane Checkout. Used for X-Cart 4 with the Fast Lane Checkout module. The payment form is displayed at the last step of the checkout process.
:* '''lite''': Iframe for X-Cart 4 One Page Checkout. Used for X-Cart 4 with the One Page Checkout module. The payment form is displayed in the payment section at checkout.
:* '''magento_iframe''': Iframe for Magento. Use this template for Magento and iframe.
:* '''mobile''': Template for mobile devices. Used with the X-Cart Mobile module.
:* '''xc5''': Iframe for X-Cart 5. Used for X-Cart 5 and iframe.

===Request example===

<pre>
<confId>8</confId>
<refId>1120</refId>
<cart>
<login>customer</login>
<billingAddress>
<firstname>John</firstname>
<lastname>Smith</lastname>
<address>10 Main street</address>
<city>Fillmore</city>
<state>UT</state>
<country>US</country>
<zipcode>84631</zipcode>
<company>IQ testing</company>
<email>bit-bucket@x-cart.com</email>
<phone>927348572</phone>
<fax></fax>
</billingAddress>
<shippingAddress>
<firstname>John</firstname>
<lastname>Smith</lastname>
<address>10 Main street</address>
<city>Fillmore</city>
<state>UT</state>
<country>US</country>
<zipcode>84631</zipcode>
<company>IQ testing</company>
<email>bit-bucket@x-cart.com</email>
<phone>927348572</phone>
<fax></fax>
</shippingAddress>
<items type="cell">
<sku>SKU17513</sku>
<name>Three Stone Princess Cut Diamond Ring</name>
<price>399.99</price>
<quantity>1</quantity>
</items>
<currency>USD</currency>
<shippingCost>15</shippingCost>
<taxCost>0</taxCost>
<discount>0</discount>
<totalCost>414.99</totalCost>
<description>Order(s) #1120</description>
<merchantEmail>bit-bucket@x-cart.com</merchantEmail>
<forceTransactionType></forceTransactionType>
</cart>
<returnUrl>https://example.com/xcart/payment/cc_xpc.php</returnUrl>
<callbackUrl>https://example.com/xcart/payment/cc_xpc.php</callbackUrl>
<language>ru</language>
<target>payment</target>
<action>init</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | token
| colspan="1" | string,32
| colspan="1" | Temporary payment token, expires immediately after the customer has submitted the cardholder data form
|-
| colspan="1" | txnId
| colspan="1" | string,32
| colspan="1" | A unique payment ID. Is used for all further requests to this payment through the API.
|}

===Response example===

<pre>
<data>
<token>41b2ef3b34698d4f6ed73151ae7307d2</token>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<error></error>
<error_message></error_message>
</data>
</pre>

==Redirecting a customer to the cardholder data entering page==

A POST form is created that sends data to the URL <XPayments_web_root>/payment.php; the form contains the following fields:

* target - has the value "main";
* token - uses the value from the token field received in the response to the payment initialisation request.

Request protocol - HTTPS 
The form must be sent by the POST method. All data must also be sent as POST variables.

==Payment information request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal get_info
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | refresh
| colspan="1" | N
| colspan="1" | 0 или 1
| colspan="1" | A flag specifying that the data in X-Payments must be overwritten by the data from the payment gateway. By default - 0
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<refresh>0</target>
<target>payment</target>
<action>get_info</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Payment status codes|Payment status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Human readable message containing the payment status
|-
| colspan="1" | isFraudStatus
| colspan="1" | 0 or 1
| colspan="1" | Means that the payment is blocked by the gateway, because the customer has not passed the gateway security check
|-
| colspan="1" | currency
| colspan="1" | string, 3
| colspan="1" | Payment currency code
|-
| colspan="1" | amount
| colspan="1" | currency
| colspan="1" | Payment total
|-
| colspan="1" | authorized
| colspan="1" | currency
| colspan="1" | Authorized payment total
|-
| colspan="1" | chargedAmount
| colspan="1" | currency
| colspan="1" | Charged payment total
|-
| colspan="1" | capturedAmount
| colspan="1" | currency
| colspan="1" | Captured amount of the authorized amount
|-
| colspan="1" | capturedAmountAvail
| colspan="1" | currency
| colspan="1" | Amount that is authorized and can be captured
|-
| colspan="1" | voidedAmount
| colspan="1" | currency
| colspan="1" | Amount that is authorized but voided
|-
| colspan="1" | voidedAmountAvail
| colspan="1" | currency
| colspan="1" | Amount that is authorized and can be voided
|-
| colspan="1" | refundedAmount
| colspan="1" | currency
| colspan="1" | Amount that can be refunded
|-
| colspan="1" | refundedAmountAvail
| colspan="1" | currency
| colspan="1" | Amount that can be refunded
|-
| colspan="1" | fraudAuthorized
| colspan="1" | currency
| colspan="1" | A part of the authorized amount that was blocked by the gateway because the customer had not passed the gateway security check
|-
| colspan="1" | fraudCharged
| colspan="1" | currency
| colspan="1" | A part of the charged amount that was blocked by the gateway because the customer had not passed the gateway security check
|-
| colspan="1" | authorizeInProgress
| colspan="1" | currency
| colspan="1" | A part of the authorized amount that is being handled by the gateway
|-
| colspan="1" | chargeInProgress
| colspan="1" | currency
| colspan="1" | A part of the charged amount that is being handled by the gateway
|-
| colspan="1" | transactionInProgress
| colspan="1" | 0 или 1
| colspan="1" | Are there any payment transactions handled by the gateway?
|-
| colspan="1" | capturedAmountAvailMin
| colspan="1" | currency
| colspan="1" | Minimum amount that can be captured from the authorized amount
|-
| colspan="1" | capturedAmountAvailGateway
| colspan="1" | currency
| colspan="1" | Amount that can be captured from the authorized amount through the gateway
|-
| colspan="1" | capturedAmountAvailMinGateway
| colspan="1" | currency
| colspan="1" | Minimum amount that can be captured from the authorized amount through the gateway
|-
| colspan="1" | voidedAmountAvailGateway
| colspan="1" | currency
| colspan="1" | Amount that can be voided from the authorized amount through the gateway
|-
| colspan="1" | refundedAmountAvailGateway
| colspan="1" | currency
| colspan="1" | Amount that can be refunded from the authorized amount through the gateway
|-
| colspan="1" | txnId
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | lastMessage
| colspan="1" | string, 65536
| colspan="1" | Last gateway message
|-
| colspan="1" | error
| colspan="1" | string, 128
| colspan="1" | Error code
|-
| colspan="1" | error_message
| colspan="1" | string, 65536
| colspan="1" | Error message
|}

{{Note|Fields ending in "Gateway" contain amounts that can be used in transactions through the gateway. For example, if a sum of $100 was authorized, and then a capture transaction was emulated for $100, the next refund operation will be available in the emulation mode only. The value of the refundedAmountAvailGateway field will be equal to 0.}}

===Response example===

<pre>
<data>
<status>2</status>
<message>Payment is authorized</message>
<isFraudStatus></isFraudStatus>
<currency>USD</currency>
<amount>414.99</amount>
<authorized>414.99</authorized>
<chargedAmount>0.00</chargedAmount>
<capturedAmount>0.00</capturedAmount>
<capturedAmountAvail>414.99</capturedAmountAvail>
<voidedAmount>0.00</voidedAmount>
<voidedAmountAvail>414.99</voidedAmountAvail>
<refundedAmount>0.00</refundedAmount>
<refundedAmountAvail>0.00</refundedAmountAvail>
<fraudAuthorized>0.00</fraudAuthorized>
<fraudCharged>0.00</fraudCharged>
<authorizeInProgress>0.00</authorizeInProgress>
<chargeInProgress>0.00</chargeInProgress>
<transactionInProgress></transactionInProgress>
<capturedAmountAvailMin>0.00</capturedAmountAvailMin>
<capturedAmountAvailGateway>414.99</capturedAmountAvailGateway>
<capturedAmountAvailMinGateway>0.00</capturedAmountAvailMinGateway>
<voidedAmountAvailGateway>414.99</voidedAmountAvailGateway>
<refundedAmountAvailGateway>0.00</refundedAmountAvailGateway>
<txnId>8e67e0da23ce7ed451b2c1adbbd7373c</txnId>
<lastMessage>Success</lastMessage>
<error></error>
<error_message></error_message>
</data>
</pre>

==Detailed payment and transaction information request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal get_additional_info
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | A unique payment ID received in the payment initialisation request response
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<target>payment</target>
<action>get_additional_info</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | payment
| colspan="1" | container
| colspan="1" | Payment information request response
|-
| colspan="1" | transactions
| colspan="1" | container
| colspan="1" | Transaction list
|-
| colspan="1" | transactions/date
| colspan="1" | integer, 11
| colspan="1" | Transaction date (Unix timestamp)
|-
| colspan="1" | transactions/action
| colspan="1" | string, 255
| colspan="1" | Transaction name
|-
| colspan="1" | transactions/status
| colspan="1" | string, 255
| colspan="1" | Transaction status
|-
| colspan="1" | transactions/message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|-
| colspan="1" | transactions/total
| colspan="1" | string, 32
| colspan="1" | Transaction amount and currency
|-
| colspan="1" | transactions/txnid
| colspan="1" | string, 255
| colspan="1" | Gateway transaction unique ID
|-
| colspan="1" | transactions/payment_status
| colspan="1" | string, 255
| colspan="1" | The payment status after the transaction
|-
| colspan="1" | transactions/fields
| colspan="1" | container
| colspan="1" | Transaction additional fields list
|-
| colspan="1" | transactions/fields/name
| colspan="1" | string, 255
| colspan="1" | Field name
|-
| colspan="1" | transactions/fields/name
| colspan="1" | string, 255
| colspan="1" | Field value
|-
| colspan="1" | payment/cardValidation (API 1.5 and later)
| colspan="1" | container
| colspan="1" | container for Address validation system (AVS)
|-
| colspan="1" | payment/cardValidation/avs_z (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Flag for AVS ZIP-code ("0" - unknown, "1" - matches, "2" - does not match)
|-
| colspan="1" | payment/cardValidation/avs_c (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Flag for AVS cardholder name ("0" - unknown, "1" - matches, "2" - does not match)
|-
| colspan="1" | payment/cardValidation/avs_a (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Flag for AVS street address ("0" - unknown, "1" - matches, "2" - does not match)
|-
| colspan="1" | payment/cardValidation/cvv (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Flag for CVV/CVV2/CVD ("0" - unknown, "1" - matches, "2" - does not match)
|-
| colspan="1" | payment/maskedCardData (API 1.5 and later)
| colspan="1" | container
| colspan="1" | container for Credit Card details (which are allowed to store and display by PA-DSS)
|-
| colspan="1" | payment/maskedCardData/first6 (API 1.5 and later)
| colspan="1" | string
| colspan="1" | First six digits of the credit card number
|-
| colspan="1" | payment/maskedCardData/last4 (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Last four digits of the credit card number
|-
| colspan="1" | payment/maskedCardData/type (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Credit card type: VISA, MC, AMEX, etc
|-
| colspan="1" | payment/maskedCardData/expire_month (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Credit card expiration month
|-
| colspan="1" | payment/maskedCardData/expire_year (API 1.5 and later)
| colspan="1" | string
| colspan="1" | Credit card expiration year
|}

===Response example===

<pre>
<data>
<payment>
<status>2</status>
<message>Payment is authorized</message>
<isFraudStatus>1</isFraudStatus>
<currency>USD</currency>
<amount>10.61</amount>
<authorized>10.61</authorized>
<chargedAmount>0.00</chargedAmount>
<capturedAmount>0.00</capturedAmount>
<capturedAmountAvail>10.61</capturedAmountAvail>
<voidedAmount>0.00</voidedAmount>
<voidedAmountAvail>10.61</voidedAmountAvail>
<refundedAmount>0.00</refundedAmount>
<refundedAmountAvail>0.00</refundedAmountAvail>
<fraudAuthorized>0.00</fraudAuthorized>
<fraudCharged>0.00</fraudCharged>
<authorizeInProgress>0.00</authorizeInProgress>
<chargeInProgress>0.00</chargeInProgress>
<advinfo>
<Message></Message>
<Response code>1</Response>
<txn_id>6583</txn_id>
<Authorization number>ET154399</Authorization>
<AVS>5: Cardholder name incorrect, billing address and postal code match</AVS>
<Bank message>Approved</Bank>
<Bank response code>100</Bank>
<CVV2>M: CVV2 / CVC2/CVD Match.</CVV2>
<Processing status>Transaction Normal</Processing>
<Transarmor Token>8393008475641111</Transarmor>
<[Kount] 702650>Distance from Device to Billing > 1000km</[Kount] 702650>
<[Kount] 702656>Billing Country not equal to BIN Country (Visa/MC)</[Kount] 702656>
<[Kount] 702662>Billing Country not equal to Device Country</[Kount] 702662>
<[Kount] Auto>R</[Kount] Auto>
<[Kount] Errors></[Kount] Errors>
<[Kount] Score>26</[Kount] Score>
<[Kount] Transaction ID>3Z7903KDCTT0</[Kount] Transaction ID>
<[Kount] Warnings></[Kount] Warnings>
</advinfo>
<transactionInProgress></transactionInProgress>
<capturedAmountAvailMin>0.00</capturedAmountAvailMin>
<capturedAmountAvailGateway>10.61</capturedAmountAvailGateway>
<capturedAmountAvailMinGateway>0.00</capturedAmountAvailMinGateway>
<voidedAmountAvailGateway>10.61</voidedAmountAvailGateway>
<refundedAmountAvailGateway>0.00</refundedAmountAvailGateway>
<cardValidation>
<avs_z>1</avs_z>
<avs_c>2</avs_c>
<avs_a>1</avs_a>
<cvv>1</cvv>
</cardValidation>
<maskedCardData>
<first6>411111</first6>
<last4>1111</last4>
<type>VISA</type>
<expire_month>03</expire_month>
<expire_year>2020</expire_year>
</maskedCardData>
</payment>
<transactions type="cell">
<date>1438098759</date>
<action>Authorize</action>
<status>Success</status>
<message>Transaction Normal</message>
<total>10.61 USD</total>
<txnid>57629270</txnid>
<fields type="cell">
<name>Authorization number</name>
<value>ET154399</value>
</fields>
<fields type="cell">
<name>AVS</name>
<value>5: Cardholder name incorrect, billing address and postal code match</value>
</fields>
<fields type="cell">
<name>Bank message</name>
<value>Approved</value>
</fields>
<fields type="cell">
<name>Bank response code</name>
<value>100</value>
</fields>
<fields type="cell">
<name>CVV2</name>
<value>M: CVV2 / CVC2/CVD Match.</value>
</fields>
<fields type="cell">
<name>Processing status</name>
<value>Transaction Normal</value>
</fields>
<fields type="cell">
<name>Transarmor Token</name>
<value>8393008475641111</value>
</fields>
<fields type="cell">
<name>[Kount] 702650</name>
<value>Distance from Device to Billing > 1000km</value>
</fields>
<fields type="cell">
<name>[Kount] 702656</name>
<value>Billing Country not equal to BIN Country (Visa/MC)</value>
</fields>
<fields type="cell">
<name>[Kount] 702662</name>
<value>Billing Country not equal to Device Country</value>
</fields>
<fields type="cell">
<name>[Kount] Auto</name>
<value>R</value>
</fields>
<fields type="cell">
<name>[Kount] Score</name>
<value>26</value>
</fields>
<fields type="cell">
<name>[Kount] Transaction ID</name>
<value>3Z7903KDCTT0</value>
</fields>
<payment_status>Charged</payment_status>
</transactions>
<error></error>
<error_message></error_message>
<is_error_message></is_error_message>
<version>2.2.0</version>
</data>
</pre>

 
''The following pertains to API 1.5 and later:'' 
If the transaction was checked by Kount antifraud screening service, the "advinfo" and "tansaction/fields" containers contain information of kount results. The field names related to Kount start with the [Kount] prefix. The information can be extracted as follows:

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Description'''
|-
| colspan="1"| [Kount] %%%%%, where %%%%% is some number
| colspan="1"| triggered rule, the number is the number of this rule
|-
| colspan="1"| [Kount] Auto
| colspan="1"| The status of the transaction in Kount ("R" - review, "D" - declined, "A" - approved)
|-
| colspan="1"| [Kount] Errors
| colspan="1"| list of errors (if any)
|-
| colspan="1"| [Kount] Warnings:
| colspan="1"| list of warnings (if any)
|-
| colspan="1"| [Kount] Score
| colspan="1"| Risk score
|-
| colspan="1"| [Kount] Transaction ID
| colspan="1"| Transaction ID in Kount, can be used to display the direct link to the transaction in Kount, https://awc.test.kount.net/workflow/detail.html?id=%%%%%% for test mode or https://awc.kount.net/workflow/detail.html?id=%%%%%%, where %%%%% should be replaced with the transaction ID
|}
 

==Capture authorized transaction request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string,128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal capture
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | amount
| colspan="1" | N
| colspan="1" | currency
| colspan="1" | The amount to capture from the previously authorized transaction. By default equals the amount of the authorized transaction
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

=== Request example ===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<target>payment</target>
<action>capture</action>
</pre>

===Response example===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|}

Response example <pre><data>
<status>1</status>
<message>Success</message>
<error></error>
<error_message></error_message>
</data>
</pre>

==Void authorized transaction request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal void
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | amount
| colspan="1" | N
| colspan="1" | currency
| colspan="1" | Amount to void of the authorized transaction. By default equals to the amount of the authorized transaction
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<target>payment</target>
<action>void</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|}

===Response example===

<pre>
<data>
<status>1</status>
<message>Success</message>
<error></error>
<error_message></error_message>
</data>
</pre>

==Refund captured transaction request==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal capture
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | amount
| colspan="1" | N
| colspan="1" | currency
| colspan="1" | Amount to be refunded to the customer of the previously captured transactions. By default equals to the amount of captured transactions
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre><txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<target>payment</target>
<action>refund</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|}

===Response example===

<pre><data>
<status>1</status>
<message>Success</message>
<error></error>
<error_message></error_message>
</data>
</pre>

==Blocked by gateway transaction accept request (Accept)==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal accept
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<target>payment</target>
<action>accept</action>
</pre>

===Response example===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|}

Response example <pre><data>
<status>1</status>
<message>Success</message>
<error></error>
<error_message></error_message>
</data>
</pre>

==Blocked by gateway transaction decline request (Decline)==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal decline
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<target>payment</target>
<action>decline</action>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | message
| colspan="1" | string, 65536
| colspan="1" | Gateway transaction message
|}

===Response example===

<pre>
<data>
<status>1</status>
<message>Success</message>
<error></error>
<error_message></error_message>
</data>
</pre>

==Charge again transaction request (Tokenization)==

===Request specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | target
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal payment
|-
| colspan="1" | action
| colspan="1" | Y
| colspan="1" | string, 128
| colspan="1" | Must equal recharge
|-
| colspan="1" | txnId
| colspan="1" | Y
| colspan="1" | string, 32
| colspan="1" | Unique payment ID which references the token that will be used to identify the payment on the side of the payment gateway
|-
| colspan="1" | amount
| colspan="1" | Y
| colspan="1" | currency
| colspan="1" | The amount for which the "saved" card is to be charged using the token from the previous successful transaction
|-
| colspan="1" | description
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Description of the transaction
|-
| colspan="1" | api_version
| colspan="1" | Y
| colspan="1" | string
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
|-
| colspan="1" | refId (supported by API 1.4 and later)
| colspan="1" | N
| colspan="1" | string, 128
| colspan="1" | Order ID in the online store
|}

===Request example===

<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<description>Recurring payment for the new issue of Playboy</description>
<target>payment</target>
<action>recharge</action>
<api_version>1.2</api_version>
</pre>

===Response specification===

{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | integer, 1
| colspan="1" | [[#Operation status codes|Operation status code]]
|-
| colspan="1" | data
| colspan="1" | array
| colspan="1" |
|-
| colspan="1" | data[status]
| colspan="1" | integer
| colspan="1" | Status of the new payment (See [[#Payment status codes|Payment status codes]])
|-
| colspan="1" | data[transaction_id]
| colspan="1" | string
| colspan="1" | ID of the created payment for further references (capture/void/refund etc)
|-
| colspan="1" | data[error]
| colspan="1" | string
| colspan="1" |
|-
| colspan="1" | data[error_message]
| colspan="1" | string
| colspan="1" |
|-
| colspan="1" | data[is_error_message]
| colspan="1" | string
| colspan="1" |
|}
 

==Callback request with service payment information==

This is a background request that X-Payments sends to the store after a payment has been completed and it’s result (accepted, declined, etc) has been received from the payment gateway. The request is sent via HTTP POST to the callbackURL defined in the Payment initialisation request. Once this request has been sent, the customer is redirected back to the store.

===POSTed data===
{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Value'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | action
| colspan="1" | callback
| colspan="1" | fixed string
| colspan="1" | Identifies the callback request
|-
| colspan="1" | txnId
| colspan="1" | (mixed)
| colspan="1" | string (MD5 hash)
| colspan="1" | A unique ID of the payment on the side of X-Payments
|-
| colspan="1" | updateData
| colspan="1" | (mixed)
| colspan="1" | string
| colspan="1" | Encrypted response from X-Payments
|}

X-Payments does not expect a response from the store for this request; however, if the HTTP status of the response is not 200 OK, the request is considered failed, and a special notification is sent to the X-Payments admin. The store needs to decrypt the encrypted part of the response and update the order on its side accordingly. Once the updateData value has been decrypted, it is an XML document with the same structure as the [[X-Payments:API#Response_specification_2|response for Payment information request]].
 

==Check cart callback request==

After the customer has submitted credit card data, right before sending this data to the payment gateway, X-Payments connects to the store to verify the cart total and contents.

The HTTP POST request is sent to the '''callbackURL''' defined in the '''Payment initialisation request'''.

===POSTed data===
{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Value'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | action
| colspan="1" | check_cart
| colspan="1" | fixed string
| colspan="1" | Identifies the check-cart callback request
|-
| colspan="1" | txnId
| colspan="1" | (mixed)
| colspan="1" | string (MD5 hash)
| colspan="1" | A unique ID of the payment on the side of X-Payments
|-
| colspan="1" | refId
| colspan="1" | (mixed)
| colspan="1" | string
| colspan="1" | Order ID (or any other reference) in the online store
|}
 
As of API v1.3, the store must respond to this callback request. The response must be an encrypted XML document (i.e. the same way as for other communication between the store and X-Payments).

===Encrypted response for check-cart callback request===
{| cellspacing="0" cellpadding="2" border="1"
| colspan="1" | '''Field'''
| colspan="1" | '''Required'''
| colspan="1" | '''Type'''
| colspan="1" | '''Description'''
|-
| colspan="1" | status
| colspan="1" | Y
| colspan="1" | fixed string
| colspan="1" | Should be “cart-changed” or "cart-not-changed"
|-
| colspan="1" | cart
| colspan="1" | Y
| colspan="1" | container
| colspan="1" | A container with cart/order description. See [[X-Payments:API#Request_specification|Payment initialisation request specification]] for details. This container must be included for "status = cart-changed" and is not necessary for "status = cart-not-changed"
|-
| colspan="1" | saveCard
| colspan="1" | N
| colspan="1" | string
| colspan="1" | Whether the customer has chosen to save their card for future use (“Y” if the customer would like to save the card)
|}
 

==Communication between X-Payments iframe and the store==

===Communication structure===
Communication between the online store (parent frame) and X-Payments (iframe) is implemented with the help of the javascript Window.postMessage method. Notifictions to both the sides represent stringified JSON formatted texts that consist of a service message (string) and an optional list of parameters:
:* '''height''': height of the iframe
:* '''error''': human readable message
:* '''type''': message type. X-Payments sends it as 2, which indicates that the online store should re-initialize the payment. In API v1.3 no other values are supported.

===Messages sent from the online store to X-Payments===
'''Submit payment form''' 
X-Payments’ iframe does not have a Submit button, so instead of it the payment form should be submitted from the parent window by any kind of “Submit order” or “Place order” button at checkout. At the same time, the special message '''submitPaymentForm''' with no parameters should be sent.
-----------------------------------------------------------
{
:::message: 'submitPaymentForm',
:::params: {}
}
-----------------------------------------------------------

 
===Messages sent from X-Payments to the online store===
'''Iframe is loaded and ready''' 
The message ready notifies the parent window that the payment form is ready. The actual height of the iframe is included in the parameters, so the parent window (checkout page) can perform the necessary adjustments.
-----------------------------------------------------------
{
:::message: 'ready',
:::params: {
::::::height: $(document).height()
:::}
}
-----------------------------------------------------------
 
'''Payment form submitted with an error''' 
The message '''paymentFormSubmitError''' with no parameters is sent in the case of any validation error. This may be the case, for example, if the customer’s credit card expiration date is in the past, or the credit card number does not match the card type (e.g. VISA, MasterCard), or when a required field has not been submitted (e.g. CVV2). Once the message '''paymentFormSubmitError''' with no parameters has been received, the store should not proceed to the next step of the checkout process, but should expect the payment form to be submitted again.
-----------------------------------------------------------
{
:::message: 'paymentFormSubmitError',
:::params: {}
}
-----------------------------------------------------------
 
'''Internal error''' 
The '''paymentFormSubmitError''' message with a special set of parameters is used to notify the store if something is wrong outside X-Payments, and X-Payments cannot do anything about it (for example, if the payment gateway has sent an unknown/unexpected piece of data).
-----------------------------------------------------------
{
:::message: 'paymentFormSubmitError',
:::params: {
::::::height: $(document).height(),
::::::error: 'Internal error',
::::::type: '2'
:::}
}
-----------------------------------------------------------
 
'''Session is expired''' 
For security reasons the length of the session is limited to 15 minutes. After this period the store has to re-initialize the payment. In this case X-Payments sends the '''paymentFormSubmitError''' message with the “Payment session expired” error.
-----------------------------------------------------------
{
:::message: 'paymentFormSubmitError',
:::params: {
::::::height: $(document).height(),
::::::error: 'Payment session expired',
::::::type: '2'
:::}
}
-----------------------------------------------------------
 
'''Payment form in Iframe is submitted''' (supported by API v1.4 and later) 
The message '''paymentFormSubmit''' notifies the parent window that the payment form has been submitted from the X-Payments side; for example, if a customer clicks the Enter key inside the iframe. Once the store receives this message, it should operate in the same way as though the customer has clicked the Place order button at checkout.
-----------------------------------------------------------
{
:::message: 'paymentFormSubmit',
:::params: {}
}

-----------------------------------------------------------
 

==Appendix A. Status codes.==

===Payment status codes===
: 1 - New
: 2 - Authorized
: 3 - Declined
: 4 - Charged
: 5 - Refunded
: 6 - Partially refunded

===Operation status codes===
: 0 - transaction failed
: 1 - transaction is successful
: 2 - transaction is successful and is duplicate

==See also==

* [http://lu53.crtdev.local/%7Emixon/google-cache-w.php?q=/index.php?title=X-Cart:X-Payments_Connector X-Cart:X-Payments Connector]

[[Category:X-Payments Developer Guide]]

X-Payments:PCI DSS implementation guide for X-Payments 2.2

2015-12-17T12:03:29Z

Alex “Ambal” Mulin: /* X-Cart Payments versioning policy */

== Introduction ==

This guide covers '''X-Cart Payments''' 1.0, 2.0, 2.1, 2.2 and is intended for merchants and integrators who wish to implement the application in accordance with guidelines set by the PCI Data Security Standard (PCI DSS).

== X-Cart Payments versioning policy ==

X-Cart Payments version number must look like "X.Y.Z" (e.g. 1.0.6, 2.0.1, 2.2.1, 3.0.0), where

* X - major release version number that gets incremented when high impact changes are introduced and certified under PA-DSS requirements;
* Y - minor release version number that gets incremented when low impact changes are added to X-Cart Payments package;
* Z - maintenance/bug-fix release version number that gets incremented when no impact changes are done to X-Cart Payments package.

== PCI DSS ==

PCI DSS specifies 12 requirements broken into 6 groups for compliance that apply both to hardware and software parts of the system that is used to collect, store, transmit and process valuable credit card data as well as the human factor.

{| border
| Build and Maintain a Secure Network
|

* Requirement 1: Install and maintain a firewall configuration to protect cardholder data
* Requirement 2: Do not use vendor-supplied defaults for system passwords and other security parameters
|-
| Protect Cardholder Data
|

* Requirement 3: Protect stored cardholder data
* Requirement 4: Encrypt transmission of cardholder data across open, public networks
|-
| Maintain a Vulnerability Management Program
|

* Requirement 5: Use and regularly update anti-virus software
* Requirement 6: Develop and maintain secure systems and applications
|-
| Implement Strong Access Control Measures
|

* Requirement 7: Restrict access to cardholder data by business need-to-know
* Requirement 8: Assign a unique ID to each person with computer access
* Requirement 9: Restrict physical access to cardholder data
|-
| Regularly Monitor and Test Networks
|

* Requirement 10: Track and monitor all access to network resources and cardholder data
* Requirement 11: Regularly test security systems and processes
|-
| Maintain an Information Security Policy
|

* Requirement 12: Maintain a policy that addresses information security
|}

Specifically, relevant elements to an e-commerce business' PCI compliance status include:

* Properly using your payment application. For this purpose, carefully review the section below for information on how to use '''X-Cart Payments''' in a way that ensures PCI compliance.

* Using a PCI compliant Web hosting environment

* Using a PCI compliant payment provider

You can find and review the complete specification by visiting [https://www.pcisecuritystandards.org/ https://www.pcisecuritystandards.org/]

This guide is intended to help merchants implement the '''X-Cart Payments''' application in a way that is compliant with version 2.0 of the PCI DSS.

== Payment Card Industry Data Security Standard ('''PCI DSS''') ==

The Payment Card Industry Data Security Standard is a worldwide information security standard assembled by the major credit card vendors, including American Express, Discover Financial Services, JCB International, MasterCard Worldwide, and Visa, Inc. The standard was designed to help organizations involved in processing credit card payments online make their payment systems secure from cardholder data fraud.

'''X-Cart Payments''' has been designed and certified to meet all of the requirements of the '''PA-DSS''' version 2.0. This does not automatically make you, the merchant, PCI DSS compliant. To ensure PCI DSS compliance, it is necessary that you follow the recommendations and instructions provided in this guide.

For additional information about '''PCI DSS''' please visit the [https://www.pcisecuritystandards.org Official PCI Security Standards Council Site].

== Cardholder data storage==

'''X-Cart Payments''' has [[X-Payments:General_settings#Cardholder_Data | the ability to store parts of cardholder data temporarily]] for performing 3D Secure verification and certain types of transactions for some of the integrated payment processors. While stored cardholder data is encrypted using special [[X-Payments:Encryption_keys | cryptographic algorithm]]. The data is removed automatically when its storing period is over using "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.

'''X-Cart Payments''' can not be configured to store permanently in the database the following types of data:

* unmasked PAN
* PIN
* CVV
* magnetic stripe (track data)

Merchants and/or developers implementing '''X-Cart Payments''' should not attempt to customize this as a feature.

'''X-Cart Payments''' can display masked PAN on "Payment details" pages and in "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. '''X-Cart Payments''' does not have the ability to display full PAN anywhere and there are no settings that can change this behavior of the user interface.

==Configuring and using '''X-Cart Payments''' in PCI compliant manner ==

===Installation===

Follow the [[X-Payments:Installation | standard procedure]] for deployment of X-Cart Payments files to the web server.

{{Note1|Once installed, X-Cart Payments WILL NEVER: 
* store unmasked credit card numbers (PANs)
* send credit card data or any other information to Qualiteam for debug purposes}}

===Access control===

There are no built-in/default user accounts in '''X-Cart Payments'''.
You must carefully control access to '''X-Cart Payments'''. Follow these rules:

* Restrict the number of employees who have access to '''X-Cart Payments''' to only those who have a business need.
* Always provide unique usernames for each person who needs access.
* Do not use system-default usernames and/or passwords
* Web server must be run under a non-privileged user account. Application must access the database from a limited privilege user account.
* All default user accounts use secure authentication mechanisms and password policy settings that comply with all the standard requirements:
** user accounts inactive for more than 3 days are blocked
** password lifetime is set to 30 days

:: To set password lifetime:

::# Login to '''X-Cart Payments'''
::# Go to Settings -> General Settings
::# Enter the number of days the user account password will be valid for in the "User account password lifetime" field. The maximum allowed password lifetime is 90 days.

:* minimum password length is 8 characters
:* password must contain both lower and upper case characters and numbers
:* the last 4 passwords must be unique
:* user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password
:* user is logged off after inactivity period of 10 minutes

<div> Please note that changing default password policy settings will lead to breaking PCI DSS standard requirements.</div>

===Enabling SSL (Secure Socket Layer)===

SSL protects data that is transmitted between a browser and your web server. It is critical that you have SSL enabled on your web server, and this should be among the first steps taken after installation.

* Your web server must be configured to use TLS v1.2 protocols with strong encryption (128-bit or longer key is required)
* You will need to have a certificate issued for your web domain. Read [http://help.qtmsoft.com/index.php?title=Instant_SSL_certificate guidelines on installing Comodo's Instant SSL certificates].

If a web server does not have SSL enabled '''X-Cart Payments''' will not function or will be notifying users depending on '''allow_insecure_protocol''' parameter set in config.ini.php file (disabled by default).

===Data Collected while Testing===

Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:

# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever collect credit card information to troubleshoot a problem that one of your customers is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access
#* Only collect a limited amount of such data as needed to solve a specific problem
#* Sensitive authentication data must be encrypted while stored. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Such data must be securely deleted immediately after use.

===Encryption Key Management===

As part of your PA DSS v3.1 requirements, encryption key must be changed annually (changing every 90 days is recommended). You should also change the key any time an employee with access to the key leaves your company. Always replace the key if you know or suspect it has been compromised by any means.

To change the encryption keys:

# Log in to '''X-Cart Payments'''
# Go to Maintenance -> Encryption keys
# Click "Generate new keys"

===Use unique user IDs and secure authentication to access PCs, servers and databases ===

PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:

# For your Web hosting account administration area (Web hosting account where your online store is hosted)
# For FTP access to the Web server
# For Remote Desktop Connection to the Web server (if available)
# To connect to the MySQL server that contains your store data.

The passwords for the accounts mentioned above must also meet the following requirements:

* be at least 8 characters in length
* contain both numbers and letters in lower and upper case
* not coincide with any part of your email address
* not coincide with any of the last four passwords you have used
* have a lifetime of less than 90 days
* account lockout threshold must be set to 6.
* account lockout duration must be set to 30 minutes (or until unblocked by the administrator).
* user must be logged off after 15 minutes of inactivity

===Audit trails===

Audit trails are automatically enabled with the default installation of X-Cart Payments. There is no option to disable audit logging. The log files are created in the var/log/ directory. Make sure you restrict access to the log files by business need-to-know.

The following types of activity are logged:

* All actions taken by any individual with root or administrative privileges
* Successes and failures of all individual accesses to application sections and functions

* Initialization of the audit logs
* User sign in and sign out.

Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to files access.log and error.log.

Each log event includes:

* Type of event
* Date and time of event
* Username and IP address
* Success or failure indication
* Action which led to the event

* Component which led to the event

There is also a meta-log which contains information about other log files being created.

=== OS-level audit trails ===

Make sure you have a system-level auditing software properly configured to monitor users' activity on server. This software should:

* warn on a checksum change of any of X-Cart Payments source code files except of log file and database files
* record any file writing operations related to X-Cart Payments files

===Encrypting network traffic===

X-Cart Payments uses encryption, such as TLS or IPSEC, for:

* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
* providing remote web-based access to the application

If you use tools to remotely access the application, you should encrypt all communication using technologies such as TLS or IPSEC.

As per PCI DSS requirement 4.2, cardholder data should never be sent unencrypted by e-mail, and X-Cart Payments does meet this requirement '''never''' sending cardholder data by e-mail or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.

===Wireless communications===

If you use wireless networking to access '''X-Cart Payments''', it is your responsibility to ensure your wireless security con figuration follows the PCI DSS requirements.

* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
* Use with a minimum 104-bit encryption key and 24 bit-initialization value
* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS
* Rotate shared WEP keys quarterly (or automatically if the technology permits)
* Rotate shared WEP keys whenever there are changes in personnel with access to keys
* Restrict access based on media access cod e (MAC) address.
* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.

===Remote access===

X-Cart Payments provides web-based access using two-factor authentication based on one-time PIN codes. Detailed information can be found at [[X-Payments:Managing_PIN_codes | Managing PIN codes]] page.

If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:

* Change default settings in the remote access software (for example, change default passwords and use unique passwords for each customer)
* Allow connections only from specific (known) IP/MAC addresses
* Use strong authentication or complex passwords for logins
* Enable encrypted data transmission
* Enable account lockout after a certain number of failed login attempts
* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed
* Enable any logging or auditing functions
* Restrict access to customer passwords to authorized reseller/integrator personnel
* Establish customer passwords according to PCI DSS requirements 8.1, 8.2, 8.4, 8.5

Qualiteam does not provide software updates via remote access on an automated basis.

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PCI DSS implementation guide for X-Payments 2.2

2015-12-17T12:02:10Z

Alex “Ambal” Mulin: /* X-Cart Payments versioning policy */

== Introduction ==

This guide covers '''X-Cart Payments''' 1.0, 2.0, 2.1, 2.2 and is intended for merchants and integrators who wish to implement the application in accordance with guidelines set by the PCI Data Security Standard (PCI DSS).

== X-Cart Payments versioning policy ==

X-Cart Payments version number must look like "X.Y.Z" (e.g. 1.0.6, 2.0.1, 2.2.1, 3.0.0), where

* X - major version number that gets incremented when high impact changes are introduced and certified under PA-DSS requirements;
* Y - minor version number that gets incremented when low impact changes are added to X-Cart Payments package;
* Z - bug-fix version number that gets incremented when no impact changes are done to X-Cart Payments package.

== PCI DSS ==

PCI DSS specifies 12 requirements broken into 6 groups for compliance that apply both to hardware and software parts of the system that is used to collect, store, transmit and process valuable credit card data as well as the human factor.

{| border
| Build and Maintain a Secure Network
|

* Requirement 1: Install and maintain a firewall configuration to protect cardholder data
* Requirement 2: Do not use vendor-supplied defaults for system passwords and other security parameters
|-
| Protect Cardholder Data
|

* Requirement 3: Protect stored cardholder data
* Requirement 4: Encrypt transmission of cardholder data across open, public networks
|-
| Maintain a Vulnerability Management Program
|

* Requirement 5: Use and regularly update anti-virus software
* Requirement 6: Develop and maintain secure systems and applications
|-
| Implement Strong Access Control Measures
|

* Requirement 7: Restrict access to cardholder data by business need-to-know
* Requirement 8: Assign a unique ID to each person with computer access
* Requirement 9: Restrict physical access to cardholder data
|-
| Regularly Monitor and Test Networks
|

* Requirement 10: Track and monitor all access to network resources and cardholder data
* Requirement 11: Regularly test security systems and processes
|-
| Maintain an Information Security Policy
|

* Requirement 12: Maintain a policy that addresses information security
|}

Specifically, relevant elements to an e-commerce business' PCI compliance status include:

* Properly using your payment application. For this purpose, carefully review the section below for information on how to use '''X-Cart Payments''' in a way that ensures PCI compliance.

* Using a PCI compliant Web hosting environment

* Using a PCI compliant payment provider

You can find and review the complete specification by visiting [https://www.pcisecuritystandards.org/ https://www.pcisecuritystandards.org/]

This guide is intended to help merchants implement the '''X-Cart Payments''' application in a way that is compliant with version 2.0 of the PCI DSS.

== Payment Card Industry Data Security Standard ('''PCI DSS''') ==

The Payment Card Industry Data Security Standard is a worldwide information security standard assembled by the major credit card vendors, including American Express, Discover Financial Services, JCB International, MasterCard Worldwide, and Visa, Inc. The standard was designed to help organizations involved in processing credit card payments online make their payment systems secure from cardholder data fraud.

'''X-Cart Payments''' has been designed and certified to meet all of the requirements of the '''PA-DSS''' version 2.0. This does not automatically make you, the merchant, PCI DSS compliant. To ensure PCI DSS compliance, it is necessary that you follow the recommendations and instructions provided in this guide.

For additional information about '''PCI DSS''' please visit the [https://www.pcisecuritystandards.org Official PCI Security Standards Council Site].

== Cardholder data storage==

'''X-Cart Payments''' has [[X-Payments:General_settings#Cardholder_Data | the ability to store parts of cardholder data temporarily]] for performing 3D Secure verification and certain types of transactions for some of the integrated payment processors. While stored cardholder data is encrypted using special [[X-Payments:Encryption_keys | cryptographic algorithm]]. The data is removed automatically when its storing period is over using "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.

'''X-Cart Payments''' can not be configured to store permanently in the database the following types of data:

* unmasked PAN
* PIN
* CVV
* magnetic stripe (track data)

Merchants and/or developers implementing '''X-Cart Payments''' should not attempt to customize this as a feature.

'''X-Cart Payments''' can display masked PAN on "Payment details" pages and in "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. '''X-Cart Payments''' does not have the ability to display full PAN anywhere and there are no settings that can change this behavior of the user interface.

==Configuring and using '''X-Cart Payments''' in PCI compliant manner ==

===Installation===

Follow the [[X-Payments:Installation | standard procedure]] for deployment of X-Cart Payments files to the web server.

{{Note1|Once installed, X-Cart Payments WILL NEVER: 
* store unmasked credit card numbers (PANs)
* send credit card data or any other information to Qualiteam for debug purposes}}

===Access control===

There are no built-in/default user accounts in '''X-Cart Payments'''.
You must carefully control access to '''X-Cart Payments'''. Follow these rules:

* Restrict the number of employees who have access to '''X-Cart Payments''' to only those who have a business need.
* Always provide unique usernames for each person who needs access.
* Do not use system-default usernames and/or passwords
* Web server must be run under a non-privileged user account. Application must access the database from a limited privilege user account.
* All default user accounts use secure authentication mechanisms and password policy settings that comply with all the standard requirements:
** user accounts inactive for more than 3 days are blocked
** password lifetime is set to 30 days

:: To set password lifetime:

::# Login to '''X-Cart Payments'''
::# Go to Settings -> General Settings
::# Enter the number of days the user account password will be valid for in the "User account password lifetime" field. The maximum allowed password lifetime is 90 days.

:* minimum password length is 8 characters
:* password must contain both lower and upper case characters and numbers
:* the last 4 passwords must be unique
:* user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password
:* user is logged off after inactivity period of 10 minutes

<div> Please note that changing default password policy settings will lead to breaking PCI DSS standard requirements.</div>

===Enabling SSL (Secure Socket Layer)===

SSL protects data that is transmitted between a browser and your web server. It is critical that you have SSL enabled on your web server, and this should be among the first steps taken after installation.

* Your web server must be configured to use TLS v1.2 protocols with strong encryption (128-bit or longer key is required)
* You will need to have a certificate issued for your web domain. Read [http://help.qtmsoft.com/index.php?title=Instant_SSL_certificate guidelines on installing Comodo's Instant SSL certificates].

If a web server does not have SSL enabled '''X-Cart Payments''' will not function or will be notifying users depending on '''allow_insecure_protocol''' parameter set in config.ini.php file (disabled by default).

===Data Collected while Testing===

Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:

# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever collect credit card information to troubleshoot a problem that one of your customers is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access
#* Only collect a limited amount of such data as needed to solve a specific problem
#* Sensitive authentication data must be encrypted while stored. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Such data must be securely deleted immediately after use.

===Encryption Key Management===

As part of your PA DSS v3.1 requirements, encryption key must be changed annually (changing every 90 days is recommended). You should also change the key any time an employee with access to the key leaves your company. Always replace the key if you know or suspect it has been compromised by any means.

To change the encryption keys:

# Log in to '''X-Cart Payments'''
# Go to Maintenance -> Encryption keys
# Click "Generate new keys"

===Use unique user IDs and secure authentication to access PCs, servers and databases ===

PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:

# For your Web hosting account administration area (Web hosting account where your online store is hosted)
# For FTP access to the Web server
# For Remote Desktop Connection to the Web server (if available)
# To connect to the MySQL server that contains your store data.

The passwords for the accounts mentioned above must also meet the following requirements:

* be at least 8 characters in length
* contain both numbers and letters in lower and upper case
* not coincide with any part of your email address
* not coincide with any of the last four passwords you have used
* have a lifetime of less than 90 days
* account lockout threshold must be set to 6.
* account lockout duration must be set to 30 minutes (or until unblocked by the administrator).
* user must be logged off after 15 minutes of inactivity

===Audit trails===

Audit trails are automatically enabled with the default installation of X-Cart Payments. There is no option to disable audit logging. The log files are created in the var/log/ directory. Make sure you restrict access to the log files by business need-to-know.

The following types of activity are logged:

* All actions taken by any individual with root or administrative privileges
* Successes and failures of all individual accesses to application sections and functions

* Initialization of the audit logs
* User sign in and sign out.

Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to files access.log and error.log.

Each log event includes:

* Type of event
* Date and time of event
* Username and IP address
* Success or failure indication
* Action which led to the event

* Component which led to the event

There is also a meta-log which contains information about other log files being created.

=== OS-level audit trails ===

Make sure you have a system-level auditing software properly configured to monitor users' activity on server. This software should:

* warn on a checksum change of any of X-Cart Payments source code files except of log file and database files
* record any file writing operations related to X-Cart Payments files

===Encrypting network traffic===

X-Cart Payments uses encryption, such as TLS or IPSEC, for:

* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
* providing remote web-based access to the application

If you use tools to remotely access the application, you should encrypt all communication using technologies such as TLS or IPSEC.

As per PCI DSS requirement 4.2, cardholder data should never be sent unencrypted by e-mail, and X-Cart Payments does meet this requirement '''never''' sending cardholder data by e-mail or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.

===Wireless communications===

If you use wireless networking to access '''X-Cart Payments''', it is your responsibility to ensure your wireless security con figuration follows the PCI DSS requirements.

* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
* Use with a minimum 104-bit encryption key and 24 bit-initialization value
* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS
* Rotate shared WEP keys quarterly (or automatically if the technology permits)
* Rotate shared WEP keys whenever there are changes in personnel with access to keys
* Restrict access based on media access cod e (MAC) address.
* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.

===Remote access===

X-Cart Payments provides web-based access using two-factor authentication based on one-time PIN codes. Detailed information can be found at [[X-Payments:Managing_PIN_codes | Managing PIN codes]] page.

If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:

* Change default settings in the remote access software (for example, change default passwords and use unique passwords for each customer)
* Allow connections only from specific (known) IP/MAC addresses
* Use strong authentication or complex passwords for logins
* Enable encrypted data transmission
* Enable account lockout after a certain number of failed login attempts
* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed
* Enable any logging or auditing functions
* Restrict access to customer passwords to authorized reseller/integrator personnel
* Establish customer passwords according to PCI DSS requirements 8.1, 8.2, 8.4, 8.5

Qualiteam does not provide software updates via remote access on an automated basis.

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PCI DSS implementation guide for X-Payments 2.2

2015-12-17T12:00:59Z

Alex “Ambal” Mulin: /* X-Cart Payments versioning policy */

== Introduction ==

This guide covers '''X-Cart Payments''' 1.0, 2.0, 2.1, 2.2 and is intended for merchants and integrators who wish to implement the application in accordance with guidelines set by the PCI Data Security Standard (PCI DSS).

== X-Cart Payments versioning policy ==

X-Cart Payments version number must look like "X.Y.Z" (e.g. 1.0.6, 2.0.1, 2.2.1, 3.0.0), where

* X - major version number that gets incremented when a high impact change is introduced and certified under PA-DSS requirements;
* Y - minor version number that gets incremented when a low impact change is added to X-Cart Payments package;
* Z - bug-fix version number that gets incremented when a no impact change is done to X-Cart Payments package.

== PCI DSS ==

PCI DSS specifies 12 requirements broken into 6 groups for compliance that apply both to hardware and software parts of the system that is used to collect, store, transmit and process valuable credit card data as well as the human factor.

{| border
| Build and Maintain a Secure Network
|

* Requirement 1: Install and maintain a firewall configuration to protect cardholder data
* Requirement 2: Do not use vendor-supplied defaults for system passwords and other security parameters
|-
| Protect Cardholder Data
|

* Requirement 3: Protect stored cardholder data
* Requirement 4: Encrypt transmission of cardholder data across open, public networks
|-
| Maintain a Vulnerability Management Program
|

* Requirement 5: Use and regularly update anti-virus software
* Requirement 6: Develop and maintain secure systems and applications
|-
| Implement Strong Access Control Measures
|

* Requirement 7: Restrict access to cardholder data by business need-to-know
* Requirement 8: Assign a unique ID to each person with computer access
* Requirement 9: Restrict physical access to cardholder data
|-
| Regularly Monitor and Test Networks
|

* Requirement 10: Track and monitor all access to network resources and cardholder data
* Requirement 11: Regularly test security systems and processes
|-
| Maintain an Information Security Policy
|

* Requirement 12: Maintain a policy that addresses information security
|}

Specifically, relevant elements to an e-commerce business' PCI compliance status include:

* Properly using your payment application. For this purpose, carefully review the section below for information on how to use '''X-Cart Payments''' in a way that ensures PCI compliance.

* Using a PCI compliant Web hosting environment

* Using a PCI compliant payment provider

You can find and review the complete specification by visiting [https://www.pcisecuritystandards.org/ https://www.pcisecuritystandards.org/]

This guide is intended to help merchants implement the '''X-Cart Payments''' application in a way that is compliant with version 2.0 of the PCI DSS.

== Payment Card Industry Data Security Standard ('''PCI DSS''') ==

The Payment Card Industry Data Security Standard is a worldwide information security standard assembled by the major credit card vendors, including American Express, Discover Financial Services, JCB International, MasterCard Worldwide, and Visa, Inc. The standard was designed to help organizations involved in processing credit card payments online make their payment systems secure from cardholder data fraud.

'''X-Cart Payments''' has been designed and certified to meet all of the requirements of the '''PA-DSS''' version 2.0. This does not automatically make you, the merchant, PCI DSS compliant. To ensure PCI DSS compliance, it is necessary that you follow the recommendations and instructions provided in this guide.

For additional information about '''PCI DSS''' please visit the [https://www.pcisecuritystandards.org Official PCI Security Standards Council Site].

== Cardholder data storage==

'''X-Cart Payments''' has [[X-Payments:General_settings#Cardholder_Data | the ability to store parts of cardholder data temporarily]] for performing 3D Secure verification and certain types of transactions for some of the integrated payment processors. While stored cardholder data is encrypted using special [[X-Payments:Encryption_keys | cryptographic algorithm]]. The data is removed automatically when its storing period is over using "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.

'''X-Cart Payments''' can not be configured to store permanently in the database the following types of data:

* unmasked PAN
* PIN
* CVV
* magnetic stripe (track data)

Merchants and/or developers implementing '''X-Cart Payments''' should not attempt to customize this as a feature.

'''X-Cart Payments''' can display masked PAN on "Payment details" pages and in "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. '''X-Cart Payments''' does not have the ability to display full PAN anywhere and there are no settings that can change this behavior of the user interface.

==Configuring and using '''X-Cart Payments''' in PCI compliant manner ==

===Installation===

Follow the [[X-Payments:Installation | standard procedure]] for deployment of X-Cart Payments files to the web server.

{{Note1|Once installed, X-Cart Payments WILL NEVER: 
* store unmasked credit card numbers (PANs)
* send credit card data or any other information to Qualiteam for debug purposes}}

===Access control===

There are no built-in/default user accounts in '''X-Cart Payments'''.
You must carefully control access to '''X-Cart Payments'''. Follow these rules:

* Restrict the number of employees who have access to '''X-Cart Payments''' to only those who have a business need.
* Always provide unique usernames for each person who needs access.
* Do not use system-default usernames and/or passwords
* Web server must be run under a non-privileged user account. Application must access the database from a limited privilege user account.
* All default user accounts use secure authentication mechanisms and password policy settings that comply with all the standard requirements:
** user accounts inactive for more than 3 days are blocked
** password lifetime is set to 30 days

:: To set password lifetime:

::# Login to '''X-Cart Payments'''
::# Go to Settings -> General Settings
::# Enter the number of days the user account password will be valid for in the "User account password lifetime" field. The maximum allowed password lifetime is 90 days.

:* minimum password length is 8 characters
:* password must contain both lower and upper case characters and numbers
:* the last 4 passwords must be unique
:* user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password
:* user is logged off after inactivity period of 10 minutes

<div> Please note that changing default password policy settings will lead to breaking PCI DSS standard requirements.</div>

===Enabling SSL (Secure Socket Layer)===

SSL protects data that is transmitted between a browser and your web server. It is critical that you have SSL enabled on your web server, and this should be among the first steps taken after installation.

* Your web server must be configured to use TLS v1.2 protocols with strong encryption (128-bit or longer key is required)
* You will need to have a certificate issued for your web domain. Read [http://help.qtmsoft.com/index.php?title=Instant_SSL_certificate guidelines on installing Comodo's Instant SSL certificates].

If a web server does not have SSL enabled '''X-Cart Payments''' will not function or will be notifying users depending on '''allow_insecure_protocol''' parameter set in config.ini.php file (disabled by default).

===Data Collected while Testing===

Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:

# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever collect credit card information to troubleshoot a problem that one of your customers is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access
#* Only collect a limited amount of such data as needed to solve a specific problem
#* Sensitive authentication data must be encrypted while stored. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Such data must be securely deleted immediately after use.

===Encryption Key Management===

As part of your PA DSS v3.1 requirements, encryption key must be changed annually (changing every 90 days is recommended). You should also change the key any time an employee with access to the key leaves your company. Always replace the key if you know or suspect it has been compromised by any means.

To change the encryption keys:

# Log in to '''X-Cart Payments'''
# Go to Maintenance -> Encryption keys
# Click "Generate new keys"

===Use unique user IDs and secure authentication to access PCs, servers and databases ===

PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:

# For your Web hosting account administration area (Web hosting account where your online store is hosted)
# For FTP access to the Web server
# For Remote Desktop Connection to the Web server (if available)
# To connect to the MySQL server that contains your store data.

The passwords for the accounts mentioned above must also meet the following requirements:

* be at least 8 characters in length
* contain both numbers and letters in lower and upper case
* not coincide with any part of your email address
* not coincide with any of the last four passwords you have used
* have a lifetime of less than 90 days
* account lockout threshold must be set to 6.
* account lockout duration must be set to 30 minutes (or until unblocked by the administrator).
* user must be logged off after 15 minutes of inactivity

===Audit trails===

Audit trails are automatically enabled with the default installation of X-Cart Payments. There is no option to disable audit logging. The log files are created in the var/log/ directory. Make sure you restrict access to the log files by business need-to-know.

The following types of activity are logged:

* All actions taken by any individual with root or administrative privileges
* Successes and failures of all individual accesses to application sections and functions

* Initialization of the audit logs
* User sign in and sign out.

Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to files access.log and error.log.

Each log event includes:

* Type of event
* Date and time of event
* Username and IP address
* Success or failure indication
* Action which led to the event

* Component which led to the event

There is also a meta-log which contains information about other log files being created.

=== OS-level audit trails ===

Make sure you have a system-level auditing software properly configured to monitor users' activity on server. This software should:

* warn on a checksum change of any of X-Cart Payments source code files except of log file and database files
* record any file writing operations related to X-Cart Payments files

===Encrypting network traffic===

X-Cart Payments uses encryption, such as TLS or IPSEC, for:

* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
* providing remote web-based access to the application

If you use tools to remotely access the application, you should encrypt all communication using technologies such as TLS or IPSEC.

As per PCI DSS requirement 4.2, cardholder data should never be sent unencrypted by e-mail, and X-Cart Payments does meet this requirement '''never''' sending cardholder data by e-mail or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.

===Wireless communications===

If you use wireless networking to access '''X-Cart Payments''', it is your responsibility to ensure your wireless security con figuration follows the PCI DSS requirements.

* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
* Use with a minimum 104-bit encryption key and 24 bit-initialization value
* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS
* Rotate shared WEP keys quarterly (or automatically if the technology permits)
* Rotate shared WEP keys whenever there are changes in personnel with access to keys
* Restrict access based on media access cod e (MAC) address.
* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.

===Remote access===

X-Cart Payments provides web-based access using two-factor authentication based on one-time PIN codes. Detailed information can be found at [[X-Payments:Managing_PIN_codes | Managing PIN codes]] page.

If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:

* Change default settings in the remote access software (for example, change default passwords and use unique passwords for each customer)
* Allow connections only from specific (known) IP/MAC addresses
* Use strong authentication or complex passwords for logins
* Enable encrypted data transmission
* Enable account lockout after a certain number of failed login attempts
* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed
* Enable any logging or auditing functions
* Restrict access to customer passwords to authorized reseller/integrator personnel
* Establish customer passwords according to PCI DSS requirements 8.1, 8.2, 8.4, 8.5

Qualiteam does not provide software updates via remote access on an automated basis.

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PCI DSS implementation guide for X-Payments 2.2

2015-12-17T12:00:12Z

Alex “Ambal” Mulin: /* X-Cart Payments versioning policy */

== Introduction ==

This guide covers '''X-Cart Payments''' 1.0, 2.0, 2.1, 2.2 and is intended for merchants and integrators who wish to implement the application in accordance with guidelines set by the PCI Data Security Standard (PCI DSS).

== X-Cart Payments versioning policy ==

X-Cart Payments version number must look like "X.Y.Z" (e.g. 1.0.6, 2.0.1, 2.2.1, 3.0.0), where

X - major version number that gets incremented when a high impact change is introduced and certified under PA-DSS requirements;

Y - minor version number that gets incremented when a low impact change is added to X-Cart Payments package;

Z - bug-fix version number that gets incremented when a no impact change is done to X-Cart Payments package.

== PCI DSS ==

PCI DSS specifies 12 requirements broken into 6 groups for compliance that apply both to hardware and software parts of the system that is used to collect, store, transmit and process valuable credit card data as well as the human factor.

{| border
| Build and Maintain a Secure Network
|

* Requirement 1: Install and maintain a firewall configuration to protect cardholder data
* Requirement 2: Do not use vendor-supplied defaults for system passwords and other security parameters
|-
| Protect Cardholder Data
|

* Requirement 3: Protect stored cardholder data
* Requirement 4: Encrypt transmission of cardholder data across open, public networks
|-
| Maintain a Vulnerability Management Program
|

* Requirement 5: Use and regularly update anti-virus software
* Requirement 6: Develop and maintain secure systems and applications
|-
| Implement Strong Access Control Measures
|

* Requirement 7: Restrict access to cardholder data by business need-to-know
* Requirement 8: Assign a unique ID to each person with computer access
* Requirement 9: Restrict physical access to cardholder data
|-
| Regularly Monitor and Test Networks
|

* Requirement 10: Track and monitor all access to network resources and cardholder data
* Requirement 11: Regularly test security systems and processes
|-
| Maintain an Information Security Policy
|

* Requirement 12: Maintain a policy that addresses information security
|}

Specifically, relevant elements to an e-commerce business' PCI compliance status include:

* Properly using your payment application. For this purpose, carefully review the section below for information on how to use '''X-Cart Payments''' in a way that ensures PCI compliance.

* Using a PCI compliant Web hosting environment

* Using a PCI compliant payment provider

You can find and review the complete specification by visiting [https://www.pcisecuritystandards.org/ https://www.pcisecuritystandards.org/]

This guide is intended to help merchants implement the '''X-Cart Payments''' application in a way that is compliant with version 2.0 of the PCI DSS.

== Payment Card Industry Data Security Standard ('''PCI DSS''') ==

The Payment Card Industry Data Security Standard is a worldwide information security standard assembled by the major credit card vendors, including American Express, Discover Financial Services, JCB International, MasterCard Worldwide, and Visa, Inc. The standard was designed to help organizations involved in processing credit card payments online make their payment systems secure from cardholder data fraud.

'''X-Cart Payments''' has been designed and certified to meet all of the requirements of the '''PA-DSS''' version 2.0. This does not automatically make you, the merchant, PCI DSS compliant. To ensure PCI DSS compliance, it is necessary that you follow the recommendations and instructions provided in this guide.

For additional information about '''PCI DSS''' please visit the [https://www.pcisecuritystandards.org Official PCI Security Standards Council Site].

== Cardholder data storage==

'''X-Cart Payments''' has [[X-Payments:General_settings#Cardholder_Data | the ability to store parts of cardholder data temporarily]] for performing 3D Secure verification and certain types of transactions for some of the integrated payment processors. While stored cardholder data is encrypted using special [[X-Payments:Encryption_keys | cryptographic algorithm]]. The data is removed automatically when its storing period is over using "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.

'''X-Cart Payments''' can not be configured to store permanently in the database the following types of data:

* unmasked PAN
* PIN
* CVV
* magnetic stripe (track data)

Merchants and/or developers implementing '''X-Cart Payments''' should not attempt to customize this as a feature.

'''X-Cart Payments''' can display masked PAN on "Payment details" pages and in "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. '''X-Cart Payments''' does not have the ability to display full PAN anywhere and there are no settings that can change this behavior of the user interface.

==Configuring and using '''X-Cart Payments''' in PCI compliant manner ==

===Installation===

Follow the [[X-Payments:Installation | standard procedure]] for deployment of X-Cart Payments files to the web server.

{{Note1|Once installed, X-Cart Payments WILL NEVER: 
* store unmasked credit card numbers (PANs)
* send credit card data or any other information to Qualiteam for debug purposes}}

===Access control===

There are no built-in/default user accounts in '''X-Cart Payments'''.
You must carefully control access to '''X-Cart Payments'''. Follow these rules:

* Restrict the number of employees who have access to '''X-Cart Payments''' to only those who have a business need.
* Always provide unique usernames for each person who needs access.
* Do not use system-default usernames and/or passwords
* Web server must be run under a non-privileged user account. Application must access the database from a limited privilege user account.
* All default user accounts use secure authentication mechanisms and password policy settings that comply with all the standard requirements:
** user accounts inactive for more than 3 days are blocked
** password lifetime is set to 30 days

:: To set password lifetime:

::# Login to '''X-Cart Payments'''
::# Go to Settings -> General Settings
::# Enter the number of days the user account password will be valid for in the "User account password lifetime" field. The maximum allowed password lifetime is 90 days.

:* minimum password length is 8 characters
:* password must contain both lower and upper case characters and numbers
:* the last 4 passwords must be unique
:* user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password
:* user is logged off after inactivity period of 10 minutes

<div> Please note that changing default password policy settings will lead to breaking PCI DSS standard requirements.</div>

===Enabling SSL (Secure Socket Layer)===

SSL protects data that is transmitted between a browser and your web server. It is critical that you have SSL enabled on your web server, and this should be among the first steps taken after installation.

* Your web server must be configured to use TLS v1.2 protocols with strong encryption (128-bit or longer key is required)
* You will need to have a certificate issued for your web domain. Read [http://help.qtmsoft.com/index.php?title=Instant_SSL_certificate guidelines on installing Comodo's Instant SSL certificates].

If a web server does not have SSL enabled '''X-Cart Payments''' will not function or will be notifying users depending on '''allow_insecure_protocol''' parameter set in config.ini.php file (disabled by default).

===Data Collected while Testing===

Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:

# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever collect credit card information to troubleshoot a problem that one of your customers is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access
#* Only collect a limited amount of such data as needed to solve a specific problem
#* Sensitive authentication data must be encrypted while stored. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Such data must be securely deleted immediately after use.

===Encryption Key Management===

As part of your PA DSS v3.1 requirements, encryption key must be changed annually (changing every 90 days is recommended). You should also change the key any time an employee with access to the key leaves your company. Always replace the key if you know or suspect it has been compromised by any means.

To change the encryption keys:

# Log in to '''X-Cart Payments'''
# Go to Maintenance -> Encryption keys
# Click "Generate new keys"

===Use unique user IDs and secure authentication to access PCs, servers and databases ===

PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:

# For your Web hosting account administration area (Web hosting account where your online store is hosted)
# For FTP access to the Web server
# For Remote Desktop Connection to the Web server (if available)
# To connect to the MySQL server that contains your store data.

The passwords for the accounts mentioned above must also meet the following requirements:

* be at least 8 characters in length
* contain both numbers and letters in lower and upper case
* not coincide with any part of your email address
* not coincide with any of the last four passwords you have used
* have a lifetime of less than 90 days
* account lockout threshold must be set to 6.
* account lockout duration must be set to 30 minutes (or until unblocked by the administrator).
* user must be logged off after 15 minutes of inactivity

===Audit trails===

Audit trails are automatically enabled with the default installation of X-Cart Payments. There is no option to disable audit logging. The log files are created in the var/log/ directory. Make sure you restrict access to the log files by business need-to-know.

The following types of activity are logged:

* All actions taken by any individual with root or administrative privileges
* Successes and failures of all individual accesses to application sections and functions

* Initialization of the audit logs
* User sign in and sign out.

Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to files access.log and error.log.

Each log event includes:

* Type of event
* Date and time of event
* Username and IP address
* Success or failure indication
* Action which led to the event

* Component which led to the event

There is also a meta-log which contains information about other log files being created.

=== OS-level audit trails ===

Make sure you have a system-level auditing software properly configured to monitor users' activity on server. This software should:

* warn on a checksum change of any of X-Cart Payments source code files except of log file and database files
* record any file writing operations related to X-Cart Payments files

===Encrypting network traffic===

X-Cart Payments uses encryption, such as TLS or IPSEC, for:

* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
* providing remote web-based access to the application

If you use tools to remotely access the application, you should encrypt all communication using technologies such as TLS or IPSEC.

As per PCI DSS requirement 4.2, cardholder data should never be sent unencrypted by e-mail, and X-Cart Payments does meet this requirement '''never''' sending cardholder data by e-mail or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.

===Wireless communications===

If you use wireless networking to access '''X-Cart Payments''', it is your responsibility to ensure your wireless security con figuration follows the PCI DSS requirements.

* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
* Use with a minimum 104-bit encryption key and 24 bit-initialization value
* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS
* Rotate shared WEP keys quarterly (or automatically if the technology permits)
* Rotate shared WEP keys whenever there are changes in personnel with access to keys
* Restrict access based on media access cod e (MAC) address.
* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.

===Remote access===

X-Cart Payments provides web-based access using two-factor authentication based on one-time PIN codes. Detailed information can be found at [[X-Payments:Managing_PIN_codes | Managing PIN codes]] page.

If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:

* Change default settings in the remote access software (for example, change default passwords and use unique passwords for each customer)
* Allow connections only from specific (known) IP/MAC addresses
* Use strong authentication or complex passwords for logins
* Enable encrypted data transmission
* Enable account lockout after a certain number of failed login attempts
* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed
* Enable any logging or auditing functions
* Restrict access to customer passwords to authorized reseller/integrator personnel
* Establish customer passwords according to PCI DSS requirements 8.1, 8.2, 8.4, 8.5

Qualiteam does not provide software updates via remote access on an automated basis.

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PCI DSS implementation guide for X-Payments 2.2

2015-12-17T11:58:31Z

Alex “Ambal” Mulin: /* X-Cart Payments version policy */

== Introduction ==

This guide covers '''X-Cart Payments''' 1.0, 2.0, 2.1, 2.2 and is intended for merchants and integrators who wish to implement the application in accordance with guidelines set by the PCI Data Security Standard (PCI DSS).

== X-Cart Payments versioning policy ==

X-Cart Payments version number must look like "X.Y.Z" (e.g. 1.0.6, 2.0.1, 2.2.1, 3.0.0), where

X - major version number that gets incremented when a high impact change is introduced and certified under PA-DSS requirements;
Y - minor version number that gets incremented when a low impact change is added to X-Cart Payments package;
Z - bug-fix version number that gets incremented when a no impact change is done to X-Cart Payments package.

== PCI DSS ==

PCI DSS specifies 12 requirements broken into 6 groups for compliance that apply both to hardware and software parts of the system that is used to collect, store, transmit and process valuable credit card data as well as the human factor.

{| border
| Build and Maintain a Secure Network
|

* Requirement 1: Install and maintain a firewall configuration to protect cardholder data
* Requirement 2: Do not use vendor-supplied defaults for system passwords and other security parameters
|-
| Protect Cardholder Data
|

* Requirement 3: Protect stored cardholder data
* Requirement 4: Encrypt transmission of cardholder data across open, public networks
|-
| Maintain a Vulnerability Management Program
|

* Requirement 5: Use and regularly update anti-virus software
* Requirement 6: Develop and maintain secure systems and applications
|-
| Implement Strong Access Control Measures
|

* Requirement 7: Restrict access to cardholder data by business need-to-know
* Requirement 8: Assign a unique ID to each person with computer access
* Requirement 9: Restrict physical access to cardholder data
|-
| Regularly Monitor and Test Networks
|

* Requirement 10: Track and monitor all access to network resources and cardholder data
* Requirement 11: Regularly test security systems and processes
|-
| Maintain an Information Security Policy
|

* Requirement 12: Maintain a policy that addresses information security
|}

Specifically, relevant elements to an e-commerce business' PCI compliance status include:

* Properly using your payment application. For this purpose, carefully review the section below for information on how to use '''X-Cart Payments''' in a way that ensures PCI compliance.

* Using a PCI compliant Web hosting environment

* Using a PCI compliant payment provider

You can find and review the complete specification by visiting [https://www.pcisecuritystandards.org/ https://www.pcisecuritystandards.org/]

This guide is intended to help merchants implement the '''X-Cart Payments''' application in a way that is compliant with version 2.0 of the PCI DSS.

== Payment Card Industry Data Security Standard ('''PCI DSS''') ==

The Payment Card Industry Data Security Standard is a worldwide information security standard assembled by the major credit card vendors, including American Express, Discover Financial Services, JCB International, MasterCard Worldwide, and Visa, Inc. The standard was designed to help organizations involved in processing credit card payments online make their payment systems secure from cardholder data fraud.

'''X-Cart Payments''' has been designed and certified to meet all of the requirements of the '''PA-DSS''' version 2.0. This does not automatically make you, the merchant, PCI DSS compliant. To ensure PCI DSS compliance, it is necessary that you follow the recommendations and instructions provided in this guide.

For additional information about '''PCI DSS''' please visit the [https://www.pcisecuritystandards.org Official PCI Security Standards Council Site].

== Cardholder data storage==

'''X-Cart Payments''' has [[X-Payments:General_settings#Cardholder_Data | the ability to store parts of cardholder data temporarily]] for performing 3D Secure verification and certain types of transactions for some of the integrated payment processors. While stored cardholder data is encrypted using special [[X-Payments:Encryption_keys | cryptographic algorithm]]. The data is removed automatically when its storing period is over using "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.

'''X-Cart Payments''' can not be configured to store permanently in the database the following types of data:

* unmasked PAN
* PIN
* CVV
* magnetic stripe (track data)

Merchants and/or developers implementing '''X-Cart Payments''' should not attempt to customize this as a feature.

'''X-Cart Payments''' can display masked PAN on "Payment details" pages and in "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. '''X-Cart Payments''' does not have the ability to display full PAN anywhere and there are no settings that can change this behavior of the user interface.

==Configuring and using '''X-Cart Payments''' in PCI compliant manner ==

===Installation===

Follow the [[X-Payments:Installation | standard procedure]] for deployment of X-Cart Payments files to the web server.

{{Note1|Once installed, X-Cart Payments WILL NEVER: 
* store unmasked credit card numbers (PANs)
* send credit card data or any other information to Qualiteam for debug purposes}}

===Access control===

There are no built-in/default user accounts in '''X-Cart Payments'''.
You must carefully control access to '''X-Cart Payments'''. Follow these rules:

* Restrict the number of employees who have access to '''X-Cart Payments''' to only those who have a business need.
* Always provide unique usernames for each person who needs access.
* Do not use system-default usernames and/or passwords
* Web server must be run under a non-privileged user account. Application must access the database from a limited privilege user account.
* All default user accounts use secure authentication mechanisms and password policy settings that comply with all the standard requirements:
** user accounts inactive for more than 3 days are blocked
** password lifetime is set to 30 days

:: To set password lifetime:

::# Login to '''X-Cart Payments'''
::# Go to Settings -> General Settings
::# Enter the number of days the user account password will be valid for in the "User account password lifetime" field. The maximum allowed password lifetime is 90 days.

:* minimum password length is 8 characters
:* password must contain both lower and upper case characters and numbers
:* the last 4 passwords must be unique
:* user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password
:* user is logged off after inactivity period of 10 minutes

<div> Please note that changing default password policy settings will lead to breaking PCI DSS standard requirements.</div>

===Enabling SSL (Secure Socket Layer)===

SSL protects data that is transmitted between a browser and your web server. It is critical that you have SSL enabled on your web server, and this should be among the first steps taken after installation.

* Your web server must be configured to use TLS v1.2 protocols with strong encryption (128-bit or longer key is required)
* You will need to have a certificate issued for your web domain. Read [http://help.qtmsoft.com/index.php?title=Instant_SSL_certificate guidelines on installing Comodo's Instant SSL certificates].

If a web server does not have SSL enabled '''X-Cart Payments''' will not function or will be notifying users depending on '''allow_insecure_protocol''' parameter set in config.ini.php file (disabled by default).

===Data Collected while Testing===

Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:

# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever collect credit card information to troubleshoot a problem that one of your customers is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access
#* Only collect a limited amount of such data as needed to solve a specific problem
#* Sensitive authentication data must be encrypted while stored. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Such data must be securely deleted immediately after use.

===Encryption Key Management===

As part of your PA DSS v3.1 requirements, encryption key must be changed annually (changing every 90 days is recommended). You should also change the key any time an employee with access to the key leaves your company. Always replace the key if you know or suspect it has been compromised by any means.

To change the encryption keys:

# Log in to '''X-Cart Payments'''
# Go to Maintenance -> Encryption keys
# Click "Generate new keys"

===Use unique user IDs and secure authentication to access PCs, servers and databases ===

PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:

# For your Web hosting account administration area (Web hosting account where your online store is hosted)
# For FTP access to the Web server
# For Remote Desktop Connection to the Web server (if available)
# To connect to the MySQL server that contains your store data.

The passwords for the accounts mentioned above must also meet the following requirements:

* be at least 8 characters in length
* contain both numbers and letters in lower and upper case
* not coincide with any part of your email address
* not coincide with any of the last four passwords you have used
* have a lifetime of less than 90 days
* account lockout threshold must be set to 6.
* account lockout duration must be set to 30 minutes (or until unblocked by the administrator).
* user must be logged off after 15 minutes of inactivity

===Audit trails===

Audit trails are automatically enabled with the default installation of X-Cart Payments. There is no option to disable audit logging. The log files are created in the var/log/ directory. Make sure you restrict access to the log files by business need-to-know.

The following types of activity are logged:

* All actions taken by any individual with root or administrative privileges
* Successes and failures of all individual accesses to application sections and functions

* Initialization of the audit logs
* User sign in and sign out.

Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to files access.log and error.log.

Each log event includes:

* Type of event
* Date and time of event
* Username and IP address
* Success or failure indication
* Action which led to the event

* Component which led to the event

There is also a meta-log which contains information about other log files being created.

=== OS-level audit trails ===

Make sure you have a system-level auditing software properly configured to monitor users' activity on server. This software should:

* warn on a checksum change of any of X-Cart Payments source code files except of log file and database files
* record any file writing operations related to X-Cart Payments files

===Encrypting network traffic===

X-Cart Payments uses encryption, such as TLS or IPSEC, for:

* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
* providing remote web-based access to the application

If you use tools to remotely access the application, you should encrypt all communication using technologies such as TLS or IPSEC.

As per PCI DSS requirement 4.2, cardholder data should never be sent unencrypted by e-mail, and X-Cart Payments does meet this requirement '''never''' sending cardholder data by e-mail or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.

===Wireless communications===

If you use wireless networking to access '''X-Cart Payments''', it is your responsibility to ensure your wireless security con figuration follows the PCI DSS requirements.

* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
* Use with a minimum 104-bit encryption key and 24 bit-initialization value
* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS
* Rotate shared WEP keys quarterly (or automatically if the technology permits)
* Rotate shared WEP keys whenever there are changes in personnel with access to keys
* Restrict access based on media access cod e (MAC) address.
* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.

===Remote access===

X-Cart Payments provides web-based access using two-factor authentication based on one-time PIN codes. Detailed information can be found at [[X-Payments:Managing_PIN_codes | Managing PIN codes]] page.

If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:

* Change default settings in the remote access software (for example, change default passwords and use unique passwords for each customer)
* Allow connections only from specific (known) IP/MAC addresses
* Use strong authentication or complex passwords for logins
* Enable encrypted data transmission
* Enable account lockout after a certain number of failed login attempts
* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed
* Enable any logging or auditing functions
* Restrict access to customer passwords to authorized reseller/integrator personnel
* Establish customer passwords according to PCI DSS requirements 8.1, 8.2, 8.4, 8.5

Qualiteam does not provide software updates via remote access on an automated basis.

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PCI DSS implementation guide for X-Payments 2.2

2015-12-17T11:56:49Z

Alex “Ambal” Mulin: /* Introduction */

== Introduction ==

This guide covers '''X-Cart Payments''' 1.0, 2.0, 2.1, 2.2 and is intended for merchants and integrators who wish to implement the application in accordance with guidelines set by the PCI Data Security Standard (PCI DSS).

== X-Cart Payments version policy ==

X-Cart Payments version number must look like "X.Y.Z" (e.g. 1.0.6, 2.0.1, 2.2.1, 3.0.0), where

X - major version number that gets incremented when a high impact change is introduced and certified under PA-DSS requirements;
Y - minor version number that gets incremented when a low impact change is added to X-Cart Payments package;
Z - bug-fix version number that gets incremented when a no impact change is done to X-Cart Payments package.

== PCI DSS ==

PCI DSS specifies 12 requirements broken into 6 groups for compliance that apply both to hardware and software parts of the system that is used to collect, store, transmit and process valuable credit card data as well as the human factor.

{| border
| Build and Maintain a Secure Network
|

* Requirement 1: Install and maintain a firewall configuration to protect cardholder data
* Requirement 2: Do not use vendor-supplied defaults for system passwords and other security parameters
|-
| Protect Cardholder Data
|

* Requirement 3: Protect stored cardholder data
* Requirement 4: Encrypt transmission of cardholder data across open, public networks
|-
| Maintain a Vulnerability Management Program
|

* Requirement 5: Use and regularly update anti-virus software
* Requirement 6: Develop and maintain secure systems and applications
|-
| Implement Strong Access Control Measures
|

* Requirement 7: Restrict access to cardholder data by business need-to-know
* Requirement 8: Assign a unique ID to each person with computer access
* Requirement 9: Restrict physical access to cardholder data
|-
| Regularly Monitor and Test Networks
|

* Requirement 10: Track and monitor all access to network resources and cardholder data
* Requirement 11: Regularly test security systems and processes
|-
| Maintain an Information Security Policy
|

* Requirement 12: Maintain a policy that addresses information security
|}

Specifically, relevant elements to an e-commerce business' PCI compliance status include:

* Properly using your payment application. For this purpose, carefully review the section below for information on how to use '''X-Cart Payments''' in a way that ensures PCI compliance.

* Using a PCI compliant Web hosting environment

* Using a PCI compliant payment provider

You can find and review the complete specification by visiting [https://www.pcisecuritystandards.org/ https://www.pcisecuritystandards.org/]

This guide is intended to help merchants implement the '''X-Cart Payments''' application in a way that is compliant with version 2.0 of the PCI DSS.

== Payment Card Industry Data Security Standard ('''PCI DSS''') ==

The Payment Card Industry Data Security Standard is a worldwide information security standard assembled by the major credit card vendors, including American Express, Discover Financial Services, JCB International, MasterCard Worldwide, and Visa, Inc. The standard was designed to help organizations involved in processing credit card payments online make their payment systems secure from cardholder data fraud.

'''X-Cart Payments''' has been designed and certified to meet all of the requirements of the '''PA-DSS''' version 2.0. This does not automatically make you, the merchant, PCI DSS compliant. To ensure PCI DSS compliance, it is necessary that you follow the recommendations and instructions provided in this guide.

For additional information about '''PCI DSS''' please visit the [https://www.pcisecuritystandards.org Official PCI Security Standards Council Site].

== Cardholder data storage==

'''X-Cart Payments''' has [[X-Payments:General_settings#Cardholder_Data | the ability to store parts of cardholder data temporarily]] for performing 3D Secure verification and certain types of transactions for some of the integrated payment processors. While stored cardholder data is encrypted using special [[X-Payments:Encryption_keys | cryptographic algorithm]]. The data is removed automatically when its storing period is over using "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.

'''X-Cart Payments''' can not be configured to store permanently in the database the following types of data:

* unmasked PAN
* PIN
* CVV
* magnetic stripe (track data)

Merchants and/or developers implementing '''X-Cart Payments''' should not attempt to customize this as a feature.

'''X-Cart Payments''' can display masked PAN on "Payment details" pages and in "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. '''X-Cart Payments''' does not have the ability to display full PAN anywhere and there are no settings that can change this behavior of the user interface.

==Configuring and using '''X-Cart Payments''' in PCI compliant manner ==

===Installation===

Follow the [[X-Payments:Installation | standard procedure]] for deployment of X-Cart Payments files to the web server.

{{Note1|Once installed, X-Cart Payments WILL NEVER: 
* store unmasked credit card numbers (PANs)
* send credit card data or any other information to Qualiteam for debug purposes}}

===Access control===

There are no built-in/default user accounts in '''X-Cart Payments'''.
You must carefully control access to '''X-Cart Payments'''. Follow these rules:

* Restrict the number of employees who have access to '''X-Cart Payments''' to only those who have a business need.
* Always provide unique usernames for each person who needs access.
* Do not use system-default usernames and/or passwords
* Web server must be run under a non-privileged user account. Application must access the database from a limited privilege user account.
* All default user accounts use secure authentication mechanisms and password policy settings that comply with all the standard requirements:
** user accounts inactive for more than 3 days are blocked
** password lifetime is set to 30 days

:: To set password lifetime:

::# Login to '''X-Cart Payments'''
::# Go to Settings -> General Settings
::# Enter the number of days the user account password will be valid for in the "User account password lifetime" field. The maximum allowed password lifetime is 90 days.

:* minimum password length is 8 characters
:* password must contain both lower and upper case characters and numbers
:* the last 4 passwords must be unique
:* user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password
:* user is logged off after inactivity period of 10 minutes

<div> Please note that changing default password policy settings will lead to breaking PCI DSS standard requirements.</div>

===Enabling SSL (Secure Socket Layer)===

SSL protects data that is transmitted between a browser and your web server. It is critical that you have SSL enabled on your web server, and this should be among the first steps taken after installation.

* Your web server must be configured to use TLS v1.2 protocols with strong encryption (128-bit or longer key is required)
* You will need to have a certificate issued for your web domain. Read [http://help.qtmsoft.com/index.php?title=Instant_SSL_certificate guidelines on installing Comodo's Instant SSL certificates].

If a web server does not have SSL enabled '''X-Cart Payments''' will not function or will be notifying users depending on '''allow_insecure_protocol''' parameter set in config.ini.php file (disabled by default).

===Data Collected while Testing===

Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:

# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever collect credit card information to troubleshoot a problem that one of your customers is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access
#* Only collect a limited amount of such data as needed to solve a specific problem
#* Sensitive authentication data must be encrypted while stored. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Such data must be securely deleted immediately after use.

===Encryption Key Management===

As part of your PA DSS v3.1 requirements, encryption key must be changed annually (changing every 90 days is recommended). You should also change the key any time an employee with access to the key leaves your company. Always replace the key if you know or suspect it has been compromised by any means.

To change the encryption keys:

# Log in to '''X-Cart Payments'''
# Go to Maintenance -> Encryption keys
# Click "Generate new keys"

===Use unique user IDs and secure authentication to access PCs, servers and databases ===

PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:

# For your Web hosting account administration area (Web hosting account where your online store is hosted)
# For FTP access to the Web server
# For Remote Desktop Connection to the Web server (if available)
# To connect to the MySQL server that contains your store data.

The passwords for the accounts mentioned above must also meet the following requirements:

* be at least 8 characters in length
* contain both numbers and letters in lower and upper case
* not coincide with any part of your email address
* not coincide with any of the last four passwords you have used
* have a lifetime of less than 90 days
* account lockout threshold must be set to 6.
* account lockout duration must be set to 30 minutes (or until unblocked by the administrator).
* user must be logged off after 15 minutes of inactivity

===Audit trails===

Audit trails are automatically enabled with the default installation of X-Cart Payments. There is no option to disable audit logging. The log files are created in the var/log/ directory. Make sure you restrict access to the log files by business need-to-know.

The following types of activity are logged:

* All actions taken by any individual with root or administrative privileges
* Successes and failures of all individual accesses to application sections and functions

* Initialization of the audit logs
* User sign in and sign out.

Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to files access.log and error.log.

Each log event includes:

* Type of event
* Date and time of event
* Username and IP address
* Success or failure indication
* Action which led to the event

* Component which led to the event

There is also a meta-log which contains information about other log files being created.

=== OS-level audit trails ===

Make sure you have a system-level auditing software properly configured to monitor users' activity on server. This software should:

* warn on a checksum change of any of X-Cart Payments source code files except of log file and database files
* record any file writing operations related to X-Cart Payments files

===Encrypting network traffic===

X-Cart Payments uses encryption, such as TLS or IPSEC, for:

* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
* providing remote web-based access to the application

If you use tools to remotely access the application, you should encrypt all communication using technologies such as TLS or IPSEC.

As per PCI DSS requirement 4.2, cardholder data should never be sent unencrypted by e-mail, and X-Cart Payments does meet this requirement '''never''' sending cardholder data by e-mail or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.

===Wireless communications===

If you use wireless networking to access '''X-Cart Payments''', it is your responsibility to ensure your wireless security con figuration follows the PCI DSS requirements.

* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
* Use with a minimum 104-bit encryption key and 24 bit-initialization value
* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS
* Rotate shared WEP keys quarterly (or automatically if the technology permits)
* Rotate shared WEP keys whenever there are changes in personnel with access to keys
* Restrict access based on media access cod e (MAC) address.
* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.

===Remote access===

X-Cart Payments provides web-based access using two-factor authentication based on one-time PIN codes. Detailed information can be found at [[X-Payments:Managing_PIN_codes | Managing PIN codes]] page.

If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:

* Change default settings in the remote access software (for example, change default passwords and use unique passwords for each customer)
* Allow connections only from specific (known) IP/MAC addresses
* Use strong authentication or complex passwords for logins
* Enable encrypted data transmission
* Enable account lockout after a certain number of failed login attempts
* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed
* Enable any logging or auditing functions
* Restrict access to customer passwords to authorized reseller/integrator personnel
* Establish customer passwords according to PCI DSS requirements 8.1, 8.2, 8.4, 8.5

Qualiteam does not provide software updates via remote access on an automated basis.

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PCI DSS implementation guide for X-Payments 2.2

2015-12-14T14:26:58Z

Alex “Ambal” Mulin: /* Access control */

== Introduction ==

This guide covers '''X-Cart Payments''' 1.0, 2.0, 2.1, 2.2 and is intended for merchants and integrators who wish to implement the application in accordance with guidelines set by the PCI Data Security Standard (PCI DSS).

== PCI DSS ==

PCI DSS specifies 12 requirements broken into 6 groups for compliance that apply both to hardware and software parts of the system that is used to collect, store, transmit and process valuable credit card data as well as the human factor.

{| border
| Build and Maintain a Secure Network
|

* Requirement 1: Install and maintain a firewall configuration to protect cardholder data
* Requirement 2: Do not use vendor-supplied defaults for system passwords and other security parameters
|-
| Protect Cardholder Data
|

* Requirement 3: Protect stored cardholder data
* Requirement 4: Encrypt transmission of cardholder data across open, public networks
|-
| Maintain a Vulnerability Management Program
|

* Requirement 5: Use and regularly update anti-virus software
* Requirement 6: Develop and maintain secure systems and applications
|-
| Implement Strong Access Control Measures
|

* Requirement 7: Restrict access to cardholder data by business need-to-know
* Requirement 8: Assign a unique ID to each person with computer access
* Requirement 9: Restrict physical access to cardholder data
|-
| Regularly Monitor and Test Networks
|

* Requirement 10: Track and monitor all access to network resources and cardholder data
* Requirement 11: Regularly test security systems and processes
|-
| Maintain an Information Security Policy
|

* Requirement 12: Maintain a policy that addresses information security
|}

Specifically, relevant elements to an e-commerce business' PCI compliance status include:

* Properly using your payment application. For this purpose, carefully review the section below for information on how to use '''X-Cart Payments''' in a way that ensures PCI compliance.

* Using a PCI compliant Web hosting environment

* Using a PCI compliant payment provider

You can find and review the complete specification by visiting [https://www.pcisecuritystandards.org/ https://www.pcisecuritystandards.org/]

This guide is intended to help merchants implement the '''X-Cart Payments''' application in a way that is compliant with version 2.0 of the PCI DSS.

== Payment Card Industry Data Security Standard ('''PCI DSS''') ==

The Payment Card Industry Data Security Standard is a worldwide information security standard assembled by the major credit card vendors, including American Express, Discover Financial Services, JCB International, MasterCard Worldwide, and Visa, Inc. The standard was designed to help organizations involved in processing credit card payments online make their payment systems secure from cardholder data fraud.

'''X-Cart Payments''' has been designed and certified to meet all of the requirements of the '''PA-DSS''' version 2.0. This does not automatically make you, the merchant, PCI DSS compliant. To ensure PCI DSS compliance, it is necessary that you follow the recommendations and instructions provided in this guide.

For additional information about '''PCI DSS''' please visit the [https://www.pcisecuritystandards.org Official PCI Security Standards Council Site].

== Cardholder data storage==

'''X-Cart Payments''' has [[X-Payments:General_settings#Cardholder_Data | the ability to store parts of cardholder data temporarily]] for performing 3D Secure verification and certain types of transactions for some of the integrated payment processors. While stored cardholder data is encrypted using special [[X-Payments:Encryption_keys | cryptographic algorithm]]. The data is removed automatically when its storing period is over using "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.

'''X-Cart Payments''' can not be configured to store permanently in the database the following types of data:

* unmasked PAN
* PIN
* CVV
* magnetic stripe (track data)

Merchants and/or developers implementing '''X-Cart Payments''' should not attempt to customize this as a feature.

'''X-Cart Payments''' can display masked PAN on "Payment details" pages and in "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. '''X-Cart Payments''' does not have the ability to display full PAN anywhere and there are no settings that can change this behavior of the user interface.

==Configuring and using '''X-Cart Payments''' in PCI compliant manner ==

===Installation===

Follow the [[X-Payments:Installation | standard procedure]] for deployment of X-Cart Payments files to the web server.

{{Note1|Once installed, X-Cart Payments WILL NEVER: 
* store unmasked credit card numbers (PANs)
* send credit card data or any other information to Qualiteam for debug purposes}}

===Access control===

There are no built-in/default user accounts in '''X-Cart Payments'''.
You must carefully control access to '''X-Cart Payments'''. Follow these rules:

* Restrict the number of employees who have access to '''X-Cart Payments''' to only those who have a business need.
* Always provide unique usernames for each person who needs access.
* Do not use system-default usernames and/or passwords
* Web server must be run under a non-privileged user account. Application must access the database from a limited privilege user account.
* All default user accounts use secure authentication mechanisms and password policy settings that comply with all the standard requirements:
** user accounts inactive for more than 3 days are blocked
** password lifetime is set to 30 days

:: To set password lifetime:

::# Login to '''X-Cart Payments'''
::# Go to Settings -> General Settings
::# Enter the number of days the user account password will be valid for in the "User account password lifetime" field. The maximum allowed password lifetime is 90 days.

:* minimum password length is 8 characters
:* password must contain both lower and upper case characters and numbers
:* the last 4 passwords must be unique
:* user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password
:* user is logged off after inactivity period of 10 minutes

<div> Please note that changing default password policy settings will lead to breaking PCI DSS standard requirements.</div>

===Enabling SSL (Secure Socket Layer)===

SSL protects data that is transmitted between a browser and your web server. It is critical that you have SSL enabled on your web server, and this should be among the first steps taken after installation.

* Your web server must be configured to use TLS v1.2 protocols with strong encryption (128-bit or longer key is required)
* You will need to have a certificate issued for your web domain. Read [http://help.qtmsoft.com/index.php?title=Instant_SSL_certificate guidelines on installing Comodo's Instant SSL certificates].

If a web server does not have SSL enabled '''X-Cart Payments''' will not function or will be notifying users depending on '''allow_insecure_protocol''' parameter set in config.ini.php file (disabled by default).

===Data Collected while Testing===

Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:

# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever collect credit card information to troubleshoot a problem that one of your customers is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access
#* Only collect a limited amount of such data as needed to solve a specific problem
#* Sensitive authentication data must be encrypted while stored. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Such data must be securely deleted immediately after use.

===Encryption Key Management===

As part of your PA DSS v3.1 requirements, encryption key must be changed annually (changing every 90 days is recommended). You should also change the key any time an employee with access to the key leaves your company. Always replace the key if you know or suspect it has been compromised by any means.

To change the encryption keys:

# Log in to '''X-Cart Payments'''
# Go to Maintenance -> Encryption keys
# Click "Generate new keys"

===Use unique user IDs and secure authentication to access PCs, servers and databases ===

PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:

# For your Web hosting account administration area (Web hosting account where your online store is hosted)
# For FTP access to the Web server
# For Remote Desktop Connection to the Web server (if available)
# To connect to the MySQL server that contains your store data.

The passwords for the accounts mentioned above must also meet the following requirements:

* be at least 8 characters in length
* contain both numbers and letters in lower and upper case
* not coincide with any part of your email address
* not coincide with any of the last four passwords you have used
* have a lifetime of less than 90 days
* account lockout threshold must be set to 6.
* account lockout duration must be set to 30 minutes (or until unblocked by the administrator).
* user must be logged off after 15 minutes of inactivity

===Audit trails===

Audit trails are automatically enabled with the default installation of X-Cart Payments. There is no option to disable audit logging. The log files are created in the var/log/ directory. Make sure you restrict access to the log files by business need-to-know.

The following types of activity are logged:

* All actions taken by any individual with root or administrative privileges
* Successes and failures of all individual accesses to application sections and functions

* Initialization of the audit logs
* User sign in and sign out.

Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to files access.log and error.log.

Each log event includes:

* Type of event
* Date and time of event
* Username and IP address
* Success or failure indication
* Action which led to the event

* Component which led to the event

There is also a meta-log which contains information about other log files being created.

=== OS-level audit trails ===

Make sure you have a system-level auditing software properly configured to monitor users' activity on server. This software should:

* warn on a checksum change of any of X-Cart Payments source code files except of log file and database files
* record any file writing operations related to X-Cart Payments files

===Encrypting network traffic===

X-Cart Payments uses encryption, such as TLS or IPSEC, for:

* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
* providing remote web-based access to the application

If you use tools to remotely access the application, you should encrypt all communication using technologies such as TLS or IPSEC.

As per PCI DSS requirement 4.2, cardholder data should never be sent unencrypted by e-mail, and X-Cart Payments does meet this requirement '''never''' sending cardholder data by e-mail or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.

===Wireless communications===

If you use wireless networking to access '''X-Cart Payments''', it is your responsibility to ensure your wireless security con figuration follows the PCI DSS requirements.

* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
* Use with a minimum 104-bit encryption key and 24 bit-initialization value
* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS
* Rotate shared WEP keys quarterly (or automatically if the technology permits)
* Rotate shared WEP keys whenever there are changes in personnel with access to keys
* Restrict access based on media access cod e (MAC) address.
* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.

===Remote access===

X-Cart Payments provides web-based access using two-factor authentication based on one-time PIN codes. Detailed information can be found at [[X-Payments:Managing_PIN_codes | Managing PIN codes]] page.

If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:

* Change default settings in the remote access software (for example, change default passwords and use unique passwords for each customer)
* Allow connections only from specific (known) IP/MAC addresses
* Use strong authentication or complex passwords for logins
* Enable encrypted data transmission
* Enable account lockout after a certain number of failed login attempts
* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed
* Enable any logging or auditing functions
* Restrict access to customer passwords to authorized reseller/integrator personnel
* Establish customer passwords according to PCI DSS requirements 8.1, 8.2, 8.4, 8.5

Qualiteam does not provide software updates via remote access on an automated basis.

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PCI DSS implementation guide for X-Payments 2.2

2015-12-14T14:25:00Z

Alex “Ambal” Mulin: /* See also */

== Introduction ==

This guide covers '''X-Cart Payments''' 1.0, 2.0, 2.1, 2.2 and is intended for merchants and integrators who wish to implement the application in accordance with guidelines set by the PCI Data Security Standard (PCI DSS).

== PCI DSS ==

PCI DSS specifies 12 requirements broken into 6 groups for compliance that apply both to hardware and software parts of the system that is used to collect, store, transmit and process valuable credit card data as well as the human factor.

{| border
| Build and Maintain a Secure Network
|

* Requirement 1: Install and maintain a firewall configuration to protect cardholder data
* Requirement 2: Do not use vendor-supplied defaults for system passwords and other security parameters
|-
| Protect Cardholder Data
|

* Requirement 3: Protect stored cardholder data
* Requirement 4: Encrypt transmission of cardholder data across open, public networks
|-
| Maintain a Vulnerability Management Program
|

* Requirement 5: Use and regularly update anti-virus software
* Requirement 6: Develop and maintain secure systems and applications
|-
| Implement Strong Access Control Measures
|

* Requirement 7: Restrict access to cardholder data by business need-to-know
* Requirement 8: Assign a unique ID to each person with computer access
* Requirement 9: Restrict physical access to cardholder data
|-
| Regularly Monitor and Test Networks
|

* Requirement 10: Track and monitor all access to network resources and cardholder data
* Requirement 11: Regularly test security systems and processes
|-
| Maintain an Information Security Policy
|

* Requirement 12: Maintain a policy that addresses information security
|}

Specifically, relevant elements to an e-commerce business' PCI compliance status include:

* Properly using your payment application. For this purpose, carefully review the section below for information on how to use '''X-Cart Payments''' in a way that ensures PCI compliance.

* Using a PCI compliant Web hosting environment

* Using a PCI compliant payment provider

You can find and review the complete specification by visiting [https://www.pcisecuritystandards.org/ https://www.pcisecuritystandards.org/]

This guide is intended to help merchants implement the '''X-Cart Payments''' application in a way that is compliant with version 2.0 of the PCI DSS.

== Payment Card Industry Data Security Standard ('''PCI DSS''') ==

The Payment Card Industry Data Security Standard is a worldwide information security standard assembled by the major credit card vendors, including American Express, Discover Financial Services, JCB International, MasterCard Worldwide, and Visa, Inc. The standard was designed to help organizations involved in processing credit card payments online make their payment systems secure from cardholder data fraud.

'''X-Cart Payments''' has been designed and certified to meet all of the requirements of the '''PA-DSS''' version 2.0. This does not automatically make you, the merchant, PCI DSS compliant. To ensure PCI DSS compliance, it is necessary that you follow the recommendations and instructions provided in this guide.

For additional information about '''PCI DSS''' please visit the [https://www.pcisecuritystandards.org Official PCI Security Standards Council Site].

== Cardholder data storage==

'''X-Cart Payments''' has [[X-Payments:General_settings#Cardholder_Data | the ability to store parts of cardholder data temporarily]] for performing 3D Secure verification and certain types of transactions for some of the integrated payment processors. While stored cardholder data is encrypted using special [[X-Payments:Encryption_keys | cryptographic algorithm]]. The data is removed automatically when its storing period is over using "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.

'''X-Cart Payments''' can not be configured to store permanently in the database the following types of data:

* unmasked PAN
* PIN
* CVV
* magnetic stripe (track data)

Merchants and/or developers implementing '''X-Cart Payments''' should not attempt to customize this as a feature.

'''X-Cart Payments''' can display masked PAN on "Payment details" pages and in "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. '''X-Cart Payments''' does not have the ability to display full PAN anywhere and there are no settings that can change this behavior of the user interface.

==Configuring and using '''X-Cart Payments''' in PCI compliant manner ==

===Installation===

Follow the [[X-Payments:Installation | standard procedure]] for deployment of X-Cart Payments files to the web server.

{{Note1|Once installed, X-Cart Payments WILL NEVER: 
* store unmasked credit card numbers (PANs)
* send credit card data or any other information to Qualiteam for debug purposes}}

===Access control===

You must carefully control access to '''X-Cart Payments'''. Follow these rules:

* Restrict the number of employees who have access to '''X-Cart Payments''' to only those who have a business need.
* Always provide unique usernames for each person who needs access.
* Do not use system-default usernames and/or passwords
* Web server must be run under a non-privileged user account. Application must access the database from a limited privilege user account.
* All default user accounts use secure authentication mechanisms and password policy settings that comply with all the standard requirements:
** user accounts inactive for more than 3 days are blocked
** password lifetime is set to 30 days

:: To set password lifetime:

::# Login to '''X-Cart Payments'''
::# Go to Settings -> General Settings
::# Enter the number of days the user account password will be valid for in the "User account password lifetime" field. The maximum allowed password lifetime is 90 days.

:* minimum password length is 8 characters
:* password must contain both lower and upper case characters and numbers
:* the last 4 passwords must be unique
:* user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password
:* user is logged off after inactivity period of 10 minutes

<div> Please note that changing default password policy settings will lead to breaking PCI DSS standard requirements.</div>

===Enabling SSL (Secure Socket Layer)===

SSL protects data that is transmitted between a browser and your web server. It is critical that you have SSL enabled on your web server, and this should be among the first steps taken after installation.

* Your web server must be configured to use TLS v1.2 protocols with strong encryption (128-bit or longer key is required)
* You will need to have a certificate issued for your web domain. Read [http://help.qtmsoft.com/index.php?title=Instant_SSL_certificate guidelines on installing Comodo's Instant SSL certificates].

If a web server does not have SSL enabled '''X-Cart Payments''' will not function or will be notifying users depending on '''allow_insecure_protocol''' parameter set in config.ini.php file (disabled by default).

===Data Collected while Testing===

Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:

# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever collect credit card information to troubleshoot a problem that one of your customers is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access
#* Only collect a limited amount of such data as needed to solve a specific problem
#* Sensitive authentication data must be encrypted while stored. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Such data must be securely deleted immediately after use.

===Encryption Key Management===

As part of your PA DSS v3.1 requirements, encryption key must be changed annually (changing every 90 days is recommended). You should also change the key any time an employee with access to the key leaves your company. Always replace the key if you know or suspect it has been compromised by any means.

To change the encryption keys:

# Log in to '''X-Cart Payments'''
# Go to Maintenance -> Encryption keys
# Click "Generate new keys"

===Use unique user IDs and secure authentication to access PCs, servers and databases ===

PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:

# For your Web hosting account administration area (Web hosting account where your online store is hosted)
# For FTP access to the Web server
# For Remote Desktop Connection to the Web server (if available)
# To connect to the MySQL server that contains your store data.

The passwords for the accounts mentioned above must also meet the following requirements:

* be at least 8 characters in length
* contain both numbers and letters in lower and upper case
* not coincide with any part of your email address
* not coincide with any of the last four passwords you have used
* have a lifetime of less than 90 days
* account lockout threshold must be set to 6.
* account lockout duration must be set to 30 minutes (or until unblocked by the administrator).
* user must be logged off after 15 minutes of inactivity

===Audit trails===

Audit trails are automatically enabled with the default installation of X-Cart Payments. There is no option to disable audit logging. The log files are created in the var/log/ directory. Make sure you restrict access to the log files by business need-to-know.

The following types of activity are logged:

* All actions taken by any individual with root or administrative privileges
* Successes and failures of all individual accesses to application sections and functions

* Initialization of the audit logs
* User sign in and sign out.

Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to files access.log and error.log.

Each log event includes:

* Type of event
* Date and time of event
* Username and IP address
* Success or failure indication
* Action which led to the event

* Component which led to the event

There is also a meta-log which contains information about other log files being created.

=== OS-level audit trails ===

Make sure you have a system-level auditing software properly configured to monitor users' activity on server. This software should:

* warn on a checksum change of any of X-Cart Payments source code files except of log file and database files
* record any file writing operations related to X-Cart Payments files

===Encrypting network traffic===

X-Cart Payments uses encryption, such as TLS or IPSEC, for:

* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
* providing remote web-based access to the application

If you use tools to remotely access the application, you should encrypt all communication using technologies such as TLS or IPSEC.

As per PCI DSS requirement 4.2, cardholder data should never be sent unencrypted by e-mail, and X-Cart Payments does meet this requirement '''never''' sending cardholder data by e-mail or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.

===Wireless communications===

If you use wireless networking to access '''X-Cart Payments''', it is your responsibility to ensure your wireless security con figuration follows the PCI DSS requirements.

* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
* Use with a minimum 104-bit encryption key and 24 bit-initialization value
* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS
* Rotate shared WEP keys quarterly (or automatically if the technology permits)
* Rotate shared WEP keys whenever there are changes in personnel with access to keys
* Restrict access based on media access cod e (MAC) address.
* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.

===Remote access===

X-Cart Payments provides web-based access using two-factor authentication based on one-time PIN codes. Detailed information can be found at [[X-Payments:Managing_PIN_codes | Managing PIN codes]] page.

If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:

* Change default settings in the remote access software (for example, change default passwords and use unique passwords for each customer)
* Allow connections only from specific (known) IP/MAC addresses
* Use strong authentication or complex passwords for logins
* Enable encrypted data transmission
* Enable account lockout after a certain number of failed login attempts
* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed
* Enable any logging or auditing functions
* Restrict access to customer passwords to authorized reseller/integrator personnel
* Establish customer passwords according to PCI DSS requirements 8.1, 8.2, 8.4, 8.5

Qualiteam does not provide software updates via remote access on an automated basis.

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PCI DSS implementation guide for X-Payments 2.2

2015-12-14T14:24:06Z

Alex “Ambal” Mulin: /* Remote access */

== Introduction ==

This guide covers '''X-Cart Payments''' 1.0, 2.0, 2.1, 2.2 and is intended for merchants and integrators who wish to implement the application in accordance with guidelines set by the PCI Data Security Standard (PCI DSS).

== PCI DSS ==

PCI DSS specifies 12 requirements broken into 6 groups for compliance that apply both to hardware and software parts of the system that is used to collect, store, transmit and process valuable credit card data as well as the human factor.

{| border
| Build and Maintain a Secure Network
|

* Requirement 1: Install and maintain a firewall configuration to protect cardholder data
* Requirement 2: Do not use vendor-supplied defaults for system passwords and other security parameters
|-
| Protect Cardholder Data
|

* Requirement 3: Protect stored cardholder data
* Requirement 4: Encrypt transmission of cardholder data across open, public networks
|-
| Maintain a Vulnerability Management Program
|

* Requirement 5: Use and regularly update anti-virus software
* Requirement 6: Develop and maintain secure systems and applications
|-
| Implement Strong Access Control Measures
|

* Requirement 7: Restrict access to cardholder data by business need-to-know
* Requirement 8: Assign a unique ID to each person with computer access
* Requirement 9: Restrict physical access to cardholder data
|-
| Regularly Monitor and Test Networks
|

* Requirement 10: Track and monitor all access to network resources and cardholder data
* Requirement 11: Regularly test security systems and processes
|-
| Maintain an Information Security Policy
|

* Requirement 12: Maintain a policy that addresses information security
|}

Specifically, relevant elements to an e-commerce business' PCI compliance status include:

* Properly using your payment application. For this purpose, carefully review the section below for information on how to use '''X-Cart Payments''' in a way that ensures PCI compliance.

* Using a PCI compliant Web hosting environment

* Using a PCI compliant payment provider

You can find and review the complete specification by visiting [https://www.pcisecuritystandards.org/ https://www.pcisecuritystandards.org/]

This guide is intended to help merchants implement the '''X-Cart Payments''' application in a way that is compliant with version 2.0 of the PCI DSS.

== Payment Card Industry Data Security Standard ('''PCI DSS''') ==

The Payment Card Industry Data Security Standard is a worldwide information security standard assembled by the major credit card vendors, including American Express, Discover Financial Services, JCB International, MasterCard Worldwide, and Visa, Inc. The standard was designed to help organizations involved in processing credit card payments online make their payment systems secure from cardholder data fraud.

'''X-Cart Payments''' has been designed and certified to meet all of the requirements of the '''PA-DSS''' version 2.0. This does not automatically make you, the merchant, PCI DSS compliant. To ensure PCI DSS compliance, it is necessary that you follow the recommendations and instructions provided in this guide.

For additional information about '''PCI DSS''' please visit the [https://www.pcisecuritystandards.org Official PCI Security Standards Council Site].

== Cardholder data storage==

'''X-Cart Payments''' has [[X-Payments:General_settings#Cardholder_Data | the ability to store parts of cardholder data temporarily]] for performing 3D Secure verification and certain types of transactions for some of the integrated payment processors. While stored cardholder data is encrypted using special [[X-Payments:Encryption_keys | cryptographic algorithm]]. The data is removed automatically when its storing period is over using "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.

'''X-Cart Payments''' can not be configured to store permanently in the database the following types of data:

* unmasked PAN
* PIN
* CVV
* magnetic stripe (track data)

Merchants and/or developers implementing '''X-Cart Payments''' should not attempt to customize this as a feature.

'''X-Cart Payments''' can display masked PAN on "Payment details" pages and in "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. '''X-Cart Payments''' does not have the ability to display full PAN anywhere and there are no settings that can change this behavior of the user interface.

==Configuring and using '''X-Cart Payments''' in PCI compliant manner ==

===Installation===

Follow the [[X-Payments:Installation | standard procedure]] for deployment of X-Cart Payments files to the web server.

{{Note1|Once installed, X-Cart Payments WILL NEVER: 
* store unmasked credit card numbers (PANs)
* send credit card data or any other information to Qualiteam for debug purposes}}

===Access control===

You must carefully control access to '''X-Cart Payments'''. Follow these rules:

* Restrict the number of employees who have access to '''X-Cart Payments''' to only those who have a business need.
* Always provide unique usernames for each person who needs access.
* Do not use system-default usernames and/or passwords
* Web server must be run under a non-privileged user account. Application must access the database from a limited privilege user account.
* All default user accounts use secure authentication mechanisms and password policy settings that comply with all the standard requirements:
** user accounts inactive for more than 3 days are blocked
** password lifetime is set to 30 days

:: To set password lifetime:

::# Login to '''X-Cart Payments'''
::# Go to Settings -> General Settings
::# Enter the number of days the user account password will be valid for in the "User account password lifetime" field. The maximum allowed password lifetime is 90 days.

:* minimum password length is 8 characters
:* password must contain both lower and upper case characters and numbers
:* the last 4 passwords must be unique
:* user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password
:* user is logged off after inactivity period of 10 minutes

<div> Please note that changing default password policy settings will lead to breaking PCI DSS standard requirements.</div>

===Enabling SSL (Secure Socket Layer)===

SSL protects data that is transmitted between a browser and your web server. It is critical that you have SSL enabled on your web server, and this should be among the first steps taken after installation.

* Your web server must be configured to use TLS v1.2 protocols with strong encryption (128-bit or longer key is required)
* You will need to have a certificate issued for your web domain. Read [http://help.qtmsoft.com/index.php?title=Instant_SSL_certificate guidelines on installing Comodo's Instant SSL certificates].

If a web server does not have SSL enabled '''X-Cart Payments''' will not function or will be notifying users depending on '''allow_insecure_protocol''' parameter set in config.ini.php file (disabled by default).

===Data Collected while Testing===

Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:

# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever collect credit card information to troubleshoot a problem that one of your customers is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access
#* Only collect a limited amount of such data as needed to solve a specific problem
#* Sensitive authentication data must be encrypted while stored. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Such data must be securely deleted immediately after use.

===Encryption Key Management===

As part of your PA DSS v3.1 requirements, encryption key must be changed annually (changing every 90 days is recommended). You should also change the key any time an employee with access to the key leaves your company. Always replace the key if you know or suspect it has been compromised by any means.

To change the encryption keys:

# Log in to '''X-Cart Payments'''
# Go to Maintenance -> Encryption keys
# Click "Generate new keys"

===Use unique user IDs and secure authentication to access PCs, servers and databases ===

PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:

# For your Web hosting account administration area (Web hosting account where your online store is hosted)
# For FTP access to the Web server
# For Remote Desktop Connection to the Web server (if available)
# To connect to the MySQL server that contains your store data.

The passwords for the accounts mentioned above must also meet the following requirements:

* be at least 8 characters in length
* contain both numbers and letters in lower and upper case
* not coincide with any part of your email address
* not coincide with any of the last four passwords you have used
* have a lifetime of less than 90 days
* account lockout threshold must be set to 6.
* account lockout duration must be set to 30 minutes (or until unblocked by the administrator).
* user must be logged off after 15 minutes of inactivity

===Audit trails===

Audit trails are automatically enabled with the default installation of X-Cart Payments. There is no option to disable audit logging. The log files are created in the var/log/ directory. Make sure you restrict access to the log files by business need-to-know.

The following types of activity are logged:

* All actions taken by any individual with root or administrative privileges
* Successes and failures of all individual accesses to application sections and functions

* Initialization of the audit logs
* User sign in and sign out.

Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to files access.log and error.log.

Each log event includes:

* Type of event
* Date and time of event
* Username and IP address
* Success or failure indication
* Action which led to the event

* Component which led to the event

There is also a meta-log which contains information about other log files being created.

=== OS-level audit trails ===

Make sure you have a system-level auditing software properly configured to monitor users' activity on server. This software should:

* warn on a checksum change of any of X-Cart Payments source code files except of log file and database files
* record any file writing operations related to X-Cart Payments files

===Encrypting network traffic===

X-Cart Payments uses encryption, such as TLS or IPSEC, for:

* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
* providing remote web-based access to the application

If you use tools to remotely access the application, you should encrypt all communication using technologies such as TLS or IPSEC.

As per PCI DSS requirement 4.2, cardholder data should never be sent unencrypted by e-mail, and X-Cart Payments does meet this requirement '''never''' sending cardholder data by e-mail or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.

===Wireless communications===

If you use wireless networking to access '''X-Cart Payments''', it is your responsibility to ensure your wireless security con figuration follows the PCI DSS requirements.

* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
* Use with a minimum 104-bit encryption key and 24 bit-initialization value
* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS
* Rotate shared WEP keys quarterly (or automatically if the technology permits)
* Rotate shared WEP keys whenever there are changes in personnel with access to keys
* Restrict access based on media access cod e (MAC) address.
* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.

===Remote access===

X-Cart Payments provides web-based access using two-factor authentication based on one-time PIN codes. Detailed information can be found at [[X-Payments:Managing_PIN_codes | Managing PIN codes]] page.

If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS 1.2 or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:

* Change default settings in the remote access software (for example, change default passwords and use unique passwords for each customer)
* Allow connections only from specific (known) IP/MAC addresses
* Use strong authentication or complex passwords for logins
* Enable encrypted data transmission
* Enable account lockout after a certain number of failed login attempts
* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed
* Enable any logging or auditing functions
* Restrict access to customer passwords to authorized reseller/integrator personnel
* Establish customer passwords according to PCI DSS requirements 8.1, 8.2, 8.4, 8.5

Qualiteam does not provide software updates via remote access on an automated basis.

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]
* [http://www.braintreepaymentsolutions.com/assets/308/PCI-Compliance.pdf Braintree PCI DSS compliance Quick Guide]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PCI DSS implementation guide for X-Payments 2.2

2015-12-14T14:23:24Z

Alex “Ambal” Mulin: /* Cardholder data storage */

== Introduction ==

This guide covers '''X-Cart Payments''' 1.0, 2.0, 2.1, 2.2 and is intended for merchants and integrators who wish to implement the application in accordance with guidelines set by the PCI Data Security Standard (PCI DSS).

== PCI DSS ==

PCI DSS specifies 12 requirements broken into 6 groups for compliance that apply both to hardware and software parts of the system that is used to collect, store, transmit and process valuable credit card data as well as the human factor.

{| border
| Build and Maintain a Secure Network
|

* Requirement 1: Install and maintain a firewall configuration to protect cardholder data
* Requirement 2: Do not use vendor-supplied defaults for system passwords and other security parameters
|-
| Protect Cardholder Data
|

* Requirement 3: Protect stored cardholder data
* Requirement 4: Encrypt transmission of cardholder data across open, public networks
|-
| Maintain a Vulnerability Management Program
|

* Requirement 5: Use and regularly update anti-virus software
* Requirement 6: Develop and maintain secure systems and applications
|-
| Implement Strong Access Control Measures
|

* Requirement 7: Restrict access to cardholder data by business need-to-know
* Requirement 8: Assign a unique ID to each person with computer access
* Requirement 9: Restrict physical access to cardholder data
|-
| Regularly Monitor and Test Networks
|

* Requirement 10: Track and monitor all access to network resources and cardholder data
* Requirement 11: Regularly test security systems and processes
|-
| Maintain an Information Security Policy
|

* Requirement 12: Maintain a policy that addresses information security
|}

Specifically, relevant elements to an e-commerce business' PCI compliance status include:

* Properly using your payment application. For this purpose, carefully review the section below for information on how to use '''X-Cart Payments''' in a way that ensures PCI compliance.

* Using a PCI compliant Web hosting environment

* Using a PCI compliant payment provider

You can find and review the complete specification by visiting [https://www.pcisecuritystandards.org/ https://www.pcisecuritystandards.org/]

This guide is intended to help merchants implement the '''X-Cart Payments''' application in a way that is compliant with version 2.0 of the PCI DSS.

== Payment Card Industry Data Security Standard ('''PCI DSS''') ==

The Payment Card Industry Data Security Standard is a worldwide information security standard assembled by the major credit card vendors, including American Express, Discover Financial Services, JCB International, MasterCard Worldwide, and Visa, Inc. The standard was designed to help organizations involved in processing credit card payments online make their payment systems secure from cardholder data fraud.

'''X-Cart Payments''' has been designed and certified to meet all of the requirements of the '''PA-DSS''' version 2.0. This does not automatically make you, the merchant, PCI DSS compliant. To ensure PCI DSS compliance, it is necessary that you follow the recommendations and instructions provided in this guide.

For additional information about '''PCI DSS''' please visit the [https://www.pcisecuritystandards.org Official PCI Security Standards Council Site].

== Cardholder data storage==

'''X-Cart Payments''' has [[X-Payments:General_settings#Cardholder_Data | the ability to store parts of cardholder data temporarily]] for performing 3D Secure verification and certain types of transactions for some of the integrated payment processors. While stored cardholder data is encrypted using special [[X-Payments:Encryption_keys | cryptographic algorithm]]. The data is removed automatically when its storing period is over using "cron" software that needs to be installed and configured to run X-Cart Payments periodic tasks.

'''X-Cart Payments''' can not be configured to store permanently in the database the following types of data:

* unmasked PAN
* PIN
* CVV
* magnetic stripe (track data)

Merchants and/or developers implementing '''X-Cart Payments''' should not attempt to customize this as a feature.

'''X-Cart Payments''' can display masked PAN on "Payment details" pages and in "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. '''X-Cart Payments''' does not have the ability to display full PAN anywhere and there are no settings that can change this behavior of the user interface.

==Configuring and using '''X-Cart Payments''' in PCI compliant manner ==

===Installation===

Follow the [[X-Payments:Installation | standard procedure]] for deployment of X-Cart Payments files to the web server.

{{Note1|Once installed, X-Cart Payments WILL NEVER: 
* store unmasked credit card numbers (PANs)
* send credit card data or any other information to Qualiteam for debug purposes}}

===Access control===

You must carefully control access to '''X-Cart Payments'''. Follow these rules:

* Restrict the number of employees who have access to '''X-Cart Payments''' to only those who have a business need.
* Always provide unique usernames for each person who needs access.
* Do not use system-default usernames and/or passwords
* Web server must be run under a non-privileged user account. Application must access the database from a limited privilege user account.
* All default user accounts use secure authentication mechanisms and password policy settings that comply with all the standard requirements:
** user accounts inactive for more than 3 days are blocked
** password lifetime is set to 30 days

:: To set password lifetime:

::# Login to '''X-Cart Payments'''
::# Go to Settings -> General Settings
::# Enter the number of days the user account password will be valid for in the "User account password lifetime" field. The maximum allowed password lifetime is 90 days.

:* minimum password length is 8 characters
:* password must contain both lower and upper case characters and numbers
:* the last 4 passwords must be unique
:* user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password
:* user is logged off after inactivity period of 10 minutes

<div> Please note that changing default password policy settings will lead to breaking PCI DSS standard requirements.</div>

===Enabling SSL (Secure Socket Layer)===

SSL protects data that is transmitted between a browser and your web server. It is critical that you have SSL enabled on your web server, and this should be among the first steps taken after installation.

* Your web server must be configured to use TLS v1.2 protocols with strong encryption (128-bit or longer key is required)
* You will need to have a certificate issued for your web domain. Read [http://help.qtmsoft.com/index.php?title=Instant_SSL_certificate guidelines on installing Comodo's Instant SSL certificates].

If a web server does not have SSL enabled '''X-Cart Payments''' will not function or will be notifying users depending on '''allow_insecure_protocol''' parameter set in config.ini.php file (disabled by default).

===Data Collected while Testing===

Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:

# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever collect credit card information to troubleshoot a problem that one of your customers is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access
#* Only collect a limited amount of such data as needed to solve a specific problem
#* Sensitive authentication data must be encrypted while stored. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Such data must be securely deleted immediately after use.

===Encryption Key Management===

As part of your PA DSS v3.1 requirements, encryption key must be changed annually (changing every 90 days is recommended). You should also change the key any time an employee with access to the key leaves your company. Always replace the key if you know or suspect it has been compromised by any means.

To change the encryption keys:

# Log in to '''X-Cart Payments'''
# Go to Maintenance -> Encryption keys
# Click "Generate new keys"

===Use unique user IDs and secure authentication to access PCs, servers and databases ===

PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:

# For your Web hosting account administration area (Web hosting account where your online store is hosted)
# For FTP access to the Web server
# For Remote Desktop Connection to the Web server (if available)
# To connect to the MySQL server that contains your store data.

The passwords for the accounts mentioned above must also meet the following requirements:

* be at least 8 characters in length
* contain both numbers and letters in lower and upper case
* not coincide with any part of your email address
* not coincide with any of the last four passwords you have used
* have a lifetime of less than 90 days
* account lockout threshold must be set to 6.
* account lockout duration must be set to 30 minutes (or until unblocked by the administrator).
* user must be logged off after 15 minutes of inactivity

===Audit trails===

Audit trails are automatically enabled with the default installation of X-Cart Payments. There is no option to disable audit logging. The log files are created in the var/log/ directory. Make sure you restrict access to the log files by business need-to-know.

The following types of activity are logged:

* All actions taken by any individual with root or administrative privileges
* Successes and failures of all individual accesses to application sections and functions

* Initialization of the audit logs
* User sign in and sign out.

Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to files access.log and error.log.

Each log event includes:

* Type of event
* Date and time of event
* Username and IP address
* Success or failure indication
* Action which led to the event

* Component which led to the event

There is also a meta-log which contains information about other log files being created.

=== OS-level audit trails ===

Make sure you have a system-level auditing software properly configured to monitor users' activity on server. This software should:

* warn on a checksum change of any of X-Cart Payments source code files except of log file and database files
* record any file writing operations related to X-Cart Payments files

===Encrypting network traffic===

X-Cart Payments uses encryption, such as TLS or IPSEC, for:

* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
* providing remote web-based access to the application

If you use tools to remotely access the application, you should encrypt all communication using technologies such as TLS or IPSEC.

As per PCI DSS requirement 4.2, cardholder data should never be sent unencrypted by e-mail, and X-Cart Payments does meet this requirement '''never''' sending cardholder data by e-mail or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.

===Wireless communications===

If you use wireless networking to access '''X-Cart Payments''', it is your responsibility to ensure your wireless security con figuration follows the PCI DSS requirements.

* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
* Use with a minimum 104-bit encryption key and 24 bit-initialization value
* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS
* Rotate shared WEP keys quarterly (or automatically if the technology permits)
* Rotate shared WEP keys whenever there are changes in personnel with access to keys
* Restrict access based on media access cod e (MAC) address.
* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.

===Remote access===

X-Cart Payments provides web-based access using two-factor authentication based on one-time PIN codes. Detailed information can be found at [[X-Payments:Managing_PIN_codes | Managing PIN codes]] page.

If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:

* Change default settings in the remote access software (for example, change default passwords and use unique passwords for each customer)
* Allow connections only from specific (known) IP/MAC addresses
* Use strong authentication or complex passwords for logins
* Enable encrypted data transmission
* Enable account lockout after a certain number of failed login attempts
* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed
* Enable any logging or auditing functions
* Restrict access to customer passwords to authorized reseller/integrator personnel
* Establish customer passwords according to PCI DSS requirements 8.1, 8.2, 8.4, 8.5

Qualiteam does not provide software updates via remote access on an automated basis.

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]
* [http://www.braintreepaymentsolutions.com/assets/308/PCI-Compliance.pdf Braintree PCI DSS compliance Quick Guide]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PCI DSS implementation guide for X-Payments 2.2

2015-12-14T14:21:41Z

Alex “Ambal” Mulin: /* Encryption Key Management */

== Introduction ==

This guide covers '''X-Cart Payments''' 1.0, 2.0, 2.1, 2.2 and is intended for merchants and integrators who wish to implement the application in accordance with guidelines set by the PCI Data Security Standard (PCI DSS).

== PCI DSS ==

PCI DSS specifies 12 requirements broken into 6 groups for compliance that apply both to hardware and software parts of the system that is used to collect, store, transmit and process valuable credit card data as well as the human factor.

{| border
| Build and Maintain a Secure Network
|

* Requirement 1: Install and maintain a firewall configuration to protect cardholder data
* Requirement 2: Do not use vendor-supplied defaults for system passwords and other security parameters
|-
| Protect Cardholder Data
|

* Requirement 3: Protect stored cardholder data
* Requirement 4: Encrypt transmission of cardholder data across open, public networks
|-
| Maintain a Vulnerability Management Program
|

* Requirement 5: Use and regularly update anti-virus software
* Requirement 6: Develop and maintain secure systems and applications
|-
| Implement Strong Access Control Measures
|

* Requirement 7: Restrict access to cardholder data by business need-to-know
* Requirement 8: Assign a unique ID to each person with computer access
* Requirement 9: Restrict physical access to cardholder data
|-
| Regularly Monitor and Test Networks
|

* Requirement 10: Track and monitor all access to network resources and cardholder data
* Requirement 11: Regularly test security systems and processes
|-
| Maintain an Information Security Policy
|

* Requirement 12: Maintain a policy that addresses information security
|}

Specifically, relevant elements to an e-commerce business' PCI compliance status include:

* Properly using your payment application. For this purpose, carefully review the section below for information on how to use '''X-Cart Payments''' in a way that ensures PCI compliance.

* Using a PCI compliant Web hosting environment

* Using a PCI compliant payment provider

You can find and review the complete specification by visiting [https://www.pcisecuritystandards.org/ https://www.pcisecuritystandards.org/]

This guide is intended to help merchants implement the '''X-Cart Payments''' application in a way that is compliant with version 2.0 of the PCI DSS.

== Payment Card Industry Data Security Standard ('''PCI DSS''') ==

The Payment Card Industry Data Security Standard is a worldwide information security standard assembled by the major credit card vendors, including American Express, Discover Financial Services, JCB International, MasterCard Worldwide, and Visa, Inc. The standard was designed to help organizations involved in processing credit card payments online make their payment systems secure from cardholder data fraud.

'''X-Cart Payments''' has been designed and certified to meet all of the requirements of the '''PA-DSS''' version 2.0. This does not automatically make you, the merchant, PCI DSS compliant. To ensure PCI DSS compliance, it is necessary that you follow the recommendations and instructions provided in this guide.

For additional information about '''PCI DSS''' please visit the [https://www.pcisecuritystandards.org Official PCI Security Standards Council Site].

== Cardholder data storage==

'''X-Cart Payments''' has [[X-Payments:General_settings#Cardholder_Data | the ability to store parts of cardholder data temporarily]] for performing 3D Secure verification and certain types of transactions for some of the integrated payment processors. While stored cardholder data is encrypted using special [[X-Payments:Encryption_keys | cryptographic algorithm]]. The data is removed automatically when its storing period is over.

'''X-Cart Payments''' can not be configured to store permanently in the database the following types of data:

* unmasked PAN
* PIN
* CVV
* magnetic stripe (track data)

Merchants and/or developers implementing '''X-Cart Payments''' should not attempt to customize this as a feature.

'''X-Cart Payments''' can display masked PAN on "Payment details" pages and in "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. '''X-Cart Payments''' does not have the ability to display full PAN anywhere and there are no settings that can change this behavior of the user interface.

==Configuring and using '''X-Cart Payments''' in PCI compliant manner ==

===Installation===

Follow the [[X-Payments:Installation | standard procedure]] for deployment of X-Cart Payments files to the web server.

{{Note1|Once installed, X-Cart Payments WILL NEVER: 
* store unmasked credit card numbers (PANs)
* send credit card data or any other information to Qualiteam for debug purposes}}

===Access control===

You must carefully control access to '''X-Cart Payments'''. Follow these rules:

* Restrict the number of employees who have access to '''X-Cart Payments''' to only those who have a business need.
* Always provide unique usernames for each person who needs access.
* Do not use system-default usernames and/or passwords
* Web server must be run under a non-privileged user account. Application must access the database from a limited privilege user account.
* All default user accounts use secure authentication mechanisms and password policy settings that comply with all the standard requirements:
** user accounts inactive for more than 3 days are blocked
** password lifetime is set to 30 days

:: To set password lifetime:

::# Login to '''X-Cart Payments'''
::# Go to Settings -> General Settings
::# Enter the number of days the user account password will be valid for in the "User account password lifetime" field. The maximum allowed password lifetime is 90 days.

:* minimum password length is 8 characters
:* password must contain both lower and upper case characters and numbers
:* the last 4 passwords must be unique
:* user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password
:* user is logged off after inactivity period of 10 minutes

<div> Please note that changing default password policy settings will lead to breaking PCI DSS standard requirements.</div>

===Enabling SSL (Secure Socket Layer)===

SSL protects data that is transmitted between a browser and your web server. It is critical that you have SSL enabled on your web server, and this should be among the first steps taken after installation.

* Your web server must be configured to use TLS v1.2 protocols with strong encryption (128-bit or longer key is required)
* You will need to have a certificate issued for your web domain. Read [http://help.qtmsoft.com/index.php?title=Instant_SSL_certificate guidelines on installing Comodo's Instant SSL certificates].

If a web server does not have SSL enabled '''X-Cart Payments''' will not function or will be notifying users depending on '''allow_insecure_protocol''' parameter set in config.ini.php file (disabled by default).

===Data Collected while Testing===

Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:

# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever collect credit card information to troubleshoot a problem that one of your customers is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access
#* Only collect a limited amount of such data as needed to solve a specific problem
#* Sensitive authentication data must be encrypted while stored. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Such data must be securely deleted immediately after use.

===Encryption Key Management===

As part of your PA DSS v3.1 requirements, encryption key must be changed annually (changing every 90 days is recommended). You should also change the key any time an employee with access to the key leaves your company. Always replace the key if you know or suspect it has been compromised by any means.

To change the encryption keys:

# Log in to '''X-Cart Payments'''
# Go to Maintenance -> Encryption keys
# Click "Generate new keys"

===Use unique user IDs and secure authentication to access PCs, servers and databases ===

PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:

# For your Web hosting account administration area (Web hosting account where your online store is hosted)
# For FTP access to the Web server
# For Remote Desktop Connection to the Web server (if available)
# To connect to the MySQL server that contains your store data.

The passwords for the accounts mentioned above must also meet the following requirements:

* be at least 8 characters in length
* contain both numbers and letters in lower and upper case
* not coincide with any part of your email address
* not coincide with any of the last four passwords you have used
* have a lifetime of less than 90 days
* account lockout threshold must be set to 6.
* account lockout duration must be set to 30 minutes (or until unblocked by the administrator).
* user must be logged off after 15 minutes of inactivity

===Audit trails===

Audit trails are automatically enabled with the default installation of X-Cart Payments. There is no option to disable audit logging. The log files are created in the var/log/ directory. Make sure you restrict access to the log files by business need-to-know.

The following types of activity are logged:

* All actions taken by any individual with root or administrative privileges
* Successes and failures of all individual accesses to application sections and functions

* Initialization of the audit logs
* User sign in and sign out.

Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to files access.log and error.log.

Each log event includes:

* Type of event
* Date and time of event
* Username and IP address
* Success or failure indication
* Action which led to the event

* Component which led to the event

There is also a meta-log which contains information about other log files being created.

=== OS-level audit trails ===

Make sure you have a system-level auditing software properly configured to monitor users' activity on server. This software should:

* warn on a checksum change of any of X-Cart Payments source code files except of log file and database files
* record any file writing operations related to X-Cart Payments files

===Encrypting network traffic===

X-Cart Payments uses encryption, such as TLS or IPSEC, for:

* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
* providing remote web-based access to the application

If you use tools to remotely access the application, you should encrypt all communication using technologies such as TLS or IPSEC.

As per PCI DSS requirement 4.2, cardholder data should never be sent unencrypted by e-mail, and X-Cart Payments does meet this requirement '''never''' sending cardholder data by e-mail or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.

===Wireless communications===

If you use wireless networking to access '''X-Cart Payments''', it is your responsibility to ensure your wireless security con figuration follows the PCI DSS requirements.

* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
* Use with a minimum 104-bit encryption key and 24 bit-initialization value
* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS
* Rotate shared WEP keys quarterly (or automatically if the technology permits)
* Rotate shared WEP keys whenever there are changes in personnel with access to keys
* Restrict access based on media access cod e (MAC) address.
* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.

===Remote access===

X-Cart Payments provides web-based access using two-factor authentication based on one-time PIN codes. Detailed information can be found at [[X-Payments:Managing_PIN_codes | Managing PIN codes]] page.

If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:

* Change default settings in the remote access software (for example, change default passwords and use unique passwords for each customer)
* Allow connections only from specific (known) IP/MAC addresses
* Use strong authentication or complex passwords for logins
* Enable encrypted data transmission
* Enable account lockout after a certain number of failed login attempts
* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed
* Enable any logging or auditing functions
* Restrict access to customer passwords to authorized reseller/integrator personnel
* Establish customer passwords according to PCI DSS requirements 8.1, 8.2, 8.4, 8.5

Qualiteam does not provide software updates via remote access on an automated basis.

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]
* [http://www.braintreepaymentsolutions.com/assets/308/PCI-Compliance.pdf Braintree PCI DSS compliance Quick Guide]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]

X-Payments:PCI DSS implementation guide for X-Payments 2.2

2015-12-14T13:47:38Z

Alex “Ambal” Mulin: /* Cardholder data storage */

== Introduction ==

This guide covers '''X-Cart Payments''' 1.0, 2.0, 2.1, 2.2 and is intended for merchants and integrators who wish to implement the application in accordance with guidelines set by the PCI Data Security Standard (PCI DSS).

== PCI DSS ==

PCI DSS specifies 12 requirements broken into 6 groups for compliance that apply both to hardware and software parts of the system that is used to collect, store, transmit and process valuable credit card data as well as the human factor.

{| border
| Build and Maintain a Secure Network
|

* Requirement 1: Install and maintain a firewall configuration to protect cardholder data
* Requirement 2: Do not use vendor-supplied defaults for system passwords and other security parameters
|-
| Protect Cardholder Data
|

* Requirement 3: Protect stored cardholder data
* Requirement 4: Encrypt transmission of cardholder data across open, public networks
|-
| Maintain a Vulnerability Management Program
|

* Requirement 5: Use and regularly update anti-virus software
* Requirement 6: Develop and maintain secure systems and applications
|-
| Implement Strong Access Control Measures
|

* Requirement 7: Restrict access to cardholder data by business need-to-know
* Requirement 8: Assign a unique ID to each person with computer access
* Requirement 9: Restrict physical access to cardholder data
|-
| Regularly Monitor and Test Networks
|

* Requirement 10: Track and monitor all access to network resources and cardholder data
* Requirement 11: Regularly test security systems and processes
|-
| Maintain an Information Security Policy
|

* Requirement 12: Maintain a policy that addresses information security
|}

Specifically, relevant elements to an e-commerce business' PCI compliance status include:

* Properly using your payment application. For this purpose, carefully review the section below for information on how to use '''X-Cart Payments''' in a way that ensures PCI compliance.

* Using a PCI compliant Web hosting environment

* Using a PCI compliant payment provider

You can find and review the complete specification by visiting [https://www.pcisecuritystandards.org/ https://www.pcisecuritystandards.org/]

This guide is intended to help merchants implement the '''X-Cart Payments''' application in a way that is compliant with version 2.0 of the PCI DSS.

== Payment Card Industry Data Security Standard ('''PCI DSS''') ==

The Payment Card Industry Data Security Standard is a worldwide information security standard assembled by the major credit card vendors, including American Express, Discover Financial Services, JCB International, MasterCard Worldwide, and Visa, Inc. The standard was designed to help organizations involved in processing credit card payments online make their payment systems secure from cardholder data fraud.

'''X-Cart Payments''' has been designed and certified to meet all of the requirements of the '''PA-DSS''' version 2.0. This does not automatically make you, the merchant, PCI DSS compliant. To ensure PCI DSS compliance, it is necessary that you follow the recommendations and instructions provided in this guide.

For additional information about '''PCI DSS''' please visit the [https://www.pcisecuritystandards.org Official PCI Security Standards Council Site].

== Cardholder data storage==

'''X-Cart Payments''' has [[X-Payments:General_settings#Cardholder_Data | the ability to store parts of cardholder data temporarily]] for performing 3D Secure verification and certain types of transactions for some of the integrated payment processors. While stored cardholder data is encrypted using special [[X-Payments:Encryption_keys | cryptographic algorithm]]. The data is removed automatically when its storing period is over.

'''X-Cart Payments''' can not be configured to store permanently in the database the following types of data:

* unmasked PAN
* PIN
* CVV
* magnetic stripe (track data)

Merchants and/or developers implementing '''X-Cart Payments''' should not attempt to customize this as a feature.

'''X-Cart Payments''' can display masked PAN on "Payment details" pages and in "View details" pop-up windows for some of the integrated payment processors in the following format: 123456******1234 MM/YY or **********1234 MM/YY. '''X-Cart Payments''' does not have the ability to display full PAN anywhere and there are no settings that can change this behavior of the user interface.

==Configuring and using '''X-Cart Payments''' in PCI compliant manner ==

===Installation===

Follow the [[X-Payments:Installation | standard procedure]] for deployment of X-Cart Payments files to the web server.

{{Note1|Once installed, X-Cart Payments WILL NEVER: 
* store unmasked credit card numbers (PANs)
* send credit card data or any other information to Qualiteam for debug purposes}}

===Access control===

You must carefully control access to '''X-Cart Payments'''. Follow these rules:

* Restrict the number of employees who have access to '''X-Cart Payments''' to only those who have a business need.
* Always provide unique usernames for each person who needs access.
* Do not use system-default usernames and/or passwords
* Web server must be run under a non-privileged user account. Application must access the database from a limited privilege user account.
* All default user accounts use secure authentication mechanisms and password policy settings that comply with all the standard requirements:
** user accounts inactive for more than 3 days are blocked
** password lifetime is set to 30 days

:: To set password lifetime:

::# Login to '''X-Cart Payments'''
::# Go to Settings -> General Settings
::# Enter the number of days the user account password will be valid for in the "User account password lifetime" field. The maximum allowed password lifetime is 90 days.

:* minimum password length is 8 characters
:* password must contain both lower and upper case characters and numbers
:* the last 4 passwords must be unique
:* user account must be blocked for a specified period (30 minutes by default) after 6 unsuccessful attempts to enter a password
:* user is logged off after inactivity period of 10 minutes

<div> Please note that changing default password policy settings will lead to breaking PCI DSS standard requirements.</div>

===Enabling SSL (Secure Socket Layer)===

SSL protects data that is transmitted between a browser and your web server. It is critical that you have SSL enabled on your web server, and this should be among the first steps taken after installation.

* Your web server must be configured to use TLS v1.2 protocols with strong encryption (128-bit or longer key is required)
* You will need to have a certificate issued for your web domain. Read [http://help.qtmsoft.com/index.php?title=Instant_SSL_certificate guidelines on installing Comodo's Instant SSL certificates].

If a web server does not have SSL enabled '''X-Cart Payments''' will not function or will be notifying users depending on '''allow_insecure_protocol''' parameter set in config.ini.php file (disabled by default).

===Data Collected while Testing===

Delete any sensitive authentication data (pre-authorization) gathered as a result of testing or troubleshooting your X-Cart Payments:

# Sensitive authentication data (pre-authorization) must only be collected when needed to solve a specific problem. You should never use real credit card information when testing your store. Instead, contact your payment gateway and ask them for special credit card numbers that you can use while testing.
# If you ever collect credit card information to troubleshoot a problem that one of your customers is having, then please note the following:
#* Such data must be stored only in specific, known locations with limited access
#* Only collect a limited amount of such data as needed to solve a specific problem
#* Sensitive authentication data must be encrypted while stored. Make sure to encrypt it before storing it. There are many encryption software packages that you can install on your computer to do so.
# Such data must be securely deleted immediately after use.

===Encryption Key Management===

As part of your PCI DSS v2.0 requirements, encryption key must be changed annually (changing every 90 days is recommended). You should also change the key any time an employee with access to the key leaves your company. Always replace the key if you know or suspect it has been compromised by any means.

To change the encryption keys:

# Log in to '''X-Cart Payments'''
# Go to Maintenance -> Encryption keys
# Click "Generate new keys"

===Use unique user IDs and secure authentication to access PCs, servers and databases ===

PCI compliance requires that you use unique user names and secure authentication to access any PCs, servers, and databases with payment applications and/or cardholder data. This means that you should use different user names/passwords:

# For your Web hosting account administration area (Web hosting account where your online store is hosted)
# For FTP access to the Web server
# For Remote Desktop Connection to the Web server (if available)
# To connect to the MySQL server that contains your store data.

The passwords for the accounts mentioned above must also meet the following requirements:

* be at least 8 characters in length
* contain both numbers and letters in lower and upper case
* not coincide with any part of your email address
* not coincide with any of the last four passwords you have used
* have a lifetime of less than 90 days
* account lockout threshold must be set to 6.
* account lockout duration must be set to 30 minutes (or until unblocked by the administrator).
* user must be logged off after 15 minutes of inactivity

===Audit trails===

Audit trails are automatically enabled with the default installation of X-Cart Payments. There is no option to disable audit logging. The log files are created in the var/log/ directory. Make sure you restrict access to the log files by business need-to-know.

The following types of activity are logged:

* All actions taken by any individual with root or administrative privileges
* Successes and failures of all individual accesses to application sections and functions

* Initialization of the audit logs
* User sign in and sign out.

Individual access to cardholder data is not logged, because cardholder data is not stored before and after authentication. Access to audit trails must be provided on the operating system level. Audit trails are written to the file system, to files access.log and error.log.

Each log event includes:

* Type of event
* Date and time of event
* Username and IP address
* Success or failure indication
* Action which led to the event

* Component which led to the event

There is also a meta-log which contains information about other log files being created.

=== OS-level audit trails ===

Make sure you have a system-level auditing software properly configured to monitor users' activity on server. This software should:

* warn on a checksum change of any of X-Cart Payments source code files except of log file and database files
* record any file writing operations related to X-Cart Payments files

===Encrypting network traffic===

X-Cart Payments uses encryption, such as TLS or IPSEC, for:

* transmission of cardholder data over public networks, per PCI DSS requirement 4.1.
* providing remote web-based access to the application

If you use tools to remotely access the application, you should encrypt all communication using technologies such as TLS or IPSEC.

As per PCI DSS requirement 4.2, cardholder data should never be sent unencrypted by e-mail, and X-Cart Payments does meet this requirement '''never''' sending cardholder data by e-mail or by IMs. Merchants and/or developers implementing X-Cart Payments should not attempt to customize this as a feature unless an encryption solution is also implemented.

===Wireless communications===

If you use wireless networking to access '''X-Cart Payments''', it is your responsibility to ensure your wireless security con figuration follows the PCI DSS requirements.

* Personal firewall software should be installed on any mobile and employee-owned computers that have direct access to the internet and are also used to access your network.
* Change wireless vendor defaults, including but not limited to, wired equivalent privacy (WEP) keys, default service set identifier (SSID), passwords and SNMP community strings. Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for encryption and authentication when WPA-capable.
* Encrypt wireless transmissions by using WiFi protected access (WPA or WPA2) technology, IPSEC VPN, or TLS.
* Never rely exclusively on wired equivalent privacy (WEP) to protect confidentiality and access to a wireless LAN. If WEP is used, do the following:
* Use with a minimum 104-bit encryption key and 24 bit-initialization value
* Use ONLY in conjunction with WiFi protected access (WPA or WPA2) technology, VPN, or TLS
* Rotate shared WEP keys quarterly (or automatically if the technology permits)
* Rotate shared WEP keys whenever there are changes in personnel with access to keys
* Restrict access based on media access cod e (MAC) address.
* Install perimeter firewalls between any wireless networks and the cardholder data environment, and configure these firewalls to deny any traffic from the wireless environment or to control any traffic if it is necessary for business purposes.

===Remote access===

X-Cart Payments provides web-based access using two-factor authentication based on one-time PIN codes. Detailed information can be found at [[X-Payments:Managing_PIN_codes | Managing PIN codes]] page.

If you enable remote access to your network and the cardholder data environment, you must implement two-factor authentication. Use technologies such as remote authentication and dial-in service (RADIUS) or terminal access controller access control system (TACACS) with tokens; or VPN (based on TLS or IPSEC) with individual certificates. You should make sure that any remote access software is securely configured by keeping in mind the following:

* Change default settings in the remote access software (for example, change default passwords and use unique passwords for each customer)
* Allow connections only from specific (known) IP/MAC addresses
* Use strong authentication or complex passwords for logins
* Enable encrypted data transmission
* Enable account lockout after a certain number of failed login attempts
* Configure the system so a remote user must establish a Virtual Private Network (“VPN”) connection via a firewall before access is allowed
* Enable any logging or auditing functions
* Restrict access to customer passwords to authorized reseller/integrator personnel
* Establish customer passwords according to PCI DSS requirements 8.1, 8.2, 8.4, 8.5

Qualiteam does not provide software updates via remote access on an automated basis.

==See also==

* [[X-Payments:PCI_FAQs | PCI FAQs]]
* [https://www.pcisecuritystandards.org/ PCI Security Standards Council website]
* [http://www.braintreepaymentsolutions.com/assets/308/PCI-Compliance.pdf Braintree PCI DSS compliance Quick Guide]

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

[[Category:X-Payments Developer Guide]]
[[Category:PCI DSS]]