Problem #

You receive an email from PayPal® that states that a PayPal Instant Payment Notification (IPN) failed:

Hi Name, 
Please check your server that handles PayPal Instant Payment Notifications (IPN). IPNs sent to the following URL(s) failed:

https://www.old-site-example.com/whmcs/modules/gateways/callback/paypal.php

 
If you don't recognise this URL, you may be using a service provider that is using IPN on your behalf. Please contact your service provider with the above information. If this problem continues, IPNs may be disabled for your account. 

Thank you for helping resolve this issue.

You may also see missing or incorrect transaction records within WHMCS, or you may see IPN Handshake Invalid or IPN Handshake Error in the Gateway Log at Configuration () > System Logs

Cause #

PayPal sends this email because it could not send a payment notification to your WHMCS installation.

This may indicate one of the following problems:

• Your website is offline or is experiencing other problems.
• You moved your WHMCS installation to a new URL.
• PayPal set your account charset to windows-1252, which can cause problems with some characters. Typically, this problem causes the IPN Handshake Invalid error.
• The system received the IPN from PayPal but could not verify it, often due to a cURL error. TLS 1.2 and HTTP/1.1 are mandatory for communication with PayPal. Typically, this problem causes the IPN Handshake Error error.

Troubleshooting #

To troubleshoot this issue:

• Check whether your website is fully operational.
• Check whether the URL in the PayPal email matches your WHMCS System URL setting in the General tab at Configuration () > System Settings > General Settings.
• Check the configured charset value in your PayPal account configuration.
• Check for cURL errors that indicate a problem with your system’s protocols.

You can also review the Gateway Log at Configuration () > System Logs.

Solution #

Use the steps below to resolve the issue.

PayPal will attempt to send the IPN again between four hours and four days after the initial failure. If you have successfully resolved the issue, WHMCS will record the payment without any additional action.

Website Inaccessible #

If your website is experiencing problems, find and resolve the issue. PayPal cannot successfully send IPNs until your site is online and functional.

Recently-Moved Installation #

If you recently moved your WHMCS installation, you may need to redirect IPN messages from your old location to the new URL.

To do this:

1. Download the paypal.php file.

2. Edit the file to update the $url value to your WHMCS installation’s new location. For example:

    ```
    $url = 'https://www.new-site-example.com/billing/modules/gateways/callback/paypal.php';
    ```
   

3. Upload the file to the location in the IPN failure email.

When PayPal’s IPN system encounters this file in the old location, it will retrieve your WHMCS installation’s new location from the $url value.

Charset Configuration #

Ensure that the charset in your PayPal account’s Language Encoding settings matches your WHMCS installation.

Callback Verification Failures #

Connection to PayPal’s callback verification service at https://www.paypal.com/cgi-bin/webscr can fail if the cURL connection does not use the required protocols. TLS 1.2 and HTTP/1.1 are mandatory for communication with PayPal.

The PayPal Basic payment gateway module does not specify a particular cryptographic protocol when communicating with PayPal. Instead, cURL on your server should automatically negotiate the best protocol to use. Work with your hosting provider or system administrator to ensure TLS 1.2 or greater is the default protocol on the server and that you can successfully connect to PayPal’s callback verification service.

You can check connection using cURL from your server’s command line:

curl -I https://www.paypal.com/cgi-bin/webscr

Last modified: February 6, 2025