4D Payments SDK 2016 .NET Edition
4D Payments SDK 2016 .NET Edition
Questions / Feedback?

TSYSDebit Configuration

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

TSYSDebit Configuration Settings

AllowPartialAuths:   Indicates whether partial authorizations are to be supported.

When this setting is True, if the debit card being authorized does not contain sufficient funds to cover the TransactionAmount, the card will not be declined. Instead, the transaction will be authorized for a lesser amount. The customer must then use another form of payment to make up the remainder. The total amount authorized by TSYS will be returned in the ResponseAuthorizedAmount configuration setting. For instance, if the TransactionAmount is $100.00, but the card only has a $50.00 balance, the card is charged for $50.00, and the ResponseAuthorizedAmount will be "50.00". The merchant may then collect the remaining $50 in cash, check, credit card, or any other acceptable form of payment. This setting is False by default.

SurchargeAmount:   The transaction fee amount charged to the customer to account for acquirer-assessed surcharge.

This configuration setting is for informational purposes only and any surcharge amounts charged to the customer should be included in the TransactionAmount.

The format of this field is 'annnnnnnn' where 'a' is either 'D' for debit or 'C' for credit. 'nnnnnnnn' is the numeric fee amount with the decimal implied. For example: 'D00000150' is a $1.50 transaction fee amount debited to the cardholder's account.

Note: If an amount is only specified, the component will generate the format above by prepending a 'D' and the necessary number of 0's.

MobileDeviceType:   Identifies the type of mobile device used by the cardholder to initiate the transaction.

This field is required for all MasterCard PayPass (contactless) transactions. Valid values are:

Value Description
00 Card (default)
01 Mobile Network Operator (MNO) controlled removable secure element (SIM or UICC) personalized for use with a mobile phone or smartphone
02 Key Fob
03 Watch using a contactless chip or a fixed (non-removable) secure element not controlled by the MNO
04 Mobile Tag
05 Wristband
06 Mobile Phone Case or Sleeve
07 Mobile Phone or Smartphone with a fixed (non-removable) secure element controlled by the MNO (such as CDMA)
08 Removable secure element not controlled by the MNO, for example, memory card personalized for use with a mobile phone or smartphone
09 Mobile Phone or Smartphone with a fixed (non-removable) secure element not controlled by the MNO
10 MNO controlled removable secure element (SIM or UICC) personalized for use with a tablet or e-book
11 Tablet or E-Book with a fixed (non-removable) secure element controlled by the MNO
12 Removable secure element not controlled by the MNO (such as memory card personalized for use with a tablet or e-book)
13 Tablet or E-Book with fixed (nonremovable) secure element not controlled by the MNO
14 Mobile Phone or Smartphone with a payment application running in a host processor
15 Tablet or E-Book with a payment application running in a host processor
16 Mobile Phone or Smartphone with a payment application running in the TEE of a host processor
17 Tablet or E-Book with a payment application running in the TEE of a host processor
18 Watch with a payment application running in the TEE of a host processor
19 Watch with a payment application running in a host processor
20 Card
21 Phone (i.e. Mobile phone)
22 Tablet/e-reader (i.e. Tablet computer or e-reader)
23 Watch/Wristband (i.e. Watch or wristband, including a fitness band, smart strap, disposable band, watch add-on, and security/ID band)
24 Sticker
25 PC (i.e. PC or laptop)
26 Device Peripheral (i.e. Mobile phone case or sleeve)
27 Tag (i.e. Key fob or mobile tag)
28 Jewelry (i.e. Ring, bracelet, necklace, and cuff links)
29 Fashion Accessory (i.e. Handbag, bag charm, and glasses)
30 Garment (i.e. Dress)
31 Domestic Appliance (i.e. Refrigerator, washing machine)
32 Vehicle (i.e. Vehicle, including vehicle attached devices)
33 Media/Gaming Device (i.e. Media or gaming device, including a set top box, media player, and television)
34-99 These values reserved for future form factors. Any value in this range may occur within form factors and transaction data without prior notice.

CardholderId:   Specifies the method used to verify the identity of the cardholder.

By default the component automatically computes the CardholderId based on several factors. Changing this config setting will override this automatic calculation. Clear this setting to "" (empty string) to restore automatic calculation. Please see the TSYSDetailRecord component's CardholderId property for more information.

