Troubleshooting “SSL3_READ_BYTES:sslv3 alert handshake failure” When Connecting to PayPal API


2 views

When your e-commerce site attempts to communicate with PayPal's API (api.paypal.com), the SSL/TLS handshake fails at the protocol level. This specific error error:14094410 indicates the server rejected the handshake attempt due to protocol or cipher suite incompatibility.

PayPal has deprecated older SSL/TLS protocols since 2018. The error occurs because:

  • Your server/client is attempting SSLv3 connection (insecure and deprecated)
  • Outdated OpenSSL version doesn't support modern TLS protocols
  • Missing intermediate certificates in your trust chain

Verify your OpenSSL capabilities with:

openssl s_client -connect api.paypal.com:443 -servername api.paypal.com -showcerts

Check supported protocols with:

openssl ciphers -v | awk '{print $2}' | sort | uniq

For Apache servers, update your SSL configuration:

SSLProtocol all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
SSLCipherSuite HIGH:!aNULL:!MD5:!RC4:!3DES
SSLHonorCipherOrder on

For cURL requests, force TLS 1.2:

curl --tlsv1.2 https://api.paypal.com/

When using PayPal SDK in PHP:

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1_2);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($ch, CURLOPT_CAINFO, '/path/to/cacert.pem');

Ensure you have updated CA certificates. On Ubuntu/Debian:

sudo apt-get install --reinstall ca-certificates
sudo update-ca-certificates

Verify the connection works with OpenSSL 1.1.1+:

openssl s_client -connect api.paypal.com:443 -tls1_2

Successful output should show the complete certificate chain and established connection.


This SSL handshake failure typically occurs when there's a protocol mismatch between client and server. PayPal's API endpoints have strict TLS requirements, and as of 2021, they officially deprecated support for TLS 1.0/1.1.

The error message indicates several key points:


1. Client attempts SSLv3 connection (deprecated)
2. Server rejects with handshake failure
3. Certificate verification path exists (/etc/ssl/certs)
4. Connection terminates during TLS negotiation

For Apache servers, update your SSL configuration:


SSLProtocol all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
SSLHonorCipherOrder on
SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH

For PHP cURL implementations:


$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.paypal.com");
curl_setopt($ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1_2);
curl_setopt($ch, CURLOPT_SSL_CIPHER_LIST, 'TLS_AES_256_GCM_SHA384');
curl_setopt($ch, CURLOPT_CAINFO, '/path/to/cacert.pem');

Use OpenSSL to verify the connection:


openssl s_client -connect api.paypal.com:443 -tls1_2

Expected output should show a successful TLS 1.2 handshake with no protocol warnings.

PayPal's current API requirements mandate:

  • TLS 1.2 as minimum protocol version
  • HTTP/1.1 or HTTP/2 support
  • SHA-256 certificates
  • 2048-bit key length minimum

To diagnose exactly which protocols your client supports:


curl --tlsv1.2 --tls-max 1.2 -vI https://api.paypal.com

Watch out for these configuration mistakes:


1. Outdated OpenSSL libraries
2. System-wide crypto policies overriding settings
3. Missing intermediate certificates
4. Firewall rules blocking modern cipher suites

If unable to upgrade server configuration:


// Use PayPal's direct IP with forced TLS 1.2
curl --resolve api.paypal.com:443:66.211.168.123 \
     --tlsv1.2 https://api.paypal.com