X-Payments:Troubleshooting

X-Payments user manual

1. X-Payments:General information
   • How It Works
   • Key features
2. What's New
   • What's New in X-Payments 3.1
   • What's New in X-Payments 3.0
3. System requirements
   • System requirements for X-Payments 3
   • System requirements for X-Payments 2.2
4. Installation
   • Installing X-Payments
   • Setting up file permissions for X-Payments
   • Getting started with X-Payments
5. Two-factor user authentication
   • Two-factor authentication (X-Payments 3)
   • Managing PIN codes (X-Payments 2.2 and earlier)
6. Configuring X-Payments
   • General settings
   • Online stores
   • Payment configurations
   • Encryption keys
   • 3D-Secure settings
   • KOUNT Antifraud screening
   • NoFraud fraud prevention
   • Signifyd fraud protection and chargeback prevention
7. Managing users
8. Customizing the interface
   • Customizing the interface (X-Payments 3)
   • Customizing the interface (X-Payments 2.2 and earlier)
9. Managing payments
10. Unistalling X-Payments
11. Upgrading
12. Moving X-Payments from one host to another
13. Viewing X-Payments logs
14. FAQ
15. Troubleshooting
16. Glossary
17. Supported payment gateways
    • Payment gateways supported by X-Payments 3.1
    • Payment gateways supported by X-Payments 3.0
    • Payment gateways supported by X-Payments 2.2
18. Popular Payment Methods Configuration Instructions
    • PayPal Payments Pro (PayPal API), PayPal Payments Pro (Payflow API), Payflow Pro
    • PayPal REST API
    • First Data Payeezy Gateway (ex- Global Gateway e4)
    • CyberSource - SOAP toolkit API

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:

define('XP_DIR', rtrim(realpath(dirname(__FILE__)), XP_DS) . XP_DS);

with this line:

define('XP_DIR', rtrim(dirname(__FILE__), XP_DS) . XP_DS);

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 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:

1. 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 [| 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.146.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 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

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.

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

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 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 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 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:

1. Make sure you use X-Payments v2.x because X-Payments v1.x doesn't support this functionality.
2. 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.
3. 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 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

div.content div.buttonRow {
  margin: 35px auto;
  width: 400px;
}

you should add

display: block !important;

e.g. after correction that code will look like

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

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 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 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 ...".

Such notifications mean that X-Payments callback requests have failed because of timeout or because your online shop site was not reachable by X-Payments.

In the 1st case, the store did not respond within 15 seconds (15 seconds is the default value coded 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 too long for the store to respond. As a quick solution, it is recommended to increase the timeout limits in your X-Payments installation: If you are using X-Payments 2.x, in the file lib/XPay/Model/Payment.php, edit the line of code that looks like the following:

$requestData->setTimeout(15);

and change "15" to a bigger value (max 60).

If you are using X-Payments 3.x, in the file config/config.ini.php, locate the section [callback] and change the value of the 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 the vendors of the software by posting them a technical support ticket via https://secure.x-cart.com.

The proper solution is, however, to investigate the problem and find out why your web site is not responding to X-Payments callbacks within 15 seconds.

In the 2nd case, the problem might have been caused by a firewall blocking X-Payments callback requests or your web shop website being down.

"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

private function getInitRequestBody(XPay_Transport_GatewayRequest $request)

In the function find lines

...
        $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')),
...

and add a line of code

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

to get something like

            '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')),

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

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

E.g.

'CURRENCY'    => 'USD',

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:

 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.

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:

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

and change "Off" to "On" there.

Chase Paymentech in test mode: transaction is not processed with an unexpected error

When testing payments via the Chase Paymentech gateway, using a whole number as the order/payment total (i.e. an amount with .00 cents) is recommended for a successful transaction. Transactions with non-whole number values may not be successful because in some cases Chase Paymentech uses such values to emulate a processing error.

This article can be downloaded as a PDF file