Retail Component

Properties   Methods   Events   Config Settings   Errors  

The Retail component is used to authorize credit card transactions with any of the supported Internet Payment Gateways.

Syntax

TibpRetail

Remarks

The Retail component allows you to use multiple Internet Payment Gateways through one interface and one component. This allows for easy migration from one gateway to another, as well as quick integration into applications or web services.

The Retail component allows your website to securely perform credit card transactions without the need to redirect to a third-party site. All transactions are accomplished through a secure HTTPS Post to any supported gateway. The secure response is received and then stored in the component's response properties. Any web site on a standard HTTP server or any stand-alone application can process transactions without the need for a secure server or third-party intervention.

The first thing you must do is select one of the many gateways supported by the Retail component, and set up an account with that gateway vendor. Once you have an account set up with a valid (or test) login Id and password, you can use the Retail component.

To begin, set the Gateway property to the gateway you wish to use. If this gateway supports an alternate URL to send test transactions to, set the GatewayURL at this time.

Next, set the MerchantLogin (and for some gateways the MerchantPassword). These are supplied by your gateway vendor when you set up an account.

Now you are ready to process transactions. For each transaction, you can set the Card and TransactionAmount properties. For swiped card transactions you can set CardMagneticStripe or for manually entered transactions you can set CardNumber, CardExpMonth, CardExpYear. Most gateways will also require additional properties, such as CustomerAddress, CustomerFirstName, CustomerLastName, InvoiceNumber, etc. Any additional required properties are listed in the Gateway property description.

Once these properties are set, you may run validity checks on the card data with the AVSOnly method, or simply authorize the transaction with the Sale method. If your Gateway supports them, you may also perform a wide variety of transaction types such as VoidTransaction, Refund, Credit, or Force. Please review the method pages for further details about these methods and their designed functionality.

The following gateways are supported by the Retail component:

Property List

---

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

Method List

---

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

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.

Config Settings

---

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

AuthCode Property (Retail Component)

Authorization code from a previous transaction.

Syntax

__property String AuthCode = { read=FAuthCode, write=FSetAuthCode };

Default Value

""

Remarks

Some gateways require the merchant to include the ResponseApprovalCode from the original transaction in Credit, VoidTransaction, and Capture transactions. You may send the original approval code in this AuthCode property. The gateways which require this are listed below:

• gwIntellipay (3)
• gwBankOfAmerica (13)
• gwInnovative (14)
• gwACHPAyments (35)
• gwForte (36)
• gwSagePay (50)
• gwDataCash (77)
• gwFirstDataE4 (80)

Data Type

String

CardType Property (Retail Component)

Type of credit card being used in this transaction.

Syntax

__property TibpRetailCardTypes CardType = { read=FCardType, write=FSetCardType };

enum TibpRetailCardTypes {
  ctUnknown=0,
  ctVisa=1,
  ctMasterCard=2,
  ctAMEX=3,
  ctDiscover=4,
  ctDiners=5,
  ctJCB=6,
  ctVisaElectron=7,
  ctMaestro=8,
  ctLaser=10
};

Default Value

ctUnknown

Remarks

Type of credit card being used in this transaction. This property contains the customer's credit card type. This is automatically computed after the CardNumber is set, but it can also be changed manually. A list of valid card types is included below.

This property is not available at design time.

Data Type

Integer

CardCVVData Property (Retail Component)

Three digit security code on back of card (optional).

Syntax

__property String CardCVVData = { read=FCardCVVData, write=FSetCardCVVData };

Default Value

""

Remarks

Three digit security code on back of card (optional).

This alphanumeric property 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 property which can be used to determine if the customer is actually in possession of the credit card.

Even if the CardCVVData is incorrect, the transaction may still be authorized. It is up to the merchant to examine the ResponseCVVResult property and decide whether to honor the transaction or not.

Note: When set to a non-empty value, CardCVVPresence will be automatically set to cvpProvided. If set to empty string (""), CardCVVPresence will be automatically set to cvpNotProvided.

This property is not available at design time.

Data Type

String

CardCVVPresence Property (Retail Component)

Indicates the presence of the card verification value.

Syntax

__property TibpRetailCardCVVPresences CardCVVPresence = { read=FCardCVVPresence, write=FSetCardCVVPresence };

enum TibpRetailCardCVVPresences {
  cvpNotProvided=0,
  cvpProvided=1,
  cvpIllegible=2,
  cvpNotOnCard=3
};

Default Value

cvpNotProvided

Remarks

Indicates the presence of the card verification value.

This property is used to indicate the presence of CardCVVData.

The component will automatically set this value to cvpProvided when a CardCVVData value is specified. You can explicitly specify the CardCVVPresence indicator by setting this property.

Available values are:

• cvpNotProvided (0)
• cvpProvided (1)
• cvpIllegible (2)
• cvpNotOnCard (3)

This property is not available at design time.

Data Type

Integer

CardEntryDataSource Property (Retail Component)

This property contains a 1-character code identifying the source of the customer data.

Syntax

__property TibpRetailCardEntryDataSources CardEntryDataSource = { read=FCardEntryDataSource, write=FSetCardEntryDataSource };

enum TibpRetailCardEntryDataSources {
  edsTrack1=0,
  edsTrack2=1,
  edsManualEntryTrack1Capable=2,
  edsManualEntryTrack2Capable=3,
  edsManualEntryNoCardReader=4,
  edsTrack1Contactless=5,
  edsTrack2Contactless=6,
  edsManualEntryContactlessCapable=7,
  edsIVR=8,
  edsKiosk=9
};

Default Value

edsTrack1

Remarks

This property contains a 1-character code identifying the source of the customer data. The table below shows all supported values for this property.

This property is not available at design time.

Data Type

Integer

CardExpMonth Property (Retail Component)

Expiration month of the credit card specified in Number .

Syntax

__property int CardExpMonth = { read=FCardExpMonth, write=FSetCardExpMonth };

Default Value

1

Remarks

Expiration month of the credit card specified in CardNumber.

This property contains the expiration date of the customer's credit card, and must be in the range 1 - 12.

This property is not available at design time.

Data Type

Integer

CardExpYear Property (Retail Component)

Expiration year of the credit card specified in Number .

Syntax

__property int CardExpYear = { read=FCardExpYear, write=FSetCardExpYear };

Default Value

2000

Remarks

Expiration year of the credit card specified in CardNumber.

This property contains the expiration date of the customer's credit card. This property must be in the range 0 - 99, or 2000 - 2099. Any date before the year 2000 or after 2099 cannot be specified.

This property is not available at design time.

Data Type

Integer

CardIsEncrypted Property (Retail Component)

Determines whether data set to the Number or MagneticStripe properties is validated.

Syntax

__property bool CardIsEncrypted = { read=FCardIsEncrypted, write=FSetCardIsEncrypted };

Default Value

false

Remarks

Determines whether data set to the CardNumber or CardMagneticStripe fields is validated.

By default, when the CardNumber or CardMagneticStripe fields are set, the value will be validated and normalized. For instance, "4444-33332222 1111" will be normalized as "4444333322221111" and CardMagneticStripe data will be parsed for the track specified by CardEntryDataSource. 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 CardNumber or CardMagneticStripe 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.

This property is not available at design time.

Data Type

Boolean

CardMagneticStripe Property (Retail Component)

Track data read off of the card's magnetic stripe.

Syntax

__property String CardMagneticStripe = { read=FCardMagneticStripe, write=FSetCardMagneticStripe };

Default Value

""

Remarks

Track data read off of the card's magnetic stripe.

If CardEntryDataSource is not one of the manually entered enumerations, then this property 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 property with track 1 or track 2 data, and may not pass both. Use the CardEntryDataSource property to indicate which track you are sending.

The following example shows how to set the CardMagneticStripe and CardEntryDataSource properties if the data read off the card is "%B4788250000028291^TSYS^05121015432112345678?;4788250000028291=05121015432112345678?"

component.CardMagneticStripe = "B4788250000028291^TSYS^05121015432112345678" component.CardEntryDataSource = edsTrack1 or component.CardMagneticStripe = "4788250000028291=05121015432112345678" component.CardEntryDataSource = edsTrack2

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.

This property is not available at design time.

Data Type

String

CardNumber Property (Retail Component)

Customer's credit card number for the transaction.

Syntax

__property String CardNumber = { read=FCardNumber, write=FSetCardNumber };

Default Value

""

Remarks

Customer's credit card number for the transaction.

If you're sending the transaction with CardMagneticStripe data, this property should be left empty.

This property is not available at design time.

Data Type

String

CustomerAddress Property (Retail Component)

Customer's street address.

Syntax

__property String CustomerAddress = { read=FCustomerAddress, write=FSetCustomerAddress };

Default Value

""

Remarks

Customer's street address. This property 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 property. City, state, and zip code are set in the CustomerCity, CustomerState, and CustomerZip properties.

The length of this property varies by gateway. If the customer's address is very long, it is admissible to include only the street number in This property.

NOTE: For the Moneris gateway, this property should contain only the customer's street number. The street name should be added via the AddSpecialField method. For example:

component.CustomerAddress = "123" component.AddSpecialField("avs_street_name", "Nowhere Ln")

This property is not available at design time.

Data Type

String

CustomerAddress2 Property (Retail Component)

A specific detail on the customer's shipping address (such as building, suite, apartment, floor number etc.

