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

TSYSECommerce 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.

TSYSECommerce Configuration Settings

IsPassengerTransport:   Indicates that the transaction is a passenger transport transaction.

This configuration setting should be set to 'True' to process Passenger Transport transaction in Mail Order (Direct Marketing) and eCommerce environments. When set to 'False' (default value) the transaction will be processed normally.

IsExistingDebtPayment:   Specifies whether the transaction is a payment on an existing debt transaction.

This configuration setting, when set to 'True', will send an Existing Debt Indicator of "9" which is used to indicate a payment on an existing debt transaction.

IsPurchaseReturnAuthorization:   Set this to process a Visa Purchase Return Authorization transaction.

To process an online Visa Purchase Return transaction you need to set this IsPurchaseReturnAuthorization flag to True. Default value is 'False'.

IsMerchantInitiatedTransaction:   Set this to process a Visa Merchant Initiated transaction.

To process a Visa Merchant Initiated Transaction you need to set this IsMerchantInitiatedTransaction flag to True. Default value is False.

MITTransactionId:   Transaction Id associated with the original authorization of a Merchant Initiated Transaction.

This configuration setting is required when sending an Merchant Initiated Transaction, when the IsMerchantInitiatedTransaction is set to 'True'. It should be set with the TransactionId from the original (first) authorization. This configuration setting is required when sending MIT Recurring, MIT Installment, MIT Standing Instruction or MIT Industry Practice transactions. To send an MIT Standing Instruction you need to set the POSEnvironmentIndicator to specify the type of merchant initiated transaction. To send an MIT Industry Practice you need to set the MessageReasonCode to specify the reason for this merchant initiated transaction.

Note: For Merchant Initiated Transactions you need to set the POSDataCode.CardInputMode to '7'.

MessageReasonCode:   Code used to identify the Merchant Initiated Transactions for Visa.

This field is used to identify the reason of the merchant initiated transaction that is related to a previous consumer-initiated transaction but is conducted without the consumer being present and without any cardholder validation performed.

Valid values are:

Code Description
3900 Incremental Authorization (this is a continuation of the consumer purchase)
3901 Resubmission (valid when the original authorization was declined for insufficient funds)
3902 Delayed Charges (account charge associated with an agreement between a cardholder and a merchant for services rendered)
3903 Reauthorization (purchase made after the original purchase such as: split shipment, estimated amount etc.)
3904 No Show (when the customer did not meet the terms of the agreement and the merchant is able to charge for it)

POSEnvironmentIndicator:   Provides additional information about the transaction.

This Visa only configuration setting is used to provide additional information about the transaction. This value should be set in the following scenarios with the respective values:

Value Description
C Card On File
I Installment Payment
R Recurring Payment

Note: If the merchant stores payment credential for the first time, the value in POSDataCode.CardInputMode should reflect the actual entry mode for the transaction (i.e. manual input, key entered).
If the merchant initiates a transaction using a stored payment credential, the value in POSDataCode.CardInputMode should be '7' for Credential on File transactions.

IncrementalTransId:   Transaction Id associated with authorization to increment.

This configuration setting is required when sending an Incremental transaction, when the ACI is set to "I". It should be set with the TransactionId from the original (first) authorization. You must keep track of the total authorized amount, which is the sum of the original authorization and all subsequent incremental authorizations, and set the TotalAuthorizedAmount configuration setting in the TSYSDetailRecord component before settlement. Only one detail record should be submitted, no matter how many incremental transactions are authorized.

IncrementalTransDate:   Transaction Date associated with authorization to increment.

This configuration setting is required when sending an Incremental transaction, when the ACI is set to "I". It should be set with the TransmissionDate from the original (first) authorization. You must keep track of the total authorized amount, which is the sum of the original authorization and all subsequent incremental authorizations, and set the TotalAuthorizedAmount configuration setting in the TSYSDetailRecord component before settlement. Only one detail record should be submitted, no matter how many incremental transactions are authorized.

IncrementalTransTime:   Transaction Time associated with authorization to increment.

This configuration setting is required when sending an Incremental transaction, when the ACI is set to "I". It should be set with the TransactionTime from the original (first) authorization. You must keep track of the total authorized amount, which is the sum of the original authorization and all subsequent incremental authorizations, and set the TotalAuthorizedAmount configuration setting in the TSYSDetailRecord component before settlement. Only one detail record should be submitted, no matter how many incremental transactions are authorized.

IncrementalApprovalCode:   Transaction Approval Code associated with authorization to increment.

This configuration setting is required when sending an Incremental transaction, when the ACI is set to "I". It should be set with the ApprovalCode from the original (first) authorization. You must keep track of the total authorized amount, which is the sum of the original authorization and all subsequent incremental authorizations, and set the TotalAuthorizedAmount configuration setting in the TSYSDetailRecord component before settlement. Only one detail record should be submitted, no matter how many incremental transactions are authorized.

IncrementalRetrievalNumber:   Transaction Retrieval Number associated with authorization to increment.

This configuration setting is required when sending an Incremental transaction, when the ACI is set to "I". It should be set with the RetrievalNumber from the original (first) authorization. You must keep track of the total authorized amount, which is the sum of the original authorization and all subsequent incremental authorizations, and set the TotalAuthorizedAmount configuration setting in the TSYSDetailRecord component before settlement. Only one detail record should be submitted, no matter how many incremental transactions are authorized.

CumulativeAmount:   Total cumulative authorized amount for series of Incremental authorization transactions (Visa and Discover only).

This configuration setting is required for Visa and Discover Incremental transaction. When supporting incremental authorizations, you must manually keep track of the sum of all authorizations made for a single transaction (all based on the same transaction id). This total will be sent on G3v022 (additional amounts) with amount type 43.

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

This configuration setting is for advanced users, and it is not recommended it be changed. Please see the TSYSDetailRecord component's CardholderId property for more information.

ECI:   Electronic Commerce Indicator.

This contains a 1-character transaction indicator identifying the type of transaction being authorized. This is also known as "MOTO". This value is used only for Card Not Present transactions. See the table below for a list of supported values.

IndicatorDescription
EMPTY ("") Do not send Electronic Commerce Indicator in authorization request (ie: for Retail transactions)
SPACE (" ")Not a Mail/Telephone Order Transaction (ie: for retail transactions).
1One Time Occurrence of a Mail/Telephone Order Transaction (use for Direct Marketing).
2Recurring Mail/Telephone Order Transaction.
3Installment Payment of a Mail/Telephone Order Transaction.
4Unknown Classification.
5Secure Electronic Transaction (3-D Secure) and MasterCard SecureCode (UCAF)
6Non-authenticated security transaction at a 3-D Secure capable merchant, and merchant attempted to authenticate the cardholder using 3-D Secure.
7Non-authenticated Security Transaction, such as a Channel-Encrypted Transaction (default for CardNotPresent eCommerce transactions).
8Non-secure Electronic Commerce Transaction
AIn-App Authentication (Discover, Mastercard and Amex)
RFirst recurring SecureCode Phone Order transaction (Mastercard Only)
TSingle nonrecurring SecureCode Phone Order transaction (Mastercard Only)

