This KB entry includes instructions and sample code detailing how to process transactions through Heartland Payment Systems with the 4D Payments SDK TSYS components.
The 4D Payments SDK provides support for processing transactions through Heartland Payment Systems. This functionality is exposed in the TSYS terminal capture components. To accomplish this, set the “Processor” configuration setting to ‘1’ (Heartland):
TSYSRetail1.Config("Processor=1");
Note that you will need to set this configuration setting for each component you use (including TSYSLevel2 and TSYSLevel3). With the lone exception of the “Processor” configuration setting, the component will be used the same as it is for TSYS (as the component internally handles the changes necessary for Heartland). For more information about how to use the TSYS components, please visit our 4D Payments SDK Tutorial.
Heartland E3 Security (End-to-End Encryption) has also been implemented along with the Heartland support. E3 Encryption requires a Magnetic Stripe Reader that is capable of encrypting cards (please contact Heartland directly to obtain more information about the available devices). Once you have an E3 capable device, the component can be setup to begin processing transactions using E3 encryption. The first thing you will need to do is set the “HeartlandEncryptionMode” to ‘3’ (Card Data Only; this is currently the only supported encryption option):
TSYSRetail1.Config("HeartlandEncryptionMode=3");
If you are always processing transactions using E3, it is good practice to set this configuration setting along with the “Processor” setting.
When retrieving card data via an E3 device, the card data (i.e. Track 1, Track 2, or Card Number) will be encrypted. The component handles this card data the same as if it was not encrypted. Thus you can set it using the Card property (just as you would if it was not encrypted). In addition to the card data, an E3 secure card swipe response (received from the E3 device) will contain base-64 encoded “Key transmission blocks” (ktb). This key block is required and is used by Heartland to decrypt the card data. Therefore you will need to parse this value from the magnetic stripe reader response and set the base-64 encoded value to the “HeartlandKeyBlock” configuration setting. Below are some code examples demonstrating how to set E3 encrypted card data:
//This is your Key Block for the below card examples
TSYSRetail1.Config("HeartlandKeyBlock=/wECAQECA....tRD0");
//This is a Track 1 example
TSYSRetail1.Card.EntryDataSource = EntryDataSources.edsTrack1;
TSYSRetail1.Card.MagneticStripe = "S8pm5APZta7OupWZgbPz41b2zNguCmueZKOsWxdOw9SbjKsJwk4anBNHZ";
//This is a Track 2 example
TSYSRetail1.Card.EntryDataSource = EntryDataSources.edsTrack2;
TSYSRetail1.Card.MagneticStripe = "DG+grdoyZaOExQ9Q5p44QQ5FhwD";
//This is a manual card data example
TSYSRetail1.Card.EntryDataSource = EntryDataSources.edsManualEntryTrack1Capable;
TSYSRetail1.Card.Number = "+++++++ZsUazr6xV";
TSYSRetail1.Card.CVVData = "123";
TSYSRetail1.Card.ExpMonth = 1;
TSYSRetail1.Card.ExpYear = 2020;