Use TSYS Terminal Authentication to Reduce Fraud Risk


Requirements: 4D Payments SDK

Introduction

4D Payments SDK supports Terminal Authentication in both Terminal Capture (Sierra) and Host Capture (Summit) platforms. Use of Terminal Authentication allows a specific terminal to be authenticated with TSYS when authenticated. A returned code is then included in all future transactions to identify the previously authenticated terminal as the source.

Authenticating a terminal can help reduce the risk of fraud. By authenticating a terminal TSYS will be able to identify all transactions originating from the terminal using the unique GenKey. Contact your TSYS representative for further details about the benefits of this program.

This article shows how to active a device, process transactions with the terminal specific GenKey value and deactivate a device for both terminal capture and host capture platforms.

Contents

Terminal Capture (Sierra)

The TSYSTerminalMgr component is used to Authenticate and Deactivate a terminal. Before authenticating a terminal the AuthenticationCode must be obtained from TSYS. After authenticating a terminal the GenKey property will be populated with a unique value that must be included in all future transactions originating from the terminal.

Authenticating a Terminal

The AuthenticateDevice method is used to authenticate a terminal. If the authentication request was successfully the Response.Code property will contain “A1” and the GenKey property will be populated. The GenKey value should be stored and used in all future transactions from the terminal. The following properties are applicable when calling AuthenticateDevice:

  • AuthenticationCode
  • TransactionNumber
  • MerchantBankId
  • MerchantCategoryCode
  • MerchantCountryCode
  • MerchantCurrencyCode
  • MerchantLanguage
  • MerchantNumber
  • MerchantServicePhone
  • MerchantStoreNumber
  • MerchantTerminalNumber
  • MerchantTimeZone
  • MerchantZip

For example:

TSYSTerminalMgr1.Merchant.BankId = "999999"; TSYSTerminalMgr1.Merchant.CategoryCode = "9999"; TSYSTerminalMgr1.Merchant.Name = "TESTMERCHANT"; TSYSTerminalMgr1.Merchant.Number = "888000002447"; TSYSTerminalMgr1.Merchant.StoreNumber = "5999"; TSYSTerminalMgr1.Merchant.TerminalNumber = "1234"; TSYSTerminalMgr1.Merchant.Zip = "27516"; TSYSTerminalMgr1.Merchant.ServicePhone = "6023337807"; TSYSTerminalMgr1.TransactionNumber = 1234; TSYSTerminalMgr1.AuthenticationCode = "N123456789"; TSYSTerminalMgr1.AuthenticateDevice(); string genkey = ""; if (TSYSTerminalMgr1.Response.Code == "A1") //approved genkey = TSYSTerminalMgr1.GenKey;

Processing Transactions

After obtaining the GenKey simply set this to the GenKey configuration setting when processing transactions. All other transaction information is provided as normal. For instance:

TSYSRetail1.TransactionAmount = "1200"; TSYSRetail1.TransactionNumber = 2345; TSYSRetail1.IndustryType = TsysretailIndustryTypes.sitRetail; TSYSRetail1.Card.EntryDataSource = EntryDataSources.edsTrack1; TSYSRetail1.Card.MagneticStripe = "B4444333322221111^DOE/JOHN E ^091210100000033301000000008000000"; TSYSRetail1.Config("GenKey=" + genkey); TSYSRetail1.Authorize(); Deactivating a Terminal

Deactivate a Terminal

To deactivate a terminal set the GenKey property and call the DeactivateDevice method. If successful Response.Code will contain “A3”. The following properties are applicable when calling this method:

  • GenKey
  • TransactionNumber
  • MerchantBankId
  • MerchantCategoryCode
  • MerchantCountryCode
  • MerchantCurrencyCode
  • MerchantLanguage
  • MerchantNumber
  • MerchantServicePhone
  • MerchantStoreNumber
  • MerchantTerminalNumber
  • MerchantTimeZone
  • MerchantZip

For instance:

TSYSTerminalMgr1.Merchant.BankId = "999999"; TSYSTerminalMgr1.Merchant.CategoryCode = "9999"; TSYSTerminalMgr1.Merchant.Name = "TESTMERCHANT"; TSYSTerminalMgr1.Merchant.Number = "888000002447"; TSYSTerminalMgr1.Merchant.StoreNumber = "5999"; TSYSTerminalMgr1.Merchant.TerminalNumber = "1234"; TSYSTerminalMgr1.Merchant.Zip = "27516"; TSYSTerminalMgr1.Merchant.ServicePhone = "6023337807"; TSYSTerminalMgr1.TransactionNumber = 1234; TSYSTerminalMgr1.GenKey = "MY_GEN_KEY"; TSYSTerminalMgr1.DeactivateDevice(); if (TSYSTerminalMgr1.Response.Code == "A3") //deactivated //...

Host Capture (Summit)

The TSYSHCTerminalMgr component is used to Authenticate and Deactivate a terminal. Before authenticating a terminal the AuthenticationCode must be obtained from TSYS. After authenticating a terminal the GenKey property will be populated with a unique value that must be included in all future transactions originating from the terminal.

Authenticating a Terminal

The AuthenticateDevice method is used to authenticate a terminal. If the authentication request was successfully the Response.Code property will contain “100” and the GenKey property will be populated. The GenKey value should be stored and used in all future transactions from the terminal. The following properties must be set when calling AuthenticateDevice:

  • MerchantId
  • RoutingId
  • AuthenticationCode
  • MerhcantPhone or MerchantZip

For example:

TSYSHCTerminalMgr1.MerchantId = "300012312312312"; TSYSHCTerminalMgr1.RoutingId = "ABC123"; TSYSHCTerminalMgr1.AuthenticationCode = "ABCD123456"; TSYSHCTerminalMgr1.MerchantZip = "27516"; TSYSHCTerminalMgr1.AuthenticateDevice(); if(TSYSHCTerminalMgr1.Response.Code == "100") //approved genkey = TSYSHCTerminalMgr1.Response.GenKey;

Processing Transactions

After obtaining the GenKey simply set this to the GenKey property when processing transactions. All other transaction information is provided as normal. For instance:

TSYSHCRetail1.GenKey = "MY_GEN_KEY"; TSYSHCRetail1.MerchantId = "300012312312312"; TSYSHCRetail1.RoutingId = "ABC123"; TSYSHCRetail1.Card.MagneticStripe = "B4444333322221111^DOE/JOHN E ^091210100000033301000000008000000"; TSYSHCRetail1.Card.EntryDataSource = EntryDataSources.edsTrack1; TSYSHCRetail1.TransactionAmount = "1250"; TSYSHCRetail1.TransactionDesc = "Test Transaction"; TSYSHCRetail1.TransactionNumber = 99; TSYSHCRetail1.Sale();

Deactivate a Terminal

To deactivate a terminal call the DeactivateDevice method and pass the GenKey as a parameter. If successful Response.Code will contain “103”. The following properties are required when calling this method:

  • MerchantId
  • RoutingId

For instance:

TSYSHCTerminalMgr1.MerchantId = "300012312312312"; TSYSHCTerminalMgr1.RoutingId = "ABC123"; TSYSHCTerminalMgr1.DeactivateDevice("MY_GEN_KEY"); if(TSYSHCTerminalMgr1.Response.Code == "103") //approved //...

TSYSTerminalMgr Response Codes

Below is a list of response codes, in addition to connectivity error codes, when trying to activate or deactivate a terminal.

  • A1 – The device was authenticated.
  • A2 – The device was not authenticated.
  • A3 – The device was deactivated.

We appreciate your feedback. If you have any questions, comments, or suggestions about this entry please contact our support team at support@4dpayments.com.