AuthorizationIndicator:   The type of authorization request.

This field defines the type of authorization request and must be included on all MasterCard authorization request transactions.

Valid values are:

Code Description
P Pre Authorization
F Final Authorization
U Undefined Authorization

Retry:   Set this to retry a failed transaction.

If an authorization returns ambiguously or times out without receiving a response, you may send the same transaction over again with this Retry flag set to True. This will prevent you from double-charging your customers in the case of a communications error (only available for credit card transactions. Does not apply to Debit, Gift Card, or EBT transactions).

SendExtendedAVS:   Specifies whether to send extended AVS data.

When set to 'True', AVS data will be sent in the extended AVS field for the transaction. ResponseCardholderVerification will contain the extended AVS verification results. When set to 'False' (default value), the CustomerAddress and CustomerZip values will be sent using the simple AVS data fields.

ResponseStoreNumber:   Check this field against the original Merchant StoreNumber.

The value of this field is used to correctly match responses with transactions by comparing its value to that of the StoreNumber. This is particularly useful when making a multi-merchant or multi-store routing system. If the system that originally made the transaction receives a response where the ResponseStoreNumber is not identical to the StoreNumber the transaction should not be stored for batch settlement. This field is read-only.

ResponseTerminalNumber:   Check this field against the original Merchant TerminalNumber.

The value of this field is used to correctly match responses with transactions by comparing its value to that of TerminalNumber. This is particularly useful when making a multi-terminal routing system within a merchant location. If the terminal that originally made the transaction receives a response where the ResponseTerminalNumber is not identical to the TerminalNumber, the transaction should not be stored for batch settlement. This field is read-only.

ResponseCardholderVerification:   Verification results for cardholder identification data (extended AVS).

This response data is returned when SendExtendedAVS is set to 'True' and is only available for American Express and Discover cards. This data is arranged in order of 5 bytes, one for each result of a cardholder identification data element:

Byte Number Description
Byte 1 Billing ZIP Code
Byte 2 Billing Street Match Code
Byte 3 Billing Name Match Code
Byte 4 Telephone Number Match Code
Byte 5 E-mail Address Match Code

The possible values for each byte are:

Value Description
Y Data Matches
U Data Unchecked
N No Match
S Service not allowed
R Retry
' ' (Space) Data not sent

For Discover transactions, byte 3 will be populated with the following values:

Value Description
B No response due to blank input
K Unknown
P Not processed
M First Name and Last Name match
F First Name Matches, Last Name does not match
L First Name does not match, Last Name matches
N Nothing matches
W No data from Issuer/Authorization system
U Retry, system unable to process

Port:   The port to which transactions are posted.

This is port that this component connects to on the server. The default value for TSYS is 5003 for the live server, and 5004 for the test server. The default live server values for Heartland is 22341 for Authorization and 22342 for Settlement. The Heartland test server values are 12341 for Authorization and 12342 for Settlement.

Server:   The server to which transactions are posted.

This is name of the server to which all transactions are posted. Do not use an IP address, use the actual name, as a server's IP address may change. The default (Live) TSYS server is "ssl2.vitalps.net", but you may use "ssltest.tsysacquiring.net" for testing. The default (Live) Heartland server is "txns.secureexchange.net", but you may use "test.txns.secureexchange.net" for testing. Note that there are several BankIds and Numbers that will always run in test mode regardless of whether you are using the live server. See the included demos for examples.

AuthenticationCode:   An alphanumeric code provided to the POS user for input when authenticating a POS device.

This field is used to specify the AuthenticationCode, assigned by TSYS, to authenticate a POS device (made via a call to ActivateTerminal).

ActivateTerminal:   Authenticates a POS device with TSYS.

This is an action config which when called will authenticate a POS device with TSYS. Authentication is required when processing transactions using Voltage Encryption or Tokenization. An AuthenticationCode is required to be specified, as is Zip and/or ServicePhone, to perform authentication. After a POS device is successfully authenticated, GenKey will be populated.

DeactivateTerminal:   Deactivates a POS device with TSYS.

This is an action config which when called will deactivate the POS device specified via GenKey with TSYS.

