4D Payments SDK 2016 .NET Edition

Questions / Feedback?

TSYSDebit Component

Properties   Methods   Events   Configuration Settings   Errors  

The TSYSDebit component is an advanced tool used to authorize debit cards in a Retail environment, where the customer is purchasing products or services in person. This component makes authorizing debit card transactions with a customer PIN very easy. Supported Industry Types include retail stores, restaurants, and grocery stores.




This component allows for simple, direct, secure connection to the Vital/TSYS SSL gateway through a standard Internet connection. Because all SSL communications are handled inside the component, any application or web page can be deployed without the need for expensive dedicated SSL servers.

The TSYSDebit component makes authorizing debit card transactions (where the customer's card is swiped through a card reader and a PIN is supplied) very easy by adding an additional layer of abstraction between the programmer and the protocol. There is no need to deal with raw sockets, SSL handshakes, or data packet formatting. The steps to setting up the component and authorizing a transaction are outlined below:

First, set the merchant properties with setup information acquired from your member bank or processor. For instance:

  TSYSDebit1.MerchantBankId = "999995" '(BIN Number)
  TSYSDebit1.MerchantNumber = "888000002447"
  TSYSDebit1.MerchantName = "TEST MERCHANT"
  TSYSDebit1.MerchantTerminalNumber = "1515"
  TSYSDebit1.MerchantStoreNumber = "5999"
  TSYSDebit1.MerchantCategoryCode = "5999"
  TSYSDebit1.MerchantCity = "Durham"
  TSYSDebit1.MerchantState = "NC"
  TSYSDebit1.MerchantZip = "27713"
  TSYSDebit1.MerchantTimeZone = "705"
  TSYSDebit1.MerchantABANumber = "123456789"
  TSYSDebit1.MerchantSettlementAgent = "V123"
  TSYSDebit1.AgentBankNumber = "000000"
  TSYSDebit1.AgentChainNumber = "111111"
  TSYSDebit1.ReimbursementAttribute = raStandardRetail
  TSYSDebit1.SharingGroup = "GWQEV5" 
  TSYSDebit1.IndustryType = itRetail

Next, set properties that contain details about the transaction. The TransactionNumber is a sequence number, and should be incremented for each transaction you send. BatchNumber indicates which batch you will settle this authorization in. It should match the BatchNumber you set in the TSYSSettle component when you settle this transaction. TransactionAmount is the amount of sale, plus any CashBackAmount returned to the customer, formatted with an implicit decimal place. The CardTrack2Data is read from the magnetic stripe on the back of the card, and the DebitPIN and DebitKSN are retrieved from a standard DUKPT Pin Pad device.

  TSYSDebit1.TransactionNumber = 1
  TSYSDebit1.BatchNumber = 213
  TSYSDebit1.TransactionAmount = "1000"
  TSYSDebit1.CashBackAmount = "300"
  TSYSDebit1.CardTrack2Data = "9999999800002773=09121015432112345678"
  TSYSDebit1.CardPIN = "83C33384650827F6"
  TSYSDebit1.CardKSN = "4A00310459400004"

Finally, submit the transaction by calling one of three authorization methods. Sale, Credit or BalanceInquiry. The following code demonstrates a purchase:


If wish refund money to a customer's debit card, you must also supply an OriginalPurchaseDate before calling Credit.

When the component receives a response from the Vital/TSYS servers, the result of the authorization will be displayed in several Response properties. The Code indicates whether the transaction was approved, and the remaining properties provide additional information about the transaction.

Once a debit card Sale or Credit is approved, the transaction must go through the batch settlement process in order for the merchant to receive the funds in his merchant account. This is done by passing the XML aggregate returned from the GetDetailAggregate method to the TSYSSettle component. Usually, a Batch Settlement of all authorized transactions is done at the end of each business day. Note that BalanceInquiry transactions can not be settled.

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

AgentBankNumberIdentifies a specific agent entity of the member bank or processor.
AgentChainNumberIdentifies a specific chain of an agent organization.
BatchNumberThe batch number that this transaction will be included in.
CardTrack2DataTrack 2 data for a debit transaction.
CashBackAmountAmount returned to the customer in cash.
DebitKSNClear-text Key Sequence Number, used for Debit and EBT transactions.
DebitPINDUKPT DES encrypted PIN block, used for Debit and EBT transactions.
IndustryTypeCode which indicates the industry the merchant is engaged in.
MerchantContains the merchant's setup information.
MerchantABANumberMerchant's routing number.
MerchantSettlementAgentMerchant's settling agent.
OriginalPurchaseDateDate and time of original purchase, used for returns.
ReimbursementAttributeIndicates the type of fee applicable to this transaction.
ResponseContains the response to a debit authorization request.
SharingGroupList of Debit and EBT networks that the merchant supports.
SSLAcceptServerCertInstructs the component to unconditionally accept the server certificate that matches the supplied certificate.
SSLCertThe certificate to be used during SSL negotiation.
SSLServerCertThe server certificate for the last established connection.
TimeoutA timeout for the component.
TransactionAmountPurchase amount to be authorized.
TransactionNumberSequence number of this transaction.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

BalanceInquiryRetrieves the current available balance of the debit card.
ConfigSets or retrieves a configuration setting.
CreditCredits a debit card (with a customer-entered PIN).
GetDetailAggregateReturns an aggregate containing details of this transaction, which is then used for settlement.
InterruptInterrupts the current action.
ResetClears all properties to their default values.
SaleAuthorizes a Debit card (with a customer-entered PIN).

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

ConnectedFired immediately after a connection completes (or fails).
DataPacketInFired when receiving a data packet from the transaction server.
DataPacketOutFired when sending a data packet to the transaction server.
DisconnectedFired when a connection is closed.
ErrorInformation about errors during data delivery.
SSLServerAuthenticationFired after the server presents its certificate to the client.
SSLStatusShows the progress of the secure connection.

Configuration Settings

The following is a list of configuration settings for the component with short descriptions. Click on the links for further details.

ActivateTerminalAuthenticates a POS device with TSYS.
AllowPartialAuthsIndicates whether partial authorizations are to be supported.
AuthenticationCodeAn alphanumeric code provided to the POS user for input when authenticating a POS device.
AuthorizationIndicatorThe type of authorization request.
CardholderIdSpecifies the method used to verify the identity of the cardholder.
ChipConditionCodeThe condition code of magnetic stripe read transactions of EMV (chip capable) cards.
DeactivateTerminalDeactivates a POS device with TSYS.
EMVDataThe EMV Data returned from a Pin Pad after reading an EMV card.
GenKeyA randomly generated string of alphanumeric characters identifying the terminal.
HeartlandDeviceIdSpecifies a device ID to uniquely identify each terminal (card data entry device).
HeartlandEncryptionModeSpecifies the encryption mode to use in Heartland transactions.
HeartlandKeyBlockSpecifies the key block used to encrypt the data.
LocalRetrievalNumberSpecifies the Retrieval Reference Number to use in a NonConfirm authorization request.
LocalTransactionDateSpecifies the local transaction date to use in a NonConfirm authorization request.
LocalTransactionTimeSpecifies the local transaction time to use in a NonConfirm authorization request.
MessageReasonCodeCode used to identify Deferred Authorizations for Visa.
MobileDeviceTypeIdentifies the type of mobile device used by the cardholder to initiate the transaction.
PortThe port to which transactions are posted.
POSDataCodeSpecifies the condition of the POS device used at the time of the transaction.
ProcessorSpecifies the Processor you are connecting to.
ResponseCardholderVerificationVerification results for cardholder identification data (extended AVS).
ResponseEMVDataThe EMV Data returned in an authorization response.
ResponseStoreNumberCheck this field against the original Merchant StoreNumber.
ResponseTerminalNumberCheck this field against the original Merchant TerminalNumber.
RetrySet this to retry a failed transaction.
SendExtendedAVSSpecifies whether to send extended AVS data.
ServerThe server to which transactions are posted.
SurchargeAmountThe transaction fee amount charged to the customer to account for acquirer-assessed surcharge.
TsysETBThe Encryption Transmission Block TSYS uses to decrypt encrypted data.
UseConfirmationRequestIndicates whether or not to send a Confirmation Request authorization transaction.
BuildInfoInformation about the product's build.
GUIAvailableTells the component whether or not a message loop is available for processing events.
LicenseInfoInformation about the current license.
UseInternalSecurityAPITells the component whether or not to use the system security libraries or an internal implementation.

Copyright (c) 2021 4D Payments Inc. - All rights reserved.
4D Payments SDK 2016 .NET Edition - Version 16.0 [Build 8017]