TSYSECommerce Component
Properties Methods Events Config Settings Errors
The TSYSECommerce component is an advanced tool used to authorize credit cards in both Mail Order (Direct Marketing) and eCommerce environments, where the customer is ordering products or services via the telephone or Internet. This component makes authorizing these types of transactions very easy.
Syntax
DPayments.DPaymentsSDK.TSYSECommerce
Remarks
This component allows for simple, direct, secure connection to the Vital/TSYS TLS/SSL gateway through a standard Internet connection. This component can be integrated into web pages or stand-alone Point Of Sale applications. Because all TLS/SSL communications are handled inside the component, any application or web page can be deployed without the need for expensive dedicated TLS/SSL servers.
The TSYSECommerce component makes authorizing Card-Not-Present Mail Order and E-Commerce transactions very easy by adding an additional layer of abstraction between the programmer and the protocol. There is no need to deal with raw sockets, TLS/SSL handshakes, or data packet formatting. The steps to setting up the component and authorizing a transaction are outlined below:
First, set the merchant properties with setup information acquired from your member bank or processor. For instance:
component.MerchantBankId = "999995" '(BIN number)
component.MerchantCategoryCode = "5999"
component.MerchantName = "test merchant"
component.MerchantNumber = "123456789012"
component.MerchantServiceNumber = "800-1234567"
component.MerchantState = "CA"
component.MerchantStoreNumber = "5999"
component.MerchantTerminalNumber = "1515"
component.MerchantZip = "90210"
Then, set the customer's credit card information, as well as his address and zip code (the address and zip code will be checked by the Vital/TSYS servers to make sure it matches the customer's billing address).
component.CardNumber = "4444333322221111"
component.CardExpMonth = 1
component.CardExpYear = 2009
component.CardCVVData = "999"
component.CustomerAddress = "8320 South Hardy Dr."
component.CustomerZip = "85284"
Next, set properties that contain details about the transaction. At the minimum, you must set a TransactionAmount and TransactionNumber. However, you may also set the TransactionType if you are doing a Mail Order or Recurring transaction.
component.TransactionAmount = "100"
component.TransactionNumber = 1
component.TransactionType = ttECommerce
Finally, submit the transaction by calling the Authorize method. The component receives a response from the Vital/TSYS servers, the result of the authorization will be displayed in several Response properties. The Code indicates whether the transaction was approved, and the AVSResult indicates whether the customer's billing address on file with his credit card company matches the information presented in the CustomerAddress and CustomerZip properties. The remaining properties provide additional information about the transaction.
Once an authorization request is approved, the money in the customer's account is blocked and tagged for the merchant. This transaction must go through the Batch Settlement process in order for the blocked money to be transferred to the merchant account. This is done by passing the XML aggregate returned from the GetDetailAggregate method to the TSYSSettle component. Usually, a Batch Settlement of all authorized transactions is done at the end of each business day.
Note: The TSYSECommerce component can be used to pass 3D-Secure and MasterCard SecureCode authentication data in an authorization to achieve a better interchange rate. To send this data, the ECI, XID and CAVV (3D-Secure), UCAFIndicator, UCAFSecurityIndicator and UCAFData (MasterCard SecureCode) configuration variables must be set before calling Authorize. The CAVV and UCAF authentication result code will be returned in the ResponseCAVV and ResponseUCAF configuration settings, respectively. For Mastercard Identity Check transactions you must set the ProgramProtocol and DirectoryServerTxnID configs.
Further Note: When sending e-commerce transactions, you must send a PurchaseIdentifier (sometimes referred to as Invoice Number) in the settlement. This can be done via the PurchaseIdentifier property of the TSYSDetailRecord component. Failure to set a PurchaseIdentifier for the e-commerce Industry Type may result in a CPS downgrade when the transaction is settled, and can cause higher interchange rates.
Property List
The following is the full list of the properties of the component with short descriptions. Click on the links for further details.
Card | Contains the customer's credit card information. |
CustomerAddress | The customer's billing address. |
CustomerZip | Customer's zip code (or postal code if outside of the USA). |
GoodsIndicator | Used to identify the type of goods purchased over the Internet. |
Merchant | Contains the merchant's setup information. |
Response | Contains the response to an authorization request. |
SSLAcceptServerCert | Instructs the component to unconditionally accept the server certificate that matches the supplied certificate. |
SSLCert | The certificate to be used during Secure Sockets Layer (SSL) negotiation. |
SSLProvider | The Secure Sockets Layer/Transport Layer Security (SSL/TLS) implementation to use. |
SSLServerCert | The server certificate for the last established connection. |
Timeout | A timeout for the component. |
TransactionAmount | Purchase amount to be authorized. |
TransactionNumber | Sequence number of this transaction. |
TransactionType | Specifies the type of transaction to process. |
VisaMVV | The Merchant Verification Value (MVV) is used by Visa to determine a merchant's eligibility to participate in a Select Merchant Fee (SMF) program. |
Method List
The following is the full list of the methods of the component with short descriptions. Click on the links for further details.
AuthenticateCard | Determines only if a card has been lost or stolen. |
Authorize | Sends an authorization request. |
Config | Sets or retrieves a configuration setting. |
GetDetailAggregate | Returns an aggregate containing details of this transaction, which is then used for settlement. |
Interrupt | Interrupts the current action. |
Reset | Clears all properties to their default values. |
Event List
The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.
Connected | Fired immediately after a connection completes (or fails). |
DataPacketIn | Fired when receiving a data packet from the transaction server. |
DataPacketOut | Fired when sending a data packet to the transaction server. |
Disconnected | Fired when a connection is closed. |
Error | Information about errors during data delivery. |
Response | Used with Interleaved Transaction Mode |
SSLServerAuthentication | Fired after the server presents its certificate to the client. |
SSLStatus | Fired when secure connection progress messages are available. |
Config Settings
The following is a list of config settings for the component with short descriptions. Click on the links for further details.
AcceptanceDeviceType | Identifies the type of device used to accept mobile Point of Sale (mPOS) transactions. |
ACI | Requested Authorization Characteristics Indicator (ACI). |
ActivateTerminal | Authenticates a POS device with TSYS. |
AllowPartialAuths | Indicates whether partial authorizations are to be supported. |
AmexAggregatorName | Amex Payment Service Provider/Aggregator Name. |
AmexAirlinePassengerData | Used by Merchants that are in the airline industry to submit information for Passenger Transport transactions. |
AmexCNPInternetPhoneData | Used by Merchants in mail-, telephone- and internet-order industries to submit additional data for Card Not Present transactions. |
AmexCPGoodsSoldData | Identifies merchandise such as gift cards, computers, and other electronics that can be resold for cash. |
AuthenticationCode | An alphanumeric code provided to the POS user for input when authenticating a POS device. |
AuthorizationIndicator | The type of authorization request. |
BusinessApplicationId | Business Application Identifier (BAI). Visa only. |
CanadaDomesticIndicator | Canada Domestic Indicator. |
CardholderId | Specifies the method used to verify the identity of the cardholder. |
CAVV | AuthenticationCAVV data from the ThreeDSecure component. |
CITMITIndicator | CIT/MIT Indicator. |
CountryCode | Identifies the country where the merchant is located. |
CumulativeAmount | Total cumulative authorized amount for series of Incremental authorization transactions (Visa and Discover only). |
CurrencyCode | Identifies the type of currency used by the merchant. |
CurrentPendingResponseCount | Current number of pending response packets. |
DeactivateTerminal | Deactivates a POS device with TSYS. |
DigitalPaymentCryptogram | Digital Payment Cryptogram used for DSRP transactions (Mastercard only). |
DirectoryServerTxnID | Directory Server Transaction ID generated by the EMV 3DS Mastercard Directory Server during authentication (Mastercard only). |
DisconnectInterleaved | To explicitly terminate the connection. |
DoEvents | Processes events from the internal message queue. |
ECI | Electronic Commerce Indicator. |
GatewayID | A unique value to identify a Gateway or Aggregator. |
GenKey | A randomly generated string of alphanumeric characters identifying the terminal. |
HeartlandDeviceId | Specifies a device ID to uniquely identify each terminal (card data entry device). |
HeartlandEncryptionMode | Specifies the encryption mode to use in Heartland transactions. |
HeartlandKeyBlock | Specifies the key block used to encrypt the data. |
IncrementalApprovalCode | Transaction Approval Code associated with authorization to increment. |
IncrementalRetrievalNumber | Transaction Retrieval Number associated with authorization to increment. |
IncrementalTransDate | Transaction Date associated with authorization to increment. |
IncrementalTransId | Transaction Id associated with authorization to increment. |
IncrementalTransTime | Transaction Time associated with authorization to increment. |
InstallmentCount | Total number of recurring or installment payments. |
InstallmentNumber | Current installment number. |
InterleavedMode | Determines whether to use Interleaved Transaction Mode for authorization requests. |
InterleavedTimeout | Timeout value to wait for a response from TSYS. |
IsBillPayment | Indicates that the transaction is a bill payment transaction. |
IsEstimatedAmount | Specifies whether the amount is an estimate. Visa transactions only. |
IsMerchantInitiatedTransaction | Set this to process a Merchant Initiated transaction. |
ISOIdentifier | ISO (Independent Sales Organization) Identifier assigned by MasterCard or Discover. |
IsPassengerTransport | Indicates that the transaction is a passenger transport transaction. |
IsPurchaseReturnAuthorization | Set this to process a Purchase Return Authorization transaction. |
LocationDetailAddress | Merchant's street address. |
LocationDetailCity | Name of the city. |
LocationDetailCountry | Country code. |
LocationDetailEmail | Merchant's e-mail adress. |
LocationDetailName | Merchant name. |
LocationDetailPhone | Merchant's phone number. |
LocationDetailPostal | Postal code. |
LocationDetailRegion | Region code that corresponds to the state, province, or other country subdivision. |
MastercardWalletId | Mastercard Wallet Identifier used to identify the Wallet Provider. |
MaxPendingResponseCount | Maximum number of pending response packets. |
MerchantLanguage | Designates the language that response messages will be returned in. |
MerchantSellerID | Merchant's Seller ID. |
MessageReasonCode | Code used to identify MIT or Deferred Authorizations for Visa. |
MITTransactionId | Transaction Id associated with the original authorization of a Merchant Initiated Transaction. |
MPGID | Merchant Payment Gateway ID. |
OriginalAmount | The Original Amount related to a previous Consumer Initiated Transaction (Discover only). |
OriginalAmountAccountType | The Account Type of the Original Amount (Discover only). |
PFAcquirerInternalReferenceNumber | Acquirer Internal Reference Number (AIRN) (Discover only). |
PFForeignRetailerIndicator | The Payment Facilitator Foreign Retailer Indicator (Visa only). |
PFIdentifier | The Payment Facilitator/Marketplace Identifier assigned by Visa, MasterCard, or Discover. |
PFNameSubMerchantName | The Payment Facilitator Name*Sub-Merchant name. |
PFSubMerchantCity | The Payment Facilitator Sub-Merchant City. |
PFSubMerchantCountry | The Payment Facilitator Sub-Merchant Country Code. |
PFSubMerchantIdentifier | The Payment Facilitator Sub-Merchant Identifier. |
PFSubMerchantPostalCode | The Payment Facilitator Sub-Merchant Postal Code. |
PFSubMerchantState | The Payment Facilitator Sub-Merchant State/Province Code. |
Port | The port to which transactions are posted. |
POSDataCode | Specifies the condition of the POS device used at the time of the transaction. |
POSEnvironmentIndicator | Provides additional information about the transaction for Visa. |
Processor | Specifies the Processor you are connecting to. |
ProgramProtocol | Identifies the version of the EMV 3D-Secure protocol (Mastercard only). |
PurchaseIdentifier | Optional purchase order number assigned by the merchant. |
RegisteredUserLastProfileDateChange | Registered User Last Profile Date Change (in DDMMYYYY format). Discover, Diners, JCB, and CUP only. |
RequestToken | Indicates whether to request a token for the specified card data sent in an Authorize request. |
ResponseCardholderVerification | Verification results for cardholder identification data (extended AVS). |
ResponseCAVV | Used for 3D-Secure transactions. Indicates whether the submitted CAVV value passed validation. |
ResponseMerchantAdviceCode | The Merchant Advice Code returned by Mastercard MIP for declined CNP transactions. |
ResponseStoreNumber | Check this field against the original Merchant StoreNumber. |
ResponseTerminalNumber | Check this field against the original Merchant TerminalNumber. |
ResponseTokenPAN | Card Brand Token PAN Last 4 Digits returned in the response. |
ResponseTokenStatus | The status of retrieval of the token. |
ResponseTransactionIntegrityClass | A 2-character value returned in the response of MasterCard Credit transactions to identify the transaction integrity class. |
ResponseUCAF | Used for MasterCard SecureCode transactions to indicate whether MasterCard downgraded the SecureCode transaction and sent it to the Issuer. |
RetrieveToken | Sends a Token Only request. |
Retry | Set this to retry a failed transaction. |
SendCommCardInd | Indicates whether to send Commercial Card Request Indicator. |
SendExtendedAVS | Specifies whether to send extended AVS data. |
Server | The server to which transactions are posted. |
ServiceLocationCity | Name of the city where the cardholder received the services. |
ServiceLocationCoordinates | Geographic Coordinates of the location where the cardholder received services. |
ServiceLocationCountryCode | Country code where the cardholder received the services. |
ServiceLocationCountrySubdivision | Region code that corresponds to the state, province, or other country subdivision. |
ServiceLocationPostalCode | Postal code where the cardholder received the services. |
SpecialConditionIndicator | Describes selected special conditions at the POS. |
SurchargeAmount | The transaction fee amount charged to the customer to account for acquirer-assessed surcharge. |
TLID | Transaction Link Identifier. |
Token | The token received from the TSYS host when a token request is sent. |
TokenRequestorID | Card brand Token Requestor ID assigned by the token service provider. |
TransactionStatus | A 1-character value used to indicate the purpose or status of the request. |
TsysETB | The Encryption Transmission Block TSYS uses to decrypt encrypted data. |
UCAFData | UCAF Authentication data from the MasterCard SecureCode authentication. |
UCAFIndicator | Indicates the merchant's support and usage of UCAF in MasterCard SecureCode transactions. |
UCAFSecurityIndicator | Indicates the security level and cardholder authentication in MasterCard SecureCode transactions. |
XID | TransactionId from a 3D Secure authentication. |
CloseStreamAfterTransfer | If true, the component will close the upload or download stream after the transfer. |
ConnectionTimeout | Sets a separate timeout value for establishing a connection. |
FirewallAutoDetect | Tells the component whether or not to automatically detect and use firewall system settings, if available. |
FirewallHost | Name or IP address of firewall (optional). |
FirewallListener | If true, the component binds to a SOCKS firewall as a server (TCPClient only). |
FirewallPassword | Password to be used if authentication is to be used when connecting through the firewall. |
FirewallPort | The TCP port for the FirewallHost;. |
FirewallType | Determines the type of firewall to connect through. |
FirewallUser | A user name if authentication is to be used connecting through a firewall. |
KeepAliveInterval | The retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received. |
KeepAliveTime | The inactivity time in milliseconds before a TCP keep-alive packet is sent. |
Linger | When set to True, connections are terminated gracefully. |
LingerTime | Time in seconds to have the connection linger. |
LocalHost | The name of the local host through which connections are initiated or accepted. |
LocalPort | The port in the local host where the component binds. |
MaxLineLength | The maximum amount of data to accumulate when no EOL is found. |
MaxTransferRate | The transfer rate limit in bytes per second. |
ProxyExceptionsList | A semicolon separated list of hosts and IPs to bypass when using a proxy. |
TCPKeepAlive | Determines whether or not the keep alive socket option is enabled. |
TcpNoDelay | Whether or not to delay when sending packets. |
UseIPv6 | Whether to use IPv6. |
UseNTLMv2 | Whether to use NTLM V2. |
CACertFilePaths | The paths to CA certificate files when using Mono on Unix/Linux. |
LogSSLPackets | Controls whether SSL packets are logged when using the internal security API. |
ReuseSSLSession | Determines if the SSL session is reused. |
SSLCACerts | A newline separated list of CA certificates to be included when performing an SSL handshake. |
SSLCheckCRL | Whether to check the Certificate Revocation List for the server certificate. |
SSLCheckOCSP | Whether to use OCSP to check the status of the server certificate. |
SSLCipherStrength | The minimum cipher strength used for bulk encryption. |
SSLClientCACerts | A newline separated list of CA certificates to use during SSL client certificate validation. |
SSLEnabledCipherSuites | The cipher suite to be used in an SSL negotiation. |
SSLEnabledProtocols | Used to enable/disable the supported security protocols. |
SSLEnableRenegotiation | Whether the renegotiation_info SSL extension is supported. |
SSLIncludeCertChain | Whether the entire certificate chain is included in the SSLServerAuthentication event. |
SSLKeyLogFile | The location of a file where per-session secrets are written for debugging purposes. |
SSLNegotiatedCipher | Returns the negotiated cipher suite. |
SSLNegotiatedCipherStrength | Returns the negotiated cipher suite strength. |
SSLNegotiatedCipherSuite | Returns the negotiated cipher suite. |
SSLNegotiatedKeyExchange | Returns the negotiated key exchange algorithm. |
SSLNegotiatedKeyExchangeStrength | Returns the negotiated key exchange algorithm strength. |
SSLNegotiatedVersion | Returns the negotiated protocol version. |
SSLSecurityFlags | Flags that control certificate verification. |
SSLServerCACerts | A newline separated list of CA certificates to use during SSL server certificate validation. |
TLS12SignatureAlgorithms | Defines the allowed TLS 1.2 signature algorithms when SSLProvider is set to Internal. |
TLS12SupportedGroups | The supported groups for ECC. |
TLS13KeyShareGroups | The groups for which to pregenerate key shares. |
TLS13SignatureAlgorithms | The allowed certificate signature algorithms. |
TLS13SupportedGroups | The supported groups for (EC)DHE key exchange. |
AbsoluteTimeout | Determines whether timeouts are inactivity timeouts or absolute timeouts. |
FirewallData | Used to send extra data to the firewall. |
InBufferSize | The size in bytes of the incoming queue of the socket. |
OutBufferSize | The size in bytes of the outgoing queue of the socket. |
BuildInfo | Information about the product's build. |
GUIAvailable | Whether or not a message loop is available for processing events. |
LicenseInfo | Information about the current license. |
MaskSensitiveData | Whether sensitive data is masked in log messages. |
UseInternalSecurityAPI | Whether or not to use the system security libraries or an internal implementation. |
Card Property (TSYSECommerce Component)
Contains the customer's credit card information.
Syntax
Remarks
This must be set to an instance of the CCCard type, which will contain information about the credit card to be charged. This may include a MagneticStripe for swiped cards, or a Number, ExpMonth, and ExpYear for manually entered cards. (EntryDataSource indicates which set of properties will be used). See the CCCard type for more information.
Note that only manually-entered card data is acceptable for this component. Setting the MagneticStripe or setting EntryDataSource to anything but dsManualEntryNoCardreader will cause the component to throws an exception.
This property is not available at design time.
Please refer to the CCCard type for a complete list of fields.CustomerAddress Property (TSYSECommerce Component)
The customer's billing address.
Syntax
Default Value
""
Remarks
This field is used as part of the Address Verification Service (AVS) and contains the customer's street address as it appears on their monthly statement. Only the street number, street name, and apartment number are required in this field. City and state are not included, and the zip code is set in the CustomerZip property.
This property is an alphanumeric field. Due to concerns with International addresses and changing specifications, the component does not do any processing on the address. The address will be included in the authorization request exactly as you set it.
Per TSYS specs, the following rules apply:
- In the address, numbers are not spelled out. "First Street" becomes "1ST Street," "Second" becomes "2ND," and so on.
- There must be a (space) between two consecutive data elements that are only numeric.
Note the following examples:
- "1234 56th Street" is equivalent to: "1234 56Street"
- "1234 56th Street" is NOT equivalent to: "123456Street" //do not strip all spaces between two numbers
- "1391 ELM STREET" is equivalent to: "1391ELMSTREET"
- "P.O. BOX 24356" is equivalent to: "POBOX24356"
The length of this property is 19 characters, and any string longer than this throws an exception. If the customer's address is much greater than the length of this field, it is admissible to include only the street number in this field.
CustomerZip Property (TSYSECommerce Component)
Customer's zip code (or postal code if outside of the USA).
Syntax
Default Value
""
Remarks
This field is used as part of the Address Verification Service (AVS). If the customer resides within the United States, this field should contain the five or nine digit zip code as it appears on the customer's monthly statement. If the customer's billing address is outside of the United States, this field should contain the customer's postal code.
This field is an alphanumeric field with a maximum length of nine characters. Spaces and dashes are automatically stripped when the property is set.
GoodsIndicator Property (TSYSECommerce Component)
Used to identify the type of goods purchased over the Internet.
Syntax
public TSYSECommerceGoodsIndicators GoodsIndicator { get; set; }
enum TSYSECommerceGoodsIndicators { tgiNotUsed, tgiDigitalGoods, tgiPhysicalGoods }
Public Property GoodsIndicator As TsysecommerceGoodsIndicators
Enum TSYSECommerceGoodsIndicators tgiNotUsed tgiDigitalGoods tgiPhysicalGoods End Enum
Default Value
0
Remarks
This property is used to identify the type of goods purchased over the Internet. Supported types are shown below.
tgiNotUsed (0) | GoodsIndicator is not used. |
tgiDigitalGoods (1) | Customer purchased digital goods (for instance, an application that was electronically delivered). |
tgiPhysicalGoods (2) | Customer purchased actual physical goods, which were then shipped to the customer. |
Note: This property is not actually used in the authorization, but will be contained in the aggregate returned from the GetDetailAggregate method. This property is only valid if the TransactionType is set to ttECommerce.
Merchant Property (TSYSECommerce Component)
Contains the merchant's setup information.
Syntax
public TSYSMerchant Merchant { get; set; }
Public Property Merchant As TSYSMerchant
Remarks
This property must be set to an instance of the TSYSMerchant type, which will contain information to identify the merchant to the TSYS processing server. Please see the TSYSMerchant type for a list of available fields.
Please refer to the TSYSMerchant type for a complete list of fields.Response Property (TSYSECommerce Component)
Contains the response to an authorization request.
Syntax
public TSYSResponse Response { get; }
Public ReadOnly Property Response As TSYSResponse
Remarks
This property will contain the response returned from the TSYS server. It should be inspected (and logged) after an authorization to determine if the transaction was approved. The TSYSResponse type contains the following fields:
ApprovalCode | Contains an authorization code for approved transactions, or a description of the error for declines. |
AuthorizedAmount | Amount actually used from the card (used when supporting partial redemptions). |
AuthSource | Indicates the source of the authorization code stored in ApprovalCode. |
AVSResult | Contains the Address Verification System result code. |
CardLevel | This field contains a two-character code created by Visa during the authorization process. |
Code | Indicates the status of the authorization request. |
CommercialCardType | Indicates whether the credit card charged is a corporate commercial card (and if so the type of commercial card). |
CVVResult | Contains the returned CVV result code (if CVV data was sent in the request). |
RetrievalNumber | This number is to be used to identify transactions and should be submitted when making adjustments, reversals or at settlement. |
ReturnedACI | Returned Authorization Characteristics Indicator contains CPS qualification status. |
Text | Text information that describes each response code. |
TransactionDate | Local transaction date returned from the server in MMDDYY format. |
TransactionId | Contains the Transaction Identifier or MasterCard Reference Number. |
TransactionNumber | Check this field against the TransactionNumber sent in the authorization. |
TransactionTime | Local transaction time returned from the server in HHMMSS format. |
ValidationCode | Additional information generated by the card issuer. |
This property is read-only.
Please refer to the TSYSResponse type for a complete list of fields.SSLAcceptServerCert Property (TSYSECommerce Component)
Instructs the component to unconditionally accept the server certificate that matches the supplied certificate.
Syntax
public Certificate SSLAcceptServerCert { get; set; }
Public Property SSLAcceptServerCert As Certificate
Remarks
If it finds any issues with the certificate presented by the server, the component will normally terminate the connection with an error.
You may override this behavior by supplying a value for SSLAcceptServerCert. If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.
Note: This functionality is provided only for cases in which you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.
Please refer to the Certificate type for a complete list of fields.SSLCert Property (TSYSECommerce Component)
The certificate to be used during Secure Sockets Layer (SSL) negotiation.
Syntax
public Certificate SSLCert { get; set; }
Public Property SSLCert As Certificate
Remarks
This property includes the digital certificate that the component will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the Encoded field to the encoded certificate. To select a certificate, use the store and subject fields.
Please refer to the Certificate type for a complete list of fields.SSLProvider Property (TSYSECommerce Component)
The Secure Sockets Layer/Transport Layer Security (SSL/TLS) implementation to use.
Syntax
public TSYSECommerceSSLProviders SSLProvider { get; set; }
enum TSYSECommerceSSLProviders { sslpAutomatic, sslpPlatform, sslpInternal }
Public Property SSLProvider As TsysecommerceSSLProviders
Enum TSYSECommerceSSLProviders sslpAutomatic sslpPlatform sslpInternal End Enum
Default Value
0
Remarks
This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic), the component will select whether to use the platform implementation or the internal implementation depending on the operating system as well as the TLS version being used.
Possible values are as follows:
0 (sslpAutomatic - default) | Automatically selects the appropriate implementation. |
1 (sslpPlatform) | Uses the platform/system implementation. |
2 (sslpInternal) | Uses the internal implementation. |
In most cases using the default value (Automatic) is recommended. The component will select a provider depending on the current platform.
When Automatic is selected, on Windows, the component will use the platform implementation. On Linux/macOS, the component will use the internal implementation. When TLS 1.3 is enabled via SSLEnabledProtocols, the internal implementation is used on all platforms.
The .NET Standard library will always use the internal implementation on all platforms.
SSLServerCert Property (TSYSECommerce Component)
The server certificate for the last established connection.
Syntax
public Certificate SSLServerCert { get; }
Public ReadOnly Property SSLServerCert As Certificate
Remarks
This property contains the server certificate for the last established connection.
SSLServerCert is reset every time a new connection is attempted.
This property is read-only.
Please refer to the Certificate type for a complete list of fields.Timeout Property (TSYSECommerce Component)
A timeout for the component.
Syntax
Default Value
30
Remarks
If Timeout is set to a positive value, and an operation cannot be completed immediately, the component will retry the operation for a maximum of Timeout seconds.
The default value for Timeout is 30 (seconds).
TransactionAmount Property (TSYSECommerce Component)
Purchase amount to be authorized.
Syntax
Default Value
""
Remarks
This field contains the transaction amount to be authorized.
This amount is to be presented with an implied decimal point. For example, US $10.00 must be represented as 1000, and $0.10 is likewise simply 10. The allowable number of significant digits as well as the positioning of any implied decimal point is dictated by the designated CurrencyCode configuration setting. In the United States (default), the number of allowable significant digits is seven. Thus the maximum TransactionAmount is "9999999", yielding a US dollar amount of $99,999.99. This field may not contain a negative number.
TransactionNumber Property (TSYSECommerce Component)
Sequence number of this transaction.
Syntax
Default Value
0
Remarks
This field contains a terminal-generated transaction sequence number to be submitted in all authorization request messages. This number is echoed back to the terminal in the TransactionNumber for the purpose of assisting in the matching of authorization request and response messages. This value must be in the range 0001 to 9999 and should be incremented on each authorization request message. This number should automatically increment from 9999 to 1. 0 is an invalid transaction number.
TransactionType Property (TSYSECommerce Component)
Specifies the type of transaction to process.
Syntax
public TSYSECommerceTransactionTypes TransactionType { get; set; }
enum TSYSECommerceTransactionTypes { dmtECommerce, dmtMOTO, dmtRecurring, dmtInstallment }
Public Property TransactionType As TsysecommerceTransactionTypes
Enum TSYSECommerceTransactionTypes dmtECommerce dmtMOTO dmtRecurring dmtInstallment End Enum
Default Value
0
Remarks
The following types of transactions are supported by this component:
dmtECommerce (0) | This is an E-Commerce transaction, and consists of goods or services sold online over the Internet. |
dmtMOTO (1) | This is a Mail Order or Telephone Order transaction, and consists of goods sold through the mail or over the phone. |
dmtRecurring (2) | This is a recurring payment, such as a magazine subscription or health club membership. |
dmtInstallment (3) | This is an installment payment. For example, "Three easy payments of $19.95". |
All of these transactions are card-not-present transactions. If you wish to authorize card-present transactions, you must use the TSYSRetail component.
To settle a transaction authorized with the ttInstallment TransactionType, you must specify the number of this installment and the total count of all installments to be made using TSYSECommerce component. For instance, if the purchase was for "Three easy payments of $19.95", and this is the first payment, then the installment number will be 1, and the installment count 3. An example is included below:
TSYSECommerce.TransactionType = ttInstallment
TSYSECommerce.TransactionAmount = "1995"
TSYSECommerce.Config("InstallmentCount=3")
TSYSECommerce.Config("InstallmentNumber=1")
TSYSECommerce.Authorize()
TSYSSettle.DetailAggregate[5] = TSYSECommerce.GetDetailAggregate()
VisaMVV Property (TSYSECommerce Component)
The Merchant Verification Value (MVV) is used by Visa to determine a merchant's eligibility to participate in a Select Merchant Fee (SMF) program.
Syntax
Default Value
""
Remarks
The maximum length of this property is 10 characters, and it may only contain 0-9 and A-F.
AuthenticateCard Method (TSYSECommerce Component)
Determines only if a card has been lost or stolen.
Syntax
public void AuthenticateCard();
Public Sub AuthenticateCard()
Remarks
This method does not send an authorization, but instead it sends an authentication request. If successful the Code will be "85". If the card is stolen or otherwise not normal, the Code and Text will indicate such. You may send AVS (CustomerAddress and CustomerZip) as well as CVVData, and the AVSResult and CVVResult will be returned as normal.
Authorize Method (TSYSECommerce Component)
Sends an authorization request.
Syntax
public void Authorize();
Public Sub Authorize()
Remarks
This method sends an authorization request to the Vital/TSYS transaction server. If the authorization request was successful, the Code property will contain "00" or "85".
An authorization blocks funds on the customer's credit card, but does not actually transfer funds. In order for funds to be transferred and the transaction completed, you must settle the transaction. To do this, you must pass an XML aggregate containing the results of the transaction to the Settlement component. For example:
TSYSECommerce.Authorize();
TSYSSettle.DetailRecords.Add(new TSYSRecordType(TSYSECommerce.GetDetailAggregate()));
Config Method (TSYSECommerce Component)
Sets or retrieves a configuration setting.
Syntax
Remarks
Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.
These 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.
To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).
To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.
GetDetailAggregate Method (TSYSECommerce Component)
Returns an aggregate containing details of this transaction, which is then used for settlement.
Syntax
Remarks
This method returns an aggregate containing all of the required data to send a transaction to settlement. This aggregate must be passed to the TSYSSettle component's DetailAggregate array property in order to settle the transaction. If you wish to view or change any part of the aggregate (such as adding a gratuity or additional info for an Installment payment), you may use the TSYSDetailRecord component to do so.
Note: This method may only be called after a successful authorization. If the authorization was not successful the method throws an exception.
An example of how this method is used is shown below:
TSYSRetail.Authorize()
TSYSSettle.DetailRecords.Add(new TSYSRecordType(TSYSRetail.GetDetailAggregate()));
Interrupt Method (TSYSECommerce Component)
Interrupts the current action.
Syntax
public void Interrupt();
Public Sub Interrupt()
Remarks
This method interrupts any processing that the component is currently executing.
Reset Method (TSYSECommerce Component)
Clears all properties to their default values.
Syntax
public void Reset();
Public Sub Reset()
Remarks
This method clears all properties to their default values.
Connected Event (TSYSECommerce Component)
Fired immediately after a connection completes (or fails).
Syntax
public event OnConnectedHandler OnConnected; public delegate void OnConnectedHandler(object sender, TSYSECommerceConnectedEventArgs e); public class TSYSECommerceConnectedEventArgs : EventArgs { public int StatusCode { get; } public string Description { get; } }
Public Event OnConnected As OnConnectedHandler Public Delegate Sub OnConnectedHandler(sender As Object, e As TSYSECommerceConnectedEventArgs) Public Class TSYSECommerceConnectedEventArgs Inherits EventArgs Public ReadOnly Property StatusCode As Integer Public ReadOnly Property Description As String End Class
Remarks
If the connection is made normally, StatusCode is 0, and Description is "OK".
If the connection fails, StatusCode has the error code returned by the TCP/IP stack. Description contains a description of this code. The value of StatusCode is equal to the value of the error.
Please refer to the Error Codes section for more information.
DataPacketIn Event (TSYSECommerce Component)
Fired when receiving a data packet from the transaction server.
Syntax
public event OnDataPacketInHandler OnDataPacketIn; public delegate void OnDataPacketInHandler(object sender, TSYSECommerceDataPacketInEventArgs e); public class TSYSECommerceDataPacketInEventArgs : EventArgs { public string DataPacket { get; }
public byte[] DataPacketB { get; } }
Public Event OnDataPacketIn As OnDataPacketInHandler Public Delegate Sub OnDataPacketInHandler(sender As Object, e As TSYSECommerceDataPacketInEventArgs) Public Class TSYSECommerceDataPacketInEventArgs Inherits EventArgs Public ReadOnly Property DataPacket As String
Public ReadOnly Property DataPacketB As Byte() End Class
Remarks
This event fires when a packet is received. The entire data packet (including all framing and error detection characters) is contained in the parameter "DataPacket". This parameter may be inspected for advanced troubleshooting, or to extract additional response properties beyond the scope of this component.
DataPacketOut Event (TSYSECommerce Component)
Fired when sending a data packet to the transaction server.
Syntax
public event OnDataPacketOutHandler OnDataPacketOut; public delegate void OnDataPacketOutHandler(object sender, TSYSECommerceDataPacketOutEventArgs e); public class TSYSECommerceDataPacketOutEventArgs : EventArgs { public string DataPacket { get; }
public byte[] DataPacketB { get; } }
Public Event OnDataPacketOut As OnDataPacketOutHandler Public Delegate Sub OnDataPacketOutHandler(sender As Object, e As TSYSECommerceDataPacketOutEventArgs) Public Class TSYSECommerceDataPacketOutEventArgs Inherits EventArgs Public ReadOnly Property DataPacket As String
Public ReadOnly Property DataPacketB As Byte() End Class
Remarks
This event fires right before each data packet is sent. The entire data packet (including all framing and error detection characters) is contained in the parameter "DataPacket". This parameter may be inspected for advanced troubleshooting, or may be modified to support additional features beyond the scope of this component.
Disconnected Event (TSYSECommerce Component)
Fired when a connection is closed.
Syntax
public event OnDisconnectedHandler OnDisconnected; public delegate void OnDisconnectedHandler(object sender, TSYSECommerceDisconnectedEventArgs e); public class TSYSECommerceDisconnectedEventArgs : EventArgs { public int StatusCode { get; } public string Description { get; } }
Public Event OnDisconnected As OnDisconnectedHandler Public Delegate Sub OnDisconnectedHandler(sender As Object, e As TSYSECommerceDisconnectedEventArgs) Public Class TSYSECommerceDisconnectedEventArgs Inherits EventArgs Public ReadOnly Property StatusCode As Integer Public ReadOnly Property Description As String End Class
Remarks
If the connection is broken normally, StatusCode is 0, and Description is "OK".
If the connection is broken for any other reason, StatusCode has the error code returned by Winsock. Description contains a description of this code. The value of StatusCode is equal to the value of the Winsock error.
Please refer to the Error Codes section for more information.
Error Event (TSYSECommerce Component)
Information about errors during data delivery.
Syntax
public event OnErrorHandler OnError; public delegate void OnErrorHandler(object sender, TSYSECommerceErrorEventArgs e); public class TSYSECommerceErrorEventArgs : EventArgs { public int ErrorCode { get; } public string Description { get; } }
Public Event OnError As OnErrorHandler Public Delegate Sub OnErrorHandler(sender As Object, e As TSYSECommerceErrorEventArgs) Public Class TSYSECommerceErrorEventArgs Inherits EventArgs Public ReadOnly Property ErrorCode As Integer Public ReadOnly Property Description As String End Class
Remarks
The Error event is fired in case of exceptional conditions during message processing.
ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.
Response Event (TSYSECommerce Component)
Used with Interleaved Transaction Mode
Syntax
public event OnResponseHandler OnResponse; public delegate void OnResponseHandler(object sender, TSYSECommerceResponseEventArgs e); public class TSYSECommerceResponseEventArgs : EventArgs { public string TransactionId { get; } public string ResponseCode { get; } public string ResponseText { get; } public string ResponseApprovalCode { get; } }
Public Event OnResponse As OnResponseHandler Public Delegate Sub OnResponseHandler(sender As Object, e As TSYSECommerceResponseEventArgs) Public Class TSYSECommerceResponseEventArgs Inherits EventArgs Public ReadOnly Property TransactionId As String Public ReadOnly Property ResponseCode As String Public ReadOnly Property ResponseText As String Public ReadOnly Property ResponseApprovalCode As String End Class
Remarks
When InterleavedMode configuration setting is set to True the component will send interleaved transactions without blocking and waiting for a response. For every response that the component receives from TSYS the Response event will fire. TransactionId parameter can be used to identify the transaction. ResponseCode and ResponseText can be used to determine if a transaction was approved or declined.
SSLServerAuthentication Event (TSYSECommerce Component)
Fired after the server presents its certificate to the client.
Syntax
public event OnSSLServerAuthenticationHandler OnSSLServerAuthentication; public delegate void OnSSLServerAuthenticationHandler(object sender, TSYSECommerceSSLServerAuthenticationEventArgs e); public class TSYSECommerceSSLServerAuthenticationEventArgs : EventArgs { public string CertEncoded { get; }
public byte[] CertEncodedB { get; } public string CertSubject { get; } public string CertIssuer { get; } public string Status { get; } public bool Accept { get; set; } }
Public Event OnSSLServerAuthentication As OnSSLServerAuthenticationHandler Public Delegate Sub OnSSLServerAuthenticationHandler(sender As Object, e As TSYSECommerceSSLServerAuthenticationEventArgs) Public Class TSYSECommerceSSLServerAuthenticationEventArgs Inherits EventArgs Public ReadOnly Property CertEncoded As String
Public ReadOnly Property CertEncodedB As Byte() Public ReadOnly Property CertSubject As String Public ReadOnly Property CertIssuer As String Public ReadOnly Property Status As String Public Property Accept As Boolean End Class
Remarks
During this event, the client can decide whether or not to continue with the connection process. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.
When Accept is False, Status shows why the verification failed (otherwise, Status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.
SSLStatus Event (TSYSECommerce Component)
Fired when secure connection progress messages are available.
Syntax
public event OnSSLStatusHandler OnSSLStatus; public delegate void OnSSLStatusHandler(object sender, TSYSECommerceSSLStatusEventArgs e); public class TSYSECommerceSSLStatusEventArgs : EventArgs { public string Message { get; } }
Public Event OnSSLStatus As OnSSLStatusHandler Public Delegate Sub OnSSLStatusHandler(sender As Object, e As TSYSECommerceSSLStatusEventArgs) Public Class TSYSECommerceSSLStatusEventArgs Inherits EventArgs Public ReadOnly Property Message As String End Class
Remarks
The event is fired for informational and logging purposes only. This event tracks the progress of the connection.
CCCard Type
Contains the customer's credit card information.
Remarks
This type contains the customer's credit card information. If you are processing transactions where the customer and his credit card are physically present, set the MagneticStripe field with the data read from the card reader. You may set either Track1 or Track2 data (but not both). You must also set the EntryDataSource to indicate which track is stored in the MagneticStripe field.
Example: Setting the Fields
CCCard card = new CCCard();
card.MagneticStripe = "B4012000033330026^FDMS TEST CARD /VISA^090410054321000000000000000 150 A";
card.EntryDataSource = edsTrack1;
Example: Using a Constructor
CCCard card = new CCCard("B4012000033330026^FDMS TEST CARD /VISA^090410054321000000000000000 150 A", edsTrack1);
If you are processing a transaction where the credit card is not physically present (eCommerce, mail/order, etc) or if the magstripe on the back of the card cannot be read by the card reader, you must set the Number, ExpMonth, and ExpYear fields, and EntryDataSource must be set to one of the manually entered enumerations.
Example: Setting the Fields
CCCard card = new CCCard();
card.Number = "4788250000028291";
card.ExpMonth = 12;
card.ExpYear = 2010;
card.EntryDataSource = edsManualEntryNoCardReader;
Example: Using a Constructor
CCCard card = new CCCard("4012000033330026", 04, 2009);
Note that the constructor in the previous example automatically sets the EntryDataSource to edsManualEntryNoCardReader. If you wish to set any
other value for the EntryDataSource, you must set it yourself before authorizing the transaction.
When authorizing a transaction, the fields used by the component are solely dependant on the value of EntryDataSource. If you set the Number, ExpMonth, and ExpYear fields, but EntryDataSource is set to edsTrack2, the component will look for MagneticStripe data when authorizing the transaction, and will throws an exception because none is present.
Fields
CardType
TCardTypes
Default: 0
Type of credit card being used in this transaction. This field contains the customer's credit card type. This is automatically computed after the Number is set, but it can also be changed manually. A list of valid card types is included below.
ctUnknown (0) | Invalid or unknown prefix, card type not known. |
ctVisa (1) | Visa or Delta Card. |
ctMasterCard (2) | MasterCard. |
ctAMEX (3) | American Express Card. |
ctDiscover (4) | Discover Card. |
ctDiners (5) | Diners Club or Carte Blanche Card. |
ctJCB (6) | JCB Card. |
ctVisaElectron (7) | Visa Electron Card (runs as a Visa for most gateways) |
ctMaestro (8) | Maestro Card |
ctLaser (10) | Laser Card (Ireland) |
CVVData
string
Default: ""
Three digit security code on back of card (optional).
This alphanumeric field contains the three digit Visa "Card Verification Value" (CVV), MasterCard "Card Verification Code" (CVC), or four-digit American Express "Card Identification Number" (CID). This value appears as additional characters embossed on the card signature line following the credit card account number on the back of the credit card. This is an optional field which can be used to determine if the customer is actually in possession of the credit card.
Even if the CVVData is incorrect, the transaction may still be authorized. It is up to the merchant to examine the ResponseCVVResult field and decide whether to honor the transaction or not.
Note: When set to a non-empty value, CVVPresence will be automatically set to cvpProvided. If set to empty string (""), CVVPresence will be automatically set to cvpNotProvided.
CVVPresence
CCCVVPresences
Default: 0
Indicates the presence of the card verification value.
This field is used to indicate the presence of CVVData.
The component will automatically set this value to cvpProvided when a CVVData value is specified. You can explicitly specify the CVVPresence indicator by setting this property.
Available values are:
- cvpNotProvided (0)
- cvpProvided (1)
- cvpIllegible (2)
- cvpNotOnCard (3)
EntryDataSource
EntryDataSources
Default: 0
This field contains a 1-character code identifying the source of the customer data. The table below shows all supported values for this field.
edsTrack1 (0) | Full Magnetic stripe read and transmit, Track 1. |
edsTrack2 (1) | Full magnetic stripe read and transmit, Track 2. |
edsManualEntryTrack1Capable (2) | Manually keyed, Track 1 capable. |
edsManualEntryTrack2Capable (3) | Manually keyed, Track 2 capable. |
edsManualEntryNoCardReader (4) | Manually keyed, terminal has no card reading capability (use this for e-commerce and MOTO transactions). |
edsTrack1Contactless (5) | Full magnetic stripe read (Track 1 only), Chip Card capable terminal (Visa, Mastercard, and JCB Transactions only). |
edsTrack2Contactless (6) | Full magnetic stripe read (Track 2 only), Chip Card capable terminal (Visa, Mastercard, and JCB Transactions only). |
edsManualEntryContactlessCapable (7) | Manually keyed, Chip Card read capable terminal (Visa, MasterCard, and JCB transactions only). |
edsIVR (8) | Interactive Voice Response processing. This is applicable to Mail Order/Telephone Order (MOTO) transactions. (Number, ExpMonth, and ExpYear are sent). |
edsKiosk (9) | Automated kiosk transaction. Track1 or Track2 data must be sent in MagneticStripe, the transaction cannot be manually entered. |
Below is a list of processors and their support EntryDataSource values:
FDMS - edsTrack1, edsTrack2, edsManualEntryTrack1Capable, edsManualEntryTrack2Capable, edsManualEntryNoCardReader, edsTrack1Contactless, edsTrack2Contactless, edsManualEntryContactlessCapable, edsIVR, edsKiosk
FDMSOmaha - All EntryDataSources applicable
FDMS Rapid Connect - All EntryDataSources applicable
Global - edsTrack1, edsTrack2, edsManualEntryTrack1Capable, edsManualEntryTrack2Capable, edsManualEntryNoCardReader, edsTrack1Contactless, edsTrack2Contactless, edsIVR, edsKiosk
PTech - edsTrack1, edsTrack2, edsManualEntryTrack1Capable, edsManualEntryTrack2Capable, edsManualEntryNoCardReader, edsTrack1Contactless, edsTrack2Contactless, edsManualEntryContactlessCapable
TSYS - edsTrack1, edsTrack2, edsManualEntryTrack1Capable, edsManualEntryTrack2Capable, edsManualEntryNoCardReader, edsTrack2Contactless, edsManualEntryContactlessCapable
TSYSHC - Values are based on Industry type.
TSYSHCBenefit | edsTrack2, edsManualEntryTrack1Capable, edsManualEntryTrack2Capable |
TSYSHCECommerce | edsManualEntryNoCardReader |
TSYSHCRetail | edsTrack1, edsTrack2, edsManualEntryTrack1Capable, edsManualEntryTrack2Capable, edsTrack1Contactless, edsTrack2Contactless, edsManualEntryContactlessCapable |
ExpMonth
int
Default: 1
Expiration month of the credit card specified in Number.
This field contains the expiration date of the customer's credit card, and must be in the range 1 - 12.
ExpYear
int
Default: 2000
Expiration year of the credit card specified in Number.
This field contains the expiration date of the customer's credit card. This field must be in the range 0 - 99, or 2000 - 2099. Any date before the year 2000 or after 2099 cannot be specified.
IsEncrypted
bool
Default: False
Determines whether data set to the Number or MagneticStripe fields is validated.
By default, when the Number or MagneticStripe fields are set, the value will be validated and normalized. For instance, "4444-33332222 1111" will be normalized as "4444333322221111" and MagneticStripe data will be parsed for the track specified by EntryDataSource. However, any other non-numerical data entered will cause an exception to be thrown. It may be useful in some gateways to send other data in the Number or MagneticStripe fields, and this can be accomplished by setting IsEncrypted to true. However, please note that in doing so automatic calculation of the CardType may be affected, and the card number will not be verified.
MagneticStripe
string
Default: ""
Track data read off of the card's magnetic stripe.
If EntryDataSource is not one of the manually entered enumerations, then this field must be set with the track1 or track2 data from the magnetic stripe on the back of the customer's credit card. This includes everything after but not including the start sentinel (% or ;) and up to but not including the end sentinel (?) and LRC check character. You may only set this field with track 1 or track 2 data, and may not pass both. Use the EntryDataSource field to indicate which track you are sending.
The following example shows how to set the MagneticStripe and EntryDataSource fields if the data read off the card is "%B4788250000028291^TSYS^05121015432112345678?;4788250000028291=05121015432112345678?"
component.Card = new CCCard("B4788250000028291^TSYS^05121015432112345678", dsTrack1)
or
component.Card = new CCCard("4788250000028291=05121015432112345678", dsTrack2)
or
CCCardType Card = new CCCard()
Card.MagneticStripe = "B4788250000028291^TSYS^05121015432112345678"
Card.EntryDataSource = dsTrack1
Industry regulations do not allow merchants or processors to store track data in any form of persistent storage. Failure to abide by this regulation can result in significant fines and other penalties.
Number
string
Default: ""
Customer's credit card number for the transaction.
If you're sending the transaction with MagneticStripe data, this field should be left empty.
Constructors
public CCCard(string magneticStripe, EntryDataSources entryDataSource);
Public CCCard(ByVal MagneticStripe As String, ByVal EntryDataSource As EntryDataSources)
Certificate Type
This is the digital certificate being used.
Remarks
This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.
- EffectiveDate
- ExpirationDate
- ExtendedKeyUsage
- Fingerprint
- FingerprintSHA1
- FingerprintSHA256
- Issuer
- PrivateKey
- PrivateKeyAvailable
- PrivateKeyContainer
- PublicKey
- PublicKeyAlgorithm
- PublicKeyLength
- SerialNumber
- SignatureAlgorithm
- Store
- StorePassword
- StoreType
- SubjectAltNames
- ThumbprintMD5
- ThumbprintSHA1
- ThumbprintSHA256
- Usage
- UsageFlags
- Version
- Subject
- Encoded
Fields
EffectiveDate
string (read-only)
Default: ""
The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:
23-Jan-2000 15:00:00.
ExpirationDate
string (read-only)
Default: ""
The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:
23-Jan-2001 15:00:00.
ExtendedKeyUsage
string (read-only)
Default: ""
A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).
Fingerprint
string (read-only)
Default: ""
The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.
The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02
FingerprintSHA1
string (read-only)
Default: ""
The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.
The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84
FingerprintSHA256
string (read-only)
Default: ""
The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.
The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53
Issuer
string (read-only)
Default: ""
The issuer of the certificate. This field contains a string representation of the name of the issuing authority for the certificate.
PrivateKey
string (read-only)
Default: ""
The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.
Note: The PrivateKey may be available but not exportable. In this case, PrivateKey returns an empty string.
PrivateKeyAvailable
bool (read-only)
Default: False
Whether a PrivateKey is available for the selected certificate. If PrivateKeyAvailable is True, the certificate may be used for authentication purposes (e.g., server authentication).
PrivateKeyContainer
string (read-only)
Default: ""
The name of the PrivateKey container for the certificate (if available). This functionality is available only on Windows platforms.
PublicKey
string (read-only)
Default: ""
The public key of the certificate. The key is provided as PEM/Base64-encoded data.
PublicKeyAlgorithm
string (read-only)
Default: ""
The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.
PublicKeyLength
int (read-only)
Default: 0
The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.
SerialNumber
string (read-only)
Default: ""
The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.
SignatureAlgorithm
string (read-only)
Default: ""
The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.
Store
string
Default: "MY"
The name of the certificate store for the client certificate.
The StoreType field denotes the type of the certificate store specified by Store. If the store is password-protected, specify the password in StorePassword.
Store is used in conjunction with the Subject field to specify client certificates. If Store has a value, and Subject or Encoded is set, a search for a certificate is initiated. Please see the Subject field for details.
Designations of certificate stores are platform dependent.
The following designations are the most common User and Machine certificate stores in Windows:
MY | A certificate store holding personal certificates with their associated private keys. |
CA | Certifying authority certificates. |
ROOT | Root certificates. |
When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).
StoreB
byte []
Default: "MY"
The name of the certificate store for the client certificate.
The StoreType field denotes the type of the certificate store specified by Store. If the store is password-protected, specify the password in StorePassword.
Store is used in conjunction with the Subject field to specify client certificates. If Store has a value, and Subject or Encoded is set, a search for a certificate is initiated. Please see the Subject field for details.
Designations of certificate stores are platform dependent.
The following designations are the most common User and Machine certificate stores in Windows:
MY | A certificate store holding personal certificates with their associated private keys. |
CA | Certifying authority certificates. |
ROOT | Root certificates. |
When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).
StorePassword
string
Default: ""
If the type of certificate store requires a password, this field is used to specify the password needed to open the certificate store.
StoreType
CertStoreTypes
Default: 0
The type of certificate store for this certificate.
The component supports both public and private keys in a variety of formats. When the cstAuto value is used, the component will automatically determine the type. This field can take one of the following values:
0 (cstUser - default) | For Windows, this specifies that the certificate store is a certificate store owned by the current user.
Note: This store type is not available in Java. |
1 (cstMachine) | For Windows, this specifies that the certificate store is a machine store.
Note: This store type is not available in Java. |
2 (cstPFXFile) | The certificate store is the name of a PFX (PKCS#12) file containing certificates. |
3 (cstPFXBlob) | The certificate store is a string (binary or Base64-encoded) representing a certificate store in PFX (PKCS#12) format. |
4 (cstJKSFile) | The certificate store is the name of a Java Key Store (JKS) file containing certificates.
Note: This store type is only available in Java. |
5 (cstJKSBlob) | The certificate store is a string (binary or Base64-encoded) representing a certificate store in Java Key Store (JKS) format.
Note: This store type is only available in Java. |
6 (cstPEMKeyFile) | The certificate store is the name of a PEM-encoded file that contains a private key and an optional certificate. |
7 (cstPEMKeyBlob) | The certificate store is a string (binary or Base64-encoded) that contains a private key and an optional certificate. |
8 (cstPublicKeyFile) | The certificate store is the name of a file that contains a PEM- or DER-encoded public key certificate. |
9 (cstPublicKeyBlob) | The certificate store is a string (binary or Base64-encoded) that contains a PEM- or DER-encoded public key certificate. |
10 (cstSSHPublicKeyBlob) | The certificate store is a string (binary or Base64-encoded) that contains an SSH-style public key. |
11 (cstP7BFile) | The certificate store is the name of a PKCS#7 file containing certificates. |
12 (cstP7BBlob) | The certificate store is a string (binary) representing a certificate store in PKCS#7 format. |
13 (cstSSHPublicKeyFile) | The certificate store is the name of a file that contains an SSH-style public key. |
14 (cstPPKFile) | The certificate store is the name of a file that contains a PPK (PuTTY Private Key). |
15 (cstPPKBlob) | The certificate store is a string (binary) that contains a PPK (PuTTY Private Key). |
16 (cstXMLFile) | The certificate store is the name of a file that contains a certificate in XML format. |
17 (cstXMLBlob) | The certificate store is a string that contains a certificate in XML format. |
18 (cstJWKFile) | The certificate store is the name of a file that contains a JWK (JSON Web Key). |
19 (cstJWKBlob) | The certificate store is a string that contains a JWK (JSON Web Key). |
21 (cstBCFKSFile) | The certificate store is the name of a file that contains a BCFKS (Bouncy Castle FIPS Key Store).
Note: This store type is only available in Java and .NET. |
22 (cstBCFKSBlob) | The certificate store is a string (binary or Base64-encoded) representing a certificate store in BCFKS (Bouncy Castle FIPS Key Store) format.
Note: This store type is only available in Java and .NET. |
23 (cstPKCS11) | The certificate is present on a physical security key accessible via a PKCS#11 interface.
To use a security key, the necessary data must first be collected using the CertMgr component. The ListStoreCertificates method may be called after setting CertStoreType to cstPKCS11, CertStorePassword to the PIN, and CertStore to the full path of the PKCS#11 DLL. The certificate information returned in the CertList event's CertEncoded parameter may be saved for later use. When using a certificate, pass the previously saved security key information as the Store and set StorePassword to the PIN. Code Example. SSH Authentication with Security Key:
|
99 (cstAuto) | The store type is automatically detected from the input data. This setting may be used with both public and private keys and can detect any of the supported formats automatically. |
SubjectAltNames
string (read-only)
Default: ""
Comma-separated lists of alternative subject names for the certificate.
ThumbprintMD5
string (read-only)
Default: ""
The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.
ThumbprintSHA1
string (read-only)
Default: ""
The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.
ThumbprintSHA256
string (read-only)
Default: ""
The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.
Usage
string (read-only)
Default: ""
The text description of UsageFlags.
This value will be one or more of the following strings and will be separated by commas:
- Digital Signature
- Non-Repudiation
- Key Encipherment
- Data Encipherment
- Key Agreement
- Certificate Signing
- CRL Signing
- Encipher Only
If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.
UsageFlags
int (read-only)
Default: 0
The flags that show intended use for the certificate. The value of UsageFlags is a combination of the following flags:
0x80 | Digital Signature |
0x40 | Non-Repudiation |
0x20 | Key Encipherment |
0x10 | Data Encipherment |
0x08 | Key Agreement |
0x04 | Certificate Signing |
0x02 | CRL Signing |
0x01 | Encipher Only |
Please see the Usage field for a text representation of UsageFlags.
This functionality currently is not available when the provider is OpenSSL.
Version
string (read-only)
Default: ""
The certificate's version number. The possible values are the strings "V1", "V2", and "V3".
Subject
string
Default: ""
The subject of the certificate used for client authentication.
This field will be populated with the full subject of the loaded certificate. When loading a certificate, the subject is used to locate the certificate in the store.
If an exact match is not found, the store is searched for subjects containing the value of the property.
If a match is still not found, the property is set to an empty string, and no certificate is selected.
The special value "*" picks a random certificate in the certificate store.
The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:
Field | Meaning |
CN | Common Name. This is commonly a hostname like www.server.com. |
O | Organization |
OU | Organizational Unit |
L | Locality |
S | State |
C | Country |
E | Email Address |
If a field value contains a comma, it must be quoted.
Encoded
string
Default: ""
The certificate (PEM/Base64 encoded). This field is used to assign a specific certificate. The Store and Subject fields also may be used to specify a certificate.
When Encoded is set, a search is initiated in the current Store for the private key of the certificate. If the key is found, Subject is updated to reflect the full subject of the selected certificate; otherwise, Subject is set to an empty string.
EncodedB
byte []
Default: ""
The certificate (PEM/Base64 encoded). This field is used to assign a specific certificate. The Store and Subject fields also may be used to specify a certificate.
When Encoded is set, a search is initiated in the current Store for the private key of the certificate. If the key is found, Subject is updated to reflect the full subject of the selected certificate; otherwise, Subject is set to an empty string.
Constructors
public Certificate();
Public Certificate()
Creates a instance whose properties can be set. This is useful for use with when generating new certificates.
public Certificate(string certificateFile);
Public Certificate(ByVal CertificateFile As String)
Opens CertificateFile and reads out the contents as an X.509 public key.
public Certificate(byte[] encoded);
Public Certificate(ByVal Encoded As Byte())
Parses Encoded as an X.509 public key.
public Certificate(CertStoreTypes storeType, string store, string storePassword, string subject);
Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String)
StoreType identifies the type of certificate store to use. See for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store.
After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN). The Subject parameter can also take an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load in a "Thumbprint=value" format.
public Certificate(CertStoreTypes storeType, string store, string storePassword, string subject, string configurationString);
Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)
StoreType identifies the type of certificate store to use. See for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store.
ConfigurationString is a newline-separated list of name-value pairs that may be used to modify the default behavior. Possible values include "PersistPFXKey", which shows whether or not the PFX key is persisted after performing operations with the private key. This correlates to the PKCS12_NO_PERSIST_KEY CryptoAPI option. The default value is True (the key is persisted). "Thumbprint" - an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load. When specified, this value is used to select the certificate in the store. This is applicable to the cstUser , cstMachine , cstPublicKeyFile , and cstPFXFile store types. "UseInternalSecurityAPI" shows whether the platform (default) or the internal security API is used when performing certificate-related operations.
After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN). The Subject parameter can also take an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load in a "Thumbprint=value" format.
public Certificate(CertStoreTypes storeType, string store, string storePassword, byte[] encoded);
Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Encoded As Byte())
StoreType identifies the type of certificate store to use. See for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store.
After the store has been successfully opened, the component will load Encoded as an X.509 certificate and search the opened store for a corresponding private key.
public Certificate(CertStoreTypes storeType, byte[] store, string storePassword, string subject);
Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As Byte(), ByVal StorePassword As String, ByVal Subject As String)
StoreType identifies the type of certificate store to use. See for descriptions of the different certificate stores. Store is a byte array containing the certificate data. StorePassword is the password used to protect the store.
After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN). The Subject parameter can also take an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load in a "Thumbprint=value" format.
public Certificate(CertStoreTypes storeType, byte[] store, string storePassword, string subject, string configurationString);
Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As Byte(), ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)
StoreType identifies the type of certificate store to use. See for descriptions of the different certificate stores. Store is a byte array containing the certificate data. StorePassword is the password used to protect the store.
After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN). The Subject parameter can also take an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load in a "Thumbprint=value" format.
public Certificate(CertStoreTypes storeType, byte[] store, string storePassword, byte[] encoded);
Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As Byte(), ByVal StorePassword As String, ByVal Encoded As Byte())
StoreType identifies the type of certificate store to use. See for descriptions of the different certificate stores. Store is a byte array containing the certificate data. StorePassword is the password used to protect the store.
After the store has been successfully opened, the component will load Encoded as an X.509 certificate and search the opened store for a corresponding private key.
TSYSMerchant Type
Contains the merchant's setup information.
Remarks
This type contains the merchant's setup information. This includes the merchant identification, bank routing information, language, location, and other fields that identify the merchant to the TSYS server. Some of the information in these fields will be included on the customer's credit card statement, such as the merchant's Name, State, ServicePhone, etc.
- BankId
- CategoryCode
- City
- CountryCode
- CurrencyCode
- Language
- Name
- Number
- Phone
- ServicePhone
- State
- StoreNumber
- StreetAddress
- TerminalNumber
- TimeZone
- Zip
Fields
BankId
string
Default: ""
The number which identifies the merchant's bank or processor.
This field contains a six digit Visa assigned Bank Identification Number issued by the merchant's member bank or processor. The acquirer Bank Identification Number (BIN) identifies the member bank that signed the merchant using the Point of Sale application. This field may not remain zero-filled.
Note, the TSYS Server uses the Merchant's BankId and Number to route the transaction to the proper back-end processor. If either number is incorrect (or if you're using test numbers and the test system is offline) the TSYS server will immediately disconnect, and will not supply an error message.
CategoryCode
string
Default: ""
Classifies a merchant by the type of store.
This four digit field contains a number assigned by the signing member or processor to identify a merchant industry classification. This value is similar to the Standard Industry Code (SIC).
City
string
Default: ""
Merchant's City
For Retail (Card Present) transactions, this field should contain the city in which the merchant is located. This is an optional field. However if it is specified, the Name and State must also be specified.
Note: For Direct Marketing and E-Commerce transactions, for Visa, Discover, and Amex, this field is ignored. ServicePhone is used for those industries instead of City (this does not apply to MasterCard).
Note: This field must contain the same data used in the batch settlement. The first character of this field may not be a space. This field may contain alphanumeric characters, but not punctuation or control characters. The maximum length of this field is 13 characters.
CountryCode
string
Default: "840"
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. For the United States, use "840".
CurrencyCode
string
Default: "840"
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. For US Dollars, use "840".
Language
string
Default: "00"
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. This field may be changed from transaction to transaction. The following table provides a summary of the languages currently supported.
Indicator | Language |
00 | English. |
01 | Spanish. |
02 | Portuguese. |
03 | Reserved for Irish. |
04 | Reserved for French. |
05 | Reserved for German. |
06 | Reserved for Italian. |
07 | Reserved for Dutch. |
Name
string
Default: ""
Name of the merchant.
This 25 character field contains the merchant name provided by the signing member or processor. The name provided must correspond to the name printed on the customer receipt. The first character of this field may not be a space. This field must contain the same value in both authorization and batch settlement.
This is an optional field. However if this field is specified, the State and City (Retail) or State and ServicePhone (E-Commerce) must also be specified.
This field may contain alphanumeric and punctuation characters. The maximum length of this field is 25 characters.
Number
string
Default: ""
A unique number used to identify the merchant within the VisaNet system.
This 12 digit field contains a unique number which is assigned by the signing merchant's bank or processor. This field is used to identify the merchant within the VisaNet system. This number will be right-justified and zero-filled.
Note, the TSYS Server uses the Merchant's BankId and Number to route the transaction to the proper back-end processor. If either number is incorrect (or if you're using test numbers and the test system is offline) the TSYS server will immediately disconnect, and will not supply an error message.
Phone
string
Default: ""
Merchant's phone number.
This field contains the Merchant's business phone number. This can be the same as the customer service phone number.
ServicePhone
string
Default: ""
Merchant's customer service number.
This field contains a merchant telephone number that the cardholder may call for service. It should contain an 11-character phone number in XXX-XXXXXXX format. The initial "1" for long-distance or toll-free calls should be omitted. For instance, "800-1234567" is acceptable, while "1-800-1234567" is not. The fourth character position MUST contain a hyphen. Hyphens may not be used anywhere else.
This field is used for authorizations in the Hotel, Auto Rental, and Direct Marketing Industry Types, and in the settlement for all industry types.
State
string
Default: ""
State or province that the merchant is located in.
This two character field contains the merchant state or province provided by the signing member or processor. This field must contain the same data used in the batch settlement.
This is an optional field. However if it is specified the Merchant Name and City (Retail) or Name and ServicePhone (E-Commerce) must also be specified.
StoreNumber
string
Default: ""
Used to identify a specific merchant's store within the VisaNet system.
This four digit field contains a number assigned by the signing member, processor, or merchant to identify a specific merchant store within the VisaNet system. This field must be right-justified and zero-filled.
StreetAddress
string
Default: ""
Merchant's street address.
This 25 character field contains the Merchant's street address, which should include the street number, street name, and other identifiers of the precise location, such as a building or unit number.
TerminalNumber
string
Default: ""
Used to identify a unique terminal within a merchant location.
This four digit field contains a number assigned by the signing member, processor, or merchant to identify a unique terminal within a merchant location. Because the terminal number submitted in the authorization request is echoed back to the terminal in the authorization response, this field may additionally be used in controller-based environments to assist in the matching and routing of authorization request and response messages at the point of concentration. This field must be right-justified and zero-filled.
TimeZone
string
Default: "705"
Specifies the GMT offset used to calculate the local time within the VisaNet system.
This filed contains a three digit code used to calculate the local time within the VisaNet authorization system. The differential is calculated by the signing member or processor, providing the standard local time zone differential from Greenwich Mean Time (GMT). The first digit specifies the direction of the differential and offset increment as well as whether daylight savings is observed. The last two digits specify the magnitude of the differential. For example, North Carolina would be "705", California would be "708", and Arizona would be "107" (daylight savings not observed). The following table provides a brief summary of the Time Zone Differential Codes.
Byte #1:
Value | Meaning |
0 | Positive offset, in hours, ahead of GMT. |
1 | Negative offset, in hours, behind GMT. |
2 | Positive offset, in 15 minute increments, ahead of GMT. |
3 | Negative offset, in 15 minute increments, behind GMT. |
4 | Positive offset, in 15 minute increments, ahead of GMT, in cities participating in daylight savings. |
5 | Negative offset, in 15 minute increments, behind GMT, in cities participating in daylight savings. |
6 | Positive offset, in hours, ahead of GMT, in cities participating in daylight savings. |
7 | Negative offset, in hours, behind GMT, in cities participating in daylight savings. |
8-9 | RESERVED. |
If byte #1 designates an area with offset in hours, (0, 1, 6, 7) the value of these bytes should be between "00" and "12", inclusive. If byte #1 designates an area with offset in 15 minute increments, (2-5) the value of these bytes should be between "00" and "48", inclusive.
Zip
string
Default: ""
Zip code where the merchant that initiated this transaction is located.
This field contains the nine character code used to further identify the merchant location. Within the United States, the five or nine digit zip code of the address of the store location is used. Outside of the United States, this field will be assigned by the signing member or processor.
This field is alphanumeric, with a maximum length of nine characters. Spaces and dashes are automatically stripped when the field is set.
Constructors
public TSYSMerchant();
Public TSYSMerchant()
TSYSResponse Type
Contains the response to the authorization.
Remarks
This type contains the results of a transaction made with the TSYSECommerce or TSYSRetail component. The fields contained by this type are listed below.
- ApprovalCode
- AuthorizedAmount
- AuthSource
- AVSResult
- CardLevel
- Code
- CommercialCardType
- CVVResult
- RetrievalNumber
- ReturnedACI
- Text
- TransactionDate
- TransactionId
- TransactionNumber
- TransactionTime
- ValidationCode
Fields
ApprovalCode
string (read-only)
Default: ""
Contains an authorization code when a transaction has been approved.
This six character field contains an authorization code when a transaction has been approved. If the Code returned indicates that the transaction has not been approved, then the contents of the field should be ignored. The ApprovalCode must be stored and submitted in the settlement data capture record.
AuthorizedAmount
string (read-only)
Default: ""
Amount actually used from the card (used when supporting partial redemptions).
The AuthorizedAmount represents the actual approved transaction amount when a transaction request is received from a client using the PartialRedemption option. If PartialAuthorization is set to True, then AuthorizedAmount will be the amount of the TransactionAmount that was actually covered by the remaining balance on the card when the requested authorization amount exceeds the available card balance.
For example, a card may have an available balance of $7.50, but the cardholder does not know this. Rather than submit a Balance Inquiry transaction followed by a Purchase transaction, the merchant can use the PartialAuthorization option. If a purchase for $10.00 is attempted on the card with a $7.50 balance, the system will respond with an approval, and the AuthorizedAmount will represent the approved amount of $7.50.In this case, the Code will also be "00" (Approval). The merchant must tender the difference between the requested TransactionAmount and the AuthorizedAmount using another form of payment. If the transaction is fully covered by the balance remaining on the FSA card (ie, the current available balance is greater than the TransactionAmount) then this field will be "0" or "".
If the card has a zero balance before submitting this transaction, it will be declined regardless of the value of PartialAuthorization.
AuthSource
string (read-only)
Default: ""
Indicates the source of the authorization code stored in ApprovalCode.
This field contains a one character code indicating the source of the ApprovalCode. The received code must be stored and submitted in the batch settlement. Valid source codes are:
Code | Description |
6 | Off-line approval: POS device generated. |
7 | Acquirer approval. |
9 | Use for non-authorized transactions; such as credit card credits |
B | Response provided by Visa Transaction Advisor Service. |
E | Off-line approval: authorization code manually keyed. |
F | CAFIS-generated response: Post-Auth.* |
G | Issuer Approval: Post-Auth.* |
H | Exceeds acquirer settlement risk exposure cap. |
N | No authorization required: Below floor limit |
L | Late clearing - authorization previously obtained (clearing beyond 30 days) |
V | Authorization obtained via VisaNet (Issuer or STIP response) |
Space | Default value, if acquirer cannot define it (MC, D, AX) |
AVSResult
string (read-only)
Default: ""
Contains the Address Verification System result code.
This one character field contains the Address Verification System (AVS) result code. An AVS result code can provide additional information concerning the authentication of a particular transaction for which cardholder address verification was requested. An AVS result code of "0" will be returned in the response message when no address verification has been requested. The value returned should be stored and submitted as part of the batch settlement. Valid AVS codes are:
Code | Description |
0 | Approved/Declined - Address verification was not requested or it was requested but the transaction was declined (Visa, MC, Amex, Discover). |
A | Address Match - CustomerAddress matches, CustomerZip does not, or the request does not include the CustomerZip (Visa, Amex, Discover). |
I* | Ver Unavailable - Address information not verified (Discover). |
N | No match - Transaction contained postal/ZIP code only, or street address only, or postal code and street address. Also used when transaction requests AVS but sends no AVS data (Visa, MC, Amex, Discover). |
R | Retry - System unable to process (Visa, MC, Amex, Discover). |
S | Serv Unavailable - Service not supported (MC, Amex, Discover). |
U | Ver Unavailable - No data from Issuer/Authorization platform (Visa, MC, Amex, Discover). |
W | Zip Match - Nine character CustomerZip matches, CustomerAddress does not (MC, Discover). |
X | Exact Match - Nine character CustomerZip and CustomerAddress match (MC, Discover). |
Y | Exact Match - CustomerZip and CustomerAddress match (Visa, MC, Amex, Discover). |
Z | Zip Match - CustomerZip matches; CustomerAddress does not match or street address not included in the request (Visa, MC, Amex, Discover). |
1 | APPROVAL - Cardholder name and ZIP match (Amex only). |
2 | APPROVAL - Cardholder name, address, and ZIP match (Amex only). |
3 | APPROVAL - Cardholder name, address match (Amex only). |
4 | APPROVAL - Cardholder name matches (Amex only). |
5 | APPROVAL - Cardholder name incorrect, ZIP matches (Amex only). |
6 | APPROVAL - Cardholder name incorrect, address and ZIP match (Amex only). |
7 | APPROVAL - Cardholder name incorrect, address matches (Amex only). |
8 | NO MATCH - Cardholder name, address, and ZIP do not match (Amex only). |
*AVS Result Code for International addresses only
CardLevel
string (read-only)
Default: ""
This field contains a two-character code created by Visa during the authorization process.
The current list of possible return values can be found in the table of contents.
Code
string (read-only)
Default: ""
Indicates the status of the authorization request.
This field contains a two character response code indicating the status of the authorization request. The Point of Sale (POS) system must evaluate this response code and NOT the Text to determine nature of a response message. A response code of "00" represents an approval. A response code of "85" represents a successful card verification (when the TransactionType set to dcCardAuthentication). A response code of "10" indicates that the transaction was partially approved for a lesser amount. In such cases, the partially authorized amount can be retrieved via ResponseAuthorizedAmount config. All other response codes represent non-approved requests. Do NOT interpret all non-approved response codes as "DECLINED".
A list of valid result Codes are listed in the table of contents.
CommercialCardType
TSYSCommercialCardTypes (read-only)
Default: 0
Response field that indicates whether the card is a commercial card.
If you wish to support Corporate Purchasing Cards with Level II or Level III data, you should inspect the value of this field after a successful authorization. If the Vital/TSYS host indicates that the authorized card is a commercial card, you may use the TSYSLevel2 or TSYSLevel3 components to add the extra data required during settlement.
Possible values for this field include:
tccNotCommercial (0) | Not a commercial card. You must not send Level II or Level III data in the settlement. |
tccBusinessCard (1) | Business Card |
tccVisaCommerce (2) | Visa Commerce (Reserved for future use) |
tccCorporateCard (3) | Corporate Card |
tccPurchaseCard (4) | Purchasing Card |
This field is only valid after a successful authorization request and response.
CVVResult
string (read-only)
Default: ""
Contains the returned CVV result code if it was requested.
If a CVV value was sent in the authorization request, then this one character field will contain the host returned Card Verification Value result code. Please note that a CVV Result code is never returned for an American Express transaction, even if the CVV data is included in the authorization. Instead, an AMEX transaction will be declined if the CVV value does not match, with an Text indicating such. The following is a list of current result codes:
M | CVV2 match. |
N | CVV2 no match. |
P | Not processed. |
S | Merchant has indicated that CVV2 is not present on card. |
U | Issuer not certified and/or has not provided Visa encryption keys. |
RetrievalNumber
string (read-only)
Default: ""
This number is to be used to identify transactions and should be submitted when making adjustments, reversals or at settlement.
This field contains a 12-character value reflecting the transaction Retrieval Reference Number returned by the authorizing system. The Point of Sale (POS) system should record the Retrieval Reference Number received in the original authorization response.
ReturnedACI
string (read-only)
Default: ""
Returned Authorization Characteristics Indicator contains CPS qualification status.
This one character field contains the returned Authorization Characteristics Indicator (ACI). This value provides information concerning the transaction's CPS qualification status. It is not recommended that the Point of Sale (POS) system attempt to interpret the meaning of this value. Instead, the POS system should extract whatever value is returned in this field and submit it in the batch settlement. The POS system should not interpret any relationship between this field and the presence of data in either the TransactionId or ValidationCode fields.
Text
string (read-only)
Default: ""
Text information that describes each response code.
This field contains a 16-character response or display text message. This message is used by the terminal to display the authorization result. The display text must not be used to determine the nature of a response message. VisaNet will translate the response according to the merchant's selected language.
The English-language response text messages are listed in the table of contents.
TransactionDate
string (read-only)
Default: ""
Local transaction date returned from the server in MMddyy format.
This six digit field contains a local transaction date calculated by the authorization center using the time zone differential specified by the Merchant's Time Zone;. This field should be recorded and submitted in the Batch Settlement.
TransactionId
string (read-only)
Default: ""
Contains the Transaction Identifier or MasterCard Reference Number.
This 15-character field can contain a Transaction Identifier (Visa, American Express or Discover) or Reference Number (MasterCard). The Point of Sale (POS) device should not attempt to interpret the meaning of any data appearing in this field. Data returned in this field (if any) should be recorded and submitted in the Batch Settlement.
TransactionNumber
string (read-only)
Default: ""
Check this field against the original Transaction Number.
This field should be compared to the TransactionNumber in order to match a response with a given authorization request when in Interleaved mode (Timeout = 0). If running in non-interleaved (synchronous) mode, this field should always be identical to TransactionNumber. If it is not, the transaction must not be settled in the Batch Settlement.
TransactionTime
string (read-only)
Default: ""
Local transaction time returned from the server in HHmmss format.
This six digit field contains the Local Transaction Time returned by the authorizing system. This field should be recorded and submitted in the Batch Settlement.
ValidationCode
string (read-only)
Default: ""
This optional field contains information generated by the card issuer.
This optional four character field contains specific information generated by the card issuer. The Point of Sale (POS) device should not attempt to interpret the meaning of any data appearing in this field. Data returned in this field should be recorded and submitted as part of a Batch Settlement.
Constructors
public TSYSResponse();
Public TSYSResponse()
Config Settings (TSYSECommerce Component)
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 Config Settings
This 1-character configuration setting is used to identify the type of device used by the merchant for accepting mobile Point of Sale (mPOS) transactions. Valid values are:
Value | Description |
0 | Dedicated mPOS Terminal with PCI compliant dongle (with or without key pad) |
1 | Off the Shelf Mobile Device |
2 | Dongle with software-based application that supports PIN entry on glass |
3 | Off the Shelf Mobile Device with software-based application that supports PIN entry on glass |
M | Mobile POS Add-On Hardware |
T | Tap on Mobile No Add-On Hardware |
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.
N | Device is not CPS capable / MasterCard TIPS (Travel Industries Premiere Service). |
Y | Device is CPS capable. |
P | CPS Capable - Manually keyed hotel/lodging transaction or preferred customer authorization request for hotel, auto rental, and passenger transport industries. |
I | CPS capable - Incremental Authorization Request. |
R | Recurring or Installment payments / MasterCard SIIP (Recurring payment). |
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.
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.
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.
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.
DepartureDate | Passenger's departure date in format YYYYMMDD. Example: 20171220 | ||||||
PassengerName | Passenger Name in format SURNAME~FIRSTNAME~MIDDLEINITIAL~TITLE. Use character space as sub-element separator. Example: FROST JANE M MRS | ||||||
CardMemberName | Cardmember Name in format SURNAME~FIRSTNAME~MIDDLEINITIAL~TITLE. Use character space as sub-element separator. Example: FROST CHARLES F MR | ||||||
Origin | First segment travel origination Airport. Example for Los Angeles (CA): LAX | ||||||
Destination | Destination 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. | ||||||
NumberOfCities | Number of Airports or Cities on ticket. Maximum is 10. | ||||||
RoutingCities | Routing 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). | ||||||
NumberOfAirlineCarriers | Number of Airline Carriers entered in AirlineCarriers subfield. Maximum is 9. | ||||||
AirlineCarriers | Airline 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). | ||||||
FareBasis | Primary and secondary discount codes which indicate class of service and fare level associated with ticket. Example: ABC123DEF456GHI789JKL012 | ||||||
NumberOfPassengers | Number of passengers in party. Default value is 1. | ||||||
ETicket | Indicates if ticket is electronic. Default value is false. Possible values:
| ||||||
ReservationCode | A precursor to a ticket number which corresponds to an airline ticket purchase reservation made by an airline or Global Distribution System (GDS). Example: ABCDE1234567890 |
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");
CustomerEmail | Customer's e-mail address. | ||||||||||||||
CustomerHostName | Name of the server that the customer is connected to. | ||||||||||||||
BrowserType | Customer's HTTP browser type. | ||||||||||||||
ShipToCountry | Three-byte, numeric country code. Example for USA: 840 | ||||||||||||||
ShippingMethod | Two-byte, shipment-type code. Possible values:
| ||||||||||||||
ProductSKU | Unique 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. | ||||||||||||||
CustomerIP | Customer's Internet IP address. | ||||||||||||||
CustomerANI | ANI (Automatic Number Identification) specified phone number that customer used to place order with merchant. | ||||||||||||||
CustomerIIDigits | Telephone company-provided ANI ii (Information Identifier) coding digits associated with CUSTOMER ANI phone number that correspond to calltype; e.g., cellular, government institution, etc. |
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");
ProductCode | Four-byte goods product indicator code. Possible values:
|
This field is used to specify the AuthenticationCode, assigned by TSYS, to authenticate a POS device (made via a call to ActivateTerminal).
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 |
This applies to merchants that are enrolled in the Visa Consumer BillPay program.
Valid values are:
Value | Description |
CB | Consumer Bill Payment |
Note: When enrolled in the Visa Consumer BillPay program, the MerchantName field must be in the 'CBPS Name * Biller' format and must match what is registered with Visa.
Sending a value of "Y" in this Mastercard only field indicates the merchant accepts Canada domestic Debit Mastercard. This value must be sent in every Credit Authorization Request for merchants that accept Canada region-issued Debit Mastercard cards.
If Canada Domestic Indicator was present in the original transaction it must be included in a reversal message.
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.
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.
This 4-character field indicates whether the transaction was initiated by the Cardholder or the Merchant (Mastercard only).
Valid values are:
Customer Initiated Transaction (CIT)
Value | Description |
C101 | Credential on File |
C102 | Standing Order (variable amount, fixed frequency) |
C103 | Subscription (fixed amount and fixed frequency) |
C104 | Installment |
Merchant Initiated Transaction (MIT) - Recurring or Installment
Value | Description |
M101 | Unscheduled Credential on File |
M102 | Standing Order (variable amount, fixed frequency) |
M103 | Subscription (fixed amount and fixed frequency) |
M104 | Installment |
Merchant Initiated Transaction (MIT) - Industry Practice
Value | Description |
M205 | Partial Shipment |
M206 | Related/Delayed Charge |
M207 | No show Charge |
M208 | Resubmission |
Note: If CIT/MIT Indicator was present in the original transaction it must be included in a reversal message.
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.
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.
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.
This is the current number of outstanding transactions that have not yet received a response. This is a read-only configuration setting.
This is an action config which when called will deactivate the POS device specified via GenKey with TSYS.
The Digital Payment Cryptogram is a 28 byte value and is used to send a Digital Secure Remote Payment (DSRP) cryptogram for DSRP transactions submitted as electronic commerce.
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.
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.
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.
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.
Indicator | Description |
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). |
1 | One Time Occurrence of a Mail/Telephone Order Transaction (use for Direct Marketing). |
2 | Recurring Mail/Telephone Order Transaction. |
3 | Installment Payment of a Mail/Telephone Order Transaction. |
4 | Unknown Classification. |
5 | Secure Electronic Transaction (3-D Secure) and MasterCard SecureCode (UCAF) |
6 | Non-authenticated security transaction at a 3-D Secure capable merchant, and merchant attempted to authenticate the cardholder using 3-D Secure. |
7 | Non-authenticated Security Transaction, such as a Channel-Encrypted Transaction (default for CardNotPresent eCommerce transactions). |
8 | Non-secure Electronic Commerce Transaction |
A | In-App Authentication (Discover, Mastercard and Amex) |
R | First recurring SecureCode Phone Order transaction (Mastercard Only) |
T | Single 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=\" \"");
This 10 character field provides a unique value to identify a Gateway or Aggregator. This number is provided by TSYS Acquiring Solutions during the certification process.
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.
The specified value must be 4 characters or less. Note that this value is required to comply with MasterCard's Authorization Data Accuracy Initiative.
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):
0 | No Encryption (default) |
1 | Merchant ID and Card Data (reserved for future use) |
2 | Merchant ID, Card Data, and Card Security Code (reserved for future use) |
3 | Card Data Only |
Note you will also need to set Processor to 1 (Heartland) and HeartlandKeyBlock if you wish to process Heartland E3 transactions.
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.
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.
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.
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.
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.
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.
This configuration setting indicates the number of recurring or installment payments that were agreed upon between the cardholder and the merchant. This field is used in both the initial and subsequent payment transactions. The current usage of this field is for Discover cards only. Valid values are:
Value | Description |
02-99 | Installment Count |
ND | Not Defined |
UC | Until Canceled |
This configuration setting is used to identify the sequence number of a transaction when there are multiple installment payments. This field is used in both the initial and subsequent payment transactions. The rcfgInstallmentNumber; should be populated in ascending order. The current usage of this field is for Discover cards only.
To settle a transaction authorized with the ttInstallment TransactionType, you must specify the number of this installment and the total count of all installments to be made using TSYSECommerce component. For instance, if the purchase was for "Three easy payments of $19.95", and this is the first payment, then the installment number will be 1, and the installment count 3. An example is included below:
TSYSECommerce.TransactionType = ttInstallment
TSYSECommerce.TransactionAmount = "1995"
TSYSECommerce.Config("InstallmentCount=3")
TSYSECommerce.Config("InstallmentNumber=1")
TSYSECommerce.Authorize()
TSYSSettle.DetailAggregate[5] = TSYSECommerce.GetDetailAggregate()
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");
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).
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.
Set this to True when the amount sent in the initial transaction is an estimate. Default value is 'False'.
To process a Merchant Initiated Transaction you need to set this IsMerchantInitiatedTransaction flag to True. Default value is False.
This 11-digit value is assigned to the Service Provider designated as an ISO (Independent Sales Organization) during registration with the card brand and must be included on all MasterCard or Discover transactions where the merchant has a relationship with an ISO.
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.
To process an online Purchase Return transaction you need to set this IsPurchaseReturnAuthorization flag to True. Default value is 'False'.
Note: To Reverse a Purchase Return Authorization you should use the TSYSReversal component and set the ReversalType to rtCreditAuthorization (5) before calling the Reverse method.
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.
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.
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.
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.
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.
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.
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.
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.
This 3-character value provides information about transactions initiated through the Masterpass Online platform or through the Mastercard Digital Enablement Service (MDES) and identifies the Wallet Provider. For MDES, Mastercard inserts the Wallet Identifier that is in the system, when available. For Masterpass, Mastercard passes the Wallet Identifier as sent in from the Point of Sale.
The following values apply to both Masterpass and MDES transactions:
Value | Description |
101 | Masterpass by Mastercard |
The following values only apply to MDES transactions:
Value | Description |
103 | Apple Pay |
216 | Google Pay |
217 | Samsung Pay |
327 | Merchant tokenization program |
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.
This field contains a two digit language indicator. This value designates the language to be used in formatting the authorization response text message.
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.
This field is used to identify Merchant Initiated or Deferred Authorizations for Visa.
Merchant Initiated Transactions A Merchant Initiated Transaction (MIT) is any transaction that relates to the 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) |
Deferred Authorizations If the merchant's Point-of-Interaction (POI) authorization system is offline and cannot process transactions, the merchant often completes the transaction with the cardholder and will then defer the authorization until their POI system is back online. Valid value is:
Code | Description |
5206 | Deferred Authorization |
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'.
The Merchant Payment Gateway Identifier (MPGID) is a unique value that is generated and provisioned by Mastercard. Payment gateways must register directly with Mastercard to obtain a unique value, and include it on the incoming authorization message. Maximum length for this field is 11 digits.
This configuration setting is required for Discover Merchant Initiated Transactions (MIT) with TransactionStatus: (P) Partial Shipment, (R) Recurring Payment, or (A) Re-authorize for Full Amount. It should be used in conjunction with OriginalAmountAccountType. The component will send the OriginalAmount on group G3v022 with amount type 57 (Original Amount).
Note: When supporting MIT transactions for Discover cards, you must keep track of the Original Amount from the initial CIT transaction.
This 2-character value configuration setting indicates the account type such as "30" for Credit Card, "40" for Universal etc. (see TSYS Specs G3v022 for complete list). It should be used in conjunction with OriginalAmount.
This unique digit internal identification code is assigned by the Acquirer to it's merchant. Discover assigns this 20-character field during registration via the Discover Network.
This 3-character field is used by marketplaces to uniquely identify domestic transactions in which the retailer is in a different country than the marketplace. Visa classifies an entity as a marketplace if it handles payments on behalf of retailers through an online marketplace that brings together multiple buyers and retailers. This field must be sent when the retailer is foreign.
Valid values are:
Code | Description |
(Space) (default) | Space indicates the retailer is not foreign. |
F | This value indicates the retailer is located in a different country than the marketplace. |
This 11-digit value is assigned to the Service Provider during registration with the card brand and must be included on all Visa, MasterCard, or Discover transactions where the merchant has a relationship with a Payment Facilitator/Service Provider.
Note: For Visa Marketplaces, the Marketplace ID must be included in this field.
This 25-character field is a subfield of Payment Facilitator and must be included on all transactions where the merchant has a relationship with a Payment Facilitator. It has two usages:
Usage 1 - Payment Facilitator Name*Sub-Merchant Name
This usage is valid for Visa, Mastercard, and Discover.
For Payment Facilitators, the field contains two parts in a concatenation of two fields separated by an asterisk (*). For Visa, Mastercard, and Discover the name submitted should match what the PayFac registered with each brand and should follow the requirements defined by each brand.
Usage 2 - Marketplace Name
For Visa Marketplaces, the field should contain the name of the Marketplace.
This 13-character field is a subfield of Payment Facilitator.
For Visa and Mastercard transactions, enter the city of the sub-merchant location (not the Payment Facilitator location).
For Discover transactions, enter the location where the transaction took place; this may or may not be the sub-merchant location.
For Direct Marketing merchants and preferred customer/passenger transport and card not present transactions, this field must contain a phone number for merchant customer service in format XXX-XXXXXXX. The dash is required. This field can also be used for e-mail or a URL.
This 3-digit field indicates the country of the Sub-Merchant location (not the Payment Facilitator location) using ISO-specified numeric codes. It is used for Visa, Mastercard, and Discover transactions and must be included on all transactions where the merchant has a relationship with a Payment Facilitator.
This 15-character field, assigned by the Payment Facilitator or the Acquirer, must be provided on all Visa, Mastercard, or Discover transactions where the merchant has a relationship with a Payment Facilitator.
This 9-character field indicates the postal code of the Sub-Merchant location (not the Payment Facilitator location). This field must be included on all transactions where the merchant has a relationship with a Payment Facilitator. It is used for Visa, Mastercard, and Discover transactions.
This 2-character field indicates the state or province code of the Sub-Merchant location (not the Payment Facilitator location). If the Sub-Merchant is non-U.S. and non-Canadian, this field should be '00'. This field must be included on all Visa, Mastercard, and Discover transactions where the merchant has a relationship with a Payment Facilitator.
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.
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 |
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.
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 |
If the merchant initiates a transaction using a stored payment credential, the value in POSDataCode.CardInputMode should be '7' for Credential on File transactions.
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:
0 | TSYS (default) |
1 | Heartland |
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.
The Program Protocol must be provided by the merchant if they are using the Mastercard Identity Check program to authenticate the cardholder. This value identifies the version of the EMV 3D-Secure protocol and it is the merchant's responsibility to know which version applies. Allowable values are:
Value | Description |
1 | EMV 3-D Secure Version 2.1 |
2 | EMV 3-D Secure Version 2.2 |
3 | EMV 3-D Secure Version 2.3 |
4 | EMV 3-D Secure Version 2.4 |
5 | EMV 3-D Secure Version 2.5 |
6 | EMV 3-D Secure Version 2.6 |
7 | EMV 3-D Secure Version 2.7 |
8 | EMV 3-D Secure Version 2.8 |
9 | EMV 3-D Secure Version 2.9 |
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()
This configuration setting is used to specify the date when the cardholder last voluntarily changed his or her registered profile (Discover, Diners, JCB, and CUP transactions only). The format for this field is DDMMYYYY.
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.
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 |
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 present | CAVV not validated. |
0 | CAVV not validated because erroneous data was submitted. |
1 | CAVV failed validation. |
2 | CAVV passed validation. |
3 | CAVV validation could not be performed; Issuer attempt incomplete. |
4 | CAVV validation could not be performed; Issuer system error. |
5 | Reserved for future use. |
6 | Reserved for future use. |
7 | CAVV attempt - failed validation - issuer available (US issued card/non-US acquirer). |
8 | CAVV attempt - passed validation - issuer available (US issued card/non-US acquirer). |
9 | CAVV attempt - failed validation - issuer unavailable (US issued card/non-US acquirer). |
A | CAVV attempt - passed validation - issuer unavailable (US issued card/non-US acquirer). |
B | CAVV passed validation, information only, no liability shift. |
C | CAVV was not validated - attempted. |
D | CAVV was not validated - authentication. |
Possible returned values are:
Value | Description |
01 | New account information |
02 | Try again later |
03 | Do not try again for recurring payment transaction |
04 | Token requirements not fulfilled for this token type |
21 | Recurring payment cancellation |
22 | Merchant does not qualify for product code |
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.
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.
This read only configuration setting if returned in the Response message contains 4 characters that represent the last 4 digits of the actual cardholder PAN. This can be used to print on the paper receipt for cardholder reference.
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. |
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.
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.
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.
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).
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.
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.
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.
This field contains the name of the city where the cardholder received the services, if it is different from the location identified by the acceptor city name. This value will be sent as part of group G3v089 in authorization and group ODG41 (Tag: "SLD") in settlement.
The maximum length for this field is 13 characters.
This field contains the geographic coordinates of the location where the cardholder received services. Providing the geographic coordinates at the transaction level for merchants that change location (i.e. food truck) may help the cardholder recognize the transaction on their statement. This value will be sent as part of group G3v089 in authorization and group ODG41 (Tag: "SLD") in settlement.
Geographic Coordinate Format Guidelines:
The geographic coordinates, when present, must contain valid latitude and longitude values, comma-separated, represented in decimal degrees to five decimal places in positions 001 through 020 with these format standards:
- Length is a range of 15 - 20
- Contains up to two '-'
- Contains precisely two '.'
- Contains precisely one ','
- At least one numeric position is before the first '.'
- Five numeric positions are found between the first '.' and ','
- At least one numeric position is found between ',' and the second '.'
- Five numeric positions are found after the second '.'
- Latitude is greater than or equal to -90.00000 and less than or equal to 90.00000
- Longitude is greater than or equal to -180.00000 and less than or equal to 180.00000
- No space character follows the comma separator
- No alpha characters allowed
This field contains the code of the country where the cardholder received the services, if it is different from the location identified by the acceptor country code. This value will be sent as part of group G3v089 in authorization and group ODG41 (Tag: "SLD") in settlement.
The maximum length for this field is 3 characters.
This field contains the code of the country subdivision where the cardholder received the services, if it is different from the location identified by the acceptor country subdivision code. This value will be sent as part of group G3v089 in authorization and group ODG41 (Tag: "SLD") in settlement.
The maximum length for this field is 3 characters.
This field contains the postal code of the country where the cardholder received the services, if it is different. This value will be sent as part of group G3v089 in authorization and group ODG41 (Tag: "SLD") in settlement.
The maximum length for this field is 10 characters.
This field describes selected special conditions at the point of sale.
Valid values are:
Value | Description |
7 | Purchase of Cryptocurrency. The transaction is related to purchase of cryptocurrency. |
8 | Quasi-Cash. The transaction is for a product or item that is representative of actual cash such as money orders, traveler's checks, foreign currency, lottery tickets, or casino gaming chips. |
9 | Existing Debt Indicator. The transaction includes payment on an existing debt. |
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.
The Transaction Link Identifier (TLID) is used to track the life cycle of activity occurring after the original transaction and other related transactions. The TLID will be returned by Mastercard in the authorization response message. The returned value will also be present in the aggregate returned from the GetDetailAggregate method and for all subsequent transactions that utilize the aggregate (such as reversals, incrementals, settlement) the value will be automatically included in the request. When not utilizing the aggregate, you may explicitly set this config with the TLID value that was saved when the original transaction was performed.
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.
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").
Use this 1-character configuration setting to indicate the purpose or status of the request.
The tables below provide the valid values for each card brand.
Valid value for Visa is:
I | One or more incremental authorizations were performed. |
Valid values for Mastercard are:
Value | Description |
0 | Normal request (original presentment) |
1 | Deferred Authorizations |
2 | SecureCode Phone Order |
3 | ATM Installment Inquiry |
4 | Preauthorized request |
5 | Time Based Payment Authorization Request-Brazil domestic transactions |
6 | ATC Update |
8 | Account Status Inquiry Service (ASI) |
9 | Tokenization Request/Notification |
Valid values for Discover are:
Value | Description |
0 | Normal request (original presentment) |
4 | Preauthorized request |
A | Re-authorize for Full Amount |
D | Delayed Card Sale |
E | Resubmission of Card Sale |
G | Transit Aggregated Transaction |
I | Incremental Authorization |
N | No-Show Charge |
P | Partial Shipment |
R | Recurring Payment |
S | Merchant Installment Payment |
T | Third Party Installment Payment |
U | Unscheduled Payment |
V | Issuer Installment Payment |
Note: For Purchase Return Authorization Requests: Value must be 0 (Mastercard and Discover).
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.
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.
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:
Indicator | Description |
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. |
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. |
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.
TCPClient Config Settings
This configuration 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. To keep streams open after the transfer of data, set this to False. The default value is True.
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.
This configuration setting is provided for use by components that do not directly expose Firewall properties.
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 setting is provided for use by components that do not directly expose Firewall properties.
This entry is for TCPClient only and does not work for other components that descend from TCPClient.
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.
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 setting is provided for use by components that do not directly expose Firewall properties.
The FirewallPort is set automatically when FirewallType is set to a valid value.
Note: This configuration setting is provided for use by components that do not directly expose Firewall properties.
Possible values are as follows:
0 | No firewall (default setting). |
1 | Connect through a tunneling proxy. FirewallPort is set to 80. |
2 | Connect through a SOCKS4 Proxy. FirewallPort is set to 1080. |
3 | Connect through a SOCKS5 Proxy. FirewallPort is set to 1080. |
10 | Connect through a SOCKS4A Proxy. FirewallPort is set to 1080. |
Note: This setting is provided for use by components that do not directly expose Firewall properties.
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 setting is provided for use by components that do not directly expose Firewall properties.
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 acknowledgment is received from the remote host, the keep-alive packet will be sent again. This configuration 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 macOS.
When set, TCPKeepAlive will automatically be set to True. By default, the operating system will determine the time a connection is idle before a Transmission Control Protocol (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.
This property controls how a connection is closed. The default is True.
In the case that Linger is True (default), two scenarios determine how long the connection will linger. In the first, if LingerTime is 0 (default), the system will attempt to send pending data for a connection until the default IP timeout expires.
In the second scenario, if 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 are 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 (e.g., by a client acknowledgment), setting this property to False might be the appropriate course of action.
LingerTime is the time, in seconds, the socket connection will linger. This value is 0 by default, which means it will use the default IP timeout.
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 multihomed 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 multihomed hosts (machines with more than one IP interface).
This configuration setting 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 configuration setting is useful when trying to connect to services that require a trusted port on the client side. An example is the remote shell (rsh) service in UNIX systems.
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.
This configuration 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.
This configuration 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.example.com
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.
When set to True, the socket will send all data that are ready to send at once. When set to False, the socket will send smaller buffered packets of data at small intervals. This is known as the Nagle algorithm.
By default, this configuration setting is set to False.
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 as follows:
0 | IPv4 only |
1 | IPv6 only |
2 | IPv6 with IPv4 fallback |
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.
SSL Config Settings
This configuration setting specifies the paths on disk to certificate authority (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 or client certificates.
The default value is as follows:
/etc/ssl/ca-bundle.pem;/etc/pki/tls/certs/ca-bundle.crt;/etc/ssl/certs/ca-certificates.crt;/etc/pki/tls/cacert.pem
When SSLProvider is set to Internal, this configuration setting controls whether Secure Sockets Layer (SSL) packets should be logged. By default, this configuration setting is False, as it is useful only 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 configuration setting has no effect if SSLProvider is set to Platform.
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.
When SSLProvider is set to Internal, this configuration setting specifies one or more CA certificates to be included with the SSLCert property. Some servers or clients require the entire chain, including CA certificates, to be presented when performing SSL authentication. The value of this configuration setting is a newline-separated (CR/LF) list of certificates. For instance:
-----BEGIN CERTIFICATE----- MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw ... Intermediate Cert ... eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w F0I1XhM+pKj7FjDr+XNj -----END CERTIFICATE----- \r \n -----BEGIN CERTIFICATE----- MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp ... Root Cert ... d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA -----END CERTIFICATE-----
This configuration setting specifies whether the component will check the Certificate Revocation List (CRL) specified by the server certificate. If set to 1 or 2, the component will first obtain the list of CRL URLs from the server certificate's CRL distribution points extension. The component will then make HTTP requests to each CRL endpoint to check the validity of the server's certificate. If the certificate has been revoked or any other issues are found during validation the component throws an exception.
When set to 0 (default), the CRL check will not be performed by the component. When set to 1, it will attempt to perform the CRL check, but it will continue without an error if the server's certificate does not support CRL. When set to 2, it will perform the CRL check and will throw an error if CRL is not supported.
This configuration setting is supported only in the Java, C#, and C++ editions. In the C++ edition, it is supported only on Windows operating systems.
This configuration setting specifies whether the component will use OCSP to check the validity of the server certificate. If set to 1 or 2, the component will first obtain the Online Certificate Status Protocol (OCSP) URL from the server certificate's OCSP extension. The component will then locate the issuing certificate and make an HTTP request to the OCSP endpoint to check the validity of the server's certificate. If the certificate has been revoked or any other issues are found during validation, the component throws an exception.
When set to 0 (default), the component will not perform an OCSP check. When set to 1, it will attempt to perform the OCSP check, but it will continue without an error if the server's certificate does not support OCSP. When set to 2, it will perform the OCSP check and will throw an error if OCSP is not supported.
This configuration setting is supported only in the Java, C#, and C++ editions. In the C++ edition, it is supported only on Windows operating systems.
This minimum cipher strength is 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.
Note: This configuration 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 configuration 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 configuration setting.
This configuration setting is only applicable to server components (e.g., TCPServer) see SSLServerCACerts for client components (e.g., TCPClient). This setting can be used to optionally specify one or more CA certificates to be used when verifying the client certificate that is presented by the client during the SSL handshake when SSLAuthenticateClients is enabled. When verifying the client's certificate, the certificates trusted by the system will be used as part of the verification process. If the client's CA certificates are not installed to the trusted system store, they may be specified here so they are included when performing the verification process. This configuration setting should be set only if the client's CA certificates are not already trusted on the system and cannot be installed to the trusted system store.
The value of this configuration setting is a newline-separated (CR/LF) list of certificates. For instance:
-----BEGIN CERTIFICATE----- MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw ... Intermediate Cert ... eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w F0I1XhM+pKj7FjDr+XNj -----END CERTIFICATE----- \r \n -----BEGIN CERTIFICATE----- MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp ... Root Cert ... d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA -----END CERTIFICATE-----
This configuration setting enables the 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 SSLProvider is set to Platform include the following:
obj.config("SSLEnabledCipherSuites=*");
obj.config("SSLEnabledCipherSuites=CALG_AES_256");
obj.config("SSLEnabledCipherSuites=CALG_AES_256;CALG_3DES");
Possible values when SSLProvider is set to Platform include the following:
- 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
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_ECDH_RSA_WITH_AES_128_CBC_SHA");
Possible values when SSLProvider is set to Internal include the following:
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384
- TLS_RSA_WITH_AES_256_GCM_SHA384
- TLS_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256
- TLS_DHE_DSS_WITH_AES_256_GCM_SHA384
- TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256
- TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_DHE_DSS_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
- TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384
- TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
- TLS_RSA_WITH_AES_256_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
- TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384
- TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
- TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
- TLS_RSA_WITH_AES_128_CBC_SHA256
- TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
- TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
- TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
- TLS_RSA_WITH_AES_256_CBC_SHA
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
- TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA
- TLS_DHE_RSA_WITH_AES_256_CBC_SHA
- TLS_ECDH_RSA_WITH_AES_256_CBC_SHA
- TLS_DHE_DSS_WITH_AES_256_CBC_SHA
- TLS_RSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
- TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
- TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
- TLS_DHE_RSA_WITH_AES_128_CBC_SHA
- TLS_DHE_DSS_WITH_AES_128_CBC_SHA
- TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
- TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
- TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
- TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
- TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
- TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
- TLS_RSA_WITH_3DES_EDE_CBC_SHA
- TLS_RSA_WITH_DES_CBC_SHA
- TLS_DHE_RSA_WITH_DES_CBC_SHA
- TLS_DHE_DSS_WITH_DES_CBC_SHA
- TLS_RSA_WITH_RC4_128_MD5
- TLS_RSA_WITH_RC4_128_SHA
When TLS 1.3 is negotiated (see SSLEnabledProtocols), only the following cipher suites are supported:
- TLS_AES_256_GCM_SHA384
- TLS_CHACHA20_POLY1305_SHA256
- TLS_AES_128_GCM_SHA256
SSLEnabledCipherSuites is used together with SSLCipherStrength.
This configuration setting is used to enable or disable the supported security protocols.
Not all supported protocols are enabled by default. The default value is 4032 for client components, and 3072 for server components. To specify a combination of enabled protocol versions set this config to the binary OR of one or more of the following values:
TLS1.3 | 12288 (Hex 3000) |
TLS1.2 | 3072 (Hex C00) (Default - Client and Server) |
TLS1.1 | 768 (Hex 300) (Default - Client) |
TLS1 | 192 (Hex C0) (Default - Client) |
SSL3 | 48 (Hex 30) |
SSL2 | 12 (Hex 0C) |
Note that only TLS 1.2 is enabled for server components that accept incoming connections. This adheres to industry standards to ensure a secure connection. Client components enable TLS 1.0, TLS 1.1, and TLS 1.2 by default and will negotiate the highest mutually supported version when connecting to a server, which should be TLS 1.2 in most cases.
SSLEnabledProtocols: Transport Layer Security (TLS) 1.3 Notes:
By default when TLS 1.3 is enabled, the component will use the internal TLS implementation when the SSLProvider is set to Automatic for all editions.
In editions that are designed to run on Windows, SSLProvider can be set to Platform to use the platform implementation instead of the internal implementation. When configured in this manner, please note that the platform provider is supported only on Windows 11/Windows Server 2022 and up. The default internal provider is available on all platforms and is not restricted to any specific OS version.
If set to 1 (Platform provider), please be aware of the following notes:
- The platform provider is available only on Windows 11/Windows Server 2022 and up.
- SSLEnabledCipherSuites and other similar SSL configuration settings are not supported.
- If SSLEnabledProtocols includes both TLS 1.3 and TLS 1.2, these restrictions are still applicable even if TLS 1.2 is negotiated. Enabling TLS 1.3 with the platform provider changes the implementation used for all TLS versions.
SSLEnabledProtocols: SSL2 and SSL3 Notes:
SSL 2.0 and 3.0 are not supported by the component when the SSLProvider is set to internal. To use SSL 2.0 or SSL 3.0, the platform security API must have the protocols enabled and SSLProvider needs to be set to platform.
This configuration setting specifies whether the renegotiation_info SSL extension will be used in the request when using the internal security API. This configuration setting is false by default, but it can be set to true to enable the extension.
This configuration setting is applicable only when SSLProvider is set to Internal.
This configuration 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 SSLProvider is set to Internal this value is automatically set to true. This is needed for proper validation when using the internal provider.
This configuration setting optionally specifies the full path to a file on disk where per-session secrets are stored for debugging purposes.
When set, the component will save the session secrets in the same format as the SSLKEYLOGFILE environment variable functionality used by most major browsers and tools, such as Chrome, Firefox, and cURL. This file can then be used in tools such as Wireshark to decrypt TLS traffic for debugging purposes. When writing to this file, the component will only append, it will not overwrite previous values.
Note: This configuration setting is applicable only when SSLProvider is set to Internal.
This configuration setting returns the cipher suite negotiated during the SSL handshake.
Note: For server components (e.g., TCPServer), this is a per-connection configuration setting accessed by passing the ConnectionId. For example:
server.Config("SSLNegotiatedCipher[connId]");
This configuration setting returns the strength of the cipher suite negotiated during the SSL handshake.
Note: For server components (e.g., TCPServer), this is a per-connection configuration setting accessed by passing the ConnectionId. For example:
server.Config("SSLNegotiatedCipherStrength[connId]");
This configuration setting returns the cipher suite negotiated during the SSL handshake represented as a single string.
Note: For server components (e.g., TCPServer), this is a per-connection configuration setting accessed by passing the ConnectionId. For example:
server.Config("SSLNegotiatedCipherSuite[connId]");
This configuration setting returns the key exchange algorithm negotiated during the SSL handshake.
Note: For server components (e.g., TCPServer), this is a per-connection configuration setting accessed by passing the ConnectionId. For example:
server.Config("SSLNegotiatedKeyExchange[connId]");
This configuration setting returns the strength of the key exchange algorithm negotiated during the SSL handshake.
Note: For server components (e.g., TCPServer), this is a per-connection configuration setting accessed by passing the ConnectionId. For example:
server.Config("SSLNegotiatedKeyExchangeStrength[connId]");
This configuration setting returns the protocol version negotiated during the SSL handshake.
Note: For server components (e.g., TCPServer), this is a per-connection configuration setting accessed by passing the ConnectionId. For example:
server.Config("SSLNegotiatedVersion[connId]");
The following flags are defined (specified in hexadecimal notation). They can be ORed together to exclude multiple conditions:
0x00000001 | Ignore time validity status of certificate. |
0x00000002 | Ignore time validity status of CTL. |
0x00000004 | Ignore non-nested certificate times. |
0x00000010 | Allow unknown certificate authority. |
0x00000020 | Ignore wrong certificate usage. |
0x00000100 | Ignore unknown certificate revocation status. |
0x00000200 | Ignore unknown CTL signer revocation status. |
0x00000400 | Ignore unknown certificate authority revocation status. |
0x00000800 | Ignore unknown root revocation status. |
0x00008000 | Allow test root certificate. |
0x00004000 | Trust test root certificate. |
0x80000000 | Ignore non-matching CN (certificate CN non-matching server name). |
This functionality is currently not available in Java or when the provider is OpenSSL.
This configuration setting is only used by client components (e.g., TCPClient) see SSLClientCACerts for server components (e.g., TCPServer). This configuration setting can be used to optionally specify one or more CA certificates to be used when connecting to the server and verifying the server certificate. When verifying the server's certificate, the certificates trusted by the system will be used as part of the verification process. If the server's CA certificates are not installed to the trusted system store, they may be specified here so they are included when performing the verification process. This configuration setting should be set only if the server's CA certificates are not already trusted on the system and cannot be installed to the trusted system store.
The value of this configuration setting is a newline-separated (CR/LF) list of certificates. For instance:
-----BEGIN CERTIFICATE----- MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw ... Intermediate Cert... eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w F0I1XhM+pKj7FjDr+XNj -----END CERTIFICATE----- \r \n -----BEGIN CERTIFICATE----- MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp ... Root Cert... d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA -----END CERTIFICATE-----
This configuration setting specifies the allowed server certificate signature algorithms when SSLProvider is set to Internal 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 configuration 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:
component.SSLProvider = TCPClientSSLProviders.sslpInternal;
component.Config("SSLEnabledProtocols=3072"); //TLS 1.2
component.Config("TLS12SignatureAlgorithms=sha256-rsa,sha256-dsa,sha1-rsa,sha1-dsa");
The default value for this configuration setting is sha512-ecdsa,sha512-rsa,sha512-dsa,sha384-ecdsa,sha384-rsa,sha384-dsa,sha256-ecdsa,sha256-rsa,sha256-dsa,sha224-ecdsa,sha224-rsa,sha224-dsa,sha1-ecdsa,sha1-rsa,sha1-dsa.
To not restrict the server's certificate signature algorithm, specify an empty string as the value for this configuration setting, which will cause the signature_algorithms TLS 1.2 extension to not be sent.
This configuration 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 SSLProvider is set to Internal, the values refer to the supported groups for ECC. The following values are supported:
- "ecdhe_secp256r1" (default)
- "ecdhe_secp384r1" (default)
- "ecdhe_secp521r1" (default)
This configuration 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 roundtrip 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 configuration setting.
Note: All supported groups can always be used during the handshake even if not listed here, but if a group is used that is not present in this list, it will incur an additional roundtrip and time to generate the key share for that group.
In most cases, this configuration setting does not need to be modified. This should be modified only if there is a specific reason to do so.
The default value is ecdhe_x25519,ecdhe_secp256r1,ecdhe_secp384r1,ffdhe_2048,ffdhe_3072
The values are ordered from most preferred to least preferred. The following values are supported:
- "ecdhe_x25519" (default)
- "ecdhe_x448"
- "ecdhe_secp256r1" (default)
- "ecdhe_secp384r1" (default)
- "ecdhe_secp521r1"
- "ffdhe_2048" (default)
- "ffdhe_3072" (default)
- "ffdhe_4096"
- "ffdhe_6144"
- "ffdhe_8192"
This configuration setting holds a comma-separated list of allowed signature algorithms. Possible values include the following:
- "ed25519" (default)
- "ed448" (default)
- "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)
This configuration setting specifies a comma-separated list of named groups used in TLS 1.3 for key exchange. This configuration setting should be modified only if there is a specific reason to do so.
The default value is ecdhe_x25519,ecdhe_x448,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_x25519" (default)
- "ecdhe_x448" (default)
- "ecdhe_secp256r1" (default)
- "ecdhe_secp384r1" (default)
- "ecdhe_secp521r1" (default)
- "ffdhe_2048" (default)
- "ffdhe_3072" (default)
- "ffdhe_4096" (default)
- "ffdhe_6144" (default)
- "ffdhe_8192" (default)
Socket Config Settings
If AbsoluteTimeout is set to True, any method that 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 User Datagram Protocol (UDP) ports.
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).
This is the size of an internal queue in the Transmission Control Protocol (TCP)/IP stack. You can increase or decrease its size depending on the amount of data that you will be receiving. In some cases, increasing the value of the InBufferSize setting can provide significant improvements in performance.
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.
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. In some cases, increasing the value of the OutBufferSize setting can provide significant improvements in performance.
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 Config Settings
When queried, this setting will return a string containing information about the product's build.
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.
When queried, this setting will return a string containing information about the license this instance of a component is using. It will return the following information:
- Product: The product the license is for.
- Product Key: The key the license was generated from.
- License Source: Where the license was found (e.g., RuntimeLicense, License File).
- License Type: The type of license installed (e.g., Royalty Free, Single Server).
- Last Valid Build: The last valid build number for which the license will work.
In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to true to mask sensitive data. The default is true.
This setting only works on these components: AS3Receiver, AS3Sender, Atom, Client(3DS), FTP, FTPServer, IMAP, OFTPClient, SSHClient, SCP, Server(3DS), Sexec, SFTP, SFTPServer, SSHServer, TCPClient, TCPServer.
When set to false, the component will use the system security libraries by default to perform cryptographic functions where applicable. In this case, 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 configuration setting to true tells the component to use the internal implementation instead of using the system security libraries.
On Windows, this setting is set to false by default. On Linux/macOS, this setting is set to true by default.
If using the .NET Standard Library, this setting will be true on all platforms. The .NET Standard library does not support using the system security libraries.
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 dynamic link library (DLL) is no longer required as a reference, as all unmanaged code is stored in that file.
Trappable Errors (TSYSECommerce Component)
TSYSECommerce Errors
501 | Data field invalid length. |
502 | Data field invalid format. |
503 | Data field out of range. |
504 | Luhn digit check failed. |
505 | Card date invalid. |
506 | Card expired. |
507 | Card type unknown. |
509 | No gateway specified. |
511 | Invalid data entered. |
512 | Truncated response. |
513 | Invalid response. |
517 | Response length mismatch. |
518 | LRC check failed. |
519 | Corrupt response. |
520 | Response packet empty. |
521 | Response truncated. |
522 | Host disconnected. |
523 | No response from host. |
524 | Server error response. |
526 | Invalid timeout value. |
527 | Vital/TSYS returned an error response. |
535 | Signature verification failed. |
544 | Error building packet. |
593 | Missing or erroneous property value. Cannot send transaction. |
594 | Response received before transmission completed. |
595 | Prematurely disconnected (check Number and BankId). |
596 | Pending responses max number exceeded (Interleaved). |
597 | Pending response timeout (Interleaved). |
The component may also return one of the following error codes, which are inherited from other components.
TCPClient Errors
100 | You cannot change the RemotePort at this time. A connection is in progress. |
101 | You cannot change the RemoteHost (Server) at this time. A connection is in progress. |
102 | The RemoteHost address is invalid (0.0.0.0). |
104 | Already connected. If you want to reconnect, close the current connection first. |
106 | You cannot change the LocalPort at this time. A connection is in progress. |
107 | You cannot change the LocalHost at this time. A connection is in progress. |
112 | You cannot change MaxLineLength at this time. A connection is in progress. |
116 | RemotePort cannot be zero. Please specify a valid service port number. |
117 | You cannot change the UseConnection option while the component is active. |
135 | Operation would block. |
201 | Timeout. |
211 | Action impossible in control's present state. |
212 | Action impossible while not connected. |
213 | Action impossible while listening. |
301 | Timeout. |
303 | Could not open file. |
434 | Unable to convert string to selected CodePage. |
1105 | Already connecting. If you want to reconnect, close the current connection first. |
1117 | You need to connect first. |
1119 | You cannot change the LocalHost at this time. A connection is in progress. |
1120 | Connection dropped by remote host. |
SSL Errors
270 | Cannot load specified security library. |
271 | Cannot open certificate store. |
272 | Cannot find specified certificate. |
273 | Cannot acquire security credentials. |
274 | Cannot find certificate chain. |
275 | Cannot verify certificate chain. |
276 | Error during handshake. |
280 | Error verifying certificate. |
281 | Could not find client certificate. |
282 | Could not find server certificate. |
283 | Error encrypting data. |
284 | Error decrypting data. |
TCP/IP Errors
10004 | [10004] Interrupted system call. |
10009 | [10009] Bad file number. |
10013 | [10013] Access denied. |
10014 | [10014] Bad address. |
10022 | [10022] Invalid argument. |
10024 | [10024] Too many open files. |
10035 | [10035] Operation would block. |
10036 | [10036] Operation now in progress. |
10037 | [10037] Operation already in progress. |
10038 | [10038] Socket operation on nonsocket. |
10039 | [10039] Destination address required. |
10040 | [10040] Message is too long. |
10041 | [10041] Protocol wrong type for socket. |
10042 | [10042] Bad protocol option. |
10043 | [10043] Protocol is not supported. |
10044 | [10044] Socket type is not supported. |
10045 | [10045] Operation is not supported on socket. |
10046 | [10046] Protocol family is not supported. |
10047 | [10047] Address family is not supported by protocol family. |
10048 | [10048] Address already in use. |
10049 | [10049] Cannot assign requested address. |
10050 | [10050] Network is down. |
10051 | [10051] Network is unreachable. |
10052 | [10052] Net dropped connection or reset. |
10053 | [10053] Software caused connection abort. |
10054 | [10054] Connection reset by peer. |
10055 | [10055] No buffer space available. |
10056 | [10056] Socket is already connected. |
10057 | [10057] Socket is not connected. |
10058 | [10058] Cannot send after socket shutdown. |
10059 | [10059] Too many references, cannot splice. |
10060 | [10060] Connection timed out. |
10061 | [10061] Connection refused. |
10062 | [10062] Too many levels of symbolic links. |
10063 | [10063] File name is too long. |
10064 | [10064] Host is down. |
10065 | [10065] No route to host. |
10066 | [10066] Directory is not empty |
10067 | [10067] Too many processes. |
10068 | [10068] Too many users. |
10069 | [10069] Disc Quota Exceeded. |
10070 | [10070] Stale NFS file handle. |
10071 | [10071] Too many levels of remote in path. |
10091 | [10091] Network subsystem is unavailable. |
10092 | [10092] WINSOCK DLL Version out of range. |
10093 | [10093] Winsock is not loaded yet. |
11001 | [11001] Host not found. |
11002 | [11002] Nonauthoritative 'Host not found' (try again or check DNS setup). |
11003 | [11003] Nonrecoverable errors: FORMERR, REFUSED, NOTIMP. |
11004 | [11004] Valid name, no data record (check DNS setup). |