GenKey:   A randomly generated string of alphanumeric characters identifying the terminal.

This field is used to specify retrieve or specify a GenKey value for a terminal. This field will be populated after a successful call to ActivateTerminal is made. The Genkey must be stored in the POS device, must be sent with every request to the TSYS Acquiring Solutions host after authentication (by setting this field), and will be checked against the terminal hierarchy. A GenKey value is required when processing transactions using Voltage Encryption or Tokenization.

TsysETB:   The Encryption Transmission Block TSYS uses to decrypt encrypted data.

This field is used to specify the Base-64 encoded ETB (Encryption Transmission Block) used by TSYS to decrypt Voltage encrypted data. The value is retrieved from the POS device containing the Voltage encryption software. When specified, the transaction will be sent as a Voltage encrypted transaction. The encrypted card data will be specified as normal via the MagneticStripe or Number fields.

UseConfirmationRequest:   Indicates whether or not to send a Confirmation Request authorization transaction.

When set to "True", a confirmation authorization transaction will be sent. In a confirmation request, TSYS will generate the Retrieval Reference Number (RetrievalNumber) and the System Trace Audit Number (Trace). When setting this property to "False" (default value), a NonConfirm authorization transaction will be sent. In these transactions, a Retrieval Reference Number, System Trace Audit Number, Local Date, and Local Time are NOT generated by TSYS and must be manually specified by the POS application. By default, the component will automatically generate these values for you. However you can override them by setting the following properties: LocalRetrievalNumber, LocalDate, , and LocalTime. Note the System Trace Audit Number is required to be the last 6 characters of the LocalRetrievalNumber and thus the component will automatically obtain and send this value for you.

Note: This setting is only valid for Debit and EBT/Benefit transactions.

LocalRetrievalNumber:   Specifies the Retrieval Reference Number to use in a NonConfirm authorization request.

This property is used to specify the Retrieval Reference Number to use in a NonConfirm authorization request (when UseConfirmationRequest = "False"). The specified value must contain a 12-character numeric value. It is suggested that the first 4 characters be the Julian date (yddd) and the remaining 8 characters are a numeric transaction identification number. If this value is set to "" (empty string), the component will generate a Retrieval Reference Number for you when the authorization request is sent.

Note: This setting is only valid for Debit and EBT/Benefit transactions.

LocalDate:   Specifies the local transaction date to use in a NonConfirm authorization request.

This property is used to specify the local transaction date to use in a NonConfirm authorization request (when UseConfirmationRequest = "False"). The specified value must be in MMDDYY format. If "" (empty string) is specified, the component will generate the local transaction date for you based on the current system time.

Note: This setting is only valid for Debit and EBT/Benefit transactions.

LocalTime:   Specifies the local transaction time to use in a NonConfirm authorization request.

This property is used to specify the local transaction time to use in a NonConfirm authorization request (when UseConfirmationRequest = "False"). The specified value must be in HHMMSS format. If "" (empty string) is specified, the component will generate the local transaction time for you based on the current system time.

Note: This setting is only valid for Debit and EBT/Benefit transactions.

ChipConditionCode:   The condition code of magnetic stripe read transactions of EMV (chip capable) cards.

This config is used to provide information about magnetic stripe read transactions using chip capable cards at chip capable POS devices.

Available values are:

Value Description
0 Service code does not begin with a two or six or fill for subsequent positions that are present.
1 Service code begins with two or six; last CCPS read at the chip capable terminal was successful, or was not a chip transaction, or unknown.
2 Service code begins with two or six; last transaction at the chip capable terminal was unsuccessful chip read.

EMVData:   The EMV Data returned from a Pin Pad after reading an EMV card.

This configuration setting takes the entire TLV (tag-length-value) response received from a Pin Pad after reading an EMV card. When setting this field, any EMV tags that are not specified within the TSYS specifications, to include in the request, will be removed from the input. The component will send this data in an authorization request. Note that when performing an EMV transaction, POSDataCode is required.

ResponseEMVData:   The EMV Data returned in an authorization response.

This configuration setting contains the EMV Data in TLV (tag-length-value) format. This field will only be populated if an EMV transaction was performed and EMV Data was received in the authorization response.

POSDataCode:   Specifies the condition of the POS device used at the time of the transaction.