Note: Other values necessary for passing 3D Secure data are CAVV and XID.

Note: Please make sure to send the SPACE (" ") value inside quotes. For Example:


TSYSRetail.Config("ECI=\" \"");

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.

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.

ACI:   Requested Authorization Characteristics Indicator (ACI).

By default the component automatically selects the correct ACI for the type of transaction being attempted. This configuration setting is for advanced users, and it is not recommended it be changed. That being said, this 1-character field contains the Requested ACI used to identify an authorization request as potentially qualifying for CPS (Custom Payment Services) and MasterCard Merit programs. If a merchant chooses not to participate in CPS, the ACI may be set to "N". The following table provides a summary of the codes currently supported by both Visa and MasterCard. Please note that not all of these ACI values are supported in Direct Marketing and Retail transactions.

NDevice is not CPS capable / MasterCard TIPS (Travel Industries Premiere Service).
YDevice is CPS capable.
PCPS Capable - Manually keyed hotel/lodging transaction or preferred customer authorization request for hotel, auto rental, and passenger transport industries.
ICPS capable - Incremental Authorization Request.
RRecurring or Installment payments / MasterCard SIIP (Recurring payment).

AllowPartialAuths:   Indicates whether partial authorizations are to be supported.

When this setting is True, if the credit 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.

AmexCNPInternetPhoneData:   Used by Merchants in mail-, telephone- and internet-order industries to submit additional data for Card Not Present transactions.

This configuration setting takes a vertical bar (|) 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:

TSYSECommerce.Config("AmexCNPInternetPhoneData=CustomerEmail=CFFROST@EMAILADDRESS.COM|CustomerHostName=PHX.QW.AOL.COM|BrowserType=MOZILLA/4.0~(COMPATIBLE;~MSIE~5.0;~WINDOWS~95)|ShipToCountry=840|ShippingMethod=02|ProductSKU=TKDC315U|CustomerIP=127.142.005.056|CustomerANI=6025551212|CustomerIIDigits=00");

CustomerEmailCustomer's e-mail address.
CustomerHostNameName of the server that the customer is connected to.
BrowserTypeCustomer's HTTP browser type.
ShipToCountryThree-byte, numeric country code. Example for USA: 840
ShippingMethodTwo-byte, shipment-type code. Possible values:

01 Same Day
02 Overnight / Next Day
03 Priority, 2-3 days
04 Ground, 4 or more days
05 Electronic Delivery
06 Ship to Store

ProductSKUUnique SKU (Stock Keeping Unit) inventory reference number of product associated with this authorization request. For multiple items, enter the SKU for the single, most expensive item.
CustomerIPCustomer's Internet IP address.
CustomerANIANI (Automatic Number Identification) specified phone number that customer used to place order with merchant.
CustomerIIDigitsTelephone company-provided ANI ii (Information Identifier) coding digits associated with CUSTOMER ANI phone number that correspond to calltype; e.g., cellular, government institution, etc.

AmexAirlinePassengerData:   Used by Merchants that are in the airline industry to submit information for Passenger Transport transactions.

This configuration setting takes a vertical bar (|) 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:

TSYSECommerce.Config("AmexAirlinePassengerData=DepartureDate=20170601|PassengerName=FROST~JANE~M~MRS|CardMemberName=FROST~CHARLES~F~MR|Origin=ABC|Destination=DEF|NumberOfCities=4|RoutingCities=ABC/DEF/GHI/JKL|NumberOfAirlineCarriers=3|AirlineCarriers=AB/XY/BC|FareBasis=ABC123DEF456GHI789JKL012|NumberOfPassengers=1|ETicket=True|ReservationCode=ABCDE1234567890");

NOTE: The tilde character "~" = character space.

DepartureDatePassenger's departure date in format YYYYMMDD. Example: 20171220
PassengerNamePassenger Name in format SURNAME~FIRSTNAME~MIDDLEINITIAL~TITLE. Use character space as sub-element separator. Example: FROST JANE M MRS
CardMemberNameCardmember Name in format SURNAME~FIRSTNAME~MIDDLEINITIAL~TITLE. Use character space as sub-element separator. Example: FROST CHARLES F MR
OriginFirst segment travel origination Airport. Example for Los Angeles (CA): LAX
DestinationDestination Airport for first travel segment of trip; not necessarily the final destination. For example, if passenger flies from STL to MIA with layover at JFK, Destination Airport for first segment is JFK.
NumberOfCitiesNumber of Airports or Cities on ticket. Maximum is 10.
RoutingCitiesRouting Airport or City Codes for each leg on ticket (including Origin and Destination) in segments with virgule (/) separator. Example: ABC/DEF/GHI/JKL/MNO/PQR/STU/VWX/YZA/XYZ. Note that the minimum number of RoutingCitites is 2 (Origin and Destination).
NumberOfAirlineCarriersNumber of Airline Carriers entered in AirlineCarriers subfield. Maximum is 9.
AirlineCarriersAirline Carrier Code for each leg on ticket (including Origin and Destination) in segments with virgule (/) separator. Example: AB/XY/BC/CD/DE/DE/CD/BC/AB. Note: Each leg must have Airline Carrier Code entry, even if multiple (or all) legs are on the same Airline. Note that the minimum number of AirlineCarriers is 1 (Airline Carrier Code from Origin to Destination).
FareBasisPrimary and secondary discount codes which indicate class of service and fare level associated with ticket. Example: ABC123DEF456GHI789JKL012
NumberOfPassengersNumber of passengers in party. Default value is 1.
ETicketIndicates if ticket is electronic. Default value is false. Possible values:

True Electronic Ticket
False Other ticket types (non-electronic ticket) (default)

ReservationCodeA precursor to a ticket number which corresponds to an airline ticket purchase reservation made by an airline or Global Distribution System (GDS). Example: ABCDE1234567890

AmexCPGoodsSoldData:   Identifies merchandise such as gift cards, computers, and other electronics that can be resold for cash.

This configuration setting takes a vertical bar (|) 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("AmexCPGoodsSoldData=ProductCode=1000");

ProductCodeFour-byte goods product indicator code. Possible values:

1000Gift Card

CountryCode:   Identifies the country where the merchant is located.