Syntax

__property String CustomerAddress2 = { read=FCustomerAddress2, write=FSetCustomerAddress2 };

Default Value

""

Remarks

A specific detail on the customer's shipping address (such as building, suite, apartment, floor number etc.).

This property is not available at design time.

Data Type

String

CustomerAggregate Property (Retail Component)

This property allows you to get or set an XML aggregate built from all of the Customer properties.

Syntax

__property String CustomerAggregate = { read=FCustomerAggregate, write=FSetCustomerAggregate };

Default Value

""

Remarks

This property allows you to get or set an XML aggregate built from all of the Customer properties. "EPCustomer" is the root element. The Customer properties make up the tags under the root, but without the beginning "Customer". For instance: <EPCustomer> <Address>123 Nowhere Ln.</Address> <Address2>Apt 3B.</Address2> <City>Beverly Hills</City> ... </EPCustomer>

This property is not available at design time.

Data Type

String

CustomerCity Property (Retail Component)

Customer's city.

Syntax

__property String CustomerCity = { read=FCustomerCity, write=FSetCustomerCity };

Default Value

""

Remarks

Customer's city. This property is used as part of the Address Verification Service (AVS) and contains the customer's city as it appears on their monthly statement. Other AVS properties include CustomerAddress, CustomerState, and CustomerZip.

This property is not available at design time.

Data Type

String

CustomerCountry Property (Retail Component)

Customer's country.

Syntax

__property String CustomerCountry = { read=FCustomerCountry, write=FSetCustomerCountry };

Default Value

""

Remarks

Customer's country. This property contains the country in which the customer is located. Most gateways use a two-letter country code, specified in ISO-3166.

Note: If using this property with the PayFuse gateway, this property should contain the ISO-3166 numeric code instead of the standard two-letter code. For example, the ISO code for the US is "840".

This property is not available at design time.

Data Type

String

CustomerEmail Property (Retail Component)

Customer's email address.

Syntax

__property String CustomerEmail = { read=FCustomerEmail, write=FSetCustomerEmail };

Default Value

""

Remarks

Customer's email address. This optional property contains the customer's email address.

This property is not available at design time.

Data Type

String

CustomerFax Property (Retail Component)

Customer's fax number.

Syntax

__property String CustomerFax = { read=FCustomerFax, write=FSetCustomerFax };

Default Value

""

Remarks

Customer's fax number. This optional property contains the customer's fax number.

This property is not available at design time.

Data Type

String

CustomerFirstName Property (Retail Component)

Customer's first name.

Syntax

__property String CustomerFirstName = { read=FCustomerFirstName, write=FSetCustomerFirstName };

Default Value

""

Remarks

Customer's first name. This property contains the customer's first name.

This property is not available at design time.

Data Type

String

CustomerFullName Property (Retail Component)

Customer's full name.

Syntax

__property String CustomerFullName = { read=FCustomerFullName, write=FSetCustomerFullName };

Default Value

""

Remarks

Customer's full name. This property contains the customer's full name as it appears on the credit card or bank account. Many gateways use this property in addition to, or instead of, the CustomerFirstName and CustomerLastName properties. If a gateway requires a CustomerFullName and the property is empty, CustomerFullName will be constructed using the contents of CustomerFirstName and CustomerLastName.

This property is not available at design time.

Data Type

String

CustomerId Property (Retail Component)

Merchant-generated customer Id.

Syntax

__property String CustomerId = { read=FCustomerId, write=FSetCustomerId };

Default Value

""

Remarks

Merchant-generated customer Id. This property contains a merchant-generated customer identification number. This number should be unique for each different customer that places an order with the merchant.

This property is not available at design time.

Data Type

String

CustomerLastName Property (Retail Component)

Customer's last name.

Syntax

__property String CustomerLastName = { read=FCustomerLastName, write=FSetCustomerLastName };

Default Value

""

Remarks

Customer's last name. This property contains the customer's last name as it appears on their credit card.

This property is not available at design time.

Data Type

String

CustomerPhone Property (Retail Component)

Customer's phone number.

Syntax

__property String CustomerPhone = { read=FCustomerPhone, write=FSetCustomerPhone };

Default Value

""

Remarks

Customer's phone number. This optional property contains the customer's phone number.

This property is not available at design time.

Data Type

String

CustomerState Property (Retail Component)

Customer's state.

Syntax

__property String CustomerState = { read=FCustomerState, write=FSetCustomerState };

Default Value

""

Remarks

Customer's state. This property is used as part of the Address Verification Service (AVS) and contains the two character postal abbreviation of the customer's state as it appears on their monthly statement. Other AVS properties include CustomerAddress, CustomerCity, and CustomerZip.

This property is not available at design time.

Data Type

String

CustomerZip Property (Retail Component)

Customer's zip code (or postal code if outside of the USA).

Syntax

__property String CustomerZip = { read=FCustomerZip, write=FSetCustomerZip };

Default Value

""

Remarks

Customer's zip code (or postal code if outside of the USA). This property is used as part of the Address Verification Service (AVS), and contains the customer's zip code as it appears on their monthly statement. Other AVS properties include CustomerAddress, CustomerCity, and CustomerState.

This property is not available at design time.

Data Type

String

Gateway Property (Retail Component)

Gateway to process transactions with.

Syntax

__property TibpRetailGateways Gateway = { read=FGateway, write=FSetGateway };

enum TibpRetailGateways {
  rgwNoGateway=0,
  rgwAuthorizeNet=1,
  rgwEprocessing=2,
  rgwITransact=4,
  rgwNetBilling=5,
  rgwPayFlowPro=6,
  rgwUSAePay=7,
  rgwPlugNPay=8,
  rgwPlanetPayment=9,
  rgwMPCS=10,
  rgwRTWare=11,
  rgwECX=12,
  rgwBankOfAmerica=13,
  rgwMerchantAnywhere=15,
  rgwSkipjack=16,
  rgwTrustCommerce=19,
  rgwPayFuse=21,
  rgwLinkPoint=24,
  rgwFastTransact=27,
  rgwNetworkMerchants=28,
  rgwPRIGate=30,
  rgwMerchantPartners=31,
  rgwFirstData=33,
  rgwYourPay=34,
  rgwACHPAyments=35,
  rgwForte=36,
  rgwCyberSource=37,
  rgwGoEMerchant=39,
  rgwChase=41,
  rgwNexCommerce=42,
  rgwTransactionCentral=44,
  rgwSterling=45,
  rgwPayJunction=46,
  rgwMyVirtualMerchant=49,
  rgwVerifi=54,
  rgwMerchantESolutions=56,
  rgwPayLeap=57,
  rgwWorldPayXML=59,
  rgwProPay=60,
  rgwQBMS=61,
  rgwHeartland=62,
  rgwLitle=63,
  rgwBrainTree=64,
  rgwJetPay=65,
  rgwHSBC=66,
  rgwBluePay=67,
  rgwPayTrace=70,
  rgwTransNationalBankcard=74,
  rgwFirstDataE4=80,
  rgwBluefin=82,
  rgwPayscape=83,
  rgwPayDirect=84,
  rgwWorldPayLink=87,
  rgwPaymentWorkSuite=88,
  rgwFirstDataPayPoint=90,
  rgwPayeezy=94,
  rgwAuthorizeNetXML=96,
  rgwPhoeniXGate=97,
  rgwRepay=98,
  rgwBASYS=106,
  rgwQBPayments=113,
  rgwShift4=114,
  rgwHeartlandPortico=116,
  rgwPayTraceJSON=117
};

Default Value

rgwNoGateway

Remarks

This property is used to select the gateway with which transactions will be processed. Setting the Gateway property will also fill the GatewayURL, SpecialFieldName, and SpecialFieldValue properties with default data for the selected gateway. The following table shows the currently supported gateways, as well as the corporate home page for each.

Data Type

Integer

GatewayURL Property (Retail Component)

Default URL for a specific Gateway .

Syntax

__property String GatewayURL = { read=FGatewayURL, write=FSetGatewayURL };

Default Value

""

Remarks

This property is used to change the default URL for a specific Gateway. This is useful for specifying a different URL for testing purposes, or to support additional gateway processors that share a protocol format (such as additional Authorize.net compatible gateways). Please note that the proper "http://" or "https://" formatting must be observed. See "Testing Information" in the Table of Contents for a list of test URLs.

Data Type

String

InvoiceNumber Property (Retail Component)

Merchant-generated invoice number.

Syntax

__property String InvoiceNumber = { read=FInvoiceNumber, write=FSetInvoiceNumber };

Default Value

""

Remarks

This field contains a merchant-generated invoice number. This number should be unique for each transaction. This property is optional for most gateways, but it is recommended that the merchant use an invoice number to keep track of transactions. See the Gateway property to determine if this is a required or optional field for the gateway you are using.

Data Type

String

Level2Aggregate Property (Retail Component)

The level 2 aggregate containing the data to be sent in the request.

Syntax

__property String Level2Aggregate = { read=FLevel2Aggregate, write=FSetLevel2Aggregate };

Default Value

""

Remarks

This property is used to specify the level 2 aggregate obtained from Level2 component. When specified, the component will parse the aggregate and send the specified values within the transaction request to process the transaction as a level 2 transaction.

Data Type

String

Level3Aggregate Property (Retail Component)

