4D Payments SDK 2016 .NET Edition

Questions / Feedback?

TSYSGiftCard Component

Properties   Methods   Events   Configuration Settings   Errors  

The TSYSGiftCard component is used to manipulate funds on Gift and Prepaid Cards using the Vital/TSYS payment system. This component supports card-present gift card transactions, and allows for simple, direct, secure communication to the Vital/TSYS TLS/SSL gateway through a standard Internet connection. This component can be integrated into web pages or stand- alone Point Of Sale applications. 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.




This component supports two different kinds of Stored Value cards. Gift Cards and Prepaid Cards. Gift Cards support only the Fifth/Third and Stored Value Systems (SVS) ReceivingInstitutions, and a merchant must have software (such as this component) to authorize gift card Purchase (redemption) transactions. On the other hand, Prepaid cards (once activated) authorize exactly like credit cards, and can be used at any store. Examples of gift and cards include a retailer's gift card, a prepaid telephone card, and a reloadable subway pass. Examples of prepaid cards would be the prepaid cards purchased at shopping malls, or sometimes given away as promotional gimmicks. Not included in either of these are government income-support cards, otherwise known as EBT cards or electronic food stamps. (Use the TSYSBenefit component for EBT cards).

The TSYSGiftCard component makes these transactions 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:

  TSYSGiftCard1.MerchantBankId = "999995"
  TSYSGiftCard1.MerchantNumber = "888000002447"
  TSYSGiftCard1.MerchantName = "TEST_MERCHANT"
  TSYSGiftCard1.MerchantTerminalNumber = "1515"
  TSYSGiftCard1.MerchantStoreNumber = "5999"
  TSYSGiftCard1.MerchantCategoryCode = "5999"
  TSYSGiftCard1.MerchantCity = "Durham"
  TSYSGiftCard1.MerchantState = "NC"
  TSYSGiftCard1.MerchantZip = "27713"
  TSYSGiftCard1.MerchantTimeZone = "705"
  TSYSGiftCard1.MerchantABANumber = "123456789"
  TSYSGiftCard1.MerchantSettlementAgent = "V123"    
  TSYSGiftCard1.AgentBankNumber = "000000"
  TSYSGiftCard1.AgentChainNumber = "111111"
  TSYSGiftCard1.IndustryType = itRetail
  TSYSGiftCard1.ReceivingInstitution = riFifthThird 

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, plus any CashBackAmount returned to the customer, formatted with an implicit decimal place (CashBackAmount is only applicable to the ttGiftCardPurchase TransactionType). The MagneticStripe data for Prepaid cards can be either track1 or track2, but Gift cards support only the dsTrack2 EntryDataSource. Both types support manual entry via the Number, ExpMonth, and ExpYear properties.

In addition, you are also be required to set an EmployeeId and BatchNumber for Gift Card transactions. (These are ignored for Prepaid transactions). Even though Gift Card transactions are not submitted for settlement, the BatchNumber should reflect the batch sequence number of the current batch. The EmployeeId is a unique number used to identify the employee operating the terminal being used to issue gift cards. For example:

  TSYSGiftCard1.TransactionNumber = 1
  TSYSGiftCard1.BatchNumber = 123  
  TSYSGiftCard1.EmployeeId = "12345678"
  TSYSGiftCard1.TransactionAmount = "1000"
  TSYSGiftCard1.CashBackAmount = "300" 
  TSYSGiftCard1.CardTrack2Data = "9999999800002773=09121015432112345678"

The TSYSGiftCard component supports both Gift Card and Prepaid Cards, so you should make sure to choose the correct TransactionType for the type of card you are using. Then call the Authorize method to submit the transaction.

  TSYSGiftCard1.TransactionType = ttGiftCardPurchase

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.

Note that Gift Card and Prepaid Card transactions, with the exception of the ttPrepaidCardPurchase TransactionType are real-time transactions, and cannot be settled with the TSYSSettle component. ttPrepaidCardPurchase is identical to a credit card purchase made with the TSYSRetail component, so it must be settled with the TSYSSettle component. However, using this component to authorize Prepaid card transactions allows you to retrieve balance information and allow partial authorizations.

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.
CardContains the customer's credit card information.
CashBackAmountAmount returned to the customer in cash.
CustomerAddressThe customer's billing address.
CustomerZipCustomer's zip code (or postal code if outside of the USA).
EmployeeIdIdentification number of the Employee making this transaction.
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.
PartialRedemptionPartial Redemption indicator.
ReceivingInstitutionIndicates which gift card network to use.
ResponseContains the response to a debit authorization request.
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.
TransactionTypeSpecifies the type of Gift Card transaction to process.

Method List

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

AuthorizeSends a Gift Card transaction.
ConfigSets or retrieves a configuration setting.
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.

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.
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.
DeactivateTerminalDeactivates a POS device with TSYS.
GenKeyA randomly generated string of alphanumeric characters identifying the terminal.
PortThe port to which transactions are posted.
POSDataCodeSpecifies the condition of the POS device used at the time of the transaction.
ResponseCardholderVerificationVerification results for cardholder identification data (extended AVS).
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.
TsysETBThe Encryption Transmission Block TSYS uses to decrypt encrypted data.
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]