RecurringBilling Control

Properties   Methods   Events   Config Settings   Errors  

The RecurringBilling control is used to authorize and set up recurring transactions with any of the supported Internet Payment Gateways.

Syntax

RecurringBilling

Remarks

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

RecurringBilling Gateway Setup and Required Properties

The RecurringBilling control allows your website to securely perform and setup recurring transactions without the need to redirect to a separate website. All transactions are accomplished through a secure HTTPS Post to any supported gateway. The secure response is received and then stored in the control's response properties. Any website or any stand-alone application can process transactions without the need for a secure server or third-party intervention.

Gateway Setup

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

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.

Many gateways have different setup requirements. See RecurringBilling Gateway Setup and Required Properties for details about each gateway's requirements.

Now you are ready to process transactions. For each transaction, you must set either Card or Bank. Most gateways will also require additional properties, such as CustomerAddress, CustomerFirstName, CustomerLastName, InvoiceNumber, etc.

Subscription Management

Once all required properties are set, you may create a recurring payment using the specified card or bank data by calling the CreateSubscription method. If the Gateway supports it, you may also Cancel recurring payments with the CancelSubscription method. Recurring payments that need to be changed may be updated with the UpdateSubscription method.

The following gateways are supported by the RecurringBilling control:

Property List

---

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

Method List

---

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

Event List

---

The following is the full list of the events fired by the control with short descriptions. Click on the links for further details.

Config Settings

---

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

CardType Property (RecurringBilling Control)

Type of credit card being used in this transaction.

Syntax

recurringbillingcontrol.CardType[=integer]

Possible Values

ctUnknown(0), 
ctVisa(1), 
ctMasterCard(2), 
ctAMEX(3), 
ctDiscover(4), 
ctDiners(5), 
ctJCB(6), 
ctVisaElectron(7), 
ctMaestro(8), 
ctLaser(10)

Default Value

0

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.CardCVVData[=string]

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 (RecurringBilling Control)

Indicates the presence of the card verification value.

Syntax

recurringbillingcontrol.CardCVVPresence[=integer]

Possible Values

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

Default Value

0

Remarks

Indicates the presence of the card verification value.

This property is used to indicate the presence of CardCVVData.

The control 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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.CardEntryDataSource[=integer]

Possible Values

edsTrack1(0), 
edsTrack2(1), 
edsManualEntryTrack1Capable(2), 
edsManualEntryTrack2Capable(3), 
edsManualEntryNoCardReader(4), 
edsTrack1Contactless(5), 
edsTrack2Contactless(6), 
edsManualEntryContactlessCapable(7), 
edsIVR(8), 
edsKiosk(9)

Default Value

0

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 (RecurringBilling Control)

Expiration month of the credit card specified in Number .

Syntax

recurringbillingcontrol.CardExpMonth[=integer]

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 (RecurringBilling Control)

Expiration year of the credit card specified in Number .

Syntax

recurringbillingcontrol.CardExpYear[=integer]

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.CardIsEncrypted[=boolean]

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.CardMagneticStripe[=string]

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?"

control.CardMagneticStripe = "B4788250000028291^TSYS^05121015432112345678" control.CardEntryDataSource = edsTrack1 or control.CardMagneticStripe = "4788250000028291=05121015432112345678" control.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 (RecurringBilling Control)

Customer's credit card number for the transaction.

Syntax

recurringbillingcontrol.CardNumber[=string]

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 (RecurringBilling Control)

Customer's street address.

Syntax

recurringbillingcontrol.CustomerAddress[=string]

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:

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

This property is not available at design time.

Data Type

String