The level 3 aggregate containing the data to be sent in the request.

Syntax

__property String Level3Aggregate = { read=FLevel3Aggregate, write=FSetLevel3Aggregate };

Default Value

""

Remarks

This property is used to specify the level 3 aggregate obtained from Level3 component. When specified, the component will parse the aggregate and send the specified values within the transaction request to process the transaction as a level 3 transaction.

Data Type

String

MerchantLogin Property (Retail Component)

Merchant's Gateway login.

Syntax

__property String MerchantLogin = { read=FMerchantLogin, write=FSetMerchantLogin };

Default Value

""

Remarks

This is the login Id supplied by the Gateway you signed up with to process credit card transactions.

Data Type

String

MerchantPassword Property (Retail Component)

Merchant's Gateway password.

Syntax

__property String MerchantPassword = { read=FMerchantPassword, write=FSetMerchantPassword };

Default Value

""

Remarks

This is the password supplied by the Gateway you signed up with to process credit card transactions. Some gateways require passwords only for Credit or Void transactions, some require it for all transactions, and some do not require this field at all.

Data Type

String

ProxyAuthScheme Property (Retail Component)

The type of authorization to perform when connecting to the proxy.

Syntax

__property TibpRetailProxyAuthSchemes ProxyAuthScheme = { read=FProxyAuthScheme, write=FSetProxyAuthScheme };

enum TibpRetailProxyAuthSchemes {
  authBasic=0,
  authDigest=1,
  authProprietary=2,
  authNone=3,
  authNtlm=4,
  authNegotiate=5
};

Default Value

authBasic

Remarks

The type of authorization to perform when connecting to the proxy. This is used only when the ProxyUser and ProxyPassword properties are set.

ProxyAuthScheme should be set to authNone (3) when no authentication is expected.

By default, ProxyAuthScheme is authBasic (0), and if the ProxyUser and ProxyPassword properties are set, the component will attempt basic authentication.

If ProxyAuthScheme is set to authDigest (1), digest authentication will be attempted instead.

If ProxyAuthScheme is set to authProprietary (2), then the authorization token will not be generated by the component. Look at the configuration file for the component being used to find more information about manually setting this token.

If ProxyAuthScheme is set to authNtlm (4), NTLM authentication will be used.

For security reasons, setting this property will clear the values of ProxyUser and ProxyPassword.

Data Type

Integer

ProxyAutoDetect Property (Retail Component)

Whether to automatically detect and use proxy system settings, if available.

Syntax

__property bool ProxyAutoDetect = { read=FProxyAutoDetect, write=FSetProxyAutoDetect };

Default Value

False

Remarks

Whether to automatically detect and use proxy system settings, if available. The default value is false.

Data Type

Boolean

ProxyPassword Property (Retail Component)

A password if authentication is to be used for the proxy.

Syntax

__property String ProxyPassword = { read=FProxyPassword, write=FSetProxyPassword };

Default Value

""

Remarks

A password if authentication is to be used for the proxy.

If ProxyAuthScheme is set to Basic Authentication, the ProxyUser and ProxyPassword properties are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If ProxyAuthScheme is set to Digest Authentication, the ProxyUser and ProxyPassword properties are used to respond to the Digest Authentication challenge from the server.

If ProxyAuthScheme is set to NTLM Authentication, the ProxyUser and ProxyPassword properties are used to authenticate through NTLM negotiation.

Data Type

String

ProxyPort Property (Retail Component)

The Transmission Control Protocol (TCP) port for the proxy Server (default 80).

Syntax

__property int ProxyPort = { read=FProxyPort, write=FSetProxyPort };

Default Value

80

Remarks

The Transmission Control Protocol (TCP) port for the proxy ProxyServer (default 80). See the description of the ProxyServer property for details.

Data Type

Integer

ProxyServer Property (Retail Component)

If a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

Syntax

__property String ProxyServer = { read=FProxyServer, write=FSetProxyServer };

Default Value

""

Remarks

If a proxy ProxyServer is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

If the ProxyServer property is set to a domain name, a DNS request is initiated. Upon successful termination of the request, the ProxyServer property is set to the corresponding address. If the search is not successful, an error is returned.

Data Type

String

ProxySSL Property (Retail Component)

When to use a Secure Sockets Layer (SSL) for the connection to the proxy.

Syntax

__property TibpRetailProxySSLs ProxySSL = { read=FProxySSL, write=FSetProxySSL };

enum TibpRetailProxySSLs {
  psAutomatic=0,
  psAlways=1,
  psNever=2,
  psTunnel=3
};

Default Value

psAutomatic

Remarks

When to use a Secure Sockets Layer (SSL) for the connection to the proxy. The applicable values are as follows:

Data Type

Integer

ProxyUser Property (Retail Component)

A username if authentication is to be used for the proxy.

Syntax

__property String ProxyUser = { read=FProxyUser, write=FSetProxyUser };

Default Value

""

Remarks

A username if authentication is to be used for the proxy.

If ProxyAuthScheme is set to Basic Authentication, the ProxyUser and ProxyPassword properties are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If ProxyAuthScheme is set to Digest Authentication, the ProxyUser and ProxyPassword properties are used to respond to the Digest Authentication challenge from the server.

If ProxyAuthScheme is set to NTLM Authentication, the ProxyUser and ProxyPassword properties are used to authenticate through NTLM negotiation.

Data Type

String

ResponseApprovalCode Property (Retail Component)

Contains an authorization code when a transaction has been approved.

Syntax

__property String ResponseApprovalCode = { read=FResponseApprovalCode };

Default Value

""

Remarks

Contains an authorization code when a transaction has been approved. This property contains an authorization code when a transaction has been approved. If the ResponseCode returned indicates that the transaction is not approved, then the contents of this property should be ignored.

This property is read-only and not available at design time.

Data Type

String

ResponseApproved Property (Retail Component)

Indicates the status of the last transaction.

Syntax

__property bool ResponseApproved = { read=FResponseApproved };

Default Value

false

Remarks

Indicates the status of the last transaction. This property will be True if the last transaction was approved. However, you should not rely solely on the value contained in this property. After every transaction, the ResponseCode should be inspected and evaluated according to the specifications of the Gateway in use. A list of response codes for each gateway is listed in the table of contents. However, it is recommended that the developer acquire the current list from the Gateway which is being used.

This property is read-only and not available at design time.

Data Type

Boolean

ResponseApprovedAmount Property (Retail Component)

The amount approved for the transaction, this is the amount actually charged to the credit card.

Syntax

__property String ResponseApprovedAmount = { read=FResponseApprovedAmount };

Default Value

""

Remarks

The amount approved for the transaction, this is the amount actually charged to the credit card.

This property is primarily used when gateways allow partial authorizations and AllowPartialAuths is 'True'. Thus this property is not used by all gateways and should not alone be used to determine if a transaction was successful (such as in the case that this property is not populated).

This property is read-only and not available at design time.

Data Type

String

ResponseAVSResult Property (Retail Component)

Contains the Address Verification System result code.

Syntax

__property String ResponseAVSResult = { read=FResponseAVSResult };

Default Value

""

Remarks

