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
nsoftware.InPayDirect.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.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 a debit authorization request. |
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.
AllowPartialAuths | Indicates whether partial authorizations are to be supported. |
SurchargeAmount | The transaction fee amount charged to the customer to account for acquirer-assessed surcharge. |
AuthorizationIndicator | The type of authorization request. |
Retry | Set this to retry a failed transaction. |
SendExtendedAVS | Specifies whether to send extended AVS data. |
ResponseStoreNumber | Check this field against the original Merchant StoreNumber. |
ResponseTerminalNumber | Check this field against the original Merchant TerminalNumber. |
ResponseCardholderVerification | Verification results for cardholder identification data (extended AVS). |
Port | The port to which transactions are posted. |
Server | The server to which transactions are posted. |
AuthenticationCode | An alphanumeric code provided to the POS user for input when authenticating a POS device. |
ActivateTerminal | Authenticates a POS device with TSYS. |
DeactivateTerminal | Deactivates a POS device with TSYS. |
GenKey | A randomly generated string of alphanumeric characters identifying the terminal. |
TsysETB | The Encryption Transmission Block TSYS uses to decrypt encrypted data. |
UseConfirmationRequest | Indicates whether or not to send a Confirmation Request authorization transaction. |
LocalRetrievalNumber | Specifies the Retrieval Reference Number to use in a NonConfirm authorization request. |
LocalDate | Specifies the local transaction date to use in a NonConfirm authorization request. |
LocalTime | Specifies the local transaction time to use in a NonConfirm authorization request. |
Processor | Specifies the Processor you are connecting to. |
HeartlandEncryptionMode | Specifies the encryption mode to use in Heartland transactions. |
HeartlandDeviceId | Specifies a device ID to uniquely identify each terminal (card data entry device). |
HeartlandKeyBlock | Specifies the key block used to encrypt the data. |
Timeout | A timeout for the component. |
CodePage | The system code page used for Unicode to Multibyte translations. |