Developer Portal

TLS 1.2 Upgrade

Heartland is upgrading the protocols used to secure all external connections made to our systems. Transport Layer Security version 1.2 (TLS 1.2) will become mandatory for communication with Heartland in 2018.

You will need to verify that your environment supports TLS 1.2, and if necessary make appropriate updates.

Learn More

The PCI SSC has extended the migration completion date to June 30th, 2018 for transitioning to a secure version of TLS.

TLS 1.2 Solutions

Please click one of the tabs below to get help with your specific implementation.

Problem 1

PHP-SDK cURL TLS 1.2 handshake failed.

If you have any questions, please contact Specialty Products Team at 866.802.9753. PHP allows complex web applications to be built rapidly. Most of the internet uses this open-source development environment for its speed from concept to deploy. Unfortunately updates are not usually automatic. PCI 3.1 introduces a requirement for the web server to support TLS 1.2 to our portico gateway. In an effort to begin dealing with this challenge prior to the hard final date in 2018 this change was applied already in our SDK.

Changes made to the SDK:

HpsSoapGatewayService | Line #327
Old Gateway:
New Gateway:

HpsSoapGatewayService | Line #331
Old gateway:

Problem 2

No error log.

This scenario applies if you suspect TLS or connectivity. Often problems follow an update to a plugin. The merchant pulls in the latest greatest version of the plugin and the change defined above is applied. They may not have access to the server logs. It may be necessary to have the merchant contact the hosting provider and or developer. Error logs are critical to getting a full picture.


For cURL to be able to connect to our PCI 3.1 compliant servers:

cURL needs to be a loaded module and it must be at least version 7.34.0 or higher. PHP Snip: curl_version()['version']

A valid SSL library loaded on the server see this reference. PHP Snip: curl_version()['ssl_version']

PHP 5.5.19 or greater

IP address of server within US or the server IP address exception. Specialty products can service this request. Secure Submit Cert Secure. | 866.802.9753


If an independent method of validation of the error or the fix they can upload this file and test. and provide the URL to us if further examination of the results is needed.

TLS 1.2 Test Script

Problem 1

Incorrect settings or outdated .NET version.


The .NET 4.5 (or greater) runtime must be installed for TLSv1.2 to be enabled.

The TLS version can be set via ServicePointManager.SecurityProtocol

Problem 1

Incorrect settings or outdated JAVA version.


The TLS version can be set via SSLContext.

The latest Java (currently 8) is preferred. In Java 8, TLSv1.2 is used by default when a TLS version is not specified.

Version TLSv1.2 support
6 and Earlier No support. A runtime update is required. (Except possibly for IBM Java. See note below.)
7 Available. TLSv1.2 must be explicitly enabled. Use the Heartland JAVA SDK.
8 Default. TLSv1.2 is enabled by default. No code change is required, though it is always recommended to make sure you're using the latest Heartland JAVA SDK .

Heartland JAVA SDK

NOTE for IBM Java: TLSv1.2 can be enabled via a system override flag in v6 service refresh 10 or higher.

To check Java, first verify that Java runtime 7 or higher is installed by running java -version from command line. If you have Java 6 or below, please upgrade it first.