CustomerAddress2 Property (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.CustomerAddress2[=string]

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.CustomerAggregate[=string]

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 (RecurringBilling Control)

Customer's city.

Syntax

recurringbillingcontrol.CustomerCity[=string]

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 (RecurringBilling Control)

Customer's country.

Syntax

recurringbillingcontrol.CustomerCountry[=string]

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 (RecurringBilling Control)

Customer's email address.

Syntax

recurringbillingcontrol.CustomerEmail[=string]

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 (RecurringBilling Control)

Customer's fax number.

Syntax

recurringbillingcontrol.CustomerFax[=string]

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 (RecurringBilling Control)

Customer's first name.

Syntax

recurringbillingcontrol.CustomerFirstName[=string]

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 (RecurringBilling Control)

Customer's full name.

Syntax

recurringbillingcontrol.CustomerFullName[=string]

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 (RecurringBilling Control)

Merchant-generated customer Id.

Syntax

recurringbillingcontrol.CustomerId[=string]

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 (RecurringBilling Control)

Customer's last name.

Syntax

recurringbillingcontrol.CustomerLastName[=string]

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 (RecurringBilling Control)

Customer's phone number.

Syntax

recurringbillingcontrol.CustomerPhone[=string]

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 (RecurringBilling Control)

Customer's state.

Syntax

recurringbillingcontrol.CustomerState[=string]

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.CustomerZip[=string]

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

BankAccountClass Property (RecurringBilling Control)

Indicates whether a personal or business account is used for this transaction.

Syntax

recurringbillingcontrol.BankAccountClass[=integer]

Possible Values

acPersonal(0), 
acBusiness(1)

Default Value

0

Remarks

Indicates whether a personal or business account is used for this transaction.

Available values:

This property is not available at design time.

Data Type

Integer

BankAccountHolderName Property (RecurringBilling Control)

Account holder's name.

Syntax

recurringbillingcontrol.BankAccountHolderName[=string]

Default Value

""

Remarks

Account holder's name. This property contains the customer's name as it appears on their account. Many gateways use this property in addition to, or instead of, the Customer Firsts and Last name properties. Note that if this property is not specified, the FullName property from the EPCustomer type will be used instead.

This property is not available at design time.

Data Type

String

BankAccountNumber Property (RecurringBilling Control)

Bank account number for ACH transactions.

Syntax

recurringbillingcontrol.BankAccountNumber[=string]

Default Value

""

Remarks

Bank account number for ACH transactions. This property contains the customer's bank account number, which along with the BankRoutingNumber identify the location of the account where funds are to be drawn from for ACH transactions. This property is required for all ACH transactions.

This property is not available at design time.

Data Type

String

BankAccountType Property (RecurringBilling Control)

Indicates whether a checking or savings account is used for this transaction.

Syntax

recurringbillingcontrol.BankAccountType[=integer]

Possible Values

atChecking(0), 
atSavings(1)

Default Value

0

Remarks

Indicates whether a checking or savings account is used for this transaction. For gateways that support it, this property allows funds to be withdrawn (or added in the case of a Credit) from either the customer's Checking or Savings account.

Available values:

This property is not available at design time.

Data Type

Integer

BankName Property (RecurringBilling Control)

Name of the account holder's bank.

Syntax

recurringbillingcontrol.BankName[=string]

Default Value

""

Remarks

Name of the account holder's bank. For example, Citibank, Wells-Fargo, Wachovia, etc. This property contains the name of the bank associated with the BankRoutingNumber.

This property is not available at design time.

Data Type

String

BankRoutingNumber Property (RecurringBilling Control)

Routing number for ACH transactions.

Syntax

recurringbillingcontrol.BankRoutingNumber[=string]

Default Value

""

Remarks

Routing number for ACH transactions. This property contains the routing number to the customer's bank (Also known as an ABA code). This number indicates at which bank the BankAccountNumber is located, and is used to identify the location of the account where funds are to be drawn from for ACH transactions. This property is required for all ACH transactions.

Note: When using ACHPayments gateway, a leading zero must be added for Canadian bank accounts.

This property is not available at design time.

Data Type

String

ECheckPaymentType Property (RecurringBilling Control)

The type of check payment request (commonly referred to as SEC Code).

Syntax

recurringbillingcontrol.ECheckPaymentType[=integer]

Possible Values

ptWEB(0), 
ptPPD(1), 
ptTEL(2), 
ptCCD(3), 
ptARC(4), 
ptBOC(5), 
ptPOP(6), 
ptRCK(7)

Default Value

0

Remarks

This property is used to specify the payment type of the check transaction.

Available values:

Data Type

Integer

Gateway Property (RecurringBilling Control)

Gateway to process transactions with.

Syntax

recurringbillingcontrol.Gateway[=integer]

Possible Values

rbgwNoGateway(0), 
rbgwAuthorizeNet(1), 
rbgwEprocessing(2), 
rbgwITransact(4), 
rbgwPayFlowPro(6), 
rbgwUSAePay(7), 
rbgwPlugNPay(8), 
rbgwPlanetPayment(9), 
rbgwMerchantAnywhere(15), 
rbgwSkipjack(16), 
rbgwOrbital(23), 
rbgwLinkPoint(24), 
rbgwMoneris(25), 
rbgwNetworkMerchants(28), 
rbgwPRIGate(30), 
rbgwMerchantPartners(31), 
rbgwFirstData(33), 
rbgwYourPay(34), 
rbgwACHPayments(35), 
rbgwForte(36), 
rbgwCyberSource(37), 
rbgwEway(38), 
rbgwChase(41), 
rbgwNexCommerce(42), 
rbgwTransactionCentral(44), 
rbgwMyVirtualMerchant(49), 
rbgwMonerisUSA(52), 
rbgwBambora(53), 
rbgwVerifi(54), 
rbgwQBMS(61), 
rbgwLitle(63), 
rbgwPayTrace(70), 
rbgwOmniFund(73), 
rbgwTransNationalBankcard(74), 
rbgwPayscape(83), 
rbgwAuthorizeNetCIM(85), 
rbgwWorldPayLink(87), 
rbgwPaymentWorkSuite(88), 
rbgwFirstDataPayPoint(90), 
rbgwConverge(93), 
rbgwAuthorizeNetXML(96), 
rbgwPhoeniXGate(97), 
rbgwRepay(98), 
rbgwPayWiser(100), 
rbgwBlueSnap(104), 
rbgwBASYS(106), 
rbgwSquare(108), 
rbgwNuvei(110)

Default Value

0

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 (RecurringBilling Control)

Default URL for a specific Gateway .

Syntax

recurringbillingcontrol.GatewayURL[=string]

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 (RecurringBilling Control)

Merchant-generated invoice number.

Syntax

recurringbillingcontrol.InvoiceNumber[=string]

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

MerchantLogin Property (RecurringBilling Control)

Merchant's Gateway login.

Syntax

recurringbillingcontrol.MerchantLogin[=string]

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 (RecurringBilling Control)

Merchant's Gateway password.

Syntax

recurringbillingcontrol.MerchantPassword[=string]

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

PaymentScheduleEndDate Property (RecurringBilling Control)

The end date of the subscription.

Syntax

recurringbillingcontrol.PaymentScheduleEndDate[=string]

Default Value

""

Remarks

The end date of the subscription.

The default format is "MM/dd/yyyy" and is controlled by DateFormat, or GetSubscriptionStatus.

This property is not available at design time.

Data Type

String

PaymentScheduleFrequency Property (RecurringBilling Control)

The frequency of payments.

Syntax

recurringbillingcontrol.PaymentScheduleFrequency[=string]

Default Value

""

Remarks

The frequency of payments.

Possible values are:

• "None"
• "Daily"
• "Weekly"
• "BiWeekly"
• "FourWeeks"
• "SemiMonthly"
• "Monthly"
• "BiMonthly"
• "Quarterly"
• "SemiAnnually"
• "Annually"

Gateway specific values not covered by the above values may also be set. Please refer to RecurringBilling Gateway Setup and Required Properties for more information pertaining to gateway specific values.

If PaymentScheduleFrequencyUnit is applicable to the gateway, this property specifies the length of time between charges. This is used in combination with PaymentScheduleFrequencyUnit to specify the frequency of the billing. For instance if PaymentScheduleFrequencyUnit is set to "Days" and PaymentScheduleFrequency is set to "5", payments will occur every 5 days.

This property is not available at design time.

Data Type

String

PaymentScheduleFrequencyUnit Property (RecurringBilling Control)

The unit of time to be used when calculating the frequency of payments.

Syntax

recurringbillingcontrol.PaymentScheduleFrequencyUnit[=string]

Default Value

""

Remarks

The unit of time to be used when calculating the frequency of payments.

Possible values are:

• "D" or "Days"
• "M" or "Months"
• "Y" or "Years"

Gateway specific values not covered by the above values may also be set. Please refer to RecurringBilling Gateway Setup and Required Properties for more information pertaining to gateway specific values.

This property is not available at design time.

Data Type

String

PaymentScheduleInitialAmount Property (RecurringBilling Control)

The initial amount to be charged (such as a trial period or setup fee).

Syntax

recurringbillingcontrol.PaymentScheduleInitialAmount[=string]

Default Value

""

Remarks

The initial amount to be charged (such as a trial period or setup fee). This amount can vary from PaymentScheduleRecurAmount.

This property is not available at design time.

Data Type

String

PaymentScheduleRecurAmount Property (RecurringBilling Control)

The amount to be charged on a recurring basis.

Syntax

recurringbillingcontrol.PaymentScheduleRecurAmount[=string]

Default Value

""

Remarks

The amount to be charged on a recurring basis. This amount can vary from PaymentScheduleInitialAmount.

This property is not available at design time.

Data Type

String

PaymentScheduleStartDate Property (RecurringBilling Control)

The date on which the recurring payments will start processing.

Syntax

recurringbillingcontrol.PaymentScheduleStartDate[=string]

Default Value

""

Remarks

The date on which the recurring payments will start processing.

This property specifies the start date. The default format is "MM/dd/yyyy" and is controlled by DateFormat, or GetSubscriptionStatus.

This property is not available at design time.

Data Type

String

PaymentScheduleTotalPayments Property (RecurringBilling Control)

The total number of payments.

Syntax

recurringbillingcontrol.PaymentScheduleTotalPayments[=integer]

Default Value

0

Remarks

The total number of payments. Valid values differ between gateways. See RecurringBilling Gateway Setup and Required Properties for details.

This property is not available at design time.

Data Type

Integer

PaymentScheduleTrialPayments Property (RecurringBilling Control)

The total number of trial payments.

Syntax

recurringbillingcontrol.PaymentScheduleTrialPayments[=integer]

Default Value

0

Remarks

The total number of trial payments.

This property is not available at design time.

Data Type

Integer

ProxyAuthScheme Property (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.ProxyAuthScheme[=integer]

Possible Values

authBasic(0), 
authDigest(1), 
authProprietary(2), 
authNone(3), 
authNtlm(4), 
authNegotiate(5)

Default Value

0

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 control 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 control. Look at the configuration file for the control 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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.ProxyAutoDetect[=boolean]

Default Value

False

Remarks

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

Data Type

Boolean

ProxyPassword Property (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.ProxyPassword[=string]

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.ProxyPort[=integer]

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.ProxyServer[=string]

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.ProxySSL[=integer]

Possible Values

psAutomatic(0), 
psAlways(1), 
psNever(2), 
psTunnel(3)

Default Value

0

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.ProxyUser[=string]

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 (RecurringBilling Control)

Contains an authorization code when a transaction has been approved.

Syntax

recurringbillingcontrol.ResponseApprovalCode

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 (RecurringBilling Control)

Indicates the status of the last transaction.

Syntax

recurringbillingcontrol.ResponseApproved

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

ResponseAVSResult Property (RecurringBilling Control)

Contains the Address Verification System result code.

Syntax

recurringbillingcontrol.ResponseAVSResult

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 (RecurringBilling Control)

Indicates the status of the authorization request.

Syntax

recurringbillingcontrol.ResponseCode

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 (RecurringBilling Control)

Contains the returned CVV2 result code if it was requested.

Syntax

recurringbillingcontrol.ResponseCVVResult

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 (RecurringBilling Control)

The entire response returned from the gateway processor.

Syntax

recurringbillingcontrol.ResponseData

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 (RecurringBilling Control)

Additional error code returned by some gateways.

Syntax

recurringbillingcontrol.ResponseErrorCode

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 (RecurringBilling Control)

Additional error description returned by some gateways.

Syntax

recurringbillingcontrol.ResponseErrorText

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 (RecurringBilling Control)

Invoice number submitted in authorization request (if applicable).

Syntax

recurringbillingcontrol.ResponseInvoiceNumber

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 (RecurringBilling Control)

Response code from the underlying processor.

Syntax

recurringbillingcontrol.ResponseProcessorCode

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

ResponseSubscriptionId Property (RecurringBilling Control)

Contains the Subscription or Profile Identifier for the recurring payment.

Syntax

recurringbillingcontrol.ResponseSubscriptionId

Default Value

""

Remarks

Contains the Subscription or Profile Identifier for the recurring payment. This property contains a subscription identifier or profile number used to reference a recurring payment. This property is used when performing subsequent actions on a recurring payment.

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

Data Type

String

ResponseText Property (RecurringBilling Control)

Text information that describes each response code.

Syntax

recurringbillingcontrol.ResponseText

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 (RecurringBilling Control)

Contains the Visa Transaction Identifier or MasterCard Reference Number.

Syntax

recurringbillingcontrol.ResponseTransactionId

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 (RecurringBilling Control)

Customer's shipping street address.

Syntax

recurringbillingcontrol.ShippingAddress[=string]

Default Value

""

Remarks

Customer's shipping street address.

This property is not available at design time.

Data Type

String

ShippingAddress2 Property (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.ShippingAddress2[=string]

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 (RecurringBilling Control)

Customer's shipping city.

Syntax

recurringbillingcontrol.ShippingCity[=string]

Default Value

""

Remarks

Customer's shipping city.

This property is not available at design time.

Data Type

String

ShippingCountry Property (RecurringBilling Control)

Customer's shipping country.

Syntax

recurringbillingcontrol.ShippingCountry[=string]

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 (RecurringBilling Control)

Customer's email address.

Syntax

recurringbillingcontrol.ShippingEmail[=string]

Default Value

""

Remarks

Customer's email address.

This property is not available at design time.

Data Type

String

ShippingFirstName Property (RecurringBilling Control)

Customer's first name.

Syntax

recurringbillingcontrol.ShippingFirstName[=string]

Default Value

""

Remarks

Customer's first name.

This property is not available at design time.

Data Type

String

ShippingLastName Property (RecurringBilling Control)

Customer's last name.

Syntax

recurringbillingcontrol.ShippingLastName[=string]

Default Value

""

Remarks

Customer's last name.

This property is not available at design time.

Data Type

String

ShippingPhone Property (RecurringBilling Control)

Customer's phone number.

Syntax

recurringbillingcontrol.ShippingPhone[=string]

Default Value

""

Remarks

Customer's phone number.

This property is not available at design time.

Data Type

String

ShippingState Property (RecurringBilling Control)

Customer's shipping state.

Syntax

recurringbillingcontrol.ShippingState[=string]

Default Value

""

Remarks

Customer's shipping state.

This property is not available at design time.

Data Type

String

ShippingZip Property (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.ShippingZip[=string]

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 (RecurringBilling Control)

The number of records in the SpecialField arrays.

Syntax

recurringbillingcontrol.SpecialFieldCount[=integer]

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 (RecurringBilling Control)

Name of special configuration property to submit in this transaction.

Syntax

recurringbillingcontrol.SpecialFieldName(FieldIndex)[=string]

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 control 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 (RecurringBilling Control)

Value of special configuration property to submit in this transaction.

Syntax

recurringbillingcontrol.SpecialFieldValue(FieldIndex)[=string]

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 control 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 (RecurringBilling Control)

The date on which this certificate becomes valid.

Syntax

recurringbillingcontrol.SSLAcceptServerCertEffectiveDate

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 (RecurringBilling Control)

The date on which the certificate expires.

Syntax

recurringbillingcontrol.SSLAcceptServerCertExpirationDate

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 (RecurringBilling Control)

A comma-delimited list of extended key usage identifiers.

Syntax

recurringbillingcontrol.SSLAcceptServerCertExtendedKeyUsage

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLAcceptServerCertFingerprint

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLAcceptServerCertFingerprintSHA1

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLAcceptServerCertFingerprintSHA256

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 (RecurringBilling Control)

The issuer of the certificate.

Syntax

recurringbillingcontrol.SSLAcceptServerCertIssuer

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 (RecurringBilling Control)

The private key of the certificate (if available).

Syntax

recurringbillingcontrol.SSLAcceptServerCertPrivateKey

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 (RecurringBilling Control)

Whether a PrivateKey is available for the selected certificate.

Syntax

recurringbillingcontrol.SSLAcceptServerCertPrivateKeyAvailable

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLAcceptServerCertPrivateKeyContainer

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 (RecurringBilling Control)

The public key of the certificate.

Syntax

recurringbillingcontrol.SSLAcceptServerCertPublicKey

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLAcceptServerCertPublicKeyAlgorithm

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLAcceptServerCertPublicKeyLength

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 (RecurringBilling Control)

The serial number of the certificate encoded as a string.

Syntax

recurringbillingcontrol.SSLAcceptServerCertSerialNumber

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 (RecurringBilling Control)

The text description of the certificate's signature algorithm.

Syntax

recurringbillingcontrol.SSLAcceptServerCertSignatureAlgorithm

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 (RecurringBilling Control)

The name of the certificate store for the client certificate.

Syntax

recurringbillingcontrol.SSLAcceptServerCertStore[=string]

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

To read or write binary data to the property, a Variant (Byte Array) version is provided in .SSLAcceptServerCertStoreB.

Data Type

Binary String

SSLAcceptServerCertStorePassword Property (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLAcceptServerCertStorePassword[=string]

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 (RecurringBilling Control)

The type of certificate store for this certificate.

Syntax

recurringbillingcontrol.SSLAcceptServerCertStoreType[=integer]

Possible Values

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

0

Remarks

The type of certificate store for this certificate.

The control supports both public and private keys in a variety of formats. When the cstAuto value is used, the control will automatically determine the type. This property can take one of the following values:

Data Type

Integer

SSLAcceptServerCertSubjectAltNames Property (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLAcceptServerCertSubjectAltNames

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

SSLAcceptServerCertThumbprintMD5 Property (RecurringBilling Control)

The MD5 hash of the certificate.

Syntax

recurringbillingcontrol.SSLAcceptServerCertThumbprintMD5

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 (RecurringBilling Control)

The SHA-1 hash of the certificate.

Syntax

recurringbillingcontrol.SSLAcceptServerCertThumbprintSHA1

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 (RecurringBilling Control)

The SHA-256 hash of the certificate.

Syntax

recurringbillingcontrol.SSLAcceptServerCertThumbprintSHA256

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 (RecurringBilling Control)

The text description of UsageFlags .

Syntax

recurringbillingcontrol.SSLAcceptServerCertUsage

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 (RecurringBilling Control)

The flags that show intended use for the certificate.

Syntax

recurringbillingcontrol.SSLAcceptServerCertUsageFlags

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 (RecurringBilling Control)

The certificate's version number.

Syntax

recurringbillingcontrol.SSLAcceptServerCertVersion

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 (RecurringBilling Control)

The subject of the certificate used for client authentication.

Syntax

recurringbillingcontrol.SSLAcceptServerCertSubject[=string]

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 (RecurringBilling Control)

The certificate (PEM/Base64 encoded).

Syntax

recurringbillingcontrol.SSLAcceptServerCertEncoded[=string]

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.

To read or write binary data to the property, a Variant (Byte Array) version is provided in .SSLAcceptServerCertEncodedB.

This property is not available at design time.

Data Type

Binary String

SSLCertEffectiveDate Property (RecurringBilling Control)

The date on which this certificate becomes valid.

Syntax

recurringbillingcontrol.SSLCertEffectiveDate

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 (RecurringBilling Control)

The date on which the certificate expires.

Syntax

recurringbillingcontrol.SSLCertExpirationDate

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 (RecurringBilling Control)

A comma-delimited list of extended key usage identifiers.

Syntax

recurringbillingcontrol.SSLCertExtendedKeyUsage

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLCertFingerprint

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLCertFingerprintSHA1

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLCertFingerprintSHA256

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 (RecurringBilling Control)

The issuer of the certificate.

Syntax

recurringbillingcontrol.SSLCertIssuer

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 (RecurringBilling Control)

The private key of the certificate (if available).

Syntax

recurringbillingcontrol.SSLCertPrivateKey

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 (RecurringBilling Control)

Whether a PrivateKey is available for the selected certificate.

Syntax

recurringbillingcontrol.SSLCertPrivateKeyAvailable

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLCertPrivateKeyContainer

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 (RecurringBilling Control)

The public key of the certificate.

Syntax

recurringbillingcontrol.SSLCertPublicKey

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLCertPublicKeyAlgorithm

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLCertPublicKeyLength

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 (RecurringBilling Control)

The serial number of the certificate encoded as a string.

Syntax

recurringbillingcontrol.SSLCertSerialNumber

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 (RecurringBilling Control)

The text description of the certificate's signature algorithm.

Syntax

recurringbillingcontrol.SSLCertSignatureAlgorithm

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 (RecurringBilling Control)

The name of the certificate store for the client certificate.

Syntax

recurringbillingcontrol.SSLCertStore[=string]

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

To read or write binary data to the property, a Variant (Byte Array) version is provided in .SSLCertStoreB.

Data Type

Binary String

SSLCertStorePassword Property (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLCertStorePassword[=string]

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 (RecurringBilling Control)

The type of certificate store for this certificate.

Syntax

recurringbillingcontrol.SSLCertStoreType[=integer]

Possible Values

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

0

Remarks

The type of certificate store for this certificate.

The control supports both public and private keys in a variety of formats. When the cstAuto value is used, the control will automatically determine the type. This property can take one of the following values:

Data Type

Integer

SSLCertSubjectAltNames Property (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLCertSubjectAltNames

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

SSLCertThumbprintMD5 Property (RecurringBilling Control)

The MD5 hash of the certificate.

Syntax

recurringbillingcontrol.SSLCertThumbprintMD5

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 (RecurringBilling Control)

The SHA-1 hash of the certificate.

Syntax

recurringbillingcontrol.SSLCertThumbprintSHA1

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 (RecurringBilling Control)

The SHA-256 hash of the certificate.

Syntax

recurringbillingcontrol.SSLCertThumbprintSHA256

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 (RecurringBilling Control)

The text description of UsageFlags .

Syntax

recurringbillingcontrol.SSLCertUsage

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 (RecurringBilling Control)

The flags that show intended use for the certificate.

Syntax

recurringbillingcontrol.SSLCertUsageFlags

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 (RecurringBilling Control)

The certificate's version number.

Syntax

recurringbillingcontrol.SSLCertVersion

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 (RecurringBilling Control)

The subject of the certificate used for client authentication.

Syntax

recurringbillingcontrol.SSLCertSubject[=string]

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 (RecurringBilling Control)

The certificate (PEM/Base64 encoded).

Syntax

recurringbillingcontrol.SSLCertEncoded[=string]

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.

To read or write binary data to the property, a Variant (Byte Array) version is provided in .SSLCertEncodedB.

This property is not available at design time.

Data Type

Binary String

SSLProvider Property (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLProvider[=integer]

Possible Values

sslpAutomatic(0), 
sslpPlatform(1), 
sslpInternal(2)

Default Value

0

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic), the control 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 control 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 (RecurringBilling Control)

The date on which this certificate becomes valid.

Syntax

recurringbillingcontrol.SSLServerCertEffectiveDate

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 (RecurringBilling Control)

The date on which the certificate expires.

Syntax

recurringbillingcontrol.SSLServerCertExpirationDate

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 (RecurringBilling Control)

A comma-delimited list of extended key usage identifiers.

Syntax

recurringbillingcontrol.SSLServerCertExtendedKeyUsage

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLServerCertFingerprint

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLServerCertFingerprintSHA1

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLServerCertFingerprintSHA256

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 (RecurringBilling Control)

The issuer of the certificate.

Syntax

recurringbillingcontrol.SSLServerCertIssuer

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 (RecurringBilling Control)

The private key of the certificate (if available).

Syntax

recurringbillingcontrol.SSLServerCertPrivateKey

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 (RecurringBilling Control)

Whether a PrivateKey is available for the selected certificate.

Syntax

recurringbillingcontrol.SSLServerCertPrivateKeyAvailable

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLServerCertPrivateKeyContainer

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 (RecurringBilling Control)

The public key of the certificate.

Syntax

recurringbillingcontrol.SSLServerCertPublicKey

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLServerCertPublicKeyAlgorithm

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 (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLServerCertPublicKeyLength

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 (RecurringBilling Control)

The serial number of the certificate encoded as a string.

Syntax

recurringbillingcontrol.SSLServerCertSerialNumber

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 (RecurringBilling Control)

The text description of the certificate's signature algorithm.

Syntax

recurringbillingcontrol.SSLServerCertSignatureAlgorithm

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 (RecurringBilling Control)

The name of the certificate store for the client certificate.

Syntax

recurringbillingcontrol.SSLServerCertStore

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

To read or write binary data to the property, a Variant (Byte Array) version is provided in .SSLServerCertStoreB.

This property is read-only.

Data Type

Binary String

SSLServerCertStorePassword Property (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLServerCertStorePassword

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 (RecurringBilling Control)

The type of certificate store for this certificate.

Syntax

recurringbillingcontrol.SSLServerCertStoreType

Possible Values

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

0

Remarks

The type of certificate store for this certificate.

The control supports both public and private keys in a variety of formats. When the cstAuto value is used, the control will automatically determine the type. This property can take one of the following values:

This property is read-only.

Data Type

Integer

SSLServerCertSubjectAltNames Property (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.SSLServerCertSubjectAltNames

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

SSLServerCertThumbprintMD5 Property (RecurringBilling Control)

The MD5 hash of the certificate.

Syntax

recurringbillingcontrol.SSLServerCertThumbprintMD5

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 (RecurringBilling Control)

The SHA-1 hash of the certificate.

Syntax

recurringbillingcontrol.SSLServerCertThumbprintSHA1

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 (RecurringBilling Control)

The SHA-256 hash of the certificate.

Syntax

recurringbillingcontrol.SSLServerCertThumbprintSHA256

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 (RecurringBilling Control)

The text description of UsageFlags .

Syntax

recurringbillingcontrol.SSLServerCertUsage

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 (RecurringBilling Control)

The flags that show intended use for the certificate.

Syntax

recurringbillingcontrol.SSLServerCertUsageFlags

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 (RecurringBilling Control)

The certificate's version number.

Syntax

recurringbillingcontrol.SSLServerCertVersion

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 (RecurringBilling Control)

The subject of the certificate used for client authentication.

Syntax

recurringbillingcontrol.SSLServerCertSubject

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 (RecurringBilling Control)

The certificate (PEM/Base64 encoded).

Syntax

recurringbillingcontrol.SSLServerCertEncoded

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.

To read or write binary data to the property, a Variant (Byte Array) version is provided in .SSLServerCertEncodedB.

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

Data Type

Binary String

SubscriptionDesc Property (RecurringBilling Control)

Description of recurring subscription.

Syntax

recurringbillingcontrol.SubscriptionDesc[=string]

Default Value

""

Remarks

This field contains a description of the recurring subscription. Please see the RecurringBilling 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

SubscriptionDetailsCardExpMonth Property (RecurringBilling Control)

The expiration month of the card currently being processed for the recurring payments.

Syntax

recurringbillingcontrol.SubscriptionDetailsCardExpMonth

Default Value

0

Remarks

The expiration month of the card currently being processed for the recurring payments.

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

Data Type

Integer

SubscriptionDetailsCardExpYear Property (RecurringBilling Control)

The expiration year of the card currently being processed for the recurring payments.

Syntax

recurringbillingcontrol.SubscriptionDetailsCardExpYear

Default Value

0

Remarks

The expiration year of the card currently being processed for the recurring payments.

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

Data Type

Integer

SubscriptionDetailsCardNumber Property (RecurringBilling Control)

The card number currently being processed for the recurring payments.

Syntax

recurringbillingcontrol.SubscriptionDetailsCardNumber

Default Value

""

Remarks

The card number currently being processed for the recurring payments.

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

Data Type

String

SubscriptionDetailsEndDate Property (RecurringBilling Control)

The date in which the recurring payments will stop processing.

Syntax

recurringbillingcontrol.SubscriptionDetailsEndDate

Default Value

""

Remarks

The date in which the recurring payments will stop processing.

The date is returned in the format specified within the DateFormat config.

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

Data Type

String

SubscriptionDetailsFrequency Property (RecurringBilling Control)

The frequency in which payments will occur.

Syntax

recurringbillingcontrol.SubscriptionDetailsFrequency

Default Value

""

Remarks

The frequency in which payments will occur.

If SubscriptionDetailsFrequencyUnit is applicable, this property will contain the length of the corresponding SubscriptionDetailsFrequencyUnit in which payments will occur.

This component uses pre-defined Frequency values which are listed below. If a gateway returns any value not contained within the pre-defined list, the raw value will be returned.

• None
• Daily
• Weekly
• BiWeekly
• FourWeeks
• SemiMonthly
• Monthly
• BiMonthly
• Quarterly
• SemiAnnually
• Annually

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

Data Type

String

SubscriptionDetailsFrequencyUnit Property (RecurringBilling Control)

The unit frequency in which the payments will be processed.

Syntax

recurringbillingcontrol.SubscriptionDetailsFrequencyUnit

Default Value

""

Remarks

The unit frequency in which the payments will be processed.

This component uses pre-defined FrequencyUnit values which are listed below. If a gateway returns any value not contained within the pre-defined list, the raw value will be returned.

• Days
• Weeks
• Months
• Years

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

Data Type

String

SubscriptionDetailsLastPaymentDate Property (RecurringBilling Control)

The date that the last/previous transaction was processed.

Syntax

recurringbillingcontrol.SubscriptionDetailsLastPaymentDate

Default Value

""

Remarks

The date that the last/previous transaction was processed.

The date is returned in the format specified within the DateFormat config.

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

Data Type

String

SubscriptionDetailsNextPaymentDate Property (RecurringBilling Control)

The date of the next upcoming transaction.

Syntax

recurringbillingcontrol.SubscriptionDetailsNextPaymentDate

Default Value

""

Remarks

The date of the next upcoming transaction.

The date is returned in the format specified within the DateFormat config.

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

Data Type

String

SubscriptionDetailsRecurAmount Property (RecurringBilling Control)

The amount being charged on a recurring basis.

Syntax

recurringbillingcontrol.SubscriptionDetailsRecurAmount

Default Value

""

Remarks

The amount being charged on a recurring basis.

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

Data Type

String

SubscriptionDetailsRemainingPayments Property (RecurringBilling Control)

The total number of remaining payments until the recurring payments will stop processing.

Syntax

recurringbillingcontrol.SubscriptionDetailsRemainingPayments

Default Value

0

Remarks

The total number of remaining payments until the recurring payments will stop processing.

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

Data Type

Integer

SubscriptionDetailsStartDate Property (RecurringBilling Control)

The date in which the recurring payments started processing.

Syntax

recurringbillingcontrol.SubscriptionDetailsStartDate

Default Value

""

Remarks

The date in which the recurring payments started processing.

The date is returned in the format specified within the DateFormat config.

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

Data Type

String

SubscriptionDetailsStatus Property (RecurringBilling Control)

The current status of the recurring subscription.

Syntax

recurringbillingcontrol.SubscriptionDetailsStatus

Default Value

""

Remarks

The current status of the recurring subscription.

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

Data Type

String

SubscriptionDetailsSubscriptionId Property (RecurringBilling Control)

Contains the Subscription or Profile Identifier for the recurring payment.

Syntax

recurringbillingcontrol.SubscriptionDetailsSubscriptionId

Default Value

""

Remarks

Contains the Subscription or Profile Identifier for the recurring payment.

This property contains a subscription identifier or profile number used to reference a recurring payment.

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

Data Type

String

SubscriptionDetailsSubscriptionName Property (RecurringBilling Control)

Contains the name of the recurring subscription or profile.

Syntax

recurringbillingcontrol.SubscriptionDetailsSubscriptionName

Default Value

""

Remarks

Contains the name of the recurring subscription or profile.

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

Data Type

String

SubscriptionDetailsTotalPayments Property (RecurringBilling Control)

The total number of payments.

Syntax

recurringbillingcontrol.SubscriptionDetailsTotalPayments

Default Value

0

Remarks

The total number of payments.

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

Data Type

Integer

SubscriptionName Property (RecurringBilling Control)

The name of the recurring subscription or profile.

Syntax

recurringbillingcontrol.SubscriptionName[=string]

Default Value

""

Remarks

This field contains the name of the recurring subscription or profile. Please see the RecurringBilling 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

TestMode Property (RecurringBilling Control)

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

Syntax

recurringbillingcontrol.TestMode[=boolean]

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 control will fails with an error.

Data Type

Boolean

Timeout Property (RecurringBilling Control)

A timeout for the control.

Syntax

recurringbillingcontrol.Timeout[=integer]

Default Value

30

Remarks

If Timeout is set to a positive value, and an operation cannot be completed immediately, the control will retry the operation for a maximum of Timeout seconds.

The default value for Timeout is 30 (seconds).

Data Type

Integer

TransactionId Property (RecurringBilling Control)

Merchant-generated transaction Id used for all transactions.

Syntax

recurringbillingcontrol.TransactionId[=string]

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 (RecurringBilling Control)

Adds a special field name and the corresponding value.

Syntax

recurringbillingcontrol.AddSpecialField Name, Value

Remarks

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

CancelSubscription Method (RecurringBilling Control)

Cancels or deletes a recurring payment subscription.

Syntax

recurringbillingcontrol.CancelSubscription SubscriptionId

Remarks

This method is used to cancel or delete a recurring subscription identified by the specified SubscriptionId.

Config Method (RecurringBilling Control)

Sets or retrieves a configuration setting.

Syntax

recurringbillingcontrol.Config ConfigurationString

Remarks

Config is a generic method available in every control. It is used to set and retrieve configuration settings for the control.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the control, 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.

CreateSubscription Method (RecurringBilling Control)

Creates a new recurring subscription.

Syntax

recurringbillingcontrol.CreateSubscription 

Remarks

This method is used to create a recurring subscription based upon the payment details entered via PaymentSchedule.

DoEvents Method (RecurringBilling Control)

This method processes events from the internal message queue.

Syntax

recurringbillingcontrol.DoEvents 

Remarks

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

GetResponseVar Method (RecurringBilling Control)

Parses additional information out of the response.

Syntax

recurringbillingcontrol.GetResponseVar Name

Remarks

Due to the fact that this control 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 control 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".

GetSubscriptionStatus Method (RecurringBilling Control)

Retrieves the status of a recurring payment subscription.

Syntax

recurringbillingcontrol.GetSubscriptionStatus SubscriptionId

Remarks

This method retrieves the current status of the recurring payment subscription specified via SubscriptionId. SubscriptionDetails will be populated with the details about the subscription.

Interrupt Method (RecurringBilling Control)

Interrupts the current action.

Syntax

recurringbillingcontrol.Interrupt 

Remarks

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

ResetSpecialFields Method (RecurringBilling Control)

Resets all special fields to the default settings.

Syntax

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

UpdateSubscription Method (RecurringBilling Control)

Updates a recurring payment subscription.

Syntax

recurringbillingcontrol.UpdateSubscription SubscriptionId

Remarks

This method is used to update a recurring subscription, specified by SubscriptionId. Specify new values via PaymentSchedule before calling this method.

Error Event (RecurringBilling Control)

Information about errors during data delivery.

Syntax

Sub recurringbillingcontrol_Error(ErrorCode As Integer, Description As String)

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 (RecurringBilling Control)

Fired after the server presents its certificate to the client.

Syntax

Sub recurringbillingcontrol_SSLServerAuthentication(CertEncoded As String, CertSubject As String, CertIssuer As String, Status As String, Accept As Boolean)

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 (RecurringBilling Control)

Fired when secure connection progress messages are available.

Syntax

Sub recurringbillingcontrol_SSLStatus(Message As String)

Remarks

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

Config Settings (RecurringBilling Control)

The control 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 control, access to these internal properties is provided through the Config method.

RecurringBilling Config Settings

HTTP Config Settings

TCPClient Config Settings

SSL Config Settings

Socket Config Settings

Base Config Settings

Trappable Errors (RecurringBilling Control)

RecurringBilling Errors

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

HTTP Errors

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

TCPClient Errors

SSL Errors

TCP/IP Errors