This configuration setting takes a semi-colon separated list of name-value pairs. The available field names and their applicable values can be found below. The fields can be set in any order and not all fields are required to be set (unless you wish to change their default values).

Code Example:

TSYSRetail.Config("POSDataCode=CardholderAuthCap=1;CardInputMode=2;CardInputCap=2");

CardInputCap (Terminal card data input capability)

0 (default) Unspecified, data not available
1 Manual; no terminal; Voice auth/ARU
2 Magnetic stripe reader capability
3 Bar code/ Payment code
4 Optical character reader (OCR) capability, [MC, AX]
5 Integrated circuit card (ICC) capability and magnetic stripe reader
6 Key entry only capability; Mastercard recurring and installment transactions
A PAN auto-entry via contactless magnetic stripe
B Magnetic stripe reader and key entry capability
C Magnetic stripe reader, ICC, and key entry capability
D Magnetic stripe reader and ICC capability
E ICC entry capability
H ICC Reader and Contactless Capability; Magnetic stripe & manual entry implied
M PAN auto-entry via contactless chip
V Other capability, [MC]
X Reserved for private use

CardholderAuthCap (Terminal cardholder authentication capability)

0 No electronic authentication capability
1 PIN entry capability
2 Electronic signature analysis capability
3 mPOS software-based PIN entry capability
5 Electronic authentication capability is inoperative
6 Other
9 (default) Unspecified, data not available

CardCaptureCap (Terminal card-capture capability)

0 No capture capability
1 Card capture capability
9 (default) Unspecified, data not available

TerminalOpEnv (Terminal operating environment)

0 No terminal used; Voice auth/ARU; Mastercard recurring/installment transactions
1 On card acceptor premises; attended terminal
2 On card acceptor premises; unattended terminal
3 Off card acceptor premises; attended
4 Off card acceptor premises; unattended
5 On cardholder premises; unattended
6 Off cardholder premises; unattended
9 (default) Unspecified, data not available
M Off card acceptor premises; merchant mobile POS environment, including mPOS
P On card acceptor premises; merchant mobile POS environment, including mPOS
Q Off card acceptor premises; cardholder mobile environment, including home PC, mobile phone, PDA
R On card acceptor premises; cardholder mobile environment, including home PC, mobile phone, PDA
S Electronic delivery of product, [AX]
T Physical delivery of product, [AX]

CardholderPresent (Cardholder present data)

0 Cardholder present
1 Cardholder not present; unspecified reason
2 Cardholder not present; mail transaction
3 Cardholder not present; phone transaction
4 Cardholder not present; standing (recurring) transaction
5 Cardholder not present; electronic commerce
8 Cardholder not present; recurrent billing such as a loan or installment payment
A Reauthorization for full amount (original transaction was token-based with a valid cryptogram; Discover only)
I Incremental authorization (Discover Only)
P Partial shipment purchase transaction (original transaction was token-based with valid cryptogram)
R Recurring purchase transaction (original transaction was token-based with valid cryptogram)
T PayButton (Discover only)

CardPresent (Card present data)

0 Card not present
1 Card present
W Transponder, [AX]
X Contactless Chip Transactions, including AMEX Expresspay
Z Digital Wallet [AX]

CardInputMode (Card data input mode)

0 (default) Unspecified, data not available
1 Manual input; no terminal; Voice auth/ARU
2 Magnetic stripe reader input
3 Bar code/Payment code
6 Key entered input
7 Payment Credential stored on file. NOTE: This value is required for all Mastercard recurring transactions.
A PAN auto-entry via contactless magnetic stripe
B Magnetic stripe reader input; track data captured and passed unaltered
C Online Chip
F Offline Chip
M PAN auto-entry via contactless Chip Card (EMV Mode)
N Track data read and sent unaltered, chip capable terminal, chip data could not be read
P Empty candidate list fallback
R PAN Entry via electronic commerce, including remote chip
S Electronic commerce, no security, channel encrypted, or SET without cardholder certificate
V Manually entered with keyed CID, [AX, JCB Canada]
W Swiped transaction with keyed CID, [AX, JCB Canada]
X Reserved for private use
Y Reserved for private use
Z Contactless Interface Change Identifies when a Chip Card Transaction with a dualinterface card switches from a contactless to a contact chip card transaction [Discover]

