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.