This field contains a three digit number assigned by the signing member or processor to identify the merchant's location country. These codes are specified by ISO-3166-1. The default is "840", indicating the United States.

CurrencyCode:   Identifies the type of currency used by the merchant.

This field contains a three digit number assigned by the signing member or processor to identify the merchant's authorization currency. The default is "840", indicating US Dollars. Other values may be used when processing multi-currency.

IsBillPayment:   Indicates that the transaction is a bill payment transaction.

This field, when set to 'True', indicates that the transaction is a Bill Payment transaction and will be processed as such. When set to 'False' (default value) the transaction will be processed normally.

MerchantLanguage:   Designates the language that response messages will be returned in.

This field contains a two digit language indicator. This value designates the language to be used in formatting the authorization response text message.

SendCommCardInd:   Indicates whether to send Commercial Card Request Indicator.

If set to True (default), the CommercialCardType field will indicate whether the credit card submitted for authorization is a Business, Corporate, or Purchasing Card (this is the default function). If False, the contents of the CommercialCardType property must be ignored.

RetrieveToken:   Sends a Token Only request.

This is an action config which when called will send a token only request to the TSYS Host. Provided the request was successful, a token will be returned for the specified Card. The token can be retrieved via Token and the status of the token will be returned via ResponseTokenStatus. For this request, no card verification or authorization will be performed.

RequestToken:   Indicates whether to request a token for the specified card data sent in an Authorize request.

When set to 'True' prior to an Authorize request, a token will be requested for the specified Card data. Provided the authorization and token generation was successful, a token will be returned in the response and can be retrieved via Token. Additionally the status of the token will be returned via ResponseTokenStatus. The returned token can then be used to process future transactions without the use of Card data with the exception of the expiration details. The default value is 'False'.

NOTE: When using this request, verification and authorization of the card will be performed.

ResponseTokenStatus:   The status of retrieval of the token.

This field will be populated after a token is requested via RetrieveToken or RequestToken. The applicable values are:

Value Description
0 Token retrieval was successful and is included.
1 Terminal not configured to receive a token.
2 Terminal was not authenticated.
3 System failure.

Token:   The token received from the TSYS host when a token request is sent.

This field will contain the token received from TSYS from either a RetrieveToken or RequestToken request. This field is also used to specify a token value, used in place of Card data, to be sent in an Authorize request. The token is formatted as a card number, with the last 4 digits preserved. Other characters in the number will be letters rather than numbers. Tokens are used as an added security measure to protect a customer's Card and may also help decrease PCI Compliance verification as storing credit card data is no longer needed.

PFIdentifier:   The Payment Facilitator Identifier value assigned by MasterCard.

This 11-digit value, assigned by MasterCard, is assigned during registration via MasterCard Connect for the Service Provider designated as a 'Payment Facilitator'. This value must be present on all MasterCard transactions that originate from a Payment Facilitator.

PFNameSubMerchantName:   The Payment Facilitator Name and Sub-Merchant name.

This 25-character field is a concatenation of two fields separated by an asterisk (*). The Payment Facilitator Name is three characters in length and is followed by the asterisk. The remainder of the field consists of the Sub-Merchant name. This field must be upper case and it is required on all MasterCard transactions that originate from a Payment Facilitator.

PFSubMerchantIdentifier:   The Payment Facilitator Sub-Merchant Identifier.

This 15-digit field is assigned by the Payment Facilitator or the Acquirer. This field is required on all MasterCard transactions that originate from a Payment Facilitator.

PFSubMerchantCity:   The Payment Facilitator Sub-Merchant City.

