TSYSBenefit Component
Properties Methods Events Configuration Settings Errors
The TSYSBenefit component is an advanced tool used to authorize Electronic Benefits (EBT) cards in a Retail environment, where the customer is purchasing products or services in person. This component makes authorizing EBT Food Stamp and Cash Benefit transactions (with a customer PIN) very easy. Supported Industry Types include retail stores, restaurants, and grocery stores.
Syntax
DPayments.DPaymentsSDK.Tsysbenefit
Remarks
This component allows for simple, direct, secure connection to the Vital/TSYS TLS/SSL gateway through a standard Internet connection. Because all TLS/SSL communications are handled inside the component, any application or web page can be deployed without the need for expensive dedicated TLS/SSL servers.
The TSYSBenefit component makes authorizing EBT 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, TLS/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:
TSYSBenefit1.Merchant.BankId = "999995"; TSYSBenefit1.Merchant.Number = "888000002447"; TSYSBenefit1.Merchant.Name = "TEST MERCHANT"; TSYSBenefit1.Merchant.TerminalNumber = "1515"; TSYSBenefit1.Merchant.StoreNumber = "5999"; TSYSBenefit1.Merchant.CategoryCode = "5999"; TSYSBenefit1.Merchant.City = "Durham"; TSYSBenefit1.Merchant.State = "NC"; TSYSBenefit1.Merchant.Zip = "27713"; TSYSBenefit1.Merchant.TimeZone = "705"; TSYSBenefit1.MerchantABANumber = "123456789"; TSYSBenefit1.MerchantSettlementAgent = "V123"; TSYSBenefit1.MerchantFCSId = "1234567"; TSYSBenefit1.AgentBankNumber = "000000"; TSYSBenefit1.AgentChainNumber = "111111"; TSYSBenefit1.SharingGroup = "8GWK" TSYSBenefit1.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. TransactionAmount is the amount of sale, formatted with an implicit decimal place. The MagneticStripe is read from the magnetic stripe on the back of the card, (Track 2 for EBT transactions) and the DebitPIN and DebitKSN are retrieved from a standard DUKPT Pin Pad device.
TSYSBenefit1.TransactionNumber = 1 TSYSBenefit1.TransactionAmount = "1000" TSYSBenefit1.CardMagneticStripe = "9999999800002773=09121015432112345678" TSYSBenefit1.CardPIN = "83C33384650827F6" TSYSBenefit1.CardKSN = "4A00310459400004"
The TSYSBenefit component supports both Food Stamp and Cash Benefit programs on the same card. Make sure to choose the correct TransactionType for the benefit program you wish to use, and then call the Authorize method. For example:
TSYSBenefit1.TransactionType = ttFoodStampPurchase TSYSBenefit1.Authorize()
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 an EBT authorization 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 ttFoodStampBalanceInquiry and ttCashBenefitBalanceInquiry TransactionTypes cannot 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.
AgentBankNumber | Identifies a specific agent entity of the member bank or processor. |
AgentChainNumber | Identifies a specific chain of an agent organization. |
BatchNumber | The batch number that this transaction will be included in. |
Card | Contains the customer's credit card information. |
CashBackAmount | Amount returned to the customer in cash. |
DebitKSN | Clear-text Key Sequence Number, used for Debit and EBT transactions. |
DebitPIN | DUKPT DES encrypted PIN block, used for Debit and EBT transactions. |
IndustryType | Code which indicates the industry the merchant is engaged in. |
Merchant | Contains the merchant's setup information. |
MerchantABANumber | Merchant's routing number. |
MerchantFCSId | Identifies the merchant as an approved Food Stamp merchant. |
MerchantSettlementAgent | Merchant's settling agent. |
Response | Contains the response to an authorization request. |
SharingGroup | List of Debit and EBT networks that the merchant supports. |
SSLAcceptServerCert | Instructs the component to unconditionally accept the server certificate that matches the supplied certificate. |
SSLCert | The certificate to be used during SSL negotiation. |
SSLServerCert | The server certificate for the last established connection. |
Timeout | A timeout for the component. |
TransactionAmount | Purchase amount to be authorized. |
TransactionNumber | Sequence number of this transaction. |
TransactionType | Specifies the type of EBT transaction to process. |
VoucherCode | Required for Food Stamp Voucher transactions. |
VoucherNumber | Required for Food Stamp Voucher transactions. |
Method List
The following is the full list of the methods of the component with short descriptions. Click on the links for further details.
Authorize | Sends a Gift Card transaction. |
Config | Sets or retrieves a configuration setting. |
GetDetailAggregate | Returns an aggregate containing details of this transaction, which is then used for settlement. |
Interrupt | Interrupts the current action. |
Reset | Clears all properties to their default values. |
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.
Connected | Fired immediately after a connection completes (or fails). |
DataPacketIn | Fired when receiving a data packet from the transaction server. |
DataPacketOut | Fired when sending a data packet to the transaction server. |
Disconnected | Fired when a connection is closed. |
Error | Information about errors during data delivery. |
SSLServerAuthentication | Fired after the server presents its certificate to the client. |
SSLStatus | Shows 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.
ActivateTerminal | Authenticates a POS device with TSYS. |
AllowPartialAuths | Indicates whether partial authorizations are to be supported. |
AuthenticationCode | An alphanumeric code provided to the POS user for input when authenticating a POS device. |
AuthorizationIndicator | The type of authorization request. |
CardholderId | Specifies the method used to verify the identity of the cardholder. |
DeactivateTerminal | Deactivates a POS device with TSYS. |
GenKey | A randomly generated string of alphanumeric characters identifying the terminal. |
HeartlandDeviceId | Specifies a device ID to uniquely identify each terminal (card data entry device). |
HeartlandEncryptionMode | Specifies the encryption mode to use in Heartland transactions. |
HeartlandKeyBlock | Specifies the key block used to encrypt the data. |
LocalRetrievalNumber | Specifies the Retrieval Reference Number to use in a NonConfirm authorization request. |
LocalTransactionDate | Specifies the local transaction date to use in a NonConfirm authorization request. |
LocalTransactionTime | Specifies the local transaction time to use in a NonConfirm authorization request. |
Port | The port to which transactions are posted. |
Processor | Specifies the Processor you are connecting to. |
ResponseCardholderVerification | Verification results for cardholder identification data (extended AVS). |
ResponseStoreNumber | Check this field against the original Merchant StoreNumber. |
ResponseTerminalNumber | Check this field against the original Merchant TerminalNumber. |
Retry | Set this to retry a failed transaction. |
SendExtendedAVS | Specifies whether to send extended AVS data. |
Server | The server to which transactions are posted. |
SurchargeAmount | The transaction fee amount charged to the customer to account for acquirer-assessed surcharge. |
Timeout | A timeout for the component. |
TsysETB | The Encryption Transmission Block TSYS uses to decrypt encrypted data. |
UseConfirmationRequest | Indicates whether or not to send a Confirmation Request authorization transaction. |
BuildInfo | Information about the product's build. |
GUIAvailable | Tells the component whether or not a message loop is available for processing events. |
LicenseInfo | Information about the current license. |
UseInternalSecurityAPI | Tells the component whether or not to use the system security libraries or an internal implementation. |