NOTE: AMEX defines ApplePay with value C - Online Chip

CardholderAuthMethod (Cardholder authentication method)

0 Not authenticated
1 PIN
2 Electronic signature analysis
5 Manual signature verification
6 Other manual verification (such as a driver's license number)
9 (default) Unspecified, data not available
S Other systematic verification
T Electronic ticket environment, [AX]

CardholderAuthEntity (Cardholder authentication entity)

0 Not authenticated
1 ICC - Offline PIN
2 Card acceptance device (CAD)
3 Authorizing agent - Online PIN
4 Merchant/card acceptor - signature
5 Other
9 (default) Unspecified, data not available

CardOutputCap (Card data output capability)

0 (default) Unspecified, data not available
1 None
2 Magnetic stripe write
3 ICC
S Other

TerminalOutputCap (Terminal data output capability)

0 (default) Unspecified, data not available
1 None
2 Printing capability only
3 Display capability only
4 Printing and display capability

PINCaptureCap (PIN capture capability)

0 No PIN capture capability
1 (default) Unspecified, data not available
2 Reserved
3 Reserved
4 PIN capture capability four characters maximum
5 PIN capture capability five characters maximum
6 PIN capture capability six characters maximum
7 PIN capture capability seven characters maximum
8 PIN capture capability eight characters maximum
9 PIN capture capability nine characters maximum
A PIN capture capability 10 characters maximum
B PIN capture capability 11 characters maximum
C PIN capture capability 12 characters maximum

Note: Setting this configuration setting in TSYSDetailRecord component will not update the POSDataCode tag in the detail aggregate of the original transaction.

Processor:   Specifies the Processor you are connecting to.

This field allows you to specify the processor that you are connecting to (thus allowing the component to correctly generate the request and parse the response). The available values are:

0TSYS (default)
1Heartland

Note that when set, this property will set the Server and Port to the default values for the specified processor. Additionally, this config must be set prior to setting Card to ensure the card data is formatted correctly.

HeartlandEncryptionMode:   Specifies the encryption mode to use in Heartland transactions.

This field allows you to specify the Heartland E3 encryption mode used when processing Heartland transactions. The available values are (descriptions describe the data that will be encrypted):

0No Encryption (default)
1Merchant ID and Card Data (reserved for future use)
2Merchant ID, Card Data, and Card Security Code (reserved for future use)
3Card Data Only

Note you will also need to set Processor to 1 (Heartland) and HeartlandKeyBlock if you wish to process Heartland E3 transactions.

HeartlandDeviceId:   Specifies a device ID to uniquely identify each terminal (card data entry device).

The specified value must be 4 characters or less. Note that this value is required to comply with MasterCard's Authorization Data Accuracy Initiative.

HeartlandKeyBlock:   Specifies the key block used to encrypt the data.

This field allows you to specify the key block that was used to encrypt the data specified by HeartlandEncryptionMode. This value will be obtained from an E3 magnetic stripe reader and is used by Heartland to decrypt the encrypted data.

Base Configuration Settings

GUIAvailable:   Tells the component whether or not a message loop is available for processing events.

In a GUI-based application, long-running blocking operations may cause the application to stop responding to input until the operation returns. The component will attempt to discover whether or not the application has a message loop and, if one is discovered, it will process events in that message loop during any such blocking operation.

In some non-GUI applications an invalid message loop may be discovered that will result in errant behavior. In these cases, setting GuiAvailable to false will ensure that the component does not attempt to process external events.

UseBackgroundThread:   Whether threads created by the component are background threads.

If set to True, when the component creates a thread the thread's IsBackground property will be explicitly set to True. By default this setting is False.

UseInternalSecurityAPI:   Tells the component whether or not to use the system security libraries or an internal implementation.

By default the component will use the system security libraries to perform cryptographic functions. When set to False calls to unmanaged code will be made. In certain environments this is not desirable. To use a completely managed security implementation set this setting to True. Setting this to True tells the component to use the internal implementation instead of using the system's security API.

Note: This setting is static. The value set is applicable to all components used in the application.

When this value is set the product's system DLL is no longer required as a reference, as all unmanaged code is stored in that file.

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