This 13-character field indicates the city of the Sub-Merchant location (not the acquirer's location). This field must be upper case and it is required on all MasterCard transactions that originate from a Payment Facilitator.

PFSubMerchantState:   The Payment Facilitator Sub-Merchant State.

This 2-character field indicates the state or province code of the Sub-Merchant location (not the acquirer's location). This field must be upper case and it is required on all MasterCard transactions that originate from a Payment Facilitator. If the Sub-Merchant is non-U.S. and non-Canadian, this field should be '00'.

PFSubMerchantCountry:   The Payment Facilitator Sub-Merchant Country Code.

This 3-digit field indicates the country of the Sub-Merchant location (not the acquirer's location) using ISO-specified numeric codes. This field is required on all MasterCard transactions that originate from a Payment Facilitator.

PFSubMerchantPostalCode:   The Payment Facilitator Sub-Merchant Postal Code.

This 9-character field indicates the geographic/postal code of the Sub-Merchant location (not the acquirer's location). This field must be upper case and it is required on all MasterCard transactions that originate from a Payment Facilitator.

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.

InterleavedMode:   Determines whether to use Interleaved Transaction Mode for authorization requests.

Interleaved Mode is intended for high volume transaction environments. When using this communication mode, transaction data is transmitted and received simultaneously without blocking. The advantage of an Interleaved Session is that the connection can stay up and is stateless once connected. Up to 10 simultaneous requests can be sent at a time. By default the value for this configuration setting is False. For instance:


        //Interleaved Transaction Mode 
        TSYSECommerce1.Config("InterleavedMode=True");

        //Maximum number of pending response packets.
        TSYSECommerce1.Config("MaxPendingResponseCount=10");

        TSYSECommerce1.OnResponse += (sender, args) =>
        {
            Console.WriteLine("Response received for {0}, {1}, {2}, {3}", args.TransactionId, args.ResponseCode, args.ResponseText, args.ResponseApprovalCode);
        };

        TSYSECommerce1.Authorize();

        //Explicitly Disconnect
        TSYSECommerce1.Config("DisconnectInterleaved");

InterleavedTimeout:   Timeout value to wait for a response from TSYS.

When InterleavedMode is set to True the component will return immediately when Authorize is called. This setting specifies the timeout (in seconds) for which the component will wait for a response. If no response is received within InterleavedTimeout seconds the Error event will fire and the connection will be closed.

The default value is 60 (seconds).

MaxPendingResponseCount:   Maximum number of pending response packets.

This is the maximum number of outstanding transactions that have not yet received a response. This should not exceed the maximum number of 10 interleaved transactions that can be sent at the same time. If an authorization is attempted that would exceed the maximum number of pending response an error occurs.

The default value is 10.

CurrentPendingResponseCount:   Current number of pending response packets.

This is the current number of outstanding transactions that have not yet received a response. This is a read-only configuration setting.

DisconnectInterleaved:   To explicitly terminate the connection.

This configuration setting is read only and can be used to explicitly close the interleaved connection. This is usually used when all response packets are received.

DoEvents:   Processes events from the internal message queue.

This configuration setting is read only and can be used to process any available events. If no events are available, it waits for a preset period of time, and then returns.

ResponseTransactionIntegrityClass:   A 2-character value returned in the response of MasterCard Credit transactions to identify the transaction integrity class.

This read-only configuration setting contains a 2-character value when returned in the response of MasterCard Credit transactions. This value encompasses the fundamental safety and security of credit transactions, including the assessment of both the validity of the card and the cardholder.

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.

MerchantSellerID:   Merchant's Seller ID.

This field is used for American Express transactions that are submitted via an Aggregator/Payment Service Provider. It contains a maximum 20-byte numeric code that uniquely identifies an American Express Payment Service Provider's (Aggregator's) seller or vendor code.

LocationDetailName:   Merchant name.

This field is used to identify the merchant name that appears on the storefront and/or customer receipts and statements. The maximum length is 38 characters (upper-case). For American Express transactions that are submitted via an Aggregator/Payment Service Provider the maximum length is 30 characters and if necessary this value should be truncated rather than abbreviated.

LocationDetailAddress:   Merchant's street address.

This field is used to identify the merchant's street address where the transaction took place. The maximum length is 38 characters (upper-case). For American Express transactions that are submitted via an Aggregator/Payment Service Provider the maximum length is 20 characters and if necessary this value should be truncated rather than abbreviated.

LocationDetailPhone:   Merchant's phone number.

This field is used for American Express transactions that are submitted via an Aggregator/Payment Service Provider. It is used to identify the Aggregator's phone number. This value should be 10 characters in length and it must include the area code.

LocationDetailEmail:   Merchant's e-mail adress.

This field is used for American Express transactions that are submitted via an Aggregator/Payment Service Provider. It is used to identify the Aggregator's e-mail address. The maximum length is 20 characters and if necessary this value should be truncated rather than abbreviated.

LocationDetailCity:   Name of the city.

This field is used to identify the name of the city where the transaction took place. The maximum length is 21 characters (upper-case). For American Express transactions that are submitted via an Aggregator/Payment Service Provider the maximum length is 13 characters.

LocationDetailRegion:   Region code that corresponds to the state, province, or other country subdivision.

This field is used to identify the region code that corresponds to the state, province, or other country subdivision of the merchant location where the transaction took place. The maximum length is 3 characters.

LocationDetailCountry:   Country code.

This field is used to identify the country code of the location where the transaction took place. For example, the country code for USA is "840." The maximum length is 3 characters.

LocationDetailPostal:   Postal code.

This field is used to identify the postal / zip code of the location where the transaction took place. The maximum length is 15 characters. For American Express transactions that are submitted via an Aggregator/Payment Service Provider the maximum length is 10 characters.

AmexAggregatorName:   Amex Payment Service Provider/Aggregator Name.

This field is used for American Express transactions that are submitted via an Aggregator, Payment Service Provider or Facilitator to identify the Aggregator's Name. The maximum length of this field is 20 characters. It must be upper-case and should not contain spaces.

PurchaseIdentifier:   Optional purchase order number assigned by the merchant.

To achieve the best interchange rate for Direct Marketing (e-commerce and MOTO) transactions, you may be required to send 25-character purchase identifier in the settlement. Normally this would require the use of the TSYSDetailRecord component to add the purchase Id to the detail aggregate before adding that aggregate to the batch. However, setting the PurchaseIdentifier configuration setting will include the identifier when calling the GetDetailAggregate method, so that the intermediary steps using the TSYSDetailRecord component are unnecessary.

For instance, instead of this:

  TSYSECommerce.Authorize()
  DetailRecord.ParseAggregate(TSYSECommerce.GetDetailAggregate())
  DetailRecord.PurchaseIdentifier = "123456"
  TSYSSettle.DetailAggreate[0] = DetailRecord.GetDetailAggregate()
You can do this:
  TSYSECommerce.Config("PurchaseIdentifier=123456")
  TSYSECommerce.Authorize()
  TSYSSettle.DetailAggregate[0] = TSYSECommerce.GetDetailAggregate()

CAVV:   AuthenticationCAVV data from the ThreeDSecure component.

This setting is used to pass 3D Secure CAVV data on to the transaction server. This field must be formatted as a 28-byte Base-64 encoded value. This component may be used in conjunction with the ThreeDSecure component from the E-Payment Integrator toolkit or with any other 3D Secure MPI implementation. Other values necessary for passing 3D Secure data include XID and ECI. This setting is only valid for E-Commerce transactions.

ResponseCAVV:   Used for 3D-Secure transactions. Indicates whether the submitted CAVV value passed validation.

This CAVV Result code indicates whether the authentication value submitted in the CAVV field can be validated by either Visa or the card issuer. The table below shows the possible values returned from Vital/TSYS.

Blank or not presentCAVV not validated.
0CAVV not validated because erroneous data was submitted.
1CAVV failed validation.
2CAVV passed validation.
3CAVV validation could not be performed; Issuer attempt incomplete.
4CAVV validation could not be performed; Issuer system error.
5Reserved for future use.
6Reserved for future use.
7CAVV attempt - failed validation - issuer available (US issued card/non-US acquirer).
8CAVV attempt - passed validation - issuer available (US issued card/non-US acquirer).
9CAVV attempt - failed validation - issuer unavailable (US issued card/non-US acquirer).
ACAVV attempt - passed validation - issuer unavailable (US issued card/non-US acquirer).
BCAVV passed validation, information only, no liability shift.
CCAVV was not validated - attempted.
DCAVV was not validated - authentication.

This field is read-only and is only returned for E-Commerce transactions where 3D-Secure data ( CAVV, ECI, and XID) was submitted in the authorization.

XID:   TransactionId from a 3D Secure authentication.

This setting is used to pass the 3D Secure TransactionId (XID) data on to the credit card processor. This setting must be formatted as a 20-byte plaintext value, or a 28-byte Base-64 encoded value. This component may be used in conjunction with the ThreeDSecure component from the E-Payment Integrator toolkit or with any other 3D Secure MPI implementation. For example: Other settings necessary for passing 3D Secure data are CAVV and ECI. This setting is only valid for E-Commerce transactions.

ProgramProtocol:   Identifies the type of 3D-Secure program.

Program Protocol must be provided by the merchant if they are participating in Mastercard Identity Check and have previously authenticated using the Mastercard Identity Check or SecureCode program. Allowable values are:

ValueDescription
1 3D Secure Version 1.0 [3DS 1.0]
2 EMV 3-D Secure [3DS 2.0]

Note: The component will send this value as part of group G3v078. It can be send for all card types but will only be used for Mastercard transactions and will be ignored for other card brands.

DirectoryServerTxnID:   Directory Server Transaction ID generated by the EMV 3DS Mastercard Directory Server during authentication.

The Directory Server Transaction ID is a 36 byte value generated by the EMV 3DS Mastercard Directory Server during the authentication transaction and passed back to the merchant with the authentication results. This field allows the merchant to pass the Directory Server Transaction ID during authorization in order to link authentication and authorization data.

Note: The component will send this value as part of group G3v078. It can be send for all card types but will only be used for Mastercard transactions and will be ignored for other card brands.

TokenRequestorID:   Card brand Token Requestor ID assigned by the token service provider.

This eleven digit value is used for Card Brand Tokenization only. If present, this configuration setting should be included in the authorization request. The component will send this value as part of group G3v062.

If Card Brand Token Requestor ID was present in the original transaction it must be included in a reversal message.

Note: The component will also send this value as part of DetailExtension Config of TSYSDetailRecord component (Group ODG41 - tag "TRI").

UCAFIndicator:   Indicates the merchant's support and usage of UCAF in MasterCard SecureCode transactions.

This configuration setting is used to pass the UCAF Collection Indicator in MasterCard SecureCode e-commerce credit transactions. Mastercard's processing rules allow merchants to gain a liability shift and interchange benefit if they submit their electronic commerce transactions for cardholder authentication. Merchants need to pass the appropriate authentication detail in UCAFData. Other values necessary for passing SecureCode data include UCAFData and ECI. This setting is required in all MasterCard SecureCode E-Commerce transactions. The valid values for this configuration setting are:

IndicatorDescription
0 UCAF data is not supported by the merchant or the merchant has chosen not to send the indicator.
1 UCAF data collection is supported by the merchant and UCAF data was present and contained an attempted AAV for Mastercard SecureCode.
2 UCAF data collection is supported by the merchant and UCAF data was present and contained a fully authenticated AAV.
5 Issuer Risk-Based Decisioning.
6 Merchant Risk-Based Decisioning.
7 Partial Shipment, Incremental or Recurring Payment.

UCAFSecurityIndicator:   Indicates the security level and cardholder authentication in MasterCard SecureCode transactions.

This configuration setting is used to pass the UCAF electronic commerce indicators representing the security level and cardholder authentication associated with the transaction. Mastercard's processing rules allow merchants to gain a liability shift and interchange benefit if they submit their electronic commerce transactions for cardholder authentication. Merchants need to pass the appropriate authentication detail in UCAFData. Other values necessary for passing SecureCode data include UCAFIndicator, UCAFData and ECI. This setting is recommended in all MasterCard SecureCode E-Commerce transactions. The valid values for this configuration setting are:

Security Protocol/Cardholder Authentication Description
21 Channel encryption; cardholder certificate not used(preferred value for Mastercard SecureCode).
22 Masterpass-generated transaction.
24 Digital Secure Remote Payment (DSRP) with UCAF Data.
91 No security protocol; cardholder certificate not used.

UCAFData:   UCAF Authentication data from the MasterCard SecureCode authentication.

This configuration setting is used to pass encoded MasterCard SecureCode issuer or cardholder-generated authentication data. This is a variable length security field up to 32 bytes in length. This setting is only valid for MasterCard E-Commerce transactions.

ResponseUCAF:   Used for MasterCard SecureCode transactions to indicate whether MasterCard downgraded the SecureCode transaction and sent it to the Issuer.

This UCAF Result code indicates the security level and cardholder authentication associated with the transaction. Mastercard's processing rules allow merchants to gain a liability shift and interchange benefit if they submit their electronic commerce transactions for cardholder authentication. If the cardholder authentication detail is not present in UCAFData field for MasterCard SecureCode transactions, MasterCard will downgrade and send the transaction to the Issuer. This field is read-only and is only returned for MasterCard SecureCode E-Commerce transactions to indicate if the transaction was downgraded or not.

IPPort Configuration Settings

ConnectionTimeout:   Sets a separate timeout value for establishing a connection.

When set, this configuration setting allows you to specify a different timeout value for establishing a connection. Otherwise, the component will use Timeout for establishing a connection and transmitting/receiving data.

FirewallAutoDetect:   Tells the component whether or not to automatically detect and use firewall system settings, if available.

This is the same as AutoDetect. This setting is provided for use by components that do not directly expose Firewall properties.

FirewallHost:   Name or IP address of firewall (optional).

If a FirewallHost is given, requested connections will be authenticated through the specified firewall when connecting.

If the FirewallHost setting is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, the FirewallHost setting is set to the corresponding address. If the search is not successful, an error is returned.

NOTE: This is the same as Host. This setting is provided for use by components that do not directly expose Firewall properties.

FirewallListener:   If true, the component binds to a SOCKS firewall as a server (IPPort only).

This entry is for IPPort only and does not work for other components that descend from IPPort.

If this entry is set, the component acts as a server. RemoteHost and RemotePort are used to tell the SOCKS firewall in which address and port to listen to. The firewall rules may ignore RemoteHost, and it is recommended that RemoteHost be set to empty string in this case.

RemotePort is the port in which the firewall will listen to. If set to 0, the firewall will select a random port. The binding (address and port) is provided through the ConnectionStatus event.

The connection to the firewall is made by calling the Connect method.

FirewallPassword:   Password to be used if authentication is to be used when connecting through the firewall.

If FirewallHost is specified, the FirewallUser and FirewallPassword settings are used to connect and authenticate to the given firewall. If the authentication fails, the component throws an exception.

NOTE: This is the same as Password. This setting is provided for use by components that do not directly expose Firewall properties.

FirewallPort:   The TCP port for the FirewallHost;.

Note that the FirewallPort is set automatically when FirewallType is set to a valid value.

NOTE: This is the same as Port. This setting is provided for use by components that do not directly expose Firewall properties.

FirewallType:   Determines the type of firewall to connect through.

The appropriate values are as follows:

0No firewall (default setting).
1Connect through a tunneling proxy. FirewallPort is set to 80.
2Connect through a SOCKS4 Proxy. FirewallPort is set to 1080.
3Connect through a SOCKS5 Proxy. FirewallPort is set to 1080.

NOTE: This is the same as FirewallType. This setting is provided for use by components that do not directly expose Firewall properties.

FirewallUser:   A user name if authentication is to be used connecting through a firewall.

If the FirewallHost is specified, the FirewallUser and FirewallPassword settings are used to connect and authenticate to the Firewall. If the authentication fails, the component throws an exception.

NOTE: This is the same as User. This setting is provided for use by components that do not directly expose Firewall properties.

KeepAliveTime:   The inactivity time in milliseconds before a TCP keep-alive packet is sent.

When set, TCPKeepAlive will automatically be set to true. By default the operating system will determine the time a connection is idle before a TCP keep-alive packet is sent. This system default if this value is not specified here is 2 hours. In many cases a shorter interval is more useful. Set this value to the desired interval in milliseconds.

Note: This value is not applicable in Java.

KeepAliveInterval:   The retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received.

When set, TCPKeepAlive will automatically be set to true. A TCP keep-alive packet will be sent after a period of inactivity as defined by KeepAliveTime. If no acknowledgement is received from the remote host the keep-alive packet will be re-sent. This setting specifies the interval at which the successive keep-alive packets are sent in milliseconds. This system default if this value is not specified here is 1 second.

Note: This value is not applicable in Java or MAC.

Linger:   When set to True, connections are terminated gracefully.

This property controls how a connection is closed. The default is True.

In the case that Linger is True (default), there are two scenarios for determining how long the connection will linger. The first, if LingerTime is 0 (default), the system will attempt to send pending data for a connection until the default IP protocol timeout expires.

In the second scenario, LingerTime is a positive value, the system will attempt to send pending data until the specified LingerTime is reached. If this attempt fails, then the system will reset the connection.

The default behavior (which is also the default mode for stream sockets) might result in a long delay in closing the connection. Although the component returns control immediately, the system could hold system resources until all pending data is sent (even after your application closes).

Setting this property to False forces an immediate disconnection. If you know that the other side has received all the data you sent (by a client acknowledgment, for example), setting this property to False might be the appropriate course of action.

LingerTime:   Time in seconds to have the connection linger.

LingerTime is the time, in seconds, to leave the socket connection linger. This value is 0 by default, which means it will use the default IP protocol timeout.

LocalHost:   The name of the local host through which connections are initiated or accepted.

The LocalHost setting contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the component initiate connections (or accept in the case of server components) only through that interface.

If the component is connected, the LocalHost setting shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multi-homed hosts (machines with more than one IP interface).

LocalPort:   The port in the local host where the component binds.

This must be set before a connection is attempted. It instructs the component to bind to a specific port (or communication endpoint) in the local machine.

Setting this to 0 (default) enables the system to choose a port at random. The chosen port will be shown by LocalPort after the connection is established.

LocalPort cannot be changed once a connection is made. Any attempt to set this when a connection is active will generate an error.

This; setting is useful when trying to connect to services that require a trusted port in the client side. An example is the remote shell (rsh) service in UNIX systems.

MaxLineLength:   The maximum amount of data to accumulate when no EOL is found.

MaxLineLength is the size of an internal buffer, which holds received data while waiting for an EOL string.

If an EOL string is found in the input stream before MaxLineLength bytes are received, the DataIn event is fired with the EOL parameter set to True, and the buffer is reset.

If no EOL is found, and MaxLineLength bytes are accumulated in the buffer, the DataIn event is fired with the EOL parameter set to False, and the buffer is reset.

The minimum value for MaxLineLength is 256 bytes. The default value is 2048 bytes. The maximum value is 65536 bytes.

MaxTransferRate:   The transfer rate limit in bytes per second.

This setting can be used to throttle outbound TCP traffic. Set this to the number of bytes to be sent per second. By default this is not set and there is no limit.

ProxyExceptionsList:   A semicolon separated list of hosts and IPs to bypass when using a proxy.

This setting optionally specifies a semicolon separated list of hostnames or IP addresses to bypass when a proxy is in use. When requests are made to hosts specified in this property the proxy will not be used. For instance:

www.google.com;www.nsoftware.com

TCPKeepAlive:   Determines whether or not the keep alive socket option is enabled.

If set to true, the socket's keep-alive option is enabled and keep-alive packets will be sent periodically to maintain the connection. Set KeepAliveTime and KeepAliveInterval to configure the timing of the keep-alive packets.

Note: This value is not applicable in Java.

UseIPv6:   Whether to use IPv6.

When set to 0 (default), the component will use IPv4 exclusively. When set to 1, the component will use IPv6 exclusively. To instruct the component to prefer IPv6 addresses, but use IPv4 if IPv6 is not supported on the system, this setting should be set to 2. The default value is 0. Possible values are:

0 IPv4 Only
1 IPv6 Only
2 IPv6 with IPv4 fallback

UseNTLMv2:   Whether to use NTLM V2.

When authenticating with NTLM this setting specifies whether NTLM V2 is used. By default this value is False and NTLM V1 will be used. Set this to True to use NTLM V2.

CloseStreamAfterTransfer:   If true, the component will close the upload or download stream after the transfer.

This setting determines whether the input or output stream is closed after the transfer completes. When set to True (default), all streams will be closed after a transfer is completed. In order to keep streams open after the transfer of data, set this to False. the default value is True.

TcpNoDelay:   Whether or not to delay when sending packets.

When true, the socket will send all data that is ready to send at once. When false, the socket will send smaller buffered packets of data at small intervals. This is known as the Nagle algorithm.

By default, this config is set to false.

SSL Configuration Settings

CACertFilePaths:   The paths to CA certificate files when using Mono on Unix/Linux.

This setting specifies the paths on disk to CA certificate files when using Mono on Unix/Linux. It is not applicable in any other circumstances.

The value is formatted as a list of paths separated by semicolons. The component will check for the existence of each file in the order specified. When a file is found the CA certificates within the file will be loaded and used to determine the validity of server certificates.

The default value is:

/etc/ssl/ca-bundle.pem;/etc/pki/tls/certs/ca-bundle.crt;/etc/ssl/certs/ca-certificates.crt;/etc/pki/tls/cacert.pem

LogSSLPackets:   Controls whether SSL packets are logged when using the internal security API.

When the UseInternalSecurityAPI configuration setting is True, this setting controls whether SSL packets should be logged. By default, this setting is False, as it is only useful for debugging purposes.

When enabled, SSL packet logs are output using the SSLStatus event, which will fire each time an SSL packet is sent or received.

Enabling this setting has no effect if UseInternalSecurityAPI is False.

ReuseSSLSession:   Determines if the SSL session is reused.

If set to true, the component will reuse the context if and only if the following criteria are met:

  • The target host name is the same.
  • The system cache entry has not expired (default timeout is 10 hours).
  • The application process that calls the function is the same.
  • The logon session is the same.
  • The instance of the component is the same.

SSLCipherStrength:   The minimum cipher strength used for bulk encryption.

This minimum cipher strength largely dependent on the security modules installed on the system. If the cipher strength specified is not supported, an error will be returned when connections are initiated.

Please note that this setting contains the minimum cipher strength requested from the security library. The actual cipher strength used for the connection is shown by the SSLStatus event.

Use this setting with caution. Requesting a lower cipher strength than necessary could potentially cause serious security vulnerabilities in your application.

When the provider is OpenSSL, SSLCipherStrength is currently not supported. This functionality is instead made available through the OpenSSLCipherList config setting.

SSLEnabledProtocols:   Used to enable/disable the supported security protocols.

Used to enable/disable the supported security protocols.

Not all supported protocols are enabled by default (the value of this setting is 4032). If you want more granular control over the enabled protocols, you can set this property to the binary 'OR' of one or more of the following values:

TLS1.312288 (Hex 3000)
TLS1.23072 (Hex C00) (Default)
TLS1.1768 (Hex 300) (Default)
TLS1 192 (Hex C0) (Default)
SSL3 48 (Hex 30)
SSL2 12 (Hex 0C)

When the provider is OpenSSL, SSLCipherStrength is currently not supported. This functionality is instead made available through the OpenSSLCipherList setting.

Note: TLS 1.1 and TLS1.2 support are only available starting with Windows 7.

Note: Enabling TLS 1.3 will automatically set UseInternalSecurityAPI to True.

SSLIncludeCertChain:   Whether the entire certificate chain is included in the SSLServerAuthentication event.

This setting specifies whether the Encoded parameter of the SSLServerAuthentication event contains the full certificate chain. By default this value is False and only the leaf certificate will be present in the Encoded parameter of the SSLServerAuthentication event.

If set to True all certificates returned by the server will be present in the Encoded parameter of the SSLServerAuthentication event. This includes the leaf certificate, any intermediate certificate, and the root certificate.

Note: When UseInternalSecurityAPI is set to True this value is automatically set to True. This is needed for proper validation when using the internal provider.

SSLProvider:   The name of the security provider to use.

Change this setting to use security providers other than the system default.

Use this setting with caution. Disabling SSL security or pointing to the wrong provider could potentially cause serious security vulnerabilities in your application.

The special value "*" (default) picks the default SSL provider defined in the system.

The special value "Internal" picks the internal SSL implementation. This does not rely on any system libraries. This is equivalent to setting UseInternalSecurityAPI to True.

Note: On Windows systems, the default SSL Provider is "Microsoft Unified Security Protocol Provider" and cannot be changed except to a value of "Internal".

SSLSecurityFlags:   Flags that control certificate verification.

The following flags are defined (specified in hexadecimal notation). They can be or-ed together to exclude multiple conditions:

0x00000001Ignore time validity status of certificate.
0x00000002Ignore time validity status of CTL.
0x00000004Ignore non-nested certificate times.
0x00000010Allow unknown Certificate Authority.
0x00000020Ignore wrong certificate usage.
0x00000100Ignore unknown certificate revocation status.
0x00000200Ignore unknown CTL signer revocation status.
0x00000400Ignore unknown Certificate Authority revocation status.
0x00000800Ignore unknown Root revocation status.
0x00008000Allow test Root certificate.
0x00004000Trust test Root certificate.
0x80000000Ignore non-matching CN (certificate CN not-matching server name).

This functionality is currently not available in Java or when the provider is OpenSSL.

SSLCACerts:   A newline separated list of CA certificate to use during SSL client authentication.

This setting specifies one or more CA certificates to be included in the request when performing SSL client authentication. Some servers require the entire chain, including CA certificates, to be presented when performing SSL client authentication. The value of this setting is a newline (CrLf) separated list of certificates. For instance:


-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
..
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

SSLEnabledCipherSuites:   The cipher suite to be used in an SSL negotiation.

The enabled cipher suites to be used in SSL negotiation.

By default, the enabled cipher suites will include all available ciphers ("*").

The special value "*" means that the component will pick all of the supported cipher suites. If SSLEnabledCipherSuites is set to any other value, only the specified cipher suites will be considered.

Multiple cipher suites are separated by semicolons.

Example values when UseInternalSecurityAPI is False (default):

obj.config("SSLEnabledCipherSuites=*");
obj.config("SSLEnabledCipherSuites=CALG_AES_256");
obj.config("SSLEnabledCipherSuites=CALG_AES_256;CALG_3DES");
Possible values when UseInternalSecurityAPI is False (default) include:
  • CALG_3DES
  • CALG_3DES_112
  • CALG_AES
  • CALG_AES_128
  • CALG_AES_192
  • CALG_AES_256
  • CALG_AGREEDKEY_ANY
  • CALG_CYLINK_MEK
  • CALG_DES
  • CALG_DESX
  • CALG_DH_EPHEM
  • CALG_DH_SF
  • CALG_DSS_SIGN
  • CALG_ECDH
  • CALG_ECDH_EPHEM
  • CALG_ECDSA
  • CALG_ECMQV
  • CALG_HASH_REPLACE_OWF
  • CALG_HUGHES_MD5
  • CALG_HMAC
  • CALG_KEA_KEYX
  • CALG_MAC
  • CALG_MD2
  • CALG_MD4
  • CALG_MD5
  • CALG_NO_SIGN
  • CALG_OID_INFO_CNG_ONLY
  • CALG_OID_INFO_PARAMETERS
  • CALG_PCT1_MASTER
  • CALG_RC2
  • CALG_RC4
  • CALG_RC5
  • CALG_RSA_KEYX
  • CALG_RSA_SIGN
  • CALG_SCHANNEL_ENC_KEY
  • CALG_SCHANNEL_MAC_KEY
  • CALG_SCHANNEL_MASTER_HASH
  • CALG_SEAL
  • CALG_SHA
  • CALG_SHA1
  • CALG_SHA_256
  • CALG_SHA_384
  • CALG_SHA_512
  • CALG_SKIPJACK
  • CALG_SSL2_MASTER
  • CALG_SSL3_MASTER
  • CALG_SSL3_SHAMD5
  • CALG_TEK
  • CALG_TLS1_MASTER
  • CALG_TLS1PRF
Example values when UseInternalSecurityAPI is True:
obj.config("SSLEnabledCipherSuites=*");
obj.config("SSLEnabledCipherSuites=TLS_DHE_DSS_WITH_AES_128_CBC_SHA");
obj.config("SSLEnabledCipherSuites=TLS_DHE_DSS_WITH_AES_128_CBC_SHA;TLS_DH_ANON_WITH_AES_128_CBC_SHA");
Possible values when UseInternalSecurityAPI is True include:
  • TLS_DHE_DSS_WITH_AES_128_GCM_SHA256
  • TLS_DHE_DSS_WITH_AES_256_GCM_SHA384
  • TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
  • TLS_DHE_DSS_WITH_AES_256_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
  • TLS_DHE_DSS_WITH_DES_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
  • TLS_DHE_RSA_WITH_DES_CBC_SHA
  • TLS_RSA_WITH_AES_256_GCM_SHA384
  • TLS_RSA_WITH_AES_128_GCM_SHA256
  • TLS_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA256
  • TLS_RSA_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_AES_256_CBC_SHA256
  • TLS_RSA_WITH_DES_CBC_SHA
  • TLS_RSA_WITH_RC4_128_MD5
  • TLS_RSA_WITH_RC4_128_SHA
  • TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
  • TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA
  • TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
  • TLS_ECDH_RSA_WITH_AES_256_CBC_SHA
  • TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

When TLS 1.3 is negotiated (see SSLEnabledProtocols) only the following cipher suites are supported:

  • TLS_AES_128_GCM_SHA256
  • TLS_AES_256_GCM_SHA384
  • TLS_CHACHA20_POLY1305_SHA256

SSLEnabledCipherSuites is used together with SSLCipherStrength.

TLS12SignatureAlgorithms:   Defines the allowed TLS 1.2 signature algorithms when UseInternalSecurityAPI is True.

This setting specifies the allowed server certificate signature algorithms when UseInternalSecurityAPI is True and SSLEnabledProtocols is set to allow TLS 1.2.

When specified the component will verify that the server certificate signature algorithm is among the values specified in this setting. If the server certificate signature algorithm is unsupported the component throws an exception.

The format of this value is a comma separated list of hash-signature combinations. For instance:

IPPort.Config("UseInternalSecurityAPI=true");
IPPort.Config("SSLEnabledProtocols=3072"); //TLS 1.2
IPPort.Config("TLS12SignatureAlgorithms=sha1-rsa,sha1-dsa,sha256-rsa,sha256-dsa");
The default value for this setting is "sha1-rsa,sha1-dsa,sha224-rsa,sha224-dsa,sha256-rsa,sha256-dsa,sha384-rsa,sha384-dsa,sha512-rsa,sha512-dsa".

In order to not restrict the server's certificate signature algorithm, specify an empty string as the value for this setting, which will cause the signature_algorithms TLS 1.2 extension to not be sent.

TLS12SupportedGroups:   The supported groups for ECC.

This setting specifies a comma separated list of named groups used in TLS 1.2 for ECC.

The default value is ecdhe_secp256r1,ecdhe_secp384r1,ecdhe_secp521r1.

When using TLS 1.2 and UseInternalSecurityAPI is set to True, the values refer to the supported groups for ECC. The following values are supported:

  • "ecdhe_secp256r1" (default)
  • "ecdhe_secp384r1" (default)
  • "ecdhe_secp521r1" (default)

TLS13KeyShareGroups:   The groups for which to pregenerate key shares.

This setting specifies a comma separated list of named groups used in TLS 1.3 for key exchange. The groups specified here will have key share data pregenerated locally before establishing a connection. This can prevent an additional round trip during the handshake if the group is supported by the server.

The default value is set to balance common supported groups and the computational resources required to generate key shares. As a result only some groups are included by default in this setting.

Note: All supported groups can always be used during the handshake even if not listed here, but if a group is used which is not present in this list it will incur an additional round trip and time to generate the key share for that group.

In most cases this setting does not need to be modified. This should only be modified if there is a specific reason to do so.

The default value is ecdhe_secp256r1,ecdhe_secp384r1,ffdhe_2048,ffdhe_3072

The values are ordered from most preferred to least preferred. The following values are supported:

  • "ecdhe_secp256r1" (default)
  • "ecdhe_secp384r1" (default)
  • "ecdhe_secp521r1"
  • "ffdhe_2048" (default)
  • "ffdhe_3072" (default)
  • "ffdhe_4096"
  • "ffdhe_6144"
  • "ffdhe_8192"

TLS13SupportedGroups:   The supported groups for (EC)DHE key exchange.

This setting specifies a comma separated list of named groups used in TLS 1.3 for key exchange. This setting should only be modified if there is a specific reason to do so.

The default value is ecdhe_secp256r1,ecdhe_secp384r1,ecdhe_secp521r1,ffdhe_2048,ffdhe_3072,ffdhe_4096,ffdhe_6144,ffdhe_8192

The values are ordered from most preferred to least preferred. The following values are supported:

  • "ecdhe_secp256r1" (default)
  • "ecdhe_secp384r1" (default)
  • "ecdhe_secp521r1" (default)
  • "ffdhe_2048" (default)
  • "ffdhe_3072" (default)
  • "ffdhe_4096" (default)
  • "ffdhe_6144" (default)
  • "ffdhe_8192" (default)

TLS13SignatureAlgorithms:   The allowed certificate signature algorithms.

This setting holds a comma separated list of allowed signature algorithms. Possible values are:

  • "ecdsa_secp256r1_sha256" (default)
  • "ecdsa_secp384r1_sha384" (default)
  • "ecdsa_secp521r1_sha512" (default)
  • "rsa_pkcs1_sha256" (default)
  • "rsa_pkcs1_sha384" (default)
  • "rsa_pkcs1_sha512" (default)
  • "rsa_pss_sha256" (default)
  • "rsa_pss_sha384" (default)
  • "rsa_pss_sha512" (default)
The default value is rsa_pss_sha256,rsa_pss_sha384,rsa_pss_sha512,rsa_pkcs1_sha256,rsa_pkcs1_sha384,rsa_pkcs1_sha512,ecdsa_secp256r1_sha256,ecdsa_secp384r1_sha384,ecdsa_secp521r1_sha512. This setting is only applicable when SSLEnabledProtocols includes TLS 1.3.

Socket Configuration Settings

AbsoluteTimeout:   Determines whether timeouts are inactivity timeouts or absolute timeouts.

If AbsoluteTimeout is set to True, any method which does not complete within Timeout seconds will be aborted. By default, AbsoluteTimeout is False, and the timeout is an inactivity timeout.

Note: This option is not valid for UDP ports.

FirewallData:   Used to send extra data to the firewall.

When the firewall is a tunneling proxy, use this property to send custom (additional) headers to the firewall (e.g. headers for custom authentication schemes).

InBufferSize:   The size in bytes of the incoming queue of the socket.

This is the size of an internal queue in the TCP/IP stack. You can increase or decrease its size depending on the amount of data that you will be receiving. Increasing the value of the InBufferSize setting can provide significant improvements in performance in some cases.

Some TCP/IP implementations do not support variable buffer sizes. If that is the case, when the component is activated the InBufferSize reverts to its defined size. The same happens if you attempt to make it too large or too small.

OutBufferSize:   The size in bytes of the outgoing queue of the socket.

This is the size of an internal queue in the TCP/IP stack. You can increase or decrease its size depending on the amount of data that you will be sending. Increasing the value of the OutBufferSize setting can provide significant improvements in performance in some cases.

Some TCP/IP implementations do not support variable buffer sizes. If that is the case, when the component is activated the OutBufferSize reverts to its defined size. The same happens if you attempt to make it too large or too small.

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 7311]