Contains the Address Verification System result code. This one character property contains the Address Verification Service (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 for later retrieval, as it may be required when voiding or refunding a transaction. Valid AVS response codes are listed below, and are identical across all Gateway (note that some gateways do not return an AVS response).

Note: Some gateways use their own response codes instead of those in the above table; those response codes are detailed below for such gateways.

Adyen

For Adyen, this property will contain the following possible values:

American Payment Solutions

For American Payment Solutions, this property will contain the following possible values:

Barclay

For Barclay, the property will contain the following possible values:

BlueSnap

For BlueSnap, the property will contain a 3-character string (if AVS checks were done), which contains the AVS checks for the following properties:

The possible values for each result character are:

HSBC

For HSBC, the property will contain the following possible values:

PayTrace / PayTraceJSON

For PayTrace / PayTraceJSON, the property will contain the following possible values:

QBMS

For the QBMS gateway, the ResponseAVSResult property will contain the result for the street address, a comma, and then the result for the zip code. The values returned are "Pass", "Fail", and "NotAvailable". Therefore, an ResponseAVSResult of "Fail,Pass" means that the street address failed validation, but the zip code passed.

DataCash

For DataCash, the property will contain the following possible values (of which correspond to both AVS and CVV checks):

Stripe

For Stripe, the property will contain the following possible values:

Worldpay

For Worldpay, the property will contain a 4-character string, which contains the AVS checks for the following properties:

The possible values for each result character are:

Worldpay Online

For Worldpay Online, the property will contain one of the following:

This property is read-only and not available at design time.

Data Type

String

ResponseCode Property (Retail Component)

Indicates the status of the authorization request.

Syntax

__property String ResponseCode = { read=FResponseCode };

Default Value

""

Remarks

Indicates the status of the authorization request. This property contains the actual response code as returned by the Gateway. Unlike the ResponseApproved property, this ResponseCode property may provide more details about why a transaction was declined. Therefore, it is recommended that developers check the ResponseCode as well as the ResponseApproved property. The Point of Sale system should evaluate this response code and NOT the ResponseText to determine nature of a response message. The current (at the time of this release) response codes for the supported Gateways are listed in the table of contents to your left.

This property is read-only and not available at design time.

Data Type

String

ResponseCVVResult Property (Retail Component)

Contains the returned CVV2 result code if it was requested.

Syntax

__property String ResponseCVVResult = { read=FResponseCVVResult };

Default Value

""

Remarks

Contains the returned CVV2 result code if it was requested. This property contains the host returned CVV2 result code (if CVV data was sent in the request). The following is a list of current result codes:

A gateway may also support custom codes or human-readable response messages in this property. Please consult your gateway documentation to determine if CVV2 codes are supported.

Note: Some gateways use their own response codes instead of those in the above table; those response codes are detailed below for such gateways.

HSBC

For HSBC, the property will contain:

Adyen

For Adyen, the property will contain:

Barclay

For Barclay, the property will contain:

BlueSnap

For BlueSnap, the property will contain:

(Note: There are some scenarios in which the property will be empty instead, refer to BlueSnap's documentation for more details.)

DataCash

For DataCash, the property will contain the following possible values (of which correspond to both AVS and CVV checks):

Stripe

For Stripe, the property will contain the following possible values:

Worldpay Online

For Worldpay Online, the property will contain one of the following:

This property is read-only and not available at design time.

Data Type

String

ResponseData Property (Retail Component)

The entire response returned from the gateway processor.

Syntax

__property String ResponseData = { read=FResponseData };

Default Value

""

Remarks

The entire response returned from the gateway processor. This property contains the entire response returned from the gateway processor. You may use this to parse additional information that is not returned in the standard response properties.

This property is read-only and not available at design time.

Data Type

String

ResponseErrorCode Property (Retail Component)

Additional error code returned by some gateways.

Syntax

__property String ResponseErrorCode = { read=FResponseErrorCode };

Default Value

""

Remarks

Additional error code returned by some gateways. If a gateway returns it, this property will contain an additional code that may explain why the transaction was declined. You may also wish to inspect ResponseErrorText for a human-readable description of this ResponseErrorCode.

This property is read-only and not available at design time.

Data Type

String

ResponseErrorText Property (Retail Component)

Additional error description returned by some gateways.

Syntax

__property String ResponseErrorText = { read=FResponseErrorText };

Default Value

""

Remarks

Additional error description returned by some gateways. If a gateway returns it, this property will contain a human-readable description of the error which occurred (if any). You may also wish to inspect ResponseErrorCode for an accompanying code which may be parsed and used by your application.

This property is read-only and not available at design time.

Data Type

String

ResponseInvoiceNumber Property (Retail Component)

Invoice number submitted in authorization request (if applicable).

Syntax

__property String ResponseInvoiceNumber = { read=FResponseInvoiceNumber };

Default Value

""

Remarks

Invoice number submitted in authorization request (if applicable). This property contains the Invoice Number submitted in the original transaction, echoed back by the Gateway host.

This property is read-only and not available at design time.

Data Type

String

ResponseProcessorCode Property (Retail Component)

Response code from the underlying processor.

Syntax

__property String ResponseProcessorCode = { read=FResponseProcessorCode };

Default Value

""

Remarks

Response code from the underlying processor. Often times a Gateway will return a ResponseCode that indicates only whether the transaction is approved or declined. Many of these also include a secondary code that provides more details as to why the transaction was declined.

Note, for the PayFlowPro Gateway this property will contain a "1" if the transaction was a duplicate, a "-1" if duplicate checking service is unavailable, and will be blank for a successfully authorized transaction.

This property is read-only and not available at design time.

Data Type

String

ResponseText Property (Retail Component)

Text information that describes each response code.

Syntax

__property String ResponseText = { read=FResponseText };

Default Value

""

Remarks

Text information that describes each response code. This property contains a response or display text message. This message can be used by the terminal to display the authorization result. The display text must not be used to determine the nature of a response message. A Gateway may translate the response according to the language indicated in the merchant account setup (if applicable).

This property is read-only and not available at design time.

Data Type

String

ResponseTransactionId Property (Retail Component)

Contains the Visa Transaction Identifier or MasterCard Reference Number.

Syntax

__property String ResponseTransactionId = { read=FResponseTransactionId };

Default Value

""

Remarks

Contains the Visa Transaction Identifier or MasterCard Reference Number. This property contains a transaction identifier or reference number. The Point of Sale (POS) device should not attempt to interpret the meaning of any data appearing in this property. Data returned in this property (if any) should be recorded and used to submit a modification of this transaction at a later time (such as voiding the transaction or capturing an authorization-only transaction, if applicable).

This property is read-only and not available at design time.

Data Type

String

ShippingAddress Property (Retail Component)

Customer's shipping street address.

Syntax

__property String ShippingAddress = { read=FShippingAddress, write=FSetShippingAddress };

Default Value

""

Remarks

Customer's shipping street address.

This property is not available at design time.

Data Type

String

ShippingAddress2 Property (Retail Component)

A specific detail on the customer's shipping address (such as building, suite, apartment, floor number etc.

Syntax

__property String ShippingAddress2 = { read=FShippingAddress2, write=FSetShippingAddress2 };

Default Value

""

Remarks

A specific detail on the customer's shipping address (such as building, suite, apartment, floor number etc.).

This property is not available at design time.

Data Type

String

ShippingCity Property (Retail Component)

Customer's shipping city.

Syntax

__property String ShippingCity = { read=FShippingCity, write=FSetShippingCity };

Default Value

""

Remarks

Customer's shipping city.

This property is not available at design time.

Data Type

String

ShippingCountry Property (Retail Component)

Customer's shipping country.

Syntax

__property String ShippingCountry = { read=FShippingCountry, write=FSetShippingCountry };

Default Value

""

Remarks

Customer's shipping country. This property contains the country in which the customer is located. Most gateways use a two-letter country code, specified in ISO-3166.

This property is not available at design time.

Data Type

String

ShippingEmail Property (Retail Component)

Customer's email address.

Syntax

__property String ShippingEmail = { read=FShippingEmail, write=FSetShippingEmail };

Default Value

""

Remarks

Customer's email address.

This property is not available at design time.

Data Type

String

ShippingFirstName Property (Retail Component)

Customer's first name.

Syntax

__property String ShippingFirstName = { read=FShippingFirstName, write=FSetShippingFirstName };

Default Value

""

Remarks

Customer's first name.

This property is not available at design time.

Data Type

String

ShippingLastName Property (Retail Component)

Customer's last name.

Syntax

__property String ShippingLastName = { read=FShippingLastName, write=FSetShippingLastName };

Default Value

""

Remarks

Customer's last name.

This property is not available at design time.

Data Type

String

ShippingPhone Property (Retail Component)

Customer's phone number.

Syntax

__property String ShippingPhone = { read=FShippingPhone, write=FSetShippingPhone };

Default Value

""

Remarks

Customer's phone number.

This property is not available at design time.

Data Type

String

ShippingState Property (Retail Component)

Customer's shipping state.

Syntax

__property String ShippingState = { read=FShippingState, write=FSetShippingState };

Default Value

""

Remarks

Customer's shipping state.

This property is not available at design time.

Data Type

String

ShippingZip Property (Retail Component)

Customer's shipping zip code (or postal code if outside of the USA).

Syntax

__property String ShippingZip = { read=FShippingZip, write=FSetShippingZip };

Default Value

""

Remarks

Customer's shipping zip code (or postal code if outside of the USA).

This property is not available at design time.

Data Type

String

SpecialFieldCount Property (Retail Component)

The number of records in the SpecialField arrays.

Syntax

__property int SpecialFieldCount = { read=FSpecialFieldCount, write=FSetSpecialFieldCount };

Default Value

0

Remarks

This property controls the size of the following arrays:

• SpecialFieldName
• SpecialFieldValue

The array indices start at 0 and end at SpecialFieldCount - 1.

This property is not available at design time.

Data Type

Integer

SpecialFieldName Property (Retail Component)

Name of special configuration property to submit in this transaction.

Syntax

__property String SpecialFieldName[int FieldIndex] = { read=FSpecialFieldName, write=FSetSpecialFieldName };

Default Value

""

Remarks

Name of special configuration field to submit in this transaction. The SpecialFieldName and SpecialFieldValue properties can be used to send special gateway configuration and transaction properties for each transaction. These properties can also be used to extend the functionality of this component by submitting additional information to the gateway.

This property is not applicable for the LinkPoint, FirstData, YourPay, PayFuse, or Orbital gateways.

The FieldIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SpecialFieldCount property.

This property is not available at design time.

Data Type

String

SpecialFieldValue Property (Retail Component)

Value of special configuration property to submit in this transaction.

Syntax

__property String SpecialFieldValue[int FieldIndex] = { read=FSpecialFieldValue, write=FSetSpecialFieldValue };

Default Value

""

Remarks

Value of special configuration field to submit in this transaction. The SpecialFieldName and SpecialFieldValue properties can be used to send special gateway configuration and transaction properties for each transaction. These properties can also be used to extend the functionality of this component by submitting additional information to the gateway.

Note: This property is not applicable for the LinkPoint, FirstData, YourPay, PayFuse, or Orbital gateways.

The FieldIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SpecialFieldCount property.

This property is not available at design time.

Data Type

String

SSLAcceptServerCertEffectiveDate Property (Retail Component)

The date on which this certificate becomes valid.

Syntax

__property String SSLAcceptServerCertEffectiveDate = { read=FSSLAcceptServerCertEffectiveDate };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLAcceptServerCertExpirationDate Property (Retail Component)

The date on which the certificate expires.

Syntax

__property String SSLAcceptServerCertExpirationDate = { read=FSSLAcceptServerCertExpirationDate };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLAcceptServerCertExtendedKeyUsage Property (Retail Component)

A comma-delimited list of extended key usage identifiers.

Syntax

__property String SSLAcceptServerCertExtendedKeyUsage = { read=FSSLAcceptServerCertExtendedKeyUsage };

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

SSLAcceptServerCertFingerprint Property (Retail Component)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

__property String SSLAcceptServerCertFingerprint = { read=FSSLAcceptServerCertFingerprint };

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

SSLAcceptServerCertFingerprintSHA1 Property (Retail Component)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

__property String SSLAcceptServerCertFingerprintSHA1 = { read=FSSLAcceptServerCertFingerprintSHA1 };

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

SSLAcceptServerCertFingerprintSHA256 Property (Retail Component)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

__property String SSLAcceptServerCertFingerprintSHA256 = { read=FSSLAcceptServerCertFingerprintSHA256 };

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

SSLAcceptServerCertIssuer Property (Retail Component)

The issuer of the certificate.

Syntax

__property String SSLAcceptServerCertIssuer = { read=FSSLAcceptServerCertIssuer };

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

SSLAcceptServerCertPrivateKey Property (Retail Component)

The private key of the certificate (if available).

Syntax

__property String SSLAcceptServerCertPrivateKey = { read=FSSLAcceptServerCertPrivateKey };

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The SSLAcceptServerCertPrivateKey may be available but not exportable. In this case, SSLAcceptServerCertPrivateKey returns an empty string.

This property is read-only.

Data Type

String

SSLAcceptServerCertPrivateKeyAvailable Property (Retail Component)

Whether a PrivateKey is available for the selected certificate.

Syntax

__property bool SSLAcceptServerCertPrivateKeyAvailable = { read=FSSLAcceptServerCertPrivateKeyAvailable };

Default Value

false

Remarks

Whether a SSLAcceptServerCertPrivateKey is available for the selected certificate. If SSLAcceptServerCertPrivateKeyAvailable is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

Boolean

SSLAcceptServerCertPrivateKeyContainer Property (Retail Component)

The name of the PrivateKey container for the certificate (if available).

Syntax

__property String SSLAcceptServerCertPrivateKeyContainer = { read=FSSLAcceptServerCertPrivateKeyContainer };

Default Value

""

Remarks

The name of the SSLAcceptServerCertPrivateKey container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

SSLAcceptServerCertPublicKey Property (Retail Component)

The public key of the certificate.

Syntax

__property String SSLAcceptServerCertPublicKey = { read=FSSLAcceptServerCertPublicKey };

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

SSLAcceptServerCertPublicKeyAlgorithm Property (Retail Component)

The textual description of the certificate's public key algorithm.

Syntax

__property String SSLAcceptServerCertPublicKeyAlgorithm = { read=FSSLAcceptServerCertPublicKeyAlgorithm };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLAcceptServerCertPublicKeyLength Property (Retail Component)

The length of the certificate's public key (in bits).

Syntax

__property int SSLAcceptServerCertPublicKeyLength = { read=FSSLAcceptServerCertPublicKeyLength };

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

Integer

SSLAcceptServerCertSerialNumber Property (Retail Component)

The serial number of the certificate encoded as a string.

Syntax

__property String SSLAcceptServerCertSerialNumber = { read=FSSLAcceptServerCertSerialNumber };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLAcceptServerCertSignatureAlgorithm Property (Retail Component)

The text description of the certificate's signature algorithm.

Syntax

__property String SSLAcceptServerCertSignatureAlgorithm = { read=FSSLAcceptServerCertSignatureAlgorithm };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLAcceptServerCertStore Property (Retail Component)

The name of the certificate store for the client certificate.

Syntax

__property String SSLAcceptServerCertStore = { read=FSSLAcceptServerCertStore, write=FSetSSLAcceptServerCertStore };
__property DynamicArray<Byte> SSLAcceptServerCertStoreB = { read=FSSLAcceptServerCertStoreB, write=FSetSSLAcceptServerCertStoreB };

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The SSLAcceptServerCertStoreType property denotes the type of the certificate store specified by SSLAcceptServerCertStore. If the store is password-protected, specify the password in SSLAcceptServerCertStorePassword.

SSLAcceptServerCertStore is used in conjunction with the SSLAcceptServerCertSubject property to specify client certificates. If SSLAcceptServerCertStore has a value, and SSLAcceptServerCertSubject or SSLAcceptServerCertEncoded is set, a search for a certificate is initiated. Please see the SSLAcceptServerCertSubject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

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

Data Type

Byte Array

SSLAcceptServerCertStorePassword Property (Retail Component)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

__property String SSLAcceptServerCertStorePassword = { read=FSSLAcceptServerCertStorePassword, write=FSetSSLAcceptServerCertStorePassword };

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Data Type

String

SSLAcceptServerCertStoreType Property (Retail Component)

The type of certificate store for this certificate.

Syntax

__property TibpRetailSSLAcceptServerCertStoreTypes SSLAcceptServerCertStoreType = { read=FSSLAcceptServerCertStoreType, write=FSetSSLAcceptServerCertStoreType };

enum TibpRetailSSLAcceptServerCertStoreTypes {
  cstUser=0,
  cstMachine=1,
  cstPFXFile=2,
  cstPFXBlob=3,
  cstJKSFile=4,
  cstJKSBlob=5,
  cstPEMKeyFile=6,
  cstPEMKeyBlob=7,
  cstPublicKeyFile=8,
  cstPublicKeyBlob=9,
  cstSSHPublicKeyBlob=10,
  cstP7BFile=11,
  cstP7BBlob=12,
  cstSSHPublicKeyFile=13,
  cstPPKFile=14,
  cstPPKBlob=15,
  cstXMLFile=16,
  cstXMLBlob=17,
  cstJWKFile=18,
  cstJWKBlob=19,
  cstSecurityKey=20,
  cstBCFKSFile=21,
  cstBCFKSBlob=22,
  cstPKCS11=23,
  cstAuto=99
};

Default Value

cstUser

Remarks

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 property can take one of the following values:

Data Type

Integer

SSLAcceptServerCertSubjectAltNames Property (Retail Component)

Comma-separated lists of alternative subject names for the certificate.

Syntax

__property String SSLAcceptServerCertSubjectAltNames = { read=FSSLAcceptServerCertSubjectAltNames };

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

SSLAcceptServerCertThumbprintMD5 Property (Retail Component)

The MD5 hash of the certificate.

Syntax

__property String SSLAcceptServerCertThumbprintMD5 = { read=FSSLAcceptServerCertThumbprintMD5 };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLAcceptServerCertThumbprintSHA1 Property (Retail Component)

The SHA-1 hash of the certificate.

Syntax

__property String SSLAcceptServerCertThumbprintSHA1 = { read=FSSLAcceptServerCertThumbprintSHA1 };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLAcceptServerCertThumbprintSHA256 Property (Retail Component)

The SHA-256 hash of the certificate.

Syntax

__property String SSLAcceptServerCertThumbprintSHA256 = { read=FSSLAcceptServerCertThumbprintSHA256 };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLAcceptServerCertUsage Property (Retail Component)

The text description of UsageFlags .

Syntax

__property String SSLAcceptServerCertUsage = { read=FSSLAcceptServerCertUsage };

Default Value

""

Remarks

The text description of SSLAcceptServerCertUsageFlags.

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.

This property is read-only.

Data Type

String

SSLAcceptServerCertUsageFlags Property (Retail Component)

The flags that show intended use for the certificate.

Syntax

__property int SSLAcceptServerCertUsageFlags = { read=FSSLAcceptServerCertUsageFlags };

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of SSLAcceptServerCertUsageFlags is a combination of the following flags:

Please see the SSLAcceptServerCertUsage property for a text representation of SSLAcceptServerCertUsageFlags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

Integer

SSLAcceptServerCertVersion Property (Retail Component)

The certificate's version number.

Syntax

__property String SSLAcceptServerCertVersion = { read=FSSLAcceptServerCertVersion };

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

SSLAcceptServerCertSubject Property (Retail Component)

The subject of the certificate used for client authentication.

Syntax

__property String SSLAcceptServerCertSubject = { read=FSSLAcceptServerCertSubject, write=FSetSSLAcceptServerCertSubject };

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

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=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

Data Type

String

SSLAcceptServerCertEncoded Property (Retail Component)

The certificate (PEM/Base64 encoded).

Syntax

__property String SSLAcceptServerCertEncoded = { read=FSSLAcceptServerCertEncoded, write=FSetSSLAcceptServerCertEncoded };
__property DynamicArray<Byte> SSLAcceptServerCertEncodedB = { read=FSSLAcceptServerCertEncodedB, write=FSetSSLAcceptServerCertEncodedB };

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The SSLAcceptServerCertStore and SSLAcceptServerCertSubject properties also may be used to specify a certificate.

When SSLAcceptServerCertEncoded is set, a search is initiated in the current SSLAcceptServerCertStore for the private key of the certificate. If the key is found, SSLAcceptServerCertSubject is updated to reflect the full subject of the selected certificate; otherwise, SSLAcceptServerCertSubject is set to an empty string.

This property is not available at design time.

Data Type

Byte Array

SSLCertEffectiveDate Property (Retail Component)

The date on which this certificate becomes valid.

Syntax

__property String SSLCertEffectiveDate = { read=FSSLCertEffectiveDate };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLCertExpirationDate Property (Retail Component)

The date on which the certificate expires.

Syntax

__property String SSLCertExpirationDate = { read=FSSLCertExpirationDate };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLCertExtendedKeyUsage Property (Retail Component)

A comma-delimited list of extended key usage identifiers.

Syntax

__property String SSLCertExtendedKeyUsage = { read=FSSLCertExtendedKeyUsage };

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

SSLCertFingerprint Property (Retail Component)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

__property String SSLCertFingerprint = { read=FSSLCertFingerprint };

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

SSLCertFingerprintSHA1 Property (Retail Component)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

__property String SSLCertFingerprintSHA1 = { read=FSSLCertFingerprintSHA1 };

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

SSLCertFingerprintSHA256 Property (Retail Component)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

__property String SSLCertFingerprintSHA256 = { read=FSSLCertFingerprintSHA256 };

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

SSLCertIssuer Property (Retail Component)

The issuer of the certificate.

Syntax

__property String SSLCertIssuer = { read=FSSLCertIssuer };

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

SSLCertPrivateKey Property (Retail Component)

The private key of the certificate (if available).

Syntax

__property String SSLCertPrivateKey = { read=FSSLCertPrivateKey };

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The SSLCertPrivateKey may be available but not exportable. In this case, SSLCertPrivateKey returns an empty string.

This property is read-only.

Data Type

String

SSLCertPrivateKeyAvailable Property (Retail Component)

Whether a PrivateKey is available for the selected certificate.

Syntax

__property bool SSLCertPrivateKeyAvailable = { read=FSSLCertPrivateKeyAvailable };

Default Value

false

Remarks

Whether a SSLCertPrivateKey is available for the selected certificate. If SSLCertPrivateKeyAvailable is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

Boolean

SSLCertPrivateKeyContainer Property (Retail Component)

The name of the PrivateKey container for the certificate (if available).

Syntax

__property String SSLCertPrivateKeyContainer = { read=FSSLCertPrivateKeyContainer };

Default Value

""

Remarks

The name of the SSLCertPrivateKey container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

SSLCertPublicKey Property (Retail Component)

The public key of the certificate.

Syntax

__property String SSLCertPublicKey = { read=FSSLCertPublicKey };

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

SSLCertPublicKeyAlgorithm Property (Retail Component)

The textual description of the certificate's public key algorithm.

Syntax

__property String SSLCertPublicKeyAlgorithm = { read=FSSLCertPublicKeyAlgorithm };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLCertPublicKeyLength Property (Retail Component)

The length of the certificate's public key (in bits).

Syntax

__property int SSLCertPublicKeyLength = { read=FSSLCertPublicKeyLength };

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

Integer

SSLCertSerialNumber Property (Retail Component)

The serial number of the certificate encoded as a string.

Syntax

__property String SSLCertSerialNumber = { read=FSSLCertSerialNumber };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLCertSignatureAlgorithm Property (Retail Component)

The text description of the certificate's signature algorithm.

Syntax

__property String SSLCertSignatureAlgorithm = { read=FSSLCertSignatureAlgorithm };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLCertStore Property (Retail Component)

The name of the certificate store for the client certificate.

Syntax

__property String SSLCertStore = { read=FSSLCertStore, write=FSetSSLCertStore };
__property DynamicArray<Byte> SSLCertStoreB = { read=FSSLCertStoreB, write=FSetSSLCertStoreB };

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The SSLCertStoreType property denotes the type of the certificate store specified by SSLCertStore. If the store is password-protected, specify the password in SSLCertStorePassword.

SSLCertStore is used in conjunction with the SSLCertSubject property to specify client certificates. If SSLCertStore has a value, and SSLCertSubject or SSLCertEncoded is set, a search for a certificate is initiated. Please see the SSLCertSubject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

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

Data Type

Byte Array

SSLCertStorePassword Property (Retail Component)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

__property String SSLCertStorePassword = { read=FSSLCertStorePassword, write=FSetSSLCertStorePassword };

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Data Type

String

SSLCertStoreType Property (Retail Component)

The type of certificate store for this certificate.

Syntax

__property TibpRetailSSLCertStoreTypes SSLCertStoreType = { read=FSSLCertStoreType, write=FSetSSLCertStoreType };

enum TibpRetailSSLCertStoreTypes {
  cstUser=0,
  cstMachine=1,
  cstPFXFile=2,
  cstPFXBlob=3,
  cstJKSFile=4,
  cstJKSBlob=5,
  cstPEMKeyFile=6,
  cstPEMKeyBlob=7,
  cstPublicKeyFile=8,
  cstPublicKeyBlob=9,
  cstSSHPublicKeyBlob=10,
  cstP7BFile=11,
  cstP7BBlob=12,
  cstSSHPublicKeyFile=13,
  cstPPKFile=14,
  cstPPKBlob=15,
  cstXMLFile=16,
  cstXMLBlob=17,
  cstJWKFile=18,
  cstJWKBlob=19,
  cstSecurityKey=20,
  cstBCFKSFile=21,
  cstBCFKSBlob=22,
  cstPKCS11=23,
  cstAuto=99
};

Default Value

cstUser

Remarks

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 property can take one of the following values:

Data Type

Integer

SSLCertSubjectAltNames Property (Retail Component)

Comma-separated lists of alternative subject names for the certificate.

Syntax

__property String SSLCertSubjectAltNames = { read=FSSLCertSubjectAltNames };

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

SSLCertThumbprintMD5 Property (Retail Component)

The MD5 hash of the certificate.

Syntax

__property String SSLCertThumbprintMD5 = { read=FSSLCertThumbprintMD5 };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLCertThumbprintSHA1 Property (Retail Component)

The SHA-1 hash of the certificate.

Syntax

__property String SSLCertThumbprintSHA1 = { read=FSSLCertThumbprintSHA1 };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLCertThumbprintSHA256 Property (Retail Component)

The SHA-256 hash of the certificate.

Syntax

__property String SSLCertThumbprintSHA256 = { read=FSSLCertThumbprintSHA256 };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLCertUsage Property (Retail Component)

The text description of UsageFlags .

Syntax

__property String SSLCertUsage = { read=FSSLCertUsage };

Default Value

""

Remarks

The text description of SSLCertUsageFlags.

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.

This property is read-only.

Data Type

String

SSLCertUsageFlags Property (Retail Component)

The flags that show intended use for the certificate.

Syntax

__property int SSLCertUsageFlags = { read=FSSLCertUsageFlags };

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of SSLCertUsageFlags is a combination of the following flags:

Please see the SSLCertUsage property for a text representation of SSLCertUsageFlags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

Integer

SSLCertVersion Property (Retail Component)

The certificate's version number.

Syntax

__property String SSLCertVersion = { read=FSSLCertVersion };

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

SSLCertSubject Property (Retail Component)

The subject of the certificate used for client authentication.

Syntax

__property String SSLCertSubject = { read=FSSLCertSubject, write=FSetSSLCertSubject };

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

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=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

Data Type

String

SSLCertEncoded Property (Retail Component)

The certificate (PEM/Base64 encoded).

Syntax

__property String SSLCertEncoded = { read=FSSLCertEncoded, write=FSetSSLCertEncoded };
__property DynamicArray<Byte> SSLCertEncodedB = { read=FSSLCertEncodedB, write=FSetSSLCertEncodedB };

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The SSLCertStore and SSLCertSubject properties also may be used to specify a certificate.

When SSLCertEncoded is set, a search is initiated in the current SSLCertStore for the private key of the certificate. If the key is found, SSLCertSubject is updated to reflect the full subject of the selected certificate; otherwise, SSLCertSubject is set to an empty string.

This property is not available at design time.

Data Type

Byte Array

SSLProvider Property (Retail Component)

The Secure Sockets Layer/Transport Layer Security (SSL/TLS) implementation to use.

Syntax

__property TibpRetailSSLProviders SSLProvider = { read=FSSLProvider, write=FSetSSLProvider };

enum TibpRetailSSLProviders {
  sslpAutomatic=0,
  sslpPlatform=1,
  sslpInternal=2
};

Default Value

sslpAutomatic

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:

Additional Notes

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, the platform implementation is used by default. When TLS 1.3 is enabled via SSLEnabledProtocols, the internal implementation is used.

Data Type

Integer

SSLServerCertEffectiveDate Property (Retail Component)

The date on which this certificate becomes valid.

Syntax

__property String SSLServerCertEffectiveDate = { read=FSSLServerCertEffectiveDate };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLServerCertExpirationDate Property (Retail Component)

The date on which the certificate expires.

Syntax

__property String SSLServerCertExpirationDate = { read=FSSLServerCertExpirationDate };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLServerCertExtendedKeyUsage Property (Retail Component)

A comma-delimited list of extended key usage identifiers.

Syntax

__property String SSLServerCertExtendedKeyUsage = { read=FSSLServerCertExtendedKeyUsage };

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

SSLServerCertFingerprint Property (Retail Component)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

__property String SSLServerCertFingerprint = { read=FSSLServerCertFingerprint };

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

SSLServerCertFingerprintSHA1 Property (Retail Component)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

__property String SSLServerCertFingerprintSHA1 = { read=FSSLServerCertFingerprintSHA1 };

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

SSLServerCertFingerprintSHA256 Property (Retail Component)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

__property String SSLServerCertFingerprintSHA256 = { read=FSSLServerCertFingerprintSHA256 };

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

SSLServerCertIssuer Property (Retail Component)

The issuer of the certificate.

Syntax

__property String SSLServerCertIssuer = { read=FSSLServerCertIssuer };

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

SSLServerCertPrivateKey Property (Retail Component)

The private key of the certificate (if available).

Syntax

__property String SSLServerCertPrivateKey = { read=FSSLServerCertPrivateKey };

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The SSLServerCertPrivateKey may be available but not exportable. In this case, SSLServerCertPrivateKey returns an empty string.

This property is read-only.

Data Type

String

SSLServerCertPrivateKeyAvailable Property (Retail Component)

Whether a PrivateKey is available for the selected certificate.

Syntax

__property bool SSLServerCertPrivateKeyAvailable = { read=FSSLServerCertPrivateKeyAvailable };

Default Value

false

Remarks

Whether a SSLServerCertPrivateKey is available for the selected certificate. If SSLServerCertPrivateKeyAvailable is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

Boolean

SSLServerCertPrivateKeyContainer Property (Retail Component)

The name of the PrivateKey container for the certificate (if available).

Syntax

__property String SSLServerCertPrivateKeyContainer = { read=FSSLServerCertPrivateKeyContainer };

Default Value

""

Remarks

The name of the SSLServerCertPrivateKey container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

SSLServerCertPublicKey Property (Retail Component)

The public key of the certificate.

Syntax

__property String SSLServerCertPublicKey = { read=FSSLServerCertPublicKey };

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

SSLServerCertPublicKeyAlgorithm Property (Retail Component)

The textual description of the certificate's public key algorithm.

Syntax

__property String SSLServerCertPublicKeyAlgorithm = { read=FSSLServerCertPublicKeyAlgorithm };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLServerCertPublicKeyLength Property (Retail Component)

The length of the certificate's public key (in bits).

Syntax

__property int SSLServerCertPublicKeyLength = { read=FSSLServerCertPublicKeyLength };

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

Integer

SSLServerCertSerialNumber Property (Retail Component)

The serial number of the certificate encoded as a string.

Syntax

__property String SSLServerCertSerialNumber = { read=FSSLServerCertSerialNumber };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLServerCertSignatureAlgorithm Property (Retail Component)

The text description of the certificate's signature algorithm.

Syntax

__property String SSLServerCertSignatureAlgorithm = { read=FSSLServerCertSignatureAlgorithm };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLServerCertStore Property (Retail Component)

The name of the certificate store for the client certificate.

Syntax

__property String SSLServerCertStore = { read=FSSLServerCertStore };
__property DynamicArray<Byte> SSLServerCertStoreB = { read=FSSLServerCertStoreB };

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The SSLServerCertStoreType property denotes the type of the certificate store specified by SSLServerCertStore. If the store is password-protected, specify the password in SSLServerCertStorePassword.

SSLServerCertStore is used in conjunction with the SSLServerCertSubject property to specify client certificates. If SSLServerCertStore has a value, and SSLServerCertSubject or SSLServerCertEncoded is set, a search for a certificate is initiated. Please see the SSLServerCertSubject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

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

This property is read-only.

Data Type

Byte Array

SSLServerCertStorePassword Property (Retail Component)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

__property String SSLServerCertStorePassword = { read=FSSLServerCertStorePassword };

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

This property is read-only.

Data Type

String

SSLServerCertStoreType Property (Retail Component)

The type of certificate store for this certificate.

Syntax

__property TibpRetailSSLServerCertStoreTypes SSLServerCertStoreType = { read=FSSLServerCertStoreType };

enum TibpRetailSSLServerCertStoreTypes {
  cstUser=0,
  cstMachine=1,
  cstPFXFile=2,
  cstPFXBlob=3,
  cstJKSFile=4,
  cstJKSBlob=5,
  cstPEMKeyFile=6,
  cstPEMKeyBlob=7,
  cstPublicKeyFile=8,
  cstPublicKeyBlob=9,
  cstSSHPublicKeyBlob=10,
  cstP7BFile=11,
  cstP7BBlob=12,
  cstSSHPublicKeyFile=13,
  cstPPKFile=14,
  cstPPKBlob=15,
  cstXMLFile=16,
  cstXMLBlob=17,
  cstJWKFile=18,
  cstJWKBlob=19,
  cstSecurityKey=20,
  cstBCFKSFile=21,
  cstBCFKSBlob=22,
  cstPKCS11=23,
  cstAuto=99
};

Default Value

cstUser

Remarks

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 property can take one of the following values:

This property is read-only.

Data Type

Integer

SSLServerCertSubjectAltNames Property (Retail Component)

Comma-separated lists of alternative subject names for the certificate.

Syntax

__property String SSLServerCertSubjectAltNames = { read=FSSLServerCertSubjectAltNames };

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

SSLServerCertThumbprintMD5 Property (Retail Component)

The MD5 hash of the certificate.

Syntax

__property String SSLServerCertThumbprintMD5 = { read=FSSLServerCertThumbprintMD5 };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLServerCertThumbprintSHA1 Property (Retail Component)

The SHA-1 hash of the certificate.

Syntax

__property String SSLServerCertThumbprintSHA1 = { read=FSSLServerCertThumbprintSHA1 };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLServerCertThumbprintSHA256 Property (Retail Component)

The SHA-256 hash of the certificate.

Syntax

__property String SSLServerCertThumbprintSHA256 = { read=FSSLServerCertThumbprintSHA256 };

Default Value

""

Remarks

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.

This property is read-only.

Data Type

String

SSLServerCertUsage Property (Retail Component)

The text description of UsageFlags .

Syntax

__property String SSLServerCertUsage = { read=FSSLServerCertUsage };

Default Value

""

Remarks

The text description of SSLServerCertUsageFlags.

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.

This property is read-only.

Data Type

String

SSLServerCertUsageFlags Property (Retail Component)

The flags that show intended use for the certificate.

Syntax

__property int SSLServerCertUsageFlags = { read=FSSLServerCertUsageFlags };

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of SSLServerCertUsageFlags is a combination of the following flags:

Please see the SSLServerCertUsage property for a text representation of SSLServerCertUsageFlags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

Integer

SSLServerCertVersion Property (Retail Component)

The certificate's version number.

Syntax

__property String SSLServerCertVersion = { read=FSSLServerCertVersion };

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

SSLServerCertSubject Property (Retail Component)

The subject of the certificate used for client authentication.

Syntax

__property String SSLServerCertSubject = { read=FSSLServerCertSubject };

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

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=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

This property is read-only.

Data Type

String

SSLServerCertEncoded Property (Retail Component)

The certificate (PEM/Base64 encoded).

Syntax

__property String SSLServerCertEncoded = { read=FSSLServerCertEncoded };
__property DynamicArray<Byte> SSLServerCertEncodedB = { read=FSSLServerCertEncodedB };

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The SSLServerCertStore and SSLServerCertSubject properties also may be used to specify a certificate.

When SSLServerCertEncoded is set, a search is initiated in the current SSLServerCertStore for the private key of the certificate. If the key is found, SSLServerCertSubject is updated to reflect the full subject of the selected certificate; otherwise, SSLServerCertSubject is set to an empty string.

This property is read-only and not available at design time.

Data Type

Byte Array

TestMode Property (Retail Component)

Turns test mode on and off for transactions sent to the current Gateway .

Syntax

__property bool TestMode = { read=FTestMode, write=FSetTestMode };

Default Value

false

Remarks

You can use this property to set a test mode flag that will be sent in an authorization request. Not all Gateways support test modes. If you set the TestMode property to True and the current Gateway does not support it, the component will raises an exception.

Data Type

Boolean

Timeout Property (Retail Component)

A timeout for the component.

Syntax

__property int Timeout = { read=FTimeout, write=FSetTimeout };

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

Data Type

Integer

TransactionAmount Property (Retail Component)

Purchase amount for an authorization transaction.

Syntax

__property String TransactionAmount = { read=FTransactionAmount, write=FSetTransactionAmount };

Default Value

""

Remarks

This field contains the transaction amount to be authorized. Gateways may have differing requirements for how the TransactionAmount should be formatted, so refer to the ICharge Gateway Setup page for details on the gateway you are using.

Data Type

String

TransactionDesc Property (Retail Component)

Description of goods purchased.

Syntax

__property String TransactionDesc = { read=FTransactionDesc, write=FSetTransactionDesc };

Default Value

""

Remarks

This field contains a description of the goods or services being purchased. Please see the "ICharge Gateway Setup and Required Properties" page to determine if this is a required or optional field for the gateway you are using.

Data Type

String

TransactionId Property (Retail Component)

Merchant-generated transaction Id used for all transactions.

Syntax

__property String TransactionId = { read=FTransactionId, write=FSetTransactionId };

Default Value

""

Remarks

This property is used to send a merchant-generated transaction id to the Gateway, if the gateway supports that feature.

Data Type

String

AddSpecialField Method (Retail Component)

Adds a special field name and the corresponding value.

Syntax

void __fastcall AddSpecialField(String Name, String Value);

Remarks

Please refer to the SpecialFieldName and SpecialFieldValue properties for more information on form variables and how they are managed.

AuthOnly Method (Retail Component)

Initiates an authorization-only request transaction.

Syntax

void __fastcall AuthOnly();

Remarks

This method sends an authorization-only request to the specified Gateway. This transaction is not added to the current open batch, and must be completed later with the Capture method (you may use the Sale method if you wish to authorize and capture in one step).

Note: If the Gateway does not support this method, the component will raises an exception.

AVSOnly Method (Retail Component)

Used to check the validity of the card without authorizing funds.

Syntax

void __fastcall AVSOnly();

Remarks

This method can be used if you wish to perform fraud (AVS and CVV) checks on a card, but don't actually wish to charge the customer. This is useful for pre-ordering an item that has not yet been released or is currently back- ordered. The card information is validated by the merchant, and when the item is later in stock and ships to the customer, an Sale transaction can be performed.

Note: If the Gateway does not support this method, the component will raises an exception.

Capture Method (Retail Component)

Captures a previously authorized transaction.

Syntax

void __fastcall Capture(String TransactionId, String CaptureAmount);

Remarks

This method captures a transaction that has been previously authorized with the AuthOnly method. The TransactionId parameter indicates to the Gateway which transaction is to be captured, and should contain the ResponseTransactionId from the original transaction. The CaptureAmount parameter is the value to be captured from the customer's credit card, and can be different from the authorized amount.

Please see the gateway information in the table of contents to determine if your gateway supports Capture transactions.

The LinkPoint and PSIGateXML gateways require you send the ResponseInvoiceNumber rather than the ResponseTransactionId.

The SecurePay gateway does not require the TransactionId for captures. Instead, you must send the ResponseApprovalCode returned from the original response in the AuthCode property.

The MyVirtualMerchant and Converge gateways do not require the TransactionId for captures. Instead, you must send the ResponseApprovalCode returned from the original response in the AuthCode property. Note that there is a new capture transaction type available for these gateways. To use the new transaction type, set the MyVirtualMerchantTransactionType to "CCCOMPLETE" and call Capture like normal. When using this transaction type, TransactionId is required and ResponseApprovalCode is not applicable.

Config Method (Retail Component)

Sets or retrieves a configuration setting.

Syntax

String __fastcall Config(String ConfigurationString);

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.

Credit Method (Retail Component)

Credits a customer's card.

Syntax

void __fastcall Credit();

Remarks

This method credits a customer's card specified via Card. This type of transaction is NOT based on previous transaction. Some gateways refer to these as "Open" or "Blind" Credits.

TransactionAmount is used to specify the amount you wish to return to the customer's card.

Please see the gateway information in the table of contents to determine if your gateway supports Credit transactions.

DoEvents Method (Retail Component)

This method processes events from the internal message queue.

Syntax

void __fastcall DoEvents();

Remarks

When DoEvents is called, the component processes any available events. If no events are available, it waits for a preset period of time, and then returns.

Force Method (Retail Component)

Used when authorization cannot be obtained online.

Syntax

void __fastcall Force(String VoiceAuthCode);

Remarks

This method is used when the response to a Sale or AuthOnly request indicates that voice authorization is required. The merchant then telephones the call center and receives a voice authorization code. Calling the Force method with this code in the VoiceAuthCode parameter will complete the transaction.

Note: If the Gateway does not support this method, the component will raises an exception.

GetResponseVar Method (Retail Component)

Parses additional information out of the response.

Syntax

String __fastcall GetResponseVar(String Name);

Remarks

Due to the fact that this component supports so many gateways, only the most commonly used response variables are parsed into the Response properties. Any additional response information contained within the ResponseData may be retrieved with this GetResponseVar method. There are three formats for the ResponseData returned by the gateways this component supports: Name/value pairs, delimited list, or XML. The value you pass in the Name parameter changes based on these formats, as detailed below:

If the ResponseData property contains name/value pairs, pass the name in the Name parameter and this method will return the value. For instance, if ResponseData contains "ResponseCode=00&FraudScore=53&ApprovalCode=123456&...", calling GetResponseVar("FraudScore") will return "53".

However, if ResponseData contains a delimited list, pass the index of the field you wish to receive. For instance, if ResponseData contains "00|53|123456|...", calling GetResponseVar("1") will return "53".

Finally, if ResponseData contains XML, pass the xpath to the value you wish to receive. For instance, if ResponseData contains "<Response><Code>00</Code><FraudScore>53</FraudScore><ApprovalCode>123456</ApprovalCode></Response>", calling GetResponseVar("/Response/FraudScore") will return "53".

Interrupt Method (Retail Component)

Interrupts the current action.

Syntax

void __fastcall Interrupt();

Remarks

This method interrupts any processing that the component is currently executing.

Refund Method (Retail Component)

Refunds a previously captured transaction.

Syntax

void __fastcall Refund(String TransactionId, String RefundAmount);

Remarks

This method refunds a transaction that has already been captured, or settled. If the transaction is still outstanding use the VoidTransaction method instead. The TransactionId parameter indicates to the Gateway which transaction is to be refunded, and should contain the ResponseTransactionId from the original transaction. The RefundAmount parameter is the value to be refunded back to the customer, and can be all or part of the original TransactionAmount

Please see the gateway information in the table of contents to determine if your gateway supports Refund transactions.

The gw3DSI gateway requires the following additional fields for Refund transactions:

component.AddSpecialField "UserId", "my 3DSI-assigned UserId" '(Different than MerchantLogin) component.MerchantPassword = "my 3DSI-assigned Pwd"

The LinkPoint and PSIGateXML gateways require you send the ResponseInvoiceNumber rather than the ResponseTransactionId.

Reset Method (Retail Component)

Clears all properties to their default values.

Syntax

void __fastcall Reset();

Remarks

This method clears all properties to their default values and returns the component to its default state.

ResetSpecialFields Method (Retail Component)

Resets all special fields to the default settings.

Syntax

void __fastcall ResetSpecialFields();

Remarks

This function resets all special gateway configuration fields to the default settings for the specified Gateway.

Please refer to the SpecialFieldName and SpecialFieldValue properties for more information on form variables and how they are managed.

Sale Method (Retail Component)

Initiates an Sale transaction (authorization and capture).

Syntax

void __fastcall Sale();

Remarks

Sends a basic sale transaction to the Gateway. This transaction decrements the cardholder's open-to-buy funds for the TransactionAmount, and the transaction is automatically added to the current open batch.

VoidTransaction Method (Retail Component)

Voids a previously authorized transaction.

Syntax

void __fastcall VoidTransaction(String TransactionId);

Remarks

This method voids a transaction that has been previously authorized, but which has not yet gone to settlement, or been "captured". The TransactionId parameter indicates to the Gateway which transaction is to be voided, and should contain the ResponseTransactionId from the original transaction.

Please see the gateway information in the table of contents to determine if your gateway supports Void transactions.

To cancel a transaction which has already been captured, use the Credit method.

The LinkPoint gateway requires you send the ResponseInvoiceNumber rather than the ResponseTransactionId.

For the PSIGateXML gateway, send the ResponseTransactionId as normal.

For the Heartland gateway, a reversal transaction will be sent when a TransactionAmount is specified. Otherwise a void transaction will be sent.

Error Event (Retail Component)

Information about errors during data delivery.

Syntax

typedef struct {
  int ErrorCode;
  String Description;
} TibpRetailErrorEventParams;
typedef void __fastcall (__closure *TibpRetailErrorEvent)(System::TObject* Sender, TibpRetailErrorEventParams *e);
__property TibpRetailErrorEvent OnError = { read=FOnError, write=FOnError };

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.

SSLServerAuthentication Event (Retail Component)

Fired after the server presents its certificate to the client.

Syntax

typedef struct {
  String CertEncoded;
  DynamicArray<Byte> CertEncodedB;
  String CertSubject;
  String CertIssuer;
  String Status;
  bool Accept;
} TibpRetailSSLServerAuthenticationEventParams;
typedef void __fastcall (__closure *TibpRetailSSLServerAuthenticationEvent)(System::TObject* Sender, TibpRetailSSLServerAuthenticationEventParams *e);
__property TibpRetailSSLServerAuthenticationEvent OnSSLServerAuthentication = { read=FOnSSLServerAuthentication, write=FOnSSLServerAuthentication };

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 (Retail Component)

Fired when secure connection progress messages are available.

Syntax

typedef struct {
  String Message;
} TibpRetailSSLStatusEventParams;
typedef void __fastcall (__closure *TibpRetailSSLStatusEvent)(System::TObject* Sender, TibpRetailSSLStatusEventParams *e);
__property TibpRetailSSLStatusEvent OnSSLStatus = { read=FOnSSLStatus, write=FOnSSLStatus };

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

Config Settings (Retail 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.

Retail Config Settings

HTTP Config Settings

TCPClient Config Settings

SSL Config Settings

Socket Config Settings

Base Config Settings

Trappable Errors (Retail Component)

Retail Errors

CardValidator Errors

The component may also return one of the following error codes, which are inherited from other components.

HTTP Errors

The component may also return one of the following error codes, which are inherited from other components.

TCPClient Errors

SSL Errors

TCP/IP Errors