Server Class

Properties   Methods   Events   Config Settings   Errors  

The Server class provides support for the 3DS Server role as defined in the EMV® 3-D Secure (EMV 3DS) specification.

Syntax

ipworks3ds.Server

Remarks

This class is designed to be used in a web server, or in a process used by a web server to facilitate EMV® 3-D Secure (EMV 3DS) functionality. The class is used primarily for the browser-based flow, but also for some operations in the app-based flow as detailed in other parts of the documentation.

Connecting with SSL Client Authentication

Many directory servers require client authentication via a client certificate. The SSLCert property is used to load the SSL client certificate. In order to properly authenticate to the directory server the entire certificate chain must be presented to the directory server during the initial SSL handshake. The sections below describe options for making sure the CA chain is included.

Option 1: PFX With CA Certs

The first option is to specify a PFX file which includes both the client certificate, and CA certificates. In this case the class will read the CA certificates from the PFX file and include them in the request.

Option 2: SSLCACerts Configuration Setting

Another option is to specify the CA certificates separately from the client certificate. To do this the SSLCACerts configuration setting may be set to a CrLf separated list of CA certificates. For instance:

String CA_INT = "-----BEGIN CERTIFICATE-----" + "\r\n" + "MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw" + "\r\n" + "..." + "\r\n" + "eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w" + "\r\n" + "F0I1XhM+pKj7FjDr+XNj" + "\r\n" + "-----END CERTIFICATE-----"; String CA_ROOT = "-----BEGIN CERTIFICATE-----" + "\r\n" + "MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp" + "\r\n" + "..." + "\r\n" + "8ECs48NRSON+/Pqm9Hxw1H3/yz2qLG4zTI7xJVDESZGEXadLwCJXD6OReX2F/BtU" + "\r\n" + "d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA" + "\r\n" + "-----END CERTIFICATE-----"; Server server = new Server(); server.config("SSLCACerts=" + CA_INT + "\r\n" + CA_ROOT);

Option 3: PEM With CA Certs

A PEM formatted certificate which also includes CA certificates may also be specified. For instance the PEM file being loaded may have a structure like:

Bag Attributes
    Microsoft Local Key set: <No Values>
    localKeyID: 01 00 00 00 
    friendlyName: te-0363d475-2ebe-48b1-9d9f-ea8cfb07b126
    Microsoft CSP Name: Microsoft RSA SChannel Cryptographic Provider
Key Attributes
    X509v3 Key Usage: 10 
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDb1RX3CYoztcwf
...
JX/XQWa1OItqrewBtxfGeQCEvvnZhyXcq7nzcmD4JrXuxfc9dFy5K7foDcQ6BWbM
9oDdzr2/+19vs5WabbBJGUo=
-----END PRIVATE KEY-----
Bag Attributes
    localKeyID: 01 00 00 00 
    friendlyName: Visa3DS
subject=/C=US/ST=NC/L=Chapel Hill/O=nsoftware/OU=3DS/CN=mail2.nsoftware.com
issuer=/CN=VBVTESTSUITE2_RSA_CA_CTE/OU=VBVTESTSUITE/O=VISA/L=Denver/ST=Colorado/C=US
-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIVANc/jXXrtQF1sbQaW4KKpku8w52KMA0GCSqGSIb3DQEB
...
/aNMmRJUNxoWX3gViV/laT8oNQmwde2+/JX1
-----END CERTIFICATE-----
Bag Attributes: <Empty Attributes>
subject=/C=US/O=Visa/OU=Visa International Service Association/CN=Visa ecommerce QA
issuer=/C=US/O=Visa/OU=Visa International Service Association/CN=Visa ecommerce QA
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----
Bag Attributes: <Empty Attributes>
subject=/CN=VBVTESTSUITE2_RSA_CA_CTE/OU=VBVTESTSUITE/O=VISA/L=Denver/ST=Colorado/C=US
issuer=/C=US/O=Visa/OU=Visa International Service Association/CN=Visa ecommerce QA
-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----

Card Ranges

The application using the 3DS Server class should maintain a cache of card range information that can be queried when a transaction is initiated. The RequestCardRanges method will retrieve card range information to be cached.

RequestCardRanges requests card ranges and additional information from the directory server.

When a transaction is initiated, the first step that should be taken is to find information about the card range to which the card number belongs. This includes the protocol version(s) supported by the ACS and DS, and if one exists, any corresponding Method URL (used in the browser flow).

Results of this method should be cached in order to quickly look up information when processing transactions. It is recommended to call this method once every 24 hours at a minimum, and once per hour as a maximum to refresh the cache. The class will not cache the returned values; it is up to the user to cache these values in an appropriate location.

The first time this method is called, SerialNumber will be empty, indicating that all results should be returned. This is an offset the server will use to return only new updates to the card ranges (if any) since the last request. The SerialNumber will be populated after this method returns, and this value should be saved to be used in subsequent calls.

When a response is received, the card ranges will be made available via the component events and properties.

When ProtocolVersion is set to 2.3.1, the CardRangeData event will fire for each card range data object received, and the Ranges and ACSProtocolInfos properties will be populated to be accessed within the event handler. Optionally, the DS may return a list of URLs that the 3DS Server can use for communication with the DS. If present, these will be available via both the DSURL event and the DSURLs property.

When ProtocolVersion is set to 2.2.0 or 2.1.0, the CardRange event will fire for each card range that is returned, and the results will also be held in the CardRanges property.

The following properties are applicable when calling this method:

The following properties are populated after calling this method:

Note that when ProtocolVersion 2.3.1, the card range data is only available using the CardRangeData event.

When using ProtocolVersion 2.2.0 or 2.3.1, the returned ranges may include ACS Information Indicators. These are used to indicate additional functionality supported by the ACS for the card range(s). For 2.2.0, a ACSInformationIndicator field is exposed in both CardRanges collection and CardRange event. In version 2.3.1, this information is availalbe in the ACSProtocolInfos collection via the Indicator field. Possible values are:

  • 01 - Authentication Available at ACS
  • 02 - Attempts Supported by ACS or DS
  • 03 - Decoupled Authentication Supported
  • 04 - Whitelisting Supported
  • 05 - Device Binding Supported (2.3.1 only)
  • 06 - WebAuthn Authentication Supported (2.3.1 only)
  • 07 - SPC Authentication Supported (2.3.1 only)
  • 08 - Transaction Risk Analysis Exemption Supported (2.3.1 only)
  • 09 - Trust List Exemption Supported (2.3.1 only)
  • 10 - Low Value Exemption Supported (2.3.1 only)
  • 11 - Secure Corporate Payments Exemption Supported (2.3.1 only)
  • 80-99 - Reserved for DS Use

If an error is identified with the card range data received from the directory server when calling the RequestCardRanges method, the ResendRequestCardRanges configuration setting will be true, indicating that the request should be resent. When resending, if SerialNumber was specified for the initial request, it should be set to an empty string before calling RequestCardRanges again. Otherwise, the request can be sent without the serial number again, but the server may respond with an error due to multiple requests within an hour.

Note that retrieving card ranges can consume a lot of memory, especially when retrieving the initial set of ranges. The StoreCardRangeData and UseJsonDOM configuration settings can be set to help minimize the amount of memory used. A CardRangeTempPath setting can also be used to specify a temporary path to which the PRes packet will be temporarily written prior to parsing.

When using ProtocolVersion 2.3.1, if UseJsonDOM is false, the card ranges will need to be cached and processed after the RequestCardRanges method returns. The card ranges would then need to be processed in the order indicated by the CardRangeRecordsReadOrder configuration setting. A check will also need to be made for overlap of ranges. If issue(s) are found, the ReportCardRangeError configuration setting should be used to report the error to the directory server.

Method Invocation

The GetMethodData method prepares data to be transmitted to the ACS via the cardholder's browser.

When a transaction begins, the card range cache should be queried to find details about the card range to which the card number belongs. If a MethodURL is defined for the card range, this method should be used to prepare data to be sent via the cardholder's browser to the MethodURL.

If the MethodURL is not set for the specified card range, set MethodCompletionIndicator to U before calling SendAuthRequest.

The following properties are applicable when calling this method:

This method returns a string which contains encoded data to be sent to the ACS. This includes ServerTransactionId and MethodNotificationURL. After calling this method, the returned string can be transmitted to the ACS via the cardholder's browser.

As per the EMVCo specification, create a hidden iframe in the browser and send a form with the field name threeDSMethodData containing the return value from this method and post the form to the MethodURL.

The ACS will record information about the customer's environment and then POST back to the MethodNotificationURL. The page at this URL should expect a form variable with the name threeDSMethodData which will contain the original ServerTransactionId value in order to match the response with the request. The form variable value will be base64url encoded and may be passed directly to the CheckResponse method. The class will decode and parse the received value and populate ServerTransactionId with the value from the received data.

If the response from the ACS is not received within 10 seconds, set MethodCompletionIndicator to N before calling SendAuthRequest.

Sending the Authentication Request

SendAuthRequest begins the 3-D Secure transaction flow by sending an authentication request to the DirectoryServerURL.

After calling this method, check TransactionStatus to determine if the cardholder is authenticated (frictionless flow) or further cardholder interaction is required to complete the authentication (challenge flow).

Prior to calling SendAuthRequest, data must to be collected to facilitate fraud checks by the ACS. The following properties are applicable for both app-based and browser-based flows:

App-Based Flow

In the app-based flow, device specific information is prepared by the 3DS SDK on the customer's device. This is transmitted to the 3DS Server class via a secure channel, the specifics of which are outside the scope of the classs. Set ClientAuthRequest to this data prepared by the 3DS SDK.

Browser-Based Flow

Before calling this method, first check the cached card-range data to determine if a MethodURL has been set by the ACS. Card range data may be retrieved by calling RequestCardRanges.

If no MethodURL is present for the given card, set MethodCompletionIndicator to U.

If a MethodURL has been specified by the ACS for the card number, the URL must be loaded in the cardholder's browser to allow the ACS to collect additional browser information for risk-based decision making. See the GetMethodData for further details.

Once the method URL invocation is complete, the authentication request may be sent. If the method URL invocation failed, set MethodCompletionIndicator to N before calling SendAuthRequest.

The following additional properties are applicable in browser-based flow:

Response Handling

After calling this method the TransactionStatus property holds the result. Possible values are:

Transaction Status Description
Y Authenticated successfully
C Cardholder challenge required
N Not authenticated
A Not authenticated, but a proof of authentication attempt was generated in AuthenticationValue
U Not authenticated due to technical or other issue
R Not authenticated because the issuer is rejecting authentication
D Challenge required; decoupled authentication confirmed
I Informational only; 3DS Requestor challenge preference acknowledged
S Challenge using SPC

If the transaction is authenticated (Y or A), no further steps are required. The flow is considered frictionless and the 3-D Secure processing is complete. If processing a payment, the AuthenticationValue and AuthenticationECI values can be included as proof of 3-D Secure authentication.

If the transaction requires a cardholder challenge (C, D or S), further steps are required.

If the transaction is not authenticated, TransactionStatusReason may contain details about the reason.

The following properties are applicable after calling this method:

Response Handling - App-Based Flow

After calling this method, ClientAuthResponse is populated with data to be transmitted back to the 3DS SDK. If a challenge is required, the ClientAuthResponse data is used by the 3DS SDK to start when initiating the challenge process.

The 3DS Server is responsible for indicating to the 3DS SDK the results of the SendAuthRequest process, and whether or not a challenge is required. Exactly how this is done is outside the scope of the classs themselves. The response to the 3DS SDK over the secure channel should include information on what to do next.

Note: The TransactionStatus is also populated in the 3DS Server class and may be inspected prior to transmitting ClientAuthResponse back to the 3DS SDK.

Response Handling - Browser-Based Flow

If TransactionStatus is C, then additional steps are required to complete the authentication. The GetChallengeRequest method should be called next to obtain data to be sent to the ACSURL in an authentication window in the customer's browser. Once authentication is complete, the ACS will post the results to the ResultsURL value that was specified when calling SendAuthRequest.

See the GetChallengeRequest method for more details.

If TransactionStatus is D, then decoupled authentication has been accepted by the ACS. DecoupledConfirmationIndicator will have a value of Y as well. Authentication will happen outside of the 3-D Secure flow and, when complete, the ACS will post the results to the ResultsURL that was specified when calling SendAuthRequest.

The DecoupledTimeRemaining value, which is calculated based on the DecoupledMaxTimeout value sent in the initial authentication request, can be checked to see the amount of time remaining before decoupled authentication must be completed. If the ACS does not post the results before this value runs out, it can be assumed that decoupled authentication was not successful.

SPC-Based Authentication

SPC (Secure Payment Confirmation) provides a method to perform a challenge using preestablished FIDO credentials when using a Browser. The SPC authentication can be initiated by the 3DS Requestor via an extra AReq/ARes message pair or by the ACS via a standard Browser Challenge Flow.

For an SPC authentication to execute correctly, the following prerequisites apply:

  1. The ACS has an enrolled FIDO authenticator on the device for this Cardholder.
  2. The 3DS Requestor and/or the ACS have detected that the Cardholder Browser supports the related SPC APIs (allow="payment *; publickey-credentialsget *"). For the ACS, this information can be obtained via the Browser User Agent data element or via data obtained via the 3DS Method.

SPC-based authentication can be enabled with the following additions:

Prior to sending the initial authentication request packet (AReq) using the SendAuthRequest method, the ThreeDSRequestorSpcSupport configuration setting should be set to Y to indicate that SPC is supported by the 3DS Requestor.

If SPC is accepted by the ACS, the resulting TransactionStatus should be S. The response will also contain a list of enrolled FIDO (WebAuthn) credentials associated with the cardholder, and SPC transaction data. This data is available in the following configuration settings:

If a new instance of the Server component will be used after authentication to send the second AReq, the AuthenticationInformation value should be saved to be used later.

This information is relayed to the 3DS Requestor implementation, and the 3DS Requestor invokes the SPC authentication (SPC API) against the WebAuthn Credential list. The cardholder authenticates using the FIDO authenticator on their device, and the 3DS Requestor retrieves the Assertion Data from the SPC API call.

The 3DS Server is then configured to includes this FIDO Assertion Data is then included in a new authentication request by setting the ReqAuthData and a ReqAuthMethod of 09. If the AuthenticationInformation value was saved earlier, it can be set via the same configuration setting. If the 3DS Requestor encounters an error during SPC API invokation, this can be indicated using the SPCIncompletionIndicator.

The SendAuthRequest method should then be called again to transmit this data to the ACS (by way of the DS) in a second AReq.

When SendAuthRequest returns, the 3DS Server proceed the same as the regular browser-based flow when the ARes is returned.

When SPC authentication is to be performed, the authenticaton must be completed within 9 minutes. The component will automatically start an internal timer that can be checked using the CheckSPCTimeout configuration setting. This will return the number of seconds left for SPC authentication to complete. If the time has expired before receiving the Assertion Data from the 3DS Requestor, checking this configuration setting will cause the component to automatically send the second AReq message with an SPCIncompletionIndicator value of 03, indicating that SPC authentication timed out.

Note that SPC-based authentication is only available when a ProtocolVersion of 2.3.1 is used.

Challenge Interaction

If the TransactionStatus is C, a challenge is required.

The GetChallengeRequest method is used to build the Challenge Request (CReq) which will be sent in a form post to the ACSURL property via the cardholder browser.

An iframe should be created in the cardholder's browser, which will be used to send the challenge request and allow the cardholder and ACS to interact directly.

The size of the challenge window (iframe) may be any of the sizes listed in ChallengeWindowSize. Before calling this method set ChallengeWindowSize to the appropriate value to let the ACS know the size of the window on the cardholder's browser.

Calling this method will return a string which should be placed in a creq form variable.

The SessionData setting may also be set with any data that may be helpful to continue processing the transaction after the final challenge response is received at the NotificationURL. To prepare the session data for submission, query EncodedSessionData. The encoded string may then be placed in the threeDSSessionData form variable.

Note: The maximum length of the threeDSSessionData form variable, after being encoded, is 1024 bytes.

Example Form

out.write("<form name='downloadForm' action='" + ACSURL + "' method='POST'>"); out.write(" <INPUT type='hidden' name='creq' value='" + ChallengeRequest + "'>"); out.write(" <input type='hidden' name='threeDSSessionData' value='" + EncodedSessionData + "'>"); out.write("</form>"); out.write("<script>"); out.write("window.onload = submitForm;"); out.write("function submitForm() { downloadForm.submit(); }"); out.write("</script>");

Response Handling

Once the challenge has been completed by the cardholder, the directory server will post a Results Request (RReq) to the ResultsURL specified when calling SendAuthRequest. See CheckResponse and GetResultsResponse for more details.

The ACS will also post the Challenge Response to the NotificationURL specified when calling SendAuthRequest. This post contains data which may be parsed to verify the challenge results. See CheckResponse for more details.

Response Handling

After a challenge is complete, the Directory Server and ACS will POST data back to the web server for additional processing. CheckResponse parses a variety of messages that are sent to the Server as part of the authentication process.

The following messages can be parsed using this method:

  • The threeDSMethodData form variables received at the MethodNotificationURL
  • The Results Request (RReq) message received at the ResultsURL
  • The cres form variables received at the NotificationURL
  • The Operation Request Message (OReq) sent from a DS.

When calling the method, pass the message to be parsed as the Response parameter. The properties which are populated after calling this method vary depending on the type of message being parsed. See below for additional information.

Method Data from MethodNotificationURL

After calling GetMethodData, a request is made to the MethodURL. After this, the ACS will make a POST to MethodNotificationURL to inform the requestor of completion. Retrieve the threeDSMethodData form variable value that was POSTed and pass it to this method. After calling this method, the following properties are populated:

The ServerTransactionId may be used to match the response with the request.

Results Request message from ResultsURL

When a challenge is completed for both app-based and browser-based flows, a POST is made to the ResultsURL with a Results Request message.

Prior to checking this RReq message, the ServerTransactionId can be extracted using the ExtractRReqServerTransactionId configuration setting. This value can then be used to look up details on the transaction that were saved prior to starting the challenge process, including the messageVersion which must be set via the ProtocolVersion configuration setting prior to passing the RReq message to the CheckResponse method.

Pass the body of the HTTP request received at ResultsURL to this method. This contains information about the results, and asks for a Results Response to be sent back containing the ResultsStatus.

After calling this method, the following properties are populated:

To respond to the POST, set ResultsStatus to the appropriate value and call GetResultsResponse to build a response message to be sent back to the directory server. Use the value from GetResultsResponse in the application as the body of the HTTP response. Set the Content-Type header to application/JSON; charset=utf-8

If TransactionStatus is D and TransactionStatusReason is 29 or 30, this indicates that decoupled authentication should now be performed. When building the Results Response, a ResultsStatus value of 04 should be used. Then, within 60 seconds, a new 3RI authentication must be started with the following field requirements:

Final Challenge Response from NotificationURL

In a browser-based flow, the challenge takes place directly between the cardholder and the ACS in a separate iframe or window. The ACS will POST the final challenge response to the NotificationURL after the challenge is complete. Retrieve the cres form variable value from the POST data and pass it to CheckResponse. After calling this method the following properties are populated:

In addition to the cres variable, a threeDSSessionData variable will be present if SessionData was set before calling GetChallengeRequest. The threeDSSessionData value POSTed to NotificationURL may be passed to EncodedSessionData. Query SessionData to get the decoded session data.

Operation Request Message (OReq)

OReq messages are used to communicate operational information from a DS to the 3DS Server. This message is not part of the 3-D Secure authentication flow.

When an OReq message is received, CheckResponse should be called to validate the message. There may be more than one OReq message sent in a sequence, and CheckResponse should be called for each. The current instance of the Server object can be cached for the duration of the OReq sequence until the final OReq is received. The Operation.SequenceNumber should also be set prior to calling CheckResponse. The component will verify the sequence number of the received OReq to ensure it's not out of sequence.

After calling this method, details are made available in Operation.

If any OReq data element fails validation, Operation.MessageStatus will be set to "02". If the OReq is valid, Operation.MessageStatus will be empty.

If the OReq is valid, determine if the final OReq has been received (Operation.SequenceNumber equals Operation.SequenceTotal). If these values match, the final OReq in the sequence has been received, and GetOperationResponse can be used to generate the ORes message.

For valid OReq messages that are not the final OReq in the sequence, the response should be HTTP Status 200 (OK) with an empty HTTP body.

Logging Notes

Logging in the component is handled through the Log event. This will fire anytime a message is built or a response is parsed, including error messages.

When the Log event is fired, the message in question is made available via the Message event parameter. Properties such as EphemeralKey and DeviceParams are also available when they are gathered by the Client. The other event arguments are LogType and LogLevel:

The LogType parameter indicates the type of the log entry. Possible values are:

  • "Info"
  • "RequestHeaders"
  • "ResponseHeaders"
  • "RequestBody"
  • "ResponseBody"
  • "ProxyRequest"
  • "ProxyResponse"
  • "FirewallRequest"
  • "FirewallResponse"
  • "AReq"
  • "ARes"
  • "CReq"
  • "CRes"
  • "RReq"
  • "RRes"
  • "PReq"
  • "PRes"
  • "Erro"
  • "EphemeralKey"
  • "DeviceParams"
The LogLevel configuration setting can be used to specify the detail of the logs raised through the Log event. The LogLevel parameter in the event indicates the log level to which the current message belongs.

It is recommended to output all messages raised in this event to a file for record keeping purposes, or for later debugging issues that may have come up.

The Server and Client components also have DataPacketIn and DataPacketOut events that fire anytime a data packet is received or sent, respectively. The entire data packet is then accessible in the DataPacket event parameter. For encrypted packets, this would contain the full encrypted data. This parameter may be inspected for advanced troubleshooting.

Property List


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

AcceptLanguageHTTP accept language header value sent from the cardholder's browser.
AccountTypeIndicates the type of account.
AcquirerBINAcquiring institution identification code.
AcquirerCountryCodeAcquirer Country Code.
AcquirerMerchantIdAcquirer-assigned merchant identifier.
ACSProtocolInfosA collection of protocol versions and other associated information supported by the ACS for a card range.
ACSURLURL of the ACS to be used for the challenge.
AuthenticationECIValue to be passed in the authorization message.
AuthenticationIndicator3DS Requestor Authentication Indicator.
AuthenticationValueUsed to provide proof of authentication.
BillingAddressThe customer's billing address.
BrowserAcceptHeaderHTTP accept header sent from the cardholder's browser.
BrowserIPAddressIP address of the cardholder's browser.
BrowserJavaEnabledValAbility of the cardholder's browser to execute Java.
BrowserJavaScriptEnabledValAbility of the cardholder's browser to execute JavaScript.
BrowserLanguageThe cardholder's browser language.
BrowserScreenColorDepthThe screen color depth of the cardholder's browser.
BrowserScreenHeightThe screen height of the cardholder's browser.
BrowserScreenWidthThe screen width of the cardholder's browser.
BrowserTimeZoneThe timezone offset of the cardholder's browser.
BrowserUserAgentThe User-Agent provided by the cardholder's browser.
CardExpDateExpiration date of the PAN or Token.
CardholderEmailThe cardholder email address.
CardholderHomePhoneThe cardholder home phone number.
CardholderMobilePhoneThe cardholder mobile phone number.
CardholderNameName of the cardholder.
CardholderWorkPhoneThe cardholder work phone number.
CardNumberCustomer's account number that will be authenticated.
CardRangesA collection of card ranges to be added to or removed from the cache.
ChallengeWindowSizeChallenge window size.
ClientAuthRequestThe data received by the class to be sent in the authentication request.
ClientAuthResponseThe authentication response for an app-based flow.
DataPacketOutContains the data packet sent to the server.
DeviceChannelDevice channel.
DirectoryServerURLThe address of the Directory Server.
DSSupportedProtocolsProtocol Versions supported by the DS.
DSURLsA collection of Directory Server URLs to which the 3DS Server will send the AReq message.
ErrorPacketThe error packet.
ExtensionsExtensions to be included in the next outgoing packet.
MerchantCategoryCodeMerchant category code.
MerchantCountryCodeCountry code of the merchant.
MerchantNameMerchant name.
MessageCategoryThe category of the message.
MethodNotificationURLThe URL to which the method notification will be posted.
NotificationURLThe notification URL to which the challenge response is sent.
OperationContains details received from an Operation Request Message sent from a Directory Server.
ProxyThis property includes a set of properties related to proxy access.
PurchaseAmountPurchase amount to be authorized.
PurchaseCurrencyIdentifies the type of currency used by the merchant.
PurchaseDateThe date of the transaction.
PurchaseExponentMinor units of currency.
RangesA collection of card ranges associated with the CardRangeData event.
RecurringExpDateRecurring expiration date.
RecurringFrequencyThe number of days between recurring payments.
RequestorIdDirectory server assigned 3DS Requestor identifier.
RequestorNameDirectory server assigned 3DS Requestor name.
RequestorURL3DS Requestor website or customer care site.
ResultsStatusThe status of the Results Request.
ResultsURL3DS Server URL.
SDKTypeType of the 3DS SDK used for the app-based flow.
SerialNumberSerial number indicating the state of the current card range cache.
ServerTransactionIdServer transaction identifier.
ShippingAddressThe customer's shipping address.
SSLAcceptServerCertInstructs the class to unconditionally accept the server certificate that matches the supplied certificate.
SSLCertThe certificate to be used during SSL negotiation.
SSLServerCertThe server certificate for the last established connection.
TimeoutA timeout for the class.
TransactionStatusThe transaction status from the last parsed message (ARes, RReq, or CRes).

Method List


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

AddExtensionAdds an extension to the collection.
AddRequestFieldAdds a field to the data in the request.
CheckResponseParses the specified message.
ConfigSets or retrieves a configuration setting.
GetChallengeRequestBuilds the Challenge Request (CReq) for browser-based flow.
GetMethodDataPrepares method data to be sent to the ACS before the authentication request is sent.
GetOperationResponseBuilds and returns the Operation Response Message (ORes) to be sent back to the Directory Server.
GetResultsResponseBuilds and returns the Results Response Message (RRes) to be sent back to the directory server.
InterruptInterrupts the current action.
RequestCardRangesRequests card ranges from the directory server.
ResetClears all properties to their default values.
ResetTransactionInfoResets transaction specific information.
SendAuthRequestSends the authentication request to the directory server.

Event List


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

CardRangeFired when the response to a Preparation Request Message (PReq) is received.
CardRangeDataFired when the response to a Preparation Request Message (PReq) is received. This event is used for card range data returned when version 2.3.1 of the protocol is used.
DataPacketInFired when receiving a data packet from the server.
DataPacketOutFired when sending a data packet to the server.
DSURLFired for each DS URL present in the Preparation Response Message (PRes).
ErrorInformation about errors during data delivery.
LogFires once for each log message.
MessageExtensionFired when a Message Extension is present in a message being parsed.
SSLServerAuthenticationFired after the server presents its certificate to the client.
SSLStatusShows the progress of the secure connection.

Config Settings


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

AccountAgeIndicatorCardholder Account Age Indicator.
AccountChangeDateCardholder Account Change Date.
AccountChangeIndicatorCardholder Account Change Indicator.
AccountDateDate cardholder account opened.
AccountDayTransactionsNumber of account transactions in the last day.
AccountIdCardholder Account Identifier.
AccountPasswordChangeDateCardholder Account Password Change Date.
AccountPasswordChangeIndicatorCardholder Account Password Change Indicator.
AccountProvisioningAttemptsNumber of account provisioning attempts in the last day.
AccountPurchaseCountCardholder Account Purchase Count.
AccountRequestorIDCardholder Account Requestor ID.
AccountYearTransactionsNumber of account transactions in the last year.
ACSChallengeMandatedIndicatorACS Challenge Mandated Indicator.
ACSOperatorIdACS identifier assigned by DS.
ACSReferenceNumberUnique ACS Reference Number.
ACSRenderingDeviceUserInterfaceModeUser interface mode the ACS will present to cardholder.
ACSRenderingInterfaceChallenge interface type presented to cardholder.
ACSRenderingUITemplateChallenge type presented to cardholder.
ACSSignedContentString value of the JWS object of the ARes message created by the ACS.
ACSTransactionIdUnique transaction identifier assigned by the ACS.
AddressMatchAddress Match Indicator.
AllowNullMethodURLAllow null MethodURL when retrieving card ranges.
AppIPApp IP Address.
AppURLIndicator3DS Requestor App URL Indicator.
AuthenticationInformation3DS Requestor Prior Transaction Authentication Information.
AuthenticationMethodA comma separated list of authentication types used by the issuer.
AuthenticationTypeType of authentication method used by the issuer.
BroadInfoBroadcast Information.
BroadInfoCategoryBroadcast Information Category.
BroadInfoDescriptionBroadcast Information Description.
BroadInfoExpiryDateBroadcast Information Expiry Date.
BroadInfoRecipientsBroadcast Information Recipient(s).
BroadInfoSeverityBroadcast Information Severity.
BroadInfoSourceBroadcast Information Source.
BrowserUserDeviceIdBrowser User Device ID.
BrowserUserIdBrowser User ID.
CardholderInformationInformation text presented to Cardholder during the transaction.
CardholderInformationIssuerImageIssuer image presented to the Cardholder during the transaction.
CardholderInformationPaymentSystemImagePayment system image presented to the Cardholder during the transaction.
CardRangeRecordsReadOrderIndicates the order in which to process the card range records from the PRes message.
CardRangeTempPathTemporary path where card range data is written.
CardSecurityCodeCard Security Code.
CardSecurityCodeStatusCard Security Code Status.
CardSecurityCodeStatusSourceCard Security Code Status Source.
ChallengeCancellationIndicatorChallenge Cancellation Indicator.
ChallengeErrorReportingACSTransIDChallenge Error Reporting ACS Transaction ID.
ChallengeErrorReportingDSTransIDChallenge Error Reporting DS Transaction ID.
ChallengeErrorReportingErrorCodeChallenge Error Reporting Error Code.
ChallengeErrorReportingErrorComponentChallenge Error Reporting Error Class.
ChallengeErrorReportingErrorDescriptionChallenge Error Reporting Error Description.
ChallengeErrorReportingErrorDetailChallenge Error Reporting Error Detail.
ChallengeErrorReportingErrorMessageTypeChallenge Error Reporting Error Message Type.
ChallengeErrorReportingMessageTypeChallenge Error Reporting Message Type.
ChallengeErrorReportingMessageVersionChallenge Error Reporting Message Version.
ChallengeErrorReportingSDKTransIDChallenge Error Reporting SDK Transaction ID.
ChallengeErrorReportingThreeDSServerTransIDChallenge Error Reporting Server Transaction ID.
ChallengeTimeRemainingAmount of time left to complete challenge.
CheckSPCTimeoutTime remaining for SPC authentication to complete.
ClearCustomRequestFieldsClear the custom request fields internal collection.
ContinueParsingCardRangesOnErrorWhether or not to continue parsing card ranges when a validation error is encountered.
DecoupledConfirmationIndicatorACS Decoupled Confirmation Indicator.
DecoupledMaxTimeout3DS Requestor Decoupled Max Time.
DecoupledRequestIndicator3DS Requestor Decoupled Request Indicator.
DecoupledTimeRemainingTime remaining before a RReq should be received during a decoupled authentication.
DeliveryEmailAddressMerchandise Delivery Email Address.
DeliveryTimeframeMerchandise Delivery Timeframe.
DeviceBindingStatusDevice Binding Status.
DeviceBindingStatusSourceDevice Binding Status Source.
DeviceInfoRecognisedVersionDevice Information Recognized Version.
DeviceRenderingInterfaceSDK Interface Device Rendering Types supported.
DeviceRenderingUITypeSDK UI Types supported.
DSEndProtocolVersionDS End Protocol Version.
DSReferenceNumberDS Reference Number.
DSStartProtocolVersionDS Start Protocol Version.
DSTransactionIdDirectory server transaction ID.
EMVPaymentTokenIndicatorEMV Payment Token Indicator.
EMVPaymentTokenSourceEMV Payment Token Source.
EnableDownloadCardRangeDataFileCard Range Data Download Indicator.
EncodedSessionDataEncoded session data that is sent in the challenge request and returned in the challenge response.
EncryptedDeviceInfoSDK Encrypted Data.
ErrorCodeCode from the last error message.
ErrorDescriptionDescription from the last error message.
ErrorDetailAdditional details from the last error message.
ExtractRReqServerTransactionIdExtacts the ServerTransactionId from the RReq packet.
GiftCardAmountTotal gift card(s) amount.
GiftCardCountTotal number of gift cards purchased.
GiftCardCurrencyGift Card Currency.
IncomingExtensionCountThe number of extensions received from the directory server.
IncomingExtensionCritical[Index]Whether the extension is critical.
IncomingExtensionData[Index]The extension data as JSON.
IncomingExtensionId[Index]The id of the specified extension.
IncomingExtensionName[Index]The extension name.
IncomingRawExtensionsThe full JSON formatted extension data received from the directory server.
InstalmentPaymentDataMax authorizations permitted for installment payments.
InteractionCounterInteraction Counter.
LogLevelLevel of logging enabled.
MaskSensitiveWhether to mask sensitive data in the Log event.
MessageTypeType of message that is passed.
MethodCompletionIndicator3DS Method Completion Indicator.
MultiTransactionAcquirerMerchantIDAcquirer Merchant ID.
MultiTransactionAVNumberUseAV Number Use.
MultiTransactionAVValidityTimeAV Validity Time.
MultiTransactionCountThe total number of additional transactions specified.
MultiTransactionMerchantAmountMerchant Amount.
MultiTransactionMerchantCurrencyCodeMerchant Currency Code.
MultiTransactionMerchantCurrencyExponentMerchant Currency Exponent.
MultiTransactionMerchantNameMerchant Name.
MultiTransactionSellerIDSeller ID.
OutgoingRawExtensionsThe full JSON formatted extension data sent to the directory server.
PaymentAccountAgePayment Account Age.
PaymentAccountAgeIndicatorPayment Account Age Indicator.
PaymentTokenEMV Payment Token.
PaymentTokenAdditionalDataEMV Payment Token Additional Data.
PaymentTokenCryptogramEMV Payment Token Cryptogram.
PaymentTokenStatusIndicatorEMV Payment Token Status Indicator.
PersistCustomRequestFieldsWhether or not to store custom request fields for subsequent requests.
PreOrderDateExpected date pre-ordered purchase will be available.
PreOrderPurchaseIndicatorPre-Order Purchase Indicator.
ProtocolVersionProtocol version identifier.
RecurringAmountRecurring Amount.
RecurringAmountIndicatorRecurring Amount Indicator.
RecurringCurrencyRecurring Currency.
RecurringDateRecurring Date.
RecurringExponentRecurring Currency Exponent.
RecurringFrequencyIndicatorRecurring Frequency Indicator.
ReorderItemsIndicatorReorder Items Indicator.
ReportCardRangeErrorReport a Card Range Error to the DS.
ReqAuthCountNumber of 3DS Requestor Authentication Data objects.
ReqAuthData3DS Requestor Authentication Data.
ReqAuthMethod3DS Requestor Authentication Method.
ReqAuthTimestamp3DS Requestor Authentication Timestamp.
RequestorChallengeInd3DS Requestor Challenge Indicator.
ResendRequestCardRangesWhether or not to resend the card ranges request.
SdkAppIdSDK App ID.
SdkAuthenticationTypeSDK Authentication Type.
SDKEphemeralPublicKeyPublic key class of the ephemeral key pair generated by the Client.
SDKMaxTimeoutSDK Maximum Timeout.
SDKMaxTimeoutSDK Maximum Timeout.
SDKReferenceNumberAssigned SDK reference number.
SDKServerSignedContentSDK Server Signed Content.
SDKTransactionIdSDK Transaction ID.
SDKWrappedDefault-SDK Wrapped Indicator.
SellerInfoSeller Information.
ServerOperatorId3DS Server identifier.
SessionDataSession data that is sent in the challenge request and returned in the challenge response.
ShipAddressUsageDateShipping address first usage date.
ShipAddressUsageIndicatorShipping address usage indicator.
ShipIndicatorShipping method indicator.
ShipNameIndicatorShipping Name Indicator.
SPCIncompletionIndicatorSPC Incompletion Indicator.
SPCTransactionAdditionalDataSPC Transaction Additional Data.
SPCTransactionChallengeSPC Transaction Challenge.
SPCTransactionChallengeInfoTextSPC Transaction Challenge Information Text.
SPCTransactionCurrencySPC Transaction Currency.
SPCTransactionDisplayNameSPC Transaction Display Name.
SPCTransactionExtensionIndicatorSPC Transaction WebAuthn SPC Extension Indicator.
SPCTransactionIconSPC Transaction Icon.
SPCTransactionIssuerImageSPC Transaction Issuer Default Image.
SPCTransactionIssuerImageDarkSPC Transaction Issuer Dark Mode Image.
SPCTransactionIssuerImageMonochromeSPC Transaction Issuer Monochrome Image.
SPCTransactionPayeeNameSPC Transaction Payee Name.
SPCTransactionPayeeOriginSPC Transaction Payee Origin.
SPCTransactionPSImageSPC Transaction Payment System Default Image.
SPCTransactionPSImageDarkSPC Transaction Payment System Dark Mode Image.
SPCTransactionPSImageMonochromeSPC Transaction Payment System Monochrome Image.
SPCTransactionTimeoutSPC Transaction Transaction Timeout.
SPCTransactionValueSPC Transaction Value.
SplitSDKLimitedLimited Split-SDK Indicator.
SplitSDKVariantSplit-SDK Variant.
StoreCardRangeDataWhether or not to store the card ranges in the CardRanges collection.
SuspiciousAccountActivitySuspicious account activity indicator.
TaxIdTax ID.
ThreeDSMethodId3DS Method ID.
ThreeDSRequestorSpcSupport3DS Requestor SPC Support.
ThreeRIIndicator3RI Indicator.
TransactionChallengeExemptionTransaction Challenge Exemption.
TransactionCharacteristicsTransaction Characteristics.
TransactionStatusReasonReason for value of TransactionStatus.
TransactionStatusReasonInfoTransaction Status Reason Information.
TransactionTypeTransaction Type.
TrustListStatusTrust List Status.
TrustListStatusSourceTrust List Status Source.
UseAESGCMWhether or not to use AESGCM as the encryption algorithm.
UseJsonDOMWhether or not the class should build an internal DOM when parsing card ranges.
WebAuthnCredentialListCountThe total number of WebAuthen Credentials.
WebAuthnCredentialListRelyingPartyIdWebAuthn Credential List: Relying Party ID.
WebAuthnCredentialListWebAuthnCredentialWebAuthn Credential List: WebAuthn Credential.
WhitelistStatusWhitelist Status.
WhitelistStatusSourceWhitelist Status Source.
XChildCountThe number of child elements of the current element.
XChildName[i]The name of the child element.
XChildXText[i]The inner text of the child element.
XElementThe name of the current element.
XParentThe parent of the current element.
XPathProvides a way to point to a specific element in the returned XML or JSON response.
XSubTreeA snapshot of the current element in the document.
XTextThe text of the current element.
LogSSLPacketsControls whether SSL packets are logged when using the internal security API.
ReuseSSLSessionDetermines if the SSL session is reused.
SSLCACertsA newline separated list of CA certificate to use during SSL client authentication.
SSLCheckCRLWhether to check the Certificate Revocation List for the server certificate.
SSLCheckOCSPWhether to use OCSP to check the status of the server certificate.
SSLCipherStrengthThe minimum cipher strength used for bulk encryption.
SSLContextProtocolThe protocol used when getting an SSLContext instance.
SSLEnabledCipherSuitesThe cipher suite to be used in an SSL negotiation.
SSLEnabledProtocolsUsed to enable/disable the supported security protocols.
SSLEnableRenegotiationWhether the renegotiation_info SSL extension is supported.
SSLIncludeCertChainWhether the entire certificate chain is included in the SSLServerAuthentication event.
SSLKeyLogFileThe location of a file where per-session secrets are written for debugging purposes.
SSLNegotiatedCipherReturns the negotiated cipher suite.
SSLNegotiatedCipherStrengthReturns the negotiated cipher suite strength.
SSLNegotiatedCipherSuiteReturns the negotiated cipher suite.
SSLNegotiatedKeyExchangeReturns the negotiated key exchange algorithm.
SSLNegotiatedKeyExchangeStrengthReturns the negotiated key exchange algorithm strength.
SSLNegotiatedVersionReturns the negotiated protocol version.
SSLServerCACertsA newline separated list of CA certificate to use during SSL server certificate validation.
SSLTrustManagerFactoryAlgorithmThe algorithm to be used to create a TrustManager through TrustManagerFactory.
TLS12SignatureAlgorithmsDefines the allowed TLS 1.2 signature algorithms when SSLProvider is set to Internal.
TLS12SupportedGroupsThe supported groups for ECC.
TLS13KeyShareGroupsThe groups for which to pregenerate key shares.
TLS13SignatureAlgorithmsThe allowed certificate signature algorithms.
TLS13SupportedGroupsThe supported groups for (EC)DHE key exchange.

AcceptLanguage Property (Server Class)

HTTP accept language header value sent from the cardholder's browser.

Syntax


public String getAcceptLanguage();


public void setAcceptLanguage(String acceptLanguage);

Default Value

""

Remarks

Value representing the browser language preference present in the HTTP header, as defined in IETF BCP 47.

This property accepts a comma separated list of language tags. For example: en,fr-FR

Valid for ProtocolVersion 2.3.1 only.

AccountType Property (Server Class)

Indicates the type of account.

Syntax


public String getAccountType();


public void setAccountType(String accountType);

Default Value

""

Remarks

This is included in the Authentication Request Message (AReq) sent to the directory server. Required if the 3-D Secure Requestor is asking the cardholder which account type they are using before making the purchase. Required in some markets (for example, for merchants in Brazil). Otherwise, this is optional.

Valid values are as follows:

01Not applicable
02Credit
03Debit

AcquirerBIN Property (Server Class)

Acquiring institution identification code.

Syntax


public String getAcquirerBIN();


public void setAcquirerBIN(String acquirerBIN);

Default Value

""

Remarks

This value correlates to the Acquirer BIN as defined by each payment system or directory server. This field is required to be set for payment authentication.

AcquirerCountryCode Property (Server Class)

Acquirer Country Code.

Syntax


public String getAcquirerCountryCode();


public void setAcquirerCountryCode(String acquirerCountryCode);

Default Value

""

Remarks

The code of the country where the acquiring institution is located (in accordance with ISO 3166).

This value should be formatted as a ISO 3166-1 numeric three-digit country code.

Valid for ProtocolVersion 2.3.1 only.

AcquirerMerchantId Property (Server Class)

Acquirer-assigned merchant identifier.

Syntax


public String getAcquirerMerchantId();


public void setAcquirerMerchantId(String acquirerMerchantId);

Default Value

""

Remarks

This field contains the merchant identifier assigned by the acquirer. The merchant id is required to be set for payment authentication.

ACSProtocolInfos Property (Server Class)

A collection of protocol versions and other associated information supported by the ACS for a card range.

Syntax


public ACSProtocolInfoList getACSProtocolInfos();


Remarks

A list of information returned when retrieving card ranges using the RequestCardRanges method.

Each card range will include information including the Protocol Version supported by the ACS for the card range, the 3DS Method URL, supported extensions, and other additional information from the ACS.

This field is only applicable when ProtocolVersion is 2.3.1.

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

Please refer to the ACSProtocolInfo type for a complete list of fields.

ACSURL Property (Server Class)

URL of the ACS to be used for the challenge.

Syntax


public String getACSURL();


public void setACSURL(String ACSURL);

Default Value

""

Remarks

This field contains the fully qualified URL of the ACS to be used for the challenge. This will be populated after the call to SendAuthRequest method if the Authentication Response Message (ARes) indicates that a challenge is required.

AuthenticationECI Property (Server Class)

Value to be passed in the authorization message.

Syntax


public String getAuthenticationECI();


Default Value

""

Remarks

This property is determined by the Access Control Server (ACS), and is filled after the call to SendAuthRequest (for a frictionless flow), or when the Results Request Message (RReq) is parsed using CheckResponse (for a challenge flow).

This property contains the two digit Electronic Commerce Indicator (ECI) value, which is to be submitted in a credit card authorization message. This value indicates to the processor that the customer data in the authorization message has been authenticated. The data contained within this property is only valid if the TransactionStatus is "Y" or "A".

This property is read-only.

AuthenticationIndicator Property (Server Class)

3DS Requestor Authentication Indicator.

Syntax


public String getAuthenticationIndicator();


public void setAuthenticationIndicator(String authenticationIndicator);

Default Value

"01"

Remarks

Indicates the type of Authentication request. This data element provides additional information to the ACS to determine the best approach for handing an authentication request. Included in the Authorization Request Message (ARes) sent by the SendAuthRequest method. Possible values are:

01Payment - default
02Recurring
03Installment
04Add Card
05Maintain Card
06Verify Cardholder
07Billing Agreement
08Split Shipment
09Delayed Shipment
10Split Payment
11-79Reserved for EMVCo future use (values invalid until defined by EMVCo)
80-99Reserved for DS use

AuthenticationValue Property (Server Class)

Used to provide proof of authentication.

Syntax


public String getAuthenticationValue();


Default Value

""

Remarks

This property is determined by the Access Control Server (ACS), and is filled after the call to SendAuthRequest (for a frictionless flow), or when the Results Request Message (RReq) is parsed using CheckResponse (for a challenge flow).

This property will be valid if the TransactionStatus is "Y" or "A". The value may be used to provide proof of authentication.

This property is read-only.

BillingAddress Property (Server Class)

The customer's billing address.

Syntax


public AddressInfo getBillingAddress();


public void setBillingAddress(AddressInfo billingAddress);

Remarks

This property specifies details about the customer's billing address. This should be set before calling SendAuthRequest.

Please refer to the AddressInfo type for a complete list of fields.

BrowserAcceptHeader Property (Server Class)

HTTP accept header sent from the cardholder's browser.

Syntax


public String getBrowserAcceptHeader();


public void setBrowserAcceptHeader(String browserAcceptHeader);

Default Value

""

Remarks

This field contains the exact content of the HTTP accept header as sent to the merchant from the cardholder's user agent. This field is required only if the cardholder's user agent supplied a value.

BrowserIPAddress Property (Server Class)

IP address of the cardholder's browser.

Syntax


public String getBrowserIPAddress();


public void setBrowserIPAddress(String browserIPAddress);

Default Value

""

Remarks

This field contains the IP address of the cardholder's browser as returned by the HTTP headers.

BrowserJavaEnabledVal Property (Server Class)

Ability of the cardholder's browser to execute Java.

Syntax


public int getBrowserJavaEnabledVal();


public void setBrowserJavaEnabledVal(int browserJavaEnabledVal);


Enumerated values:
  public final static int jeNotPresent = 0;
  public final static int jeTrue = 1;
  public final static int jeFalse = 2;

Default Value

0

Remarks

This field contains a value representing the ability of the cardholder's browser to execute Java.

Possible values are as follows:

jeNotPresent (0)Not Present
jeTrue (1)True
jeFalse (2)False

BrowserJavaScriptEnabledVal Property (Server Class)

Ability of the cardholder's browser to execute JavaScript.

Syntax


public int getBrowserJavaScriptEnabledVal();


public void setBrowserJavaScriptEnabledVal(int browserJavaScriptEnabledVal);


Enumerated values:
  public final static int bjeNotPresent = 0;
  public final static int bjeTrue = 1;
  public final static int bjeFalse = 2;

Default Value

0

Remarks

This field contains a value representing the ability of the cardholder's browser to execute JavaScript.

Possible values are as follows:

bjeNotPresent (0)Not Present
bjeTrue (1)True
bjeFalse (2)False

BrowserLanguage Property (Server Class)

The cardholder's browser language.

Syntax


public String getBrowserLanguage();


public void setBrowserLanguage(String browserLanguage);

Default Value

""

Remarks

This field contains the cardholder's browser language as defined in IETF BCP 47.

BrowserScreenColorDepth Property (Server Class)

The screen color depth of the cardholder's browser.

Syntax


public String getBrowserScreenColorDepth();


public void setBrowserScreenColorDepth(String browserScreenColorDepth);

Default Value

""

Remarks

This field contains a value representing the bit depth of the color palette, in bits per pixel, for displaying images.

For ProtocolVersion 2.1.0, this field is required. If BrowserJavaEnabledVal is False, a value of 1 can be used. When using ProtocolVersion of 2.2.0 or 2.3.1 and both BrowserJavaEnabledVal and BrowserJavaScriptEnabledVal are False, no value is required.

BrowserScreenHeight Property (Server Class)

The screen height of the cardholder's browser.

Syntax


public String getBrowserScreenHeight();


public void setBrowserScreenHeight(String browserScreenHeight);

Default Value

""

Remarks

This field contains the total height of the cardholder's screen in pixels.

For ProtocolVersion 2.1.0, this field is required. If BrowserJavaEnabledVal is False, a value of 0 can be used. When using ProtocolVersion of 2.2.0 or 2.3.1 and both BrowserJavaEnabledVal and BrowserJavaScriptEnabledVal are False, no value is required.

BrowserScreenWidth Property (Server Class)

The screen width of the cardholder's browser.

Syntax


public String getBrowserScreenWidth();


public void setBrowserScreenWidth(String browserScreenWidth);

Default Value

""

Remarks

This field contains the total width of the cardholder's screen in pixels.

For ProtocolVersion 2.1.0, this field is required. If BrowserJavaEnabledVal is False, a value of 0 can be used. When using ProtocolVersion of 2.2.0 or 2.3.1 and both BrowserJavaEnabledVal and BrowserJavaScriptEnabledVal are False, no value is required.

BrowserTimeZone Property (Server Class)

The timezone offset of the cardholder's browser.

Syntax


public String getBrowserTimeZone();


public void setBrowserTimeZone(String browserTimeZone);

Default Value

""

Remarks

This field contains the difference between UTC time and the cardholder's browser local time in minutes.

For ProtocolVersion 2.1.0, this field is required. If BrowserJavaEnabledVal is False, a value of 0 can be used. When using ProtocolVersion of 2.2.0 or 2.3.1 and both BrowserJavaEnabledVal and BrowserJavaScriptEnabledVal are False, no value is required.

BrowserUserAgent Property (Server Class)

The User-Agent provided by the cardholder's browser.

Syntax


public String getBrowserUserAgent();


public void setBrowserUserAgent(String browserUserAgent);

Default Value

""

Remarks

This field contains the exact content of the HTTP User-Agent header.

CardExpDate Property (Server Class)

Expiration date of the PAN or Token.

Syntax


public String getCardExpDate();


public void setCardExpDate(String cardExpDate);

Default Value

""

Remarks

This field contains the expiration date of the PAN or Token supplied in the CardNumber property. The format for this field is YYMM.

CardholderEmail Property (Server Class)

The cardholder email address.

Syntax


public String getCardholderEmail();


public void setCardholderEmail(String cardholderEmail);

Default Value

""

Remarks

This field contains the cardholder email address to be sent to the directory server when calling SendAuthRequest.

CardholderHomePhone Property (Server Class)

The cardholder home phone number.

Syntax


public String getCardholderHomePhone();


public void setCardholderHomePhone(String cardholderHomePhone);

Default Value

""

Remarks

This field contains the home phone number provided by the card holder.

Phone numbers must be specified in the following format: CountryCode-Subscriber (e.g. 1-1234567899)

The "-" is used to separate the "Country Code" and "Subscriber" sections. The values are then formatted according to the EMVCo specification (a JSON object) in the request like so:

  "homePhone": {
    "cc": "1",
    "subscriber": "1234567899"
  }

CardholderMobilePhone Property (Server Class)

The cardholder mobile phone number.

Syntax


public String getCardholderMobilePhone();


public void setCardholderMobilePhone(String cardholderMobilePhone);

Default Value

""

Remarks

This field contains the mobile phone number provided by the cardholder.

Phone numbers must be specified in the following format: CountryCode-Subscriber (e.g. 1-1234567899)

The "-" is used to separate the "Country Code" and "Subscriber" sections. The values are then formatted according to the EMVCo specification (a JSON object) in the request like so:

  "homePhone": {
    "cc": "1",
    "subscriber": "1234567899"
  }

CardholderName Property (Server Class)

Name of the cardholder.

Syntax


public String getCardholderName();


public void setCardholderName(String cardholderName);

Default Value

""

Remarks

This property contains the name of the cardholder. Limited to the alphanumeric characters listed in EMV Book 4, Annex B. Required to be set unless market or regional mandates restricts sending this information.

CardholderWorkPhone Property (Server Class)

The cardholder work phone number.

Syntax


public String getCardholderWorkPhone();


public void setCardholderWorkPhone(String cardholderWorkPhone);

Default Value

""

Remarks

This field contains the work phone number provided by the cardholder.

Phone numbers must be specified in the following format: CountryCode-Subscriber (e.g. 1-1234567899)

The "-" is used to separate the "Country Code" and "Subscriber" sections. The values are then formatted according to the EMVCo specification (a JSON object) in the request like so:

  "homePhone": {
    "cc": "1",
    "subscriber": "1234567899"
  }

CardNumber Property (Server Class)

Customer's account number that will be authenticated.

Syntax


public String getCardNumber();


public void setCardNumber(String cardNumber);

Default Value

""

Remarks

This property contains the customer's credit card number (PAN) or token that will be used in the authorization request for payment transactions. This property is 13-19 characters long.

CardRanges Property (Server Class)

A collection of card ranges to be added to or removed from the cache.

Syntax


public CardRangeInfoList getCardRanges();


Remarks

Card ranges may be returned from the directory server in the Preparation Response Message when the RequestCardRanges method is called. This collection will contain this information.

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

Please refer to the CardRangeInfo type for a complete list of fields.

ChallengeWindowSize Property (Server Class)

Challenge window size.

Syntax


public int getChallengeWindowSize();


public void setChallengeWindowSize(int challengeWindowSize);

Default Value

1

Remarks

This field indicates the dimensions of the challenge window that has been displayed to the cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience.

Preconfigured sizes are width x height in pixels of the window displayed in the cardholder browser. Possible values are:

1250 x 400
2390 x 400
3500 x 600
4600 x 400
5Full screen

This value is included in the Challenge Request Message (CReq) generated by the component when the GetChallengeRequest methods are called.

ClientAuthRequest Property (Server Class)

The data received by the class to be sent in the authentication request.

Syntax


public String getClientAuthRequest();


public void setClientAuthRequest(String clientAuthRequest);

Default Value

""

Remarks

The 3DS SDK should prepare data to be sent by the 3DS Server class. Set ClientAuthRequest to the data received from the 3DS SDK before calling SendAuthRequest.

See the 3DS SDK documentation for details on preparing this data.

ClientAuthResponse Property (Server Class)

The authentication response for an app-based flow.

Syntax


public String getClientAuthResponse();


Default Value

""

Remarks

This property is populated after calling SendAuthRequest, and is only applicable for the app-based flow. If a challenge is required, this data should be sent back to the 3DS SDK over the secure channel.

See SendAuthRequest for more details about handling the response.

This property is read-only.

DataPacketOut Property (Server Class)

Contains the data packet sent to the server.

Syntax


public String getDataPacketOut();


Default Value

""

Remarks

After calling either the RequestCardRanges, or SendAuthRequest methods, this property will contain the entire data packet that was sent. Also, after calling the GetChallengeRequest or GetResultsResponse method, this property will contain the constructed messages. The contents of this property should be logged for each transaction.

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

DeviceChannel Property (Server Class)

Device channel.

Syntax


public String getDeviceChannel();


public void setDeviceChannel(String deviceChannel);

Default Value

"02"

Remarks

This field indicates the type of channel interface being used to initiate the transaction.

Possible values include:

01App-based
02 - defaultBrowser
033DS Requestor Initiated (3RI)

DirectoryServerURL Property (Server Class)

The address of the Directory Server.

Syntax


public String getDirectoryServerURL();


public void setDirectoryServerURL(String directoryServerURL);

Default Value

""

Remarks

This is the URL to which the RequestCardRanges and SendAuthRequest methods post.

DSSupportedProtocols Property (Server Class)

Protocol Versions supported by the DS.

Syntax


public int getDSSupportedProtocols();


public void setDSSupportedProtocols(int DSSupportedProtocols);

Default Value

0

Remarks

The active protocol versions supported by the Directory Server. A bitwise OR of the following values:

2.1.00x02
2.2.00x04
2.3.10x08

DSURLs Property (Server Class)

A collection of Directory Server URLs to which the 3DS Server will send the AReq message.

Syntax


public DSURLList getDSURLs();


Remarks

A list of Directory Server URLs that may be returend when retrieving card ranges using the RequestCardRanges method. These URLs may optionally be provided in case there are preferred DS URLs for some countries.

This field is only applicable when ProtocolVersion is 2.3.1.

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

Please refer to the DSURL type for a complete list of fields.

ErrorPacket Property (Server Class)

The error packet.

Syntax


public String getErrorPacket();


Default Value

""

Remarks

If an error is encountered while parsing a received packet using the CheckResponse method, this field will be populated with an error packet to be sent back to the server.

If the message being parsed is an error, this field will be populated with the received error packet itself.

This property is read-only.

Extensions Property (Server Class)

Extensions to be included in the next outgoing packet.

Syntax


public ExtensionList getExtensions();


public void setExtensions(ExtensionList extensions);

Remarks

Data necessary to support requirements not otherwise defined in the 3-D Secure message are carried in Message Extensions. This collection contains extension data to be included in the next outgoing request. Extensions can be added manually or using the AddExtension method.

Note: The maximum number of extensions is 10.

Please refer to the Extension type for a complete list of fields.

MerchantCategoryCode Property (Server Class)

Merchant category code.

Syntax


public String getMerchantCategoryCode();


public void setMerchantCategoryCode(String merchantCategoryCode);

Default Value

""

Remarks

DS-specific code describing the Merchant's type of business, product, or service. Required to be set prior to calling SendAuthRequest.

MerchantCountryCode Property (Server Class)

Country code of the merchant.

Syntax


public String getMerchantCountryCode();


public void setMerchantCountryCode(String merchantCountryCode);

Default Value

""

Remarks

This field contains the country code of the merchant. This value correlates to the Merchant Country Code as defined by each Payment System or DS. Required to be set prior to calling SendAuthRequest.

MerchantName Property (Server Class)

Merchant name.

Syntax


public String getMerchantName();


public void setMerchantName(String merchantName);

Default Value

""

Remarks

The name of the merchant as assigned by the acquirer or payment system. Required to be set prior to calling SendAuthRequest.

MessageCategory Property (Server Class)

The category of the message.

Syntax


public String getMessageCategory();


public void setMessageCategory(String messageCategory);

Default Value

""

Remarks

This field identifies the category of the message (Payment Authentication or Non-Payment Authentication). This will be sent in the Authentication Request Message (AReq) sent by the component when SendAuthRequest is called, and in the Results Request Message (RReq) received from the directory server (populated after calling CheckResponse.

Possible values include:

01 (default)PA (Payment Authentication)
02NPA (Non-Payment Authentication)

MethodNotificationURL Property (Server Class)

The URL to which the method notification will be posted.

Syntax


public String getMethodNotificationURL();


public void setMethodNotificationURL(String methodNotificationURL);

Default Value

""

Remarks

This property specifies the URL to which the ACS will post when the method execution has completed. This must be set before calling GetMethodData. See GetMethodData for more details.

NotificationURL Property (Server Class)

The notification URL to which the challenge response is sent.

Syntax


public String getNotificationURL();


public void setNotificationURL(String notificationURL);

Default Value

""

Remarks

This property specifies the URL to which the final challenge response is POSTed in a browser-based flow. This must be set before calling SendAuthRequest.

After the challenge interaction is complete the ACS will post data to the URL specified in this property to notify the application that the challenge is complete. The data received at this URL can be processed by calling CheckResponse. See GetChallengeRequest and CheckResponse for more details.

Operation Property (Server Class)

Contains details received from an Operation Request Message sent from a Directory Server.

Syntax


public OperationInfo getOperation();


public void setOperation(OperationInfo operation);

Remarks

This type contains details received from an Operation Request Message sent from a Directory Server after parsing with CheckResponse. See CheckResponse and GetOperationResponse for details on how to process a received OReq message.

Please refer to the OperationInfo type for a complete list of fields.

Proxy Property (Server Class)

This property includes a set of properties related to proxy access.

Syntax


public Proxy getProxy();


public void setProxy(Proxy proxy);

Remarks

This property contains fields describing the proxy through which the class will attempt to connect.

Please refer to the Proxy type for a complete list of fields.

PurchaseAmount Property (Server Class)

Purchase amount to be authorized.

Syntax


public String getPurchaseAmount();


public void setPurchaseAmount(String purchaseAmount);

Default Value

""

Remarks

This field contains the purchase amount to be authorized. The transaction amount is to be presented with an implied decimal point. For example, US $10.00 must be represented as 1000, and $0.10 is likewise simply 10. The allowable number of significant digits as well as the positioning of any implied decimal point is dictated by the designated PurchaseExponent. This field may not contain a negative number.

PurchaseCurrency Property (Server Class)

Identifies the type of currency used by the merchant.

Syntax


public String getPurchaseCurrency();


public void setPurchaseCurrency(String purchaseCurrency);

Default Value

"840"

Remarks

This field contains the three digit number assigned by the signing member or processor to identify the currency in which PurchaseCurrency is expressed. This property should contain the ISO-4217 numeric code. For example, the ISO code for US Dollars is "840".

PurchaseDate Property (Server Class)

The date of the transaction.

Syntax


public String getPurchaseDate();


public void setPurchaseDate(String purchaseDate);

Default Value

""

Remarks

This field contains the date and time of the purchase, expressed in UTC. The format of this field must be: YYYYMMDDHHMMSS

PurchaseExponent Property (Server Class)

Minor units of currency.

Syntax


public String getPurchaseExponent();


public void setPurchaseExponent(String purchaseExponent);

Default Value

"2"

Remarks

This field indicates the minor units, or number of decimal places, of the currency specified in the PurchaseCurrency property. For instance, the Japanese Yen has a value of "0", the US Dollar a value of "2", and the Kuwati Dinar a value of "3".

Ranges Property (Server Class)

A collection of card ranges associated with the CardRangeData event.

Syntax


public RangeList getRanges();


Remarks

When card ranges are requested using ProtocolVersion 2.3.1, the CardRangeData event will fire for each card data object received in the Preparation Response Message (PRes). When the event fires, this property will contain the ranges for which the event information applies. Additional ACS information for the ranges will be contained in the ACSProtocolInfos property.

Each Range object includes a Start and End. Multiple card ranges can be associated with the data contained in the CardRangeData event.

This field is only applicable when ProtocolVersion is 2.3.1.

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

Please refer to the Range type for a complete list of fields.

RecurringExpDate Property (Server Class)

Recurring expiration date.

Syntax


public String getRecurringExpDate();


public void setRecurringExpDate(String recurringExpDate);

Default Value

""

Remarks

This field contains the date after which no further authorizations shall be performed. The format of this field must be: YYYYMMDD

Required when AuthenticationIndicator is 02 or 03, or when ThreeRIIndicator is 01 or 02.

RecurringFrequency Property (Server Class)

The number of days between recurring payments.

Syntax


public String getRecurringFrequency();


public void setRecurringFrequency(String recurringFrequency);

Default Value

""

Remarks

This field indicates the minimum number of days between authorizations.

Required when AuthenticationIndicator is 02 or 03, or when ThreeRIIndicator is 01 or 02.

RequestorId Property (Server Class)

Directory server assigned 3DS Requestor identifier.

Syntax


public String getRequestorId();


public void setRequestorId(String requestorId);

Default Value

""

Remarks

This field contains the 3DS Requestor identifier as assigned by the directory server. This is sent in the Authentication Request Message (AReq) sent by the component in the SendAuthRequest method.

RequestorName Property (Server Class)

Directory server assigned 3DS Requestor name.

Syntax


public String getRequestorName();


public void setRequestorName(String requestorName);

Default Value

""

Remarks

This field contains the 3DS Requestor name as assigned by the directory server. This is sent in the Authentication Request Message (AReq) sent by the component in the SendAuthRequest method.

RequestorURL Property (Server Class)

3DS Requestor website or customer care site.

Syntax


public String getRequestorURL();


public void setRequestorURL(String requestorURL);

Default Value

""

Remarks

This field contains the fully qualified URL of the 3DS Requestor website or customer care site. This is sent in the Authentication Request Message (AReq) sent by the component in the SendAuthRequest method.

ResultsStatus Property (Server Class)

The status of the Results Request.

Syntax


public int getResultsStatus();


public void setResultsStatus(int resultsStatus);

Default Value

0

Remarks

This field contains the status of the results request and is used when generating the Results Response Message (RRes) via the GetResultsResponse method. This will indicate if the message was successfully received for further processing or provide more detail to the ACS on why the challenge could not be completed.

Possible values include:

01Results Request Received for further Processing.
02Challenge Request not sent to ACS by 3DS Requestor (3DS Server or 3DS Requestor opted out of the challenge).
03ARes challenge data not delivered to the 3DS Requestor due to technical error.
043DS Server will process Decoupled Authentication in a subsequent authentication.

Before calling GetResultsResponse, the Server can use the value of the RequestorChallengeInd to determine whether or not a value of 02 is appropriate. It must use the necessary error handling logic when processing ARes messages to determine whether or not a value of 03 is appropriate.

If the TransactionStatus is D and a DecoupledRequestIndicator value of F or B was used, ResultsStatus should be set to 04 and a separate 3RI authentication should be initiated within 60 seconds.

ResultsURL Property (Server Class)

3DS Server URL.

Syntax


public String getResultsURL();


public void setResultsURL(String resultsURL);

Default Value

""

Remarks

Full qualified URL of the 3DS Server to which the directory server will send the Results Request Message (RReq) after the challenge has completed. This is sent to the directory server when calling the SendAuthRequest method.

SDKType Property (Server Class)

Type of the 3DS SDK used for the app-based flow.

Syntax


public String getSDKType();


public void setSDKType(String SDKType);

Default Value

"01"

Remarks

Indicates the type of 3DS SDK. This provides additional information to the DS and ACS to determine the best approach for handling the transaction.

Valid values are:

01Default-SDK
02Split-SDK
When Default-SDK is selected (01), SDKWrapped can be used to indicate if the Default-SDK is embedded as a wrapped component in the 3DS Requestor App.

When Split-SDK is selected (02), SplitSDKVariant will indicate the implementation charactistics of the Split-SDK client, and SplitSDKLimited can be used to indicate if the Split-SDK client has limited capabilities.

This property is valid for ProtocolVersion 2.3.1 only.

SerialNumber Property (Server Class)

Serial number indicating the state of the current card range cache.

Syntax


public String getSerialNumber();


public void setSerialNumber(String serialNumber);

Default Value

""

Remarks

If this element is present when submitting a Preparation Request Message (PReq) with the RequestCardRanges method, the directory server returns card ranges that have been updated since the time of the response which returned this serial number. If this element is not present, the directory server returns all card ranges. This field is updated with a new serial number after each call to RequestCardRanges.

ServerTransactionId Property (Server Class)

Server transaction identifier.

Syntax


public String getServerTransactionId();


public void setServerTransactionId(String serverTransactionId);

Default Value

""

Remarks

Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. This value is generated by the class when GetMethodData or SendAuthRequest is called.

ShippingAddress Property (Server Class)

The customer's shipping address.

Syntax


public AddressInfo getShippingAddress();


public void setShippingAddress(AddressInfo shippingAddress);

Remarks

This property specifies details about the customer's shipping address. This should be set before calling SendAuthRequest.

Please refer to the AddressInfo type for a complete list of fields.

SSLAcceptServerCert Property (Server Class)

Instructs the class to unconditionally accept the server certificate that matches the supplied certificate.

Syntax


public Certificate getSSLAcceptServerCert();


public void setSSLAcceptServerCert(Certificate SSLAcceptServerCert);

Remarks

If it finds any issues with the certificate presented by the server, the class will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert. If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

Please note that this functionality is provided only for cases where you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.

Please refer to the Certificate type for a complete list of fields.

SSLCert Property (Server Class)

The certificate to be used during SSL negotiation.

Syntax


public Certificate getSSLCert();


public void setSSLCert(Certificate SSLCert);

Remarks

The digital certificate that the class will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the Encoded field to the encoded certificate. To select a certificate, use the store and subject fields.

Please refer to the Certificate type for a complete list of fields.

SSLServerCert Property (Server Class)

The server certificate for the last established connection.

Syntax


public Certificate getSSLServerCert();


Remarks

SSLServerCert contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

Please refer to the Certificate type for a complete list of fields.

Timeout Property (Server Class)

A timeout for the class.

Syntax


public int getTimeout();


public void setTimeout(int timeout);

Default Value

30

Remarks

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If Timeout is set to a positive value, the class will wait for the operation to complete before returning control.

The class will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If Timeout expires, and the operation is not yet complete, the class throws an exception.

Please note that by default, all timeouts are inactivity timeouts, i.e. the timeout period is extended by Timeout seconds when any amount of data is successfully sent or received.

The default value for the Timeout property is 30 seconds.

TransactionStatus Property (Server Class)

The transaction status from the last parsed message (ARes, RReq, or CRes).

Syntax


public String getTransactionStatus();


Default Value

""

Remarks

Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are:

YAuthentication/account verification successful.
NNot authenticated/account not verified; transaction denied.
UAuthentication/account verification could not be performed; technical or other problem as indicated in ARes or RReq.
AAttempts processing performed; not authenticated/verified, but a proof of attempted authentication/verification is provided.
CChallenge required; additional authentication is required using the CReq/CRes.
RAuthentication/account verification rejected; issuer is rejecting authentication/verification and request that authorization not be attempted.
DChallenge required; decoupled authentication confirmed.
IInformational only; 3DS Requestor challenge preference acknowledged.

Note: The CRes message can contain only a value of Y or N. Values of D and I are only applicable for 3DS version 2.2.0.

This property is read-only.

AddExtension Method (Server Class)

Adds an extension to the collection.

Syntax

public void addExtension(String id, String name, boolean critical, String data);

Remarks

Data necessary to support requirements not otherwise defined in the 3-D Secure message are carried in Message Extensions. AddExtension adds a new extension to the Extensions collection.

Note: The maximum number of extensions is 10.

AddRequestField Method (Server Class)

Adds a field to the data in the request.

Syntax

public void addRequestField(String name, String value, int valueType);

Remarks

This method can be used to extend the requests constructed by the class. When this method is called, the component will add the specified field to the end of the request.

CheckResponse Method (Server Class)

Parses the specified message.

Syntax

public void checkResponse(String response);

Remarks

CheckResponse parses a variety of messages that are sent to the Server as part of the authentication process.

The following messages can be parsed using this method:

  • The threeDSMethodData form variables received at the MethodNotificationURL
  • The Results Request (RReq) message received at the ResultsURL
  • The cres form variables received at the NotificationURL
  • The Operation Request Message (OReq) sent from a DS.

When calling the method, pass the message to be parsed as the Response parameter. The properties which are populated after calling this method vary depending on the type of message being parsed. See below for additional information.

Method Data from MethodNotificationURL

After calling GetMethodData, a request is made to the MethodURL. After this, the ACS will make a POST to MethodNotificationURL to inform the requestor of completion. Retrieve the threeDSMethodData form variable value that was POSTed and pass it to this method. After calling this method, the following properties are populated:

The ServerTransactionId may be used to match the response with the request.

Results Request message from ResultsURL

When a challenge is completed for both app-based and browser-based flows, a POST is made to the ResultsURL with a Results Request message.

Prior to checking this RReq message, the ServerTransactionId can be extracted using the ExtractRReqServerTransactionId configuration setting. This value can then be used to look up details on the transaction that were saved prior to starting the challenge process, including the messageVersion which must be set via the ProtocolVersion configuration setting prior to passing the RReq message to the CheckResponse method.

Pass the body of the HTTP request received at ResultsURL to this method. This contains information about the results, and asks for a Results Response to be sent back containing the ResultsStatus.

After calling this method, the following properties are populated:

To respond to the POST, set ResultsStatus to the appropriate value and call GetResultsResponse to build a response message to be sent back to the directory server. Use the value from GetResultsResponse in the application as the body of the HTTP response. Set the Content-Type header to application/JSON; charset=utf-8

If TransactionStatus is D and TransactionStatusReason is 29 or 30, this indicates that decoupled authentication should now be performed. When building the Results Response, a ResultsStatus value of 04 should be used. Then, within 60 seconds, a new 3RI authentication must be started with the following field requirements:

Final Challenge Response from NotificationURL

In a browser-based flow, the challenge takes place directly between the cardholder and the ACS in a separate iframe or window. The ACS will POST the final challenge response to the NotificationURL after the challenge is complete. Retrieve the cres form variable value from the POST data and pass it to CheckResponse. After calling this method the following properties are populated:

In addition to the cres variable, a threeDSSessionData variable will be present if SessionData was set before calling GetChallengeRequest. The threeDSSessionData value POSTed to NotificationURL may be passed to EncodedSessionData. Query SessionData to get the decoded session data.

Operation Request Message (OReq)

OReq messages are used to communicate operational information from a DS to the 3DS Server. This message is not part of the 3-D Secure authentication flow.

When an OReq message is received, CheckResponse should be called to validate the message. There may be more than one OReq message sent in a sequence, and CheckResponse should be called for each. The current instance of the Server object can be cached for the duration of the OReq sequence until the final OReq is received. The Operation.SequenceNumber should also be set prior to calling CheckResponse. The component will verify the sequence number of the received OReq to ensure it's not out of sequence.

After calling this method, details are made available in Operation.

If any OReq data element fails validation, Operation.MessageStatus will be set to "02". If the OReq is valid, Operation.MessageStatus will be empty.

If the OReq is valid, determine if the final OReq has been received (Operation.SequenceNumber equals Operation.SequenceTotal). If these values match, the final OReq in the sequence has been received, and GetOperationResponse can be used to generate the ORes message.

For valid OReq messages that are not the final OReq in the sequence, the response should be HTTP Status 200 (OK) with an empty HTTP body.

Config Method (Server Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

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

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

GetChallengeRequest Method (Server Class)

Builds the Challenge Request (CReq) for browser-based flow.

Syntax

public String getChallengeRequest();

Remarks

The GetChallengeRequest method is used to build the Challenge Request (CReq) which will be sent in a form post to the ACSURL property via the cardholder browser.

An iframe should be created in the cardholder's browser, which will be used to send the challenge request and allow the cardholder and ACS to interact directly.

The size of the challenge window (iframe) may be any of the sizes listed in ChallengeWindowSize. Before calling this method set ChallengeWindowSize to the appropriate value to let the ACS know the size of the window on the cardholder's browser.

Calling this method will return a string which should be placed in a creq form variable.

The SessionData setting may also be set with any data that may be helpful to continue processing the transaction after the final challenge response is received at the NotificationURL. To prepare the session data for submission, query EncodedSessionData. The encoded string may then be placed in the threeDSSessionData form variable.

Note: The maximum length of the threeDSSessionData form variable, after being encoded, is 1024 bytes.

Example Form

out.write("<form name='downloadForm' action='" + ACSURL + "' method='POST'>"); out.write(" <INPUT type='hidden' name='creq' value='" + ChallengeRequest + "'>"); out.write(" <input type='hidden' name='threeDSSessionData' value='" + EncodedSessionData + "'>"); out.write("</form>"); out.write("<script>"); out.write("window.onload = submitForm;"); out.write("function submitForm() { downloadForm.submit(); }"); out.write("</script>");

Response Handling

Once the challenge has been completed by the cardholder, the directory server will post a Results Request (RReq) to the ResultsURL specified when calling SendAuthRequest. See CheckResponse and GetResultsResponse for more details.

The ACS will also post the Challenge Response to the NotificationURL specified when calling SendAuthRequest. This post contains data which may be parsed to verify the challenge results. See CheckResponse for more details.

GetMethodData Method (Server Class)

Prepares method data to be sent to the ACS before the authentication request is sent.

Syntax

public String getMethodData();

Remarks

The GetMethodData method prepares data to be transmitted to the ACS via the cardholder's browser.

When a transaction begins, the card range cache should be queried to find details about the card range to which the card number belongs. If a MethodURL is defined for the card range, this method should be used to prepare data to be sent via the cardholder's browser to the MethodURL.

If the MethodURL is not set for the specified card range, set MethodCompletionIndicator to U before calling SendAuthRequest.

The following properties are applicable when calling this method:

This method returns a string which contains encoded data to be sent to the ACS. This includes ServerTransactionId and MethodNotificationURL. After calling this method, the returned string can be transmitted to the ACS via the cardholder's browser.

As per the EMVCo specification, create a hidden iframe in the browser and send a form with the field name threeDSMethodData containing the return value from this method and post the form to the MethodURL.

The ACS will record information about the customer's environment and then POST back to the MethodNotificationURL. The page at this URL should expect a form variable with the name threeDSMethodData which will contain the original ServerTransactionId value in order to match the response with the request. The form variable value will be base64url encoded and may be passed directly to the CheckResponse method. The class will decode and parse the received value and populate ServerTransactionId with the value from the received data.

If the response from the ACS is not received within 10 seconds, set MethodCompletionIndicator to N before calling SendAuthRequest.

GetOperationResponse Method (Server Class)

Builds and returns the Operation Response Message (ORes) to be sent back to the Directory Server.

Syntax

public String getOperationResponse();

Remarks

This method builds the Operation Response Message (ORes) to be sent back to the Directory Server in an HTTP reply to the final Operation Request (OReq) message. It returns a JSON object containing the fields required for the ORes.

When an OReq message is received, CheckResponse should be called to validate the message. There may be more than one OReq message sent in a sequence, and CheckResponse should be called for each. While several OReq messages may be received in a sequence (totalling Operation.SequenceTotal), the ORes message is only expected to be generated using GetOperationResponse after the final OReq. For valid intermediate OReq messages the response should be HTTP Status 200 (OK) with an empty HTTP body.

After passing the final received OReq message to the CheckResponse method, all the properties required to be set before building the ORes will have been populated except for Operation.MessageStatus, which indicates whether or not the message was successfully received for further processing, or provides more detail to the DS on why the requested action could not be completed.

Possible values include:

01Successfully received messages.
02Message sequence is broken.
03Requested action is not supported or not executed by the 3DS Server or ACS when OReq message was received.
04Reserved for DS use

If any OReq data element fails validation from CheckResponse, Operation.MessageStatus will be set to "02". The ErrorPacket can be queried and should be returned to the DS.

For valid OReq messages, Operation.MessageStatus will be empty. Next, determine if the final OReq has been received (Operation.SequenceNumber equals Operation.SequenceTotal). If these values match, the final OReq in the sequence has been received, and GetOperationResponse can be used to generate the ORes message.

Once Operation.MessageStatus has been set, GetOperationResponse can be called and will return a string containing the reply to be sent in the response. In the HTTP server, use the string returned from this method as the body of the reply and set the Content-Type header to application/JSON; charset=utf-8

GetResultsResponse Method (Server Class)

Builds and returns the Results Response Message (RRes) to be sent back to the directory server.

Syntax

public String getResultsResponse();

Remarks

This method builds the Results Response Message (RRes) to be sent back to the directory server in the HTTP reply to the Results Request (RReq). It returns a JSON object containing the fields required for the RRes.

After passing the received RReq message to the CheckResponse method, all the properties required to be set before building the RRes will have been populated except for ResultsStatus, which indicates whether or not the message was successfully received for further processing, or provides more detail to the ACS on why the challenge could not be completed.

Possible values include:

01Results Request Received for further Processing.
02Challenge Request not sent to ACS by 3DS Requestor (3DS Server or 3DS Requestor opted out of the challenge).
03ARes challenge data not delivered to the 3DS Requestor due to technical error.

The Server can use the value of the RequestorChallengeInd to determine whether or not a value of 02 is appropriate. It must use the necessary error handling logic when processing ARes messages to determine whether or not a value of 03 is appropriate.

Once ResultsStatus has been set, GetResultsResponse can be called and will return a string containing the reply to be sent in the response. In the HTTP server, use the string returned from this method as the body of the reply and set the Content-Type header to application/JSON; charset=utf-8

Interrupt Method (Server Class)

Interrupts the current action.

Syntax

public void interrupt();

Remarks

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

RequestCardRanges Method (Server Class)

Requests card ranges from the directory server.

Syntax

public void requestCardRanges();

Remarks

RequestCardRanges requests card ranges and additional information from the directory server.

When a transaction is initiated, the first step that should be taken is to find information about the card range to which the card number belongs. This includes the protocol version(s) supported by the ACS and DS, and if one exists, any corresponding Method URL (used in the browser flow).

Results of this method should be cached in order to quickly look up information when processing transactions. It is recommended to call this method once every 24 hours at a minimum, and once per hour as a maximum to refresh the cache. The class will not cache the returned values; it is up to the user to cache these values in an appropriate location.

The first time this method is called, SerialNumber will be empty, indicating that all results should be returned. This is an offset the server will use to return only new updates to the card ranges (if any) since the last request. The SerialNumber will be populated after this method returns, and this value should be saved to be used in subsequent calls.

When a response is received, the card ranges will be made available via the component events and properties.

When ProtocolVersion is set to 2.3.1, the CardRangeData event will fire for each card range data object received, and the Ranges and ACSProtocolInfos properties will be populated to be accessed within the event handler. Optionally, the DS may return a list of URLs that the 3DS Server can use for communication with the DS. If present, these will be available via both the DSURL event and the DSURLs property.

When ProtocolVersion is set to 2.2.0 or 2.1.0, the CardRange event will fire for each card range that is returned, and the results will also be held in the CardRanges property.

The following properties are applicable when calling this method:

The following properties are populated after calling this method:

Note that when ProtocolVersion 2.3.1, the card range data is only available using the CardRangeData event.

When using ProtocolVersion 2.2.0 or 2.3.1, the returned ranges may include ACS Information Indicators. These are used to indicate additional functionality supported by the ACS for the card range(s). For 2.2.0, a ACSInformationIndicator field is exposed in both CardRanges collection and CardRange event. In version 2.3.1, this information is availalbe in the ACSProtocolInfos collection via the Indicator field. Possible values are:

  • 01 - Authentication Available at ACS
  • 02 - Attempts Supported by ACS or DS
  • 03 - Decoupled Authentication Supported
  • 04 - Whitelisting Supported
  • 05 - Device Binding Supported (2.3.1 only)
  • 06 - WebAuthn Authentication Supported (2.3.1 only)
  • 07 - SPC Authentication Supported (2.3.1 only)
  • 08 - Transaction Risk Analysis Exemption Supported (2.3.1 only)
  • 09 - Trust List Exemption Supported (2.3.1 only)
  • 10 - Low Value Exemption Supported (2.3.1 only)
  • 11 - Secure Corporate Payments Exemption Supported (2.3.1 only)
  • 80-99 - Reserved for DS Use

If an error is identified with the card range data received from the directory server when calling the RequestCardRanges method, the ResendRequestCardRanges configuration setting will be true, indicating that the request should be resent. When resending, if SerialNumber was specified for the initial request, it should be set to an empty string before calling RequestCardRanges again. Otherwise, the request can be sent without the serial number again, but the server may respond with an error due to multiple requests within an hour.

Note that retrieving card ranges can consume a lot of memory, especially when retrieving the initial set of ranges. The StoreCardRangeData and UseJsonDOM configuration settings can be set to help minimize the amount of memory used. A CardRangeTempPath setting can also be used to specify a temporary path to which the PRes packet will be temporarily written prior to parsing.

When using ProtocolVersion 2.3.1, if UseJsonDOM is false, the card ranges will need to be cached and processed after the RequestCardRanges method returns. The card ranges would then need to be processed in the order indicated by the CardRangeRecordsReadOrder configuration setting. A check will also need to be made for overlap of ranges. If issue(s) are found, the ReportCardRangeError configuration setting should be used to report the error to the directory server.

Reset Method (Server Class)

Clears all properties to their default values.

Syntax

public void reset();

Remarks

This method clears all properties to their default values.

ResetTransactionInfo Method (Server Class)

Resets transaction specific information.

Syntax

public void resetTransactionInfo();

Remarks

This method must be called between transactions when using the same class instance.

Each transaction that is attempted uses transaction specific values that should not be re-used in subsequent transactions. Call this method to make sure that any transaction specific information is cleared between transactions.

This method resets only the transaction specific information without resetting any other values which have been configured. This allows re-use of the same component instance.

In a Browser-Based flow the following are reset:

SendAuthRequest Method (Server Class)

Sends the authentication request to the directory server.

Syntax

public void sendAuthRequest();

Remarks

SendAuthRequest begins the 3-D Secure transaction flow by sending an authentication request to the DirectoryServerURL.

After calling this method, check TransactionStatus to determine if the cardholder is authenticated (frictionless flow) or further cardholder interaction is required to complete the authentication (challenge flow).

Prior to calling SendAuthRequest, data must to be collected to facilitate fraud checks by the ACS. The following properties are applicable for both app-based and browser-based flows:

App-Based Flow

In the app-based flow, device specific information is prepared by the 3DS SDK on the customer's device. This is transmitted to the 3DS Server class via a secure channel, the specifics of which are outside the scope of the classs. Set ClientAuthRequest to this data prepared by the 3DS SDK.

Browser-Based Flow

Before calling this method, first check the cached card-range data to determine if a MethodURL has been set by the ACS. Card range data may be retrieved by calling RequestCardRanges.

If no MethodURL is present for the given card, set MethodCompletionIndicator to U.

If a MethodURL has been specified by the ACS for the card number, the URL must be loaded in the cardholder's browser to allow the ACS to collect additional browser information for risk-based decision making. See the GetMethodData for further details.

Once the method URL invocation is complete, the authentication request may be sent. If the method URL invocation failed, set MethodCompletionIndicator to N before calling SendAuthRequest.

The following additional properties are applicable in browser-based flow:

Response Handling

After calling this method the TransactionStatus property holds the result. Possible values are:

Transaction Status Description
Y Authenticated successfully
C Cardholder challenge required
N Not authenticated
A Not authenticated, but a proof of authentication attempt was generated in AuthenticationValue
U Not authenticated due to technical or other issue
R Not authenticated because the issuer is rejecting authentication
D Challenge required; decoupled authentication confirmed
I Informational only; 3DS Requestor challenge preference acknowledged
S Challenge using SPC

If the transaction is authenticated (Y or A), no further steps are required. The flow is considered frictionless and the 3-D Secure processing is complete. If processing a payment, the AuthenticationValue and AuthenticationECI values can be included as proof of 3-D Secure authentication.

If the transaction requires a cardholder challenge (C, D or S), further steps are required.

If the transaction is not authenticated, TransactionStatusReason may contain details about the reason.

The following properties are applicable after calling this method:

Response Handling - App-Based Flow

After calling this method, ClientAuthResponse is populated with data to be transmitted back to the 3DS SDK. If a challenge is required, the ClientAuthResponse data is used by the 3DS SDK to start when initiating the challenge process.

The 3DS Server is responsible for indicating to the 3DS SDK the results of the SendAuthRequest process, and whether or not a challenge is required. Exactly how this is done is outside the scope of the classs themselves. The response to the 3DS SDK over the secure channel should include information on what to do next.

Note: The TransactionStatus is also populated in the 3DS Server class and may be inspected prior to transmitting ClientAuthResponse back to the 3DS SDK.

Response Handling - Browser-Based Flow

If TransactionStatus is C, then additional steps are required to complete the authentication. The GetChallengeRequest method should be called next to obtain data to be sent to the ACSURL in an authentication window in the customer's browser. Once authentication is complete, the ACS will post the results to the ResultsURL value that was specified when calling SendAuthRequest.

See the GetChallengeRequest method for more details.

If TransactionStatus is D, then decoupled authentication has been accepted by the ACS. DecoupledConfirmationIndicator will have a value of Y as well. Authentication will happen outside of the 3-D Secure flow and, when complete, the ACS will post the results to the ResultsURL that was specified when calling SendAuthRequest.

The DecoupledTimeRemaining value, which is calculated based on the DecoupledMaxTimeout value sent in the initial authentication request, can be checked to see the amount of time remaining before decoupled authentication must be completed. If the ACS does not post the results before this value runs out, it can be assumed that decoupled authentication was not successful.

SPC-Based Authentication

SPC (Secure Payment Confirmation) provides a method to perform a challenge using preestablished FIDO credentials when using a Browser. The SPC authentication can be initiated by the 3DS Requestor via an extra AReq/ARes message pair or by the ACS via a standard Browser Challenge Flow.

For an SPC authentication to execute correctly, the following prerequisites apply:

  1. The ACS has an enrolled FIDO authenticator on the device for this Cardholder.
  2. The 3DS Requestor and/or the ACS have detected that the Cardholder Browser supports the related SPC APIs (allow="payment *; publickey-credentialsget *"). For the ACS, this information can be obtained via the Browser User Agent data element or via data obtained via the 3DS Method.

SPC-based authentication can be enabled with the following additions:

Prior to sending the initial authentication request packet (AReq) using the SendAuthRequest method, the ThreeDSRequestorSpcSupport configuration setting should be set to Y to indicate that SPC is supported by the 3DS Requestor.

If SPC is accepted by the ACS, the resulting TransactionStatus should be S. The response will also contain a list of enrolled FIDO (WebAuthn) credentials associated with the cardholder, and SPC transaction data. This data is available in the following configuration settings:

If a new instance of the Server component will be used after authentication to send the second AReq, the AuthenticationInformation value should be saved to be used later.

This information is relayed to the 3DS Requestor implementation, and the 3DS Requestor invokes the SPC authentication (SPC API) against the WebAuthn Credential list. The cardholder authenticates using the FIDO authenticator on their device, and the 3DS Requestor retrieves the Assertion Data from the SPC API call.

The 3DS Server is then configured to includes this FIDO Assertion Data is then included in a new authentication request by setting the ReqAuthData and a ReqAuthMethod of 09. If the AuthenticationInformation value was saved earlier, it can be set via the same configuration setting. If the 3DS Requestor encounters an error during SPC API invokation, this can be indicated using the SPCIncompletionIndicator.

The SendAuthRequest method should then be called again to transmit this data to the ACS (by way of the DS) in a second AReq.

When SendAuthRequest returns, the 3DS Server proceed the same as the regular browser-based flow when the ARes is returned.

When SPC authentication is to be performed, the authenticaton must be completed within 9 minutes. The component will automatically start an internal timer that can be checked using the CheckSPCTimeout configuration setting. This will return the number of seconds left for SPC authentication to complete. If the time has expired before receiving the Assertion Data from the 3DS Requestor, checking this configuration setting will cause the component to automatically send the second AReq message with an SPCIncompletionIndicator value of 03, indicating that SPC authentication timed out.

Note that SPC-based authentication is only available when a ProtocolVersion of 2.3.1 is used.

CardRange Event (Server Class)

Fired when the response to a Preparation Request Message (PReq) is received.

Syntax

public class DefaultServerEventListener implements ServerEventListener {
  ...
  public void cardRange(ServerCardRangeEvent e) {}
  ...
}

public class ServerCardRangeEvent {
  public String rangeStart;
  public String rangeEnd;
  public String rangeAction;
  public String ACSStartProtocolVersion;
  public String ACSEndProtocolVersion;
  public String DSStartProtocolVersion;
  public String DSEndProtocolVersion;
  public String threeDSMethodURL;
  public String ACSInformationIndicator;
  public boolean valid;
}

Remarks

The CardRange event fires for each range of card numbers to be added or removed from the cache. The RangeAction parameter indicates whether the range specified by the RangeStart and RangeEnd arguments is to be added or deleted from the current cache.

RangeStart13-19 digit account number from the Directory indicating the first number in a range of account numbers to be added or deleted from the current cache.
RangeEnd13-19 digit account number from the Directory indicating the last number in a range of account numbers to be added or deleted from the current cache. This End number must be the same length as the Start number.
RangeActionIndicates the action to be taken with the card range specified by the RangeStart and RangeEnd parameters. Possible values are:
  • A - Add the card range to the cache (default value)
  • D - Delete the card range from the cache
  • M - Modify the card range data
If the SerialNumber was not included in the Card Range Request, the Action will be A (add) for all ranges returned. If no action is returned for the card range (empty value), it can be assumed that the action for the range is A.
ACSStartProtocolVersionThe earliest (i.e. oldest) active protocol version that is supported by the ACS.
ACSEndProtocolVersionThe most recent active protocol version that is supported by the ACS URL.
DSStartProtocolVersionThe earliest (i.e. oldest) active protocol version that is supported by the DS.
DSEndProtocolVersionThe most recent active protocol version that is supported by the DS.
ThreeDSMethodURLThe fully qualified ACS URL that will be used by the 3DS method.
ACSInformationIndicatorAdditional information on the card range as supplied by the ACS. This field is a comma separate list of values returned from the server; possible values are:
  • 01 - Authentication Available at ACS
  • 02 - Attempts Supported by ACS or DS
  • 03 - Decoupled Authentication Supported
  • 04 - Whitelisting Supported
  • 05 - Device Binding Supported (2.3.1 only)
  • 06 - WebAuthn Authentication Supported (2.3.1 only)
  • 07 - SPC Authentication Supported (2.3.1 only)
  • 08 - Transaction Risk Analysis Exemption Supported (2.3.1 only)
  • 09 - Trust List Exemption Supported (2.3.1 only)
  • 10 - Low Value Exemption Supported (2.3.1 only)
  • 11 - Secure Corporate Payments Exemption Supported (2.3.1 only)
  • 80-99 - Reserved for DS Use
ValidWhether or not the card range data is valid. If an issue is found with the card range data, this can be set to false to cause a 203 error to be returned to the directory server.

Note that the card ranges must be processed in the order returned.

These card ranges are also returned outside this event in the Start, End, Action, ACSStartProtocolVersion, ACSEndProtocolVersion, and MethodURL fields.

CardRangeData Event (Server Class)

Fired when the response to a Preparation Request Message (PReq) is received. This event is used for card range data returned when version 2.3.1 of the protocol is used.

Syntax

public class DefaultServerEventListener implements ServerEventListener {
  ...
  public void cardRangeData(ServerCardRangeDataEvent e) {}
  ...
}

public class ServerCardRangeDataEvent {
  public String rangeAction;
  public String issuerCountryCode;
  public int DSProtocolVersions;
  public int status;
}

Remarks

When card ranges are requested using using ProtocolVersion 2.3.1, the CardRangeData event will fire for each card range data object received in the Preparation Response Message (PRes) returned from the directory server.

This data indicates the most recent protocol versions supported by the ACS and, optionally, the DS that hosts that range. If configured, the ACS URL for the 3DS Method will be included as well, along with the 3DS features supported by the ACS, such as Trust List or Decoupled Authentication.

The RangeAction parameter indicates whether the ranges defined in the Ranges property are to be added, deleted, or modified in the current cache.

RangeActionIndicates the action to be taken with the card range specified by the RangeStart and RangeEnd parameters. Possible values are:
  • A - Add the card range to the cache (default value)
  • D - Delete the card range from the cache
  • M - Modify the card range data
If the SerialNumber was not included in the Card Range Request, the Action will be A (add) for all ranges returned. If no action is returned for the card range (empty value), it can be assumed that the action for the range is A.
IssuerCountryCodeThe Issuer country for the ranges. An ISO 3166-1 numeric three-digit country code.
DSProtocolVersionsThe active protocol versions supported by the Directory Server. A bitwise OR of the following values:
2.1.00x02
2.2.00x04
2.3.10x08
Note that the protocol versions may also be returned outside of the individual card ranges. These versions will be present in the DSSupportedProtocols property.
StatusIf an issue is found with the card range, it can be reported by setting the Status parameter. Possible values are:
  • 0: Valid (default)
  • 1: Overlap in the card ranges provided by the DS in the PRes message.
  • 2: Action is not possible for the card range.
When set to a non-zero value, the class will automatically report the appropriate error to the DS.
Within the event, a few properties will also be populated, both with details for the current ranges in question. The Ranges collection will hold the card ranges for which the rest of the data applies. The ACSProtocolInfos collection will hold protocol versions and other associated information supported by the ACS for the card ranges.

DataPacketIn Event (Server Class)

Fired when receiving a data packet from the server.

Syntax

public class DefaultServerEventListener implements ServerEventListener {
  ...
  public void dataPacketIn(ServerDataPacketInEvent e) {}
  ...
}

public class ServerDataPacketInEvent {
  public byte[] dataPacket;
}

Remarks

This event fires when a packet is received. The entire data packet (including all framing and error detection characters) is contained in the DataPacket parameter. This parameter may be inspected for advanced troubleshooting, or to extract additional response properties beyond the scope of this component.

DataPacketOut Event (Server Class)

Fired when sending a data packet to the server.

Syntax

public class DefaultServerEventListener implements ServerEventListener {
  ...
  public void dataPacketOut(ServerDataPacketOutEvent e) {}
  ...
}

public class ServerDataPacketOutEvent {
  public byte[] dataPacket;
}

Remarks

This event fires right before each data packet is sent. The entire data packet (including all framing and error detection characters) is contained in the DataPacket parameter. This parameter may be inspected for advanced troubleshooting, or may be modified to support additional features beyond the scope of this component.

DSURL Event (Server Class)

Fired for each DS URL present in the Preparation Response Message (PRes).

Syntax

public class DefaultServerEventListener implements ServerEventListener {
  ...
  public void DSURL(ServerDSURLEvent e) {}
  ...
}

public class ServerDSURLEvent {
  public String threeDSServerToDsUrl;
  public String DSCountryCode;
}

Remarks

The DSURL event fires for each DS URL returned from the directory server when requesting card ranges via the RequestCardRanges method.

Each DSURL object contains a ThreeDSServerToDsUrl and, optionally, a CountryCode. For a given card range, if the Issuer Country Code matches the DS CountryCode, the 3DS Server uses this ThreeDSServerToDsUrl to communicate with the DS. If there is no match, the 3DS Server uses the default 3DS Server to DS URL.

Error Event (Server Class)

Information about errors during data delivery.

Syntax

public class DefaultServerEventListener implements ServerEventListener {
  ...
  public void error(ServerErrorEvent e) {}
  ...
}

public class ServerErrorEvent {
  public int errorCode;
  public String description;
}

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.

Log Event (Server Class)

Fires once for each log message.

Syntax

public class DefaultServerEventListener implements ServerEventListener {
  ...
  public void log(ServerLogEvent e) {}
  ...
}

public class ServerLogEvent {
  public int logLevel;
  public String message;
  public String logType;
}

Remarks

Logging in the component is handled through the Log event. This will fire anytime a message is built or a response is parsed, including error messages.

When the Log event is fired, the message in question is made available via the Message event parameter. Properties such as EphemeralKey and DeviceParams are also available when they are gathered by the Client. The other event arguments are LogType and LogLevel:

The LogType parameter indicates the type of the log entry. Possible values are:

  • "Info"
  • "RequestHeaders"
  • "ResponseHeaders"
  • "RequestBody"
  • "ResponseBody"
  • "ProxyRequest"
  • "ProxyResponse"
  • "FirewallRequest"
  • "FirewallResponse"
  • "AReq"
  • "ARes"
  • "CReq"
  • "CRes"
  • "RReq"
  • "RRes"
  • "PReq"
  • "PRes"
  • "Erro"
  • "EphemeralKey"
  • "DeviceParams"
The LogLevel configuration setting can be used to specify the detail of the logs raised through the Log event. The LogLevel parameter in the event indicates the log level to which the current message belongs.

It is recommended to output all messages raised in this event to a file for record keeping purposes, or for later debugging issues that may have come up.

The Server and Client components also have DataPacketIn and DataPacketOut events that fire anytime a data packet is received or sent, respectively. The entire data packet is then accessible in the DataPacket event parameter. For encrypted packets, this would contain the full encrypted data. This parameter may be inspected for advanced troubleshooting.

MessageExtension Event (Server Class)

Fired when a Message Extension is present in a message being parsed.

Syntax

public class DefaultServerEventListener implements ServerEventListener {
  ...
  public void messageExtension(ServerMessageExtensionEvent e) {}
  ...
}

public class ServerMessageExtensionEvent {
  public String name;
  public String id;
  public String data;
  public boolean critical;
  public boolean recognized;
}

Remarks

Enables the parsing of Message Extension data by firing when extensions have been included in a ARes, CRes, RReq or PRes message that is being parsed. Message Extensions carry additional data not defined in the 3DS Protocol. This event fires once for each such extension. Event arguments correspond to the four elements comprising the extension, as well as an indication of whether or not the extension is recognized:

Name 'name' element - extension name
Id 'id' element - assigned extension group identifier
Data 'data' element - message extension data
Critical 'criticalityIndicator' element - criticality indicator
Recognized set by component to indicate whether or not the extension is recognized

If a 3-D Secure application receives a message containing a critical extension that it does not recognize, it must treat it as invalid and return Error Code = 202. This event will fire before the exception is thrown.

SSLServerAuthentication Event (Server Class)

Fired after the server presents its certificate to the client.

Syntax

public class DefaultServerEventListener implements ServerEventListener {
  ...
  public void SSLServerAuthentication(ServerSSLServerAuthenticationEvent e) {}
  ...
}

public class ServerSSLServerAuthenticationEvent {
  public byte[] certEncoded;
  public String certSubject;
  public String certIssuer;
  public String status;
  public boolean accept;
}

Remarks

This event is where the client can decide whether to continue with the connection process or not. 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 to continue or not.

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 (Server Class)

Shows the progress of the secure connection.

Syntax

public class DefaultServerEventListener implements ServerEventListener {
  ...
  public void SSLStatus(ServerSSLStatusEvent e) {}
  ...
}

public class ServerSSLStatusEvent {
  public String message;
}

Remarks

The event is fired for informational and logging purposes only. Used to track the progress of the connection.

ACSProtocolInfo Type

Contains information from the ACS regarded supported protocol versions and other associated information.

Remarks

Each ACSProtocolInfo object contains any supported ProtocolVersion. Other fields are optional.

Fields

Indicator
String (read-only)

Default Value: ""

Additional information on the card range as supplied by the ACS. This field is a comma separated list of values returned from the server; possible values are:

01Authentication Available at ACS
02Attempts Supported by ACS or DS
03Decoupled Authentication Supported
04Trust List Supported
05Device Binding Supported
06WebAuthn Authentication Supported
07SPC Authentication Supported
08Transaction Risk Analysis Exemption Supported
09Trust List Exemption Supported
10Low Value Exemption Supported
11Secure Corporate Payments Exemption Supported
12-79Reserved for EMVCo future use (values invalid until defined by EMVCo)
80-99Reserved for DS use

ProtocolVersion
String (read-only)

Default Value: ""

The Protocol Version supported by the ACS for the card range.

SupportedMsgExt
String (read-only)

Default Value: ""

A list of message extensions supported by the ACS that contains the Assigned Extension Group Identifier and the Extension Version Number.

This field is a comma separate list of values returned from the server in the following format:

id,version;id2,version2;...

ThreeDSMethodURL
String (read-only)

Default Value: ""

The ACS URL that will be used by the 3DS Method for a particular protocol version.

Constructors

public ACSProtocolInfo();



AddressInfo Type

This type contains address details.

Remarks

This type contains details of the cardholder's address including:

Fields

City
String

Default Value: ""

The city of the address. The maximum length is 50 characters.

Country
String

Default Value: ""

The country of the address. The format is a 3 digit country code as defined in ISO 3166-1.

Line1
String

Default Value: ""

The first line of the street address or equivalent local portion of the address. The maximum length is 50 characters.

Line2
String

Default Value: ""

The second line of the street address or equivalent local portion of the address. The maximum length is 50 characters.

Line3
String

Default Value: ""

The third line of the street address or equivalent local portion of the address. The maximum length is 50 characters.

PostalCode
String

Default Value: ""

The ZIP or other postal code of the address. The maximum length is 16 characters.

State
String

Default Value: ""

The state or province of the address. The maximum length is 3 characters and should be the country subdivision code defined in ISO 3166-2.

Constructors

public AddressInfo();



CardRangeInfo Type

Contains a range of card numbers to be added to or removed from the cache.

Remarks

Each CardRangeInfo object contains a range of card numbers from Start to End, and an Action indicating whether the range should be added to or deleted from the cache that the user is maintaining. Start and End ranges returned from the server will always be the same length, for ease of computation. Card ranges must be added to or removed from the cache in the order they were received, otherwise the cache will become out of sync.

Fields

ACSEndProtocolVersion
String (read-only)

Default Value: ""

The most recent active protocol version that is supported by the ACS.

ACSInformationIndicator
String (read-only)

Default Value: "0"

Additional information on the card range as supplied by the ACS. This field is a comma separate list of values returned from the server; possible values are:

  • 01 - Authentication Available at ACS
  • 02 - Attempts Supported by ACS or DS
  • 03 - Decoupled Authentication Supported
  • 04 - Whitelisting Supported
  • 05 - Device Binding Supported (2.3.1 only)
  • 06 - WebAuthn Authentication Supported (2.3.1 only)
  • 07 - SPC Authentication Supported (2.3.1 only)
  • 08 - Transaction Risk Analysis Exemption Supported (2.3.1 only)
  • 09 - Trust List Exemption Supported (2.3.1 only)
  • 10 - Low Value Exemption Supported (2.3.1 only)
  • 11 - Secure Corporate Payments Exemption Supported (2.3.1 only)
  • 80-99 - Reserved for DS Use

ACSStartProtocolVersion
String (read-only)

Default Value: ""

The earliest (i.e. oldest) active protocol version that is supported by the ACS.

Action
String (read-only)

Default Value: ""

The action to be taken with the card range specified by the Start and End fields. Possible values are:

  • A - Add the card range to the cache (default value)
  • D - Delete the card range from the cache
  • M - Modify the card range data
If the SerialNumber was not included in the Card Range Request, the Action will be A (add) for all ranges returned. If no action is returned for the card range (empty value), it can be assumed that the action for the range is A.

DSEndProtocolVersion
String (read-only)

Default Value: ""

The most recent active protocol version that is supported by the DS.

DSStartProtocolVersion
String (read-only)

Default Value: ""

The earliest (i.e. oldest) active protocol version that is supported by the DS.

End
String (read-only)

Default Value: ""

Last number in a range of credit card numbers returned by the Directory Server.

This field contains the final card number in the current range. The first number in the current range is contained in Start, and the action (add or delete) to take on this range is contained in Action. Note that the card ranges must be processed in the order returned.

Card ranges returned by a Card Range Request are for credit cards that support 3-D Secure. If the customer's credit card number is not within one of these ranges, you cannot use 3-D Secure for that card. Examples of card numbers that may not be eligible for 3-D Secure are check cards, corporate cards, and gift cards.

MethodURL
String (read-only)

Default Value: ""

The ACS URL that will be used by the 3DS method.

Start
String (read-only)

Default Value: ""

First number in a range of credit card numbers returned by the Directory Server.

This field contains the first card number in the current range. The final number in the current range is contained in End, and the action (add or delete) to take on this range is contained in Action. Note that the card ranges must be processed in the order returned.

Card ranges returned by a Card Range Request are for credit cards that support 3-D Secure. If the customer's credit card number is not within one of these ranges, you cannot use 3-D Secure for that card. Examples of card numbers that may not be eligible for 3-D Secure are check cards, corporate cards, and gift cards.

Constructors

public CardRangeInfo();



Certificate Type

This is the digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

Fields

EffectiveDate
String (read-only)

Default Value: ""

This is the date on which this certificate becomes valid. Before this date, it is not valid. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

Encoded
String

Default Value: ""

This is the certificate (PEM/base64 encoded). This field is used to assign a specific certificate. The Store and Subject fields also may be used to specify a certificate.

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

EncodedB
byte[]

Default Value: ""

This is the certificate (PEM/base64 encoded). This field is used to assign a specific certificate. The Store and Subject fields also may be used to specify a certificate.

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

ExpirationDate
String (read-only)

Default Value: ""

This is the date the certificate expires. After this date, the certificate will no longer be valid. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

ExtendedKeyUsage
String

Default Value: ""

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

Fingerprint
String (read-only)

Default Value: ""

This is the hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

FingerprintSHA1
String (read-only)

Default Value: ""

This is the hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

FingerprintSHA256
String (read-only)

Default Value: ""

This is the hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

Issuer
String (read-only)

Default Value: ""

This is the issuer of the certificate. This field contains a string representation of the name of the issuing authority for the certificate.

KeyPassword
String

Default Value: ""

This is the password for the certificate's private key (if any).

Some certificate stores may individually protect certificates' private keys, separate from the standard protection offered by the StorePassword. KeyPassword. This field can be used to read such password-protected private keys.

Note: this property defaults to the value of StorePassword. To clear it, you must set the property to the empty string (""). It can be set at any time, but when the private key's password is different from the store's password, then it must be set before calling PrivateKey.

PrivateKey
String (read-only)

Default Value: ""

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

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

PrivateKeyAvailable
boolean (read-only)

Default Value: False

This field shows whether a PrivateKey is available for the selected certificate. If PrivateKeyAvailable is True, the certificate may be used for authentication purposes (e.g., server authentication).

PrivateKeyContainer
String (read-only)

Default Value: ""

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

PublicKey
String (read-only)

Default Value: ""

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

PublicKeyAlgorithm
String

Default Value: ""

This field contains the textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

PublicKeyLength
int (read-only)

Default Value: 0

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

SerialNumber
String (read-only)

Default Value: ""

This is the serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

SignatureAlgorithm
String (read-only)

Default Value: ""

The field contains the text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

Store
String

Default Value: "MY"

This is the name of the certificate store for the client certificate.

The StoreType field denotes the type of the certificate store specified by Store. If the store is password protected, specify the password in StorePassword.

Store is used in conjunction with the Subject field to specify client certificates. If Store has a value, and Subject or Encoded is set, a search for a certificate is initiated. Please see the Subject field for details.

Designations of certificate stores are platform-dependent.

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

MYA certificate store holding personal certificates with their associated private keys.
CACertifying authority certificates.
ROOTRoot certificates.

In Java, the certificate store normally is a file containing certificates and optional private keys.

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).

StoreB
byte[]

Default Value: "MY"

This is the name of the certificate store for the client certificate.

The StoreType field denotes the type of the certificate store specified by Store. If the store is password protected, specify the password in StorePassword.

Store is used in conjunction with the Subject field to specify client certificates. If Store has a value, and Subject or Encoded is set, a search for a certificate is initiated. Please see the Subject field for details.

Designations of certificate stores are platform-dependent.

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

MYA certificate store holding personal certificates with their associated private keys.
CACertifying authority certificates.
ROOTRoot certificates.

In Java, the certificate store normally is a file containing certificates and optional private keys.

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).

StorePassword
String

Default Value: ""

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

StoreType
int

Default Value: 0

This is the type of certificate store for this certificate.

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

0 (cstUser - default)For Windows, this specifies that the certificate store is a certificate store owned by the current user. Note: this store type is not available in Java.
1 (cstMachine)For Windows, this specifies that the certificate store is a machine store. Note: this store type is not available in Java.
2 (cstPFXFile)The certificate store is the name of a PFX (PKCS12) file containing certificates.
3 (cstPFXBlob)The certificate store is a string (binary or base64-encoded) representing a certificate store in PFX (PKCS12) format.
4 (cstJKSFile)The certificate store is the name of a Java Key Store (JKS) file containing certificates. Note: this store type is only available in Java.
5 (cstJKSBlob)The certificate store is a string (binary or base64-encoded) representing a certificate store in Java Key Store (JKS) format. Note: this store type is only available in Java.
6 (cstPEMKeyFile)The certificate store is the name of a PEM-encoded file that contains a private key and an optional certificate.
7 (cstPEMKeyBlob)The certificate store is a string (binary or base64-encoded) that contains a private key and an optional certificate.
8 (cstPublicKeyFile)The certificate store is the name of a file that contains a PEM- or DER-encoded public key certificate.
9 (cstPublicKeyBlob)The certificate store is a string (binary or base64-encoded) that contains a PEM- or DER-encoded public key certificate.
10 (cstSSHPublicKeyBlob)The certificate store is a string (binary or base64-encoded) that contains an SSH-style public key.
11 (cstP7BFile)The certificate store is the name of a PKCS7 file containing certificates.
12 (cstP7BBlob)The certificate store is a string (binary) representing a certificate store in PKCS7 format.
13 (cstSSHPublicKeyFile)The certificate store is the name of a file that contains an SSH-style public key.
14 (cstPPKFile)The certificate store is the name of a file that contains a PPK (PuTTY Private Key).
15 (cstPPKBlob)The certificate store is a string (binary) that contains a PPK (PuTTY Private Key).
16 (cstXMLFile)The certificate store is the name of a file that contains a certificate in XML format.
17 (cstXMLBlob)The certificate store is a string that contains a certificate in XML format.
18 (cstJWKFile)The certificate store is the name of a file that contains a JWK (JSON Web Key).
19 (cstJWKBlob)The certificate store is a string that contains a JWK (JSON Web Key).
21 (cstBCFKSFile)The certificate store is the name of a file that contains a BCFKS (Bouncy Castle FIPS Key Store). Note: this store type is only available in Java and .NET.
22 (cstBCFKSBlob)The certificate store is a string (binary or base64-encoded) representing a certificate store in BCFKS (Bouncy Castle FIPS Key Store) format. Note: this store type is only available in Java and .NET.
23 (cstPKCS11)The certificate is present on a physical security key accessible via a PKCS11 interface.

To use a security key the necessary data must first be collected using the CertMgr class. The ListStoreCertificates method may be called after setting CertStoreType to cstPKCS11, CertStorePassword to the PIN, and CertStore to the full path of the PKCS11 dll. The certificate information returned in the CertList event's CertEncoded parameter may be saved for later use.

When using a certificate, pass the previously saved security key information as the Store and set StorePassword to the PIN.

Code Example: SSH Authentication with Security Key certmgr.CertStoreType = CertStoreTypes.cstPKCS11; certmgr.OnCertList += (s, e) => { secKeyBlob = e.CertEncoded; }; certmgr.CertStore = @"C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll"; certmgr.CertStorePassword = "123456"; //PIN certmgr.ListStoreCertificates(); sftp.SSHCert = new Certificate(CertStoreTypes.cstPKCS11, secKeyBlob, "123456", "*"); sftp.SSHUser = "test"; sftp.SSHLogon("myhost", 22);

99 (cstAuto)The store type is automatically detected from the input data. This setting may be used with both public and private keys and can detect any of the supported formats automatically.

Subject
String

Default Value: ""

This is the subject of the certificate used for client authentication.

This field will be populated with the full subject of the loaded certificate. When loading a certificate the subject is used to locate the certificate in the store.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma separated list of distinguished name fields and values. For instance "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are displayed below.

FieldMeaning
CNCommon Name. This is commonly a host name like www.server.com.
OOrganization
OUOrganizational Unit
LLocality
SState
CCountry
EEmail Address

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

SubjectAltNames
String (read-only)

Default Value: ""

This field contains comma-separated lists of alternative subject names for the certificate.

ThumbprintMD5
String (read-only)

Default Value: ""

This field contains the MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

ThumbprintSHA1
String (read-only)

Default Value: ""

This field contains the SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

ThumbprintSHA256
String (read-only)

Default Value: ""

This field contains the SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

Usage
String

Default Value: ""

This field contains the text description of UsageFlags.

This value will be of one or more of the following strings and will be separated by commas:

  • Digital Signatures
  • Key Authentication
  • Key Encryption
  • Data Encryption
  • Key Agreement
  • Certificate Signing
  • Key Signing

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

UsageFlags
int

Default Value: 0

This field contains the flags that show intended use for the certificate. The value of UsageFlags is a combination of the following flags:

0x80Digital Signatures
0x40Key Authentication (Non-Repudiation)
0x20Key Encryption
0x10Data Encryption
0x08Key Agreement
0x04Certificate Signing
0x02Key Signing

Please see the Usage field for a text representation of UsageFlags.

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

Version
String (read-only)

Default Value: ""

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

Constructors

public Certificate();

Creates a Certificate instance whose properties can be set. This is useful for use with CERTMGR when generating new certificates.

public Certificate( certificateFile);

Opens CertificateFile and reads out the contents as an X509 public key.

public Certificate( certificateData);

Parses CertificateData as an X509 public key.

public Certificate( certStoreType,  store,  storePassword,  subject);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate( certStoreType,  store,  storePassword,  subject,  configurationString);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. ConfigurationString is a newline separated list of name-value pairs that may be used to modify the default behavior. Possible values include "PersistPFXKey", which shows whether or not the PFX key is persisted after performing operations with the private key. This correlates to the PKCS12_NO_PERSIST_KEY CyrptoAPI option. The default value is True (the key is persisted). "Thumbprint" - a MD5, SHA1, or SHA256 thumbprint of the certificate to load. When specified, this value is used to select the certificate in the store. This is applicable to cstUser, cstMachine, cstPublicKeyFile, and cstPFXFile store types. "UseInternalSecurityAPI" shows whether the platform (default) or the internal security API is used when performing certificate-related operations. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate( certStoreType,  store,  storePassword,  encoded);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

public Certificate( certStoreType,  storeBlob,  storePassword,  subject);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate( certStoreType,  storeBlob,  storePassword,  subject,  configurationString);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate( certStoreType,  storeBlob,  storePassword,  encoded);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or base64-encoded) containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

DSURL Type

Contains a Directory Server URLs to which the 3DS Server will send the AReq message.

Remarks

Each DSURL object contains a ThreeDSServerToDsUrl and, optionally, a CountryCode. For a given card range, if the Issuer Country Code matches the DS CountryCode, the 3DS Server uses this ThreeDSServerToDsUrl to communicate with the DS. If there is no match, the 3DS Server uses the default 3DS Server to DS URL.

Fields

CountryCode
String (read-only)

Default Value: ""

The country for which the 3DS Server to DS URL can be used.

ThreeDSServerToDsUrl
String (read-only)

Default Value: ""

URL that the 3DS Server uses to communicate with a DS for a particular card range. If the DS Country Code is absent, the 3DS Server can use this URL for all card ranges.

Constructors

public DSURL();



Extension Type

This type contains extension details.

Remarks

Data necessary to support requirements not otherwise defined in the 3-D Secure message are carried in Message Extensions. This type is used to define extensions to be sent in the next outgoing request.

Fields

Critical
boolean

Default Value: False

Whether the extension is critical.

This setting specifies whether the recipient must understand the contents of the extension to interpret the entire message.

Data
String

Default Value: ""

The extension data as JSON.

This setting specifies the JSON formatted extension data.

Id
String

Default Value: ""

The id of the specified extension.

This setting specifies a unique identifier for the extension.

Name
String

Default Value: ""

The extension name.

This setting specifies the name of the extension as defined by the extension owner.

Constructors

public Extension();

Creates an empty Extension instance whose properties can be set.

public Extension( id,  name,  critical,  data);

Creates an Extension instance with the given Id, Name, Critical, and Data parameters.

OperationInfo Type

This type contains operation details.

Remarks

This type contains details of the operation received in the OReq packet, including:

Fields

Category
String (read-only)

Default Value: ""

Indicates the category/type of information.

01 General
02 Operational alert
03 Public Key Certificate expiry
04 Letter of Approval/Attestation of Compliance expiry
05 Fraud
06 Other
80-99 Reserved for DS use

Description
String (read-only)

Default Value: ""

Describes the reason for the operational communication or the response to an action taken by the recipient.

ExpirationDate
String (read-only)

Default Value: ""

The date after which the relevance of the operational information expires.

MessageStatus
String

Default Value: ""

Indicates the status of the operational request message sequence from the source of the OReq.

01 Successfully received messages
02 Message sequence is broken
03 Requested action is not supported or not executed by the 3DS Server or ACS when OReq message was received
80-99 Reserved for DS use

PriorTransactionId
String (read-only)

Default Value: ""

The transaction ID of the prior transaction to which the operational information refers.

PriorTransactionIdType
int (read-only)

Default Value: 0

The type of transaction ID of the prior transaction to which the operational information refers.

01 3DS Server
02 DS
03 ACS

SequenceId
String (read-only)

Default Value: ""

Uniquely identifies a message sequence and will remain constant in the sequence of messages.

SequenceNumber
int

Default Value: 0

The current message in the sequence. Set this before calling CheckResponse when an OReq packet is received. The component will verify the sequence number of the received OReq to ensure it's not out of sequence.

SequenceTotal
int (read-only)

Default Value: 0

The total number of messages in the sequence and will remain constant in the sequence of messages.

Severity
String (read-only)

Default Value: ""

Indicates the importance/severity level of the operational information.

01 Critical
02 Major
03 Minor
04 Informational
80-99 Reserved for DS use

Constructors

public OperationInfo();



Proxy Type

This is the proxy the class will connect to.

Remarks

When connecting through a proxy, this type is used to specify different properties of the proxy, such as the Server and the AuthScheme.

Fields

AuthScheme
int

Default Value: 0

This field is used to tell the class which type of authorization to perform when connecting to the proxy. This is used only when the User and Password fields are set.

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

By default, AuthScheme is authBasic (0), and if the User and Password fields are set, the component will attempt basic authentication.

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

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

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

For security reasons, setting this field will clear the values of User and Password.

AutoDetect
boolean

Default Value: False

This field tells the class whether or not to automatically detect and use proxy system settings, if available. The default value is false.

Note: This setting is applicable only in Windows.

Password
String

Default Value: ""

This field contains a password if authentication is to be used for the proxy.

If AuthScheme is set to Basic Authentication, the User and Password are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If AuthScheme is set to Digest Authentication, the User and Password fields are used to respond to the Digest Authentication challenge from the server.

If AuthScheme is set to NTLM Authentication, the User and Password fields are used to authenticate through NTLM negotiation.

Port
int

Default Value: 80

This field contains the Transmission Control Protocol (TCP) port for the proxy Server (default 80). See the description of the Server field for details.

Server
String

Default Value: ""

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

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

SSL
int

Default Value: 0

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

psAutomatic (0)Default setting. If the URL is an https URL, the class will use the psTunnel option. If the URL is an http URL, the class will use the psNever option.
psAlways (1)The connection is always SSL enabled.
psNever (2)The connection is not SSL enabled.
psTunnel (3)The connection is made through a tunneling (HTTP) proxy.

User
String

Default Value: ""

This field contains a user name, if authentication is to be used for the proxy.

If AuthScheme is set to Basic Authentication, the User and Password are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If AuthScheme is set to Digest Authentication, the User and Password fields are used to respond to the Digest Authentication challenge from the server.

If AuthScheme is set to NTLM Authentication, the User and Password fields are used to authenticate through NTLM negotiation.

Constructors

public Proxy();



public Proxy( server,  port);



public Proxy( server,  port,  user,  password);



Range Type

A card range associated with the CardRangeData event.

Remarks

Each Range object contains a range of card numbers from includes a Start to End, and provides a card range associated with the current firing of the CardRangeData event. Start and End values returned from the server will always be the same length, for ease of computation.

This field is only applicable when ProtocolVersion is 2.3.1.

Fields

End
String (read-only)

Default Value: ""

The final card number in the current range.

Start
String (read-only)

Default Value: ""

The first card number in the current range.

Constructors

public Range();



Config Settings (Server Class)

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

Server Config Settings

AccountAgeIndicator:   Cardholder Account Age Indicator.

Length of time that the cardholder has had the account with the 3DS Requestor.

Possible values are:

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include.

The complete list of elements (all available as config settings) comprising Cardholder Account Information is:

  • AccountAgeIndicator
  • AccountChangeDate
  • AccountChangeIndicator
  • AccountDate
  • AccountPasswordChangeDate
  • AccountPasswordChangeIndicator
  • AccountRequestorID
  • AccountPurchaseCount
  • AccountProvisioningAttempts
  • AccountDayTransactions
  • AccountYearTransactions
  • PaymentAccountAge
  • PaymentAccountAgeIndicator
  • ShipAddressUsageDate
  • ShipAddressUsageIndicator
  • ShipNameIndicator
  • SuspiciousAccountActivity

AccountChangeDate:   Cardholder Account Change Date.

Date that the cardholder's account with the 3DS Requestor was last changed. Accepted date format is YYYYMMDD.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

AccountChangeIndicator:   Cardholder Account Change Indicator.

Length of time since the cardholder's account information with the 3DS Requestor was last changed.

Possible values are:

01 Changed during this transaction
02 Less than 30 days
03 30-60 days
04 More than 60 days

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

AccountDate:   Date cardholder account opened.

Date that the cardholder opened the account with the 3DS Requestor. Accepted date format is YYYYMMDD.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

AccountDayTransactions:   Number of account transactions in the last day.

Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

AccountId:   Cardholder Account Identifier.

Additional information about the account optionally provided by the 3DS Requestor in AReq messages.

AccountPasswordChangeDate:   Cardholder Account Password Change Date.

Date that cardholder's account with the 3DS Requestor had a password change or account reset. Accepted date format is YYYYMMDD.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

AccountPasswordChangeIndicator:   Cardholder Account Password Change Indicator.

Indicates the length of time since the cardholder's account with the 3DS Requestor had a password change or account reset.

Possible values are:

01 No change
02 Changed during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

AccountProvisioningAttempts:   Number of account provisioning attempts in the last day.

Number of Add Card attempts for the account in the last 24 hours.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

AccountPurchaseCount:   Cardholder Account Purchase Count.

Number of purchases with this cardholder account during the previous six months.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

AccountRequestorID:   Cardholder Account Requestor ID.

The 3DS Requestor assigned account identifier of the transacting Cardholder.

This identifier is coded as the SHA-256 + Base64URL of the account identifier for the 3DS Requestor and is provided as a string.

AccountYearTransactions:   Number of account transactions in the last year.

Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

ACSChallengeMandatedIndicator:   ACS Challenge Mandated Indicator.

Indication of whether a challenge is required for the transaction to be authorized due to local/regional mandates or other variable. Required in ARes messages if TransactionStatus = C.

ACSOperatorId:   ACS identifier assigned by DS.

Each DS can provide a unique ID to each ACS on an individual basis. Requirements for the presence of this field in ARes messages are DS specific. Any individual DS may impose special formatting and character requirements on the contents of this field.

ACSReferenceNumber:   Unique ACS Reference Number.

Returned from the directory server in the Authentication Response Message (ARes), this field contains a unique identifier for the ACS. Used by the DS to identify the ACS and passed along to the Server in the ARes. This field will be set after a successful call to SendAuthRequest.

ACSRenderingDeviceUserInterfaceMode:   User interface mode the ACS will present to cardholder.

Indicates the user interface mode the ACS will present to the cardholder for a challenge. Possible values are:

01 Portrait
02 Landscape
03 Voice
04 Other
ACSRenderingInterface:   Challenge interface type presented to cardholder.

This setting specifies the ACS interface that must be used to present the challenge to the cardholder in an app-based flow. This setting is populated after calling SendAuthRequest in the 3DS Server. This is also populated after calling CheckResponse and passing the Results Request Message.

Possible values are:

01 Native UI
02 HTML UI

ACSRenderingUITemplate:   Challenge type presented to cardholder.

This setting holds the type of challenge that will be presented to the cardholder in an app-based flow. This setting is populated after calling SendAuthRequest in the 3DS Server. This is also populated after calling CheckResponse and passing the Results Request Message.

Possible values are:

01 Text
02 Single Select
03 Multi Select
04 OOB
05 HTML Other (valid only for HTML UI)
06 HTML OOB (valid only for 2.3.1)
07 Information (valid only for 2.3.1)

ACSSignedContent:   String value of the JWS object of the ARes message created by the ACS.

Contains the JWS object created by the ACS for the ARes message. The JWS object body contains the ACSURL, the ACS Ephemeral Public Key, and the SDK Ephemeral Public Key (available in the SDKEphemeralPublicKey configuration setting).

This setting is only applicable to the app-based flow and is informational. It does not need to be queried or set in most cases.

ACSTransactionId:   Unique transaction identifier assigned by the ACS.

This field contains a universally unique transaction identifier assigned by the ACS to identify a single transaction.

AddressMatch:   Address Match Indicator.

This field is used to indicate to the ACS whether the cardholder shipping address and billing address are the same.

YShipping address matches billing address.
NShipping address does not match billing address.
AllowNullMethodURL:   Allow null MethodURL when retrieving card ranges.

According to the EMVCo specification, if no MethodURL is available, the field should be omitted from the card ranges response. In some cases, however, the directory server has returned a "null" string instead. This is false by default, and this invalid data will result in an error raised by the RequestCardRanges method. Setting this configuration setting to true will allow a null MethodURL in the card range data.

AppIP:   App IP Address.

External IP address (i.e., the device public IP address) used by the 3DS Requestor App when it connects to the 3DS Requestor environment.

AppURLIndicator:   3DS Requestor App URL Indicator.

Indicates whether the OOB Authentication App used by the ACS during a challenge supports the 3DS Requestor App URL. This is returned by the ACS in the authentication response (ARes) packet. Possible values are:

Y3DS Requestor App URL is supported by the OOB Authentication App
N3DS Requestor App URL is NOT supported by the OOB Authentication App
AuthenticationInformation:   3DS Requestor Prior Transaction Authentication Information.

Information about how th 3DS Requestor authenticated the cardholder as part of a previous 3DS transaction. This is specified as a JSON array of objects containing the following fields:

threeDSReqPriorAuthDsTransIdThe prior DS Transaction ID (2.3.1 only)
threeDSReqPriorAuthDataData that documents and supports a specific authentication process
threeDSReqPriorAuthMethodMechanism used by the Cardholder to previously authenticate to the 3DS Requestor
threeDSReqPriorAuthTimestampData and time converted into UTC of the prior Cardholder authentication
threeDSReqPriorRefAdditional information
AuthenticationMethod:   A comma separated list of authentication types used by the issuer.

After SendAuthRequest, this will be set if the TransactionStatus is C or D and indicates the authentication type(s) the issuer will use to challenge the cardholder. When a Results Reuqest Message (RReq) is parse,d this will be set if the TransactionStatus is Y or N and indicates the authentication method(s) that were used during the challenge. Possible values include:

01Static Passcode
02SMS OTP
03Key fob or EMV card reader OTP
04App OTP
05OTP Other
06KBA
07OOB Biometrics
08OOB Login
09OOB Other
10Other
11Push Confirmation
12Decoupled
13WebAuthn
14SPC
15Behavioral biometrics
16Electronic ID
17-79Reserved for future EMVCo use
80-99Reserved for DS use
For 3RI, only present for Decoupled Authentication.
AuthenticationType:   Type of authentication method used by the issuer.

After SendAuthRequest, this will be set if TransactionStatus is C or D and indicates the type of authentication method that will be used to challenge the cardholder. When a Results Request Message (RReq) is parsed, this will be set if the TransactionStatus is Y or N and indicates the authentication method that was used during the challenge.

Possible values include:

01Static
02Dynamic
03OOB
04Decoupled

BroadInfo:   Broadcast Information.

Structured information sent between the 3DS server, the DS, and the ACS.

BroadInfoCategory:   Broadcast Information Category.

Indicates the category/type of information. Possible values are:

01General
02Certificate expiry
03Fraud alert
04Operational alert
05Transactional data
06Other
07-79Reserved for EMVCo future use
80-99Reserved for DS use
BroadInfoDescription:   Broadcast Information Description.

Information to be broadcasted to recipients.

BroadInfoExpiryDate:   Broadcast Information Expiry Date.

The date after which the relevance of the broadcasted information (e.g., certificate expiration dates) expires, in YYYYMMDD format.

BroadInfoRecipients:   Broadcast Information Recipient(s).

Indicates the intended recipient(s) of the broadcasted information. Multiple recipients can be configured by OR-ing one or more of the following values:

13DS SDK
23DS Server
4DS
8ACS
BroadInfoSeverity:   Broadcast Information Severity.

Indicates the importance/severity level of the broadcasted information. Possible values are:

01Critical
02Major
03Minor
04Informational
BroadInfoSource:   Broadcast Information Source.

Indicates the source of the broadcasted information. Possible values are:

013DS Server
02DS
03ACS
BrowserUserDeviceId:   Browser User Device ID.

Unique and immutable identifier linked to a device that is consistent across 3DS transactions for the specific user device. Examples include a Hardware Device ID or a Platform-calculated device fingerprint.

BrowserUserId:   Browser User ID.

Identifier of the transacting user's Browser Account ID. This identifier is a unique and immutable hash of the user's account identifier for the given Browser provided as a string.

CardholderInformation:   Information text presented to Cardholder during the transaction.

Text provided in ARes by the ACS/Issuer to Cardholder during a Frictionless or Decoupled transaction. The Issuer can provide information to Cardholder. If populated, this information is required to be conveyed to the cardholder. Required if DecoupledConfirmationIndicator is Y.

CardholderInformationIssuerImage:   Issuer image presented to the Cardholder during the transaction.

A URL pointing to the issuer image to be presented to the cardholder along with the CardholderInformation.

CardholderInformationPaymentSystemImage:   Payment system image presented to the Cardholder during the transaction.

A URL pointing to the payment system image to be presented to the cardholder along with the CardholderInformation.

CardRangeRecordsReadOrder:   Indicates the order in which to process the card range records from the PRes message.

Possible values are:

01Direct order/FIFO (First In First Out)
02Reverse order/LIFO (Last In First Out)
When UseJsonDOM is false, the cardrange in CardRangeData is in the sequence of received data. If the value of this field is 02, indicating a Last In First Out approach, it would be necessary to cache the cardranges first and then reverse the order of which they are processed.

This config may not be available (empty value) in the CardRangeData. This config will always be empty when UseJsonDOM is true.

CardRangeTempPath:   Temporary path where card range data is written.

When RequestCardRanges is called, this configuration setting can be used to specify the path to which the component will temporarily save the card range data. This data is saved in a file that is deleted when parsing of the ranges is complete. This can be useful in limiting memory usage of the component, especially when large amounts of ranges are returned. For the most benefit, this should be used in conjunction with StoreCardRangeData set to False.

CardSecurityCode:   Card Security Code.

Three or four digit security code printed on the card.

CardSecurityCodeStatus:   Card Security Code Status.

Enables the communication of Card Security Code Status between the ACS, the DS, and the 3DS Requestor. Possible values are:

YValidated
NFailed validation
UStatus unknown, unavailable, or does not apply
CardSecurityCodeStatusSource:   Card Security Code Status Source.

Possible values are:

01DS
02ACS
03-79Reserved for EMVCo future use
80-99Reserved for DS use
ChallengeCancellationIndicator:   Challenge Cancellation Indicator.

Indicator informing the ACS and the DS that the authentication has been canceled. Required in CReq for app-based if the authentication transaction was canceled for any of the reasons available as values. Required in the RReq if the ACS identifies that the authentication transaction was canceled for reasons indicated.

Possible values are:

01 Cardholder selected "Cancel" by interaction with the cancellation button in the UI
02 3DS Requestor canceled Authentication
03 Transaction Abandoned
04 Transaction Timed out at ACS - other timeouts
05 Transaction Timed out at ACS - First CReq not received by ACS
06 Transaction Error
07 Unknown
08 Transaction Timed Out at 3DS SDK
09 Error message in response to the CRes message sent by the ACS
10 Error in response to the CRes message received by the ACS
11-79 Reserved for future EMV/Co use (values invalid until defined by EMVCo)
80-99 Reserved for future DS use

ChallengeErrorReportingACSTransID:   Challenge Error Reporting ACS Transaction ID.

The ACS Transaction ID field from the error message (Erro) reported during the challenge process.

When an error is encountered during the CReq/CRes process, a copy of the error message (Erro) may be included in the RReq sent to the server. This is required when the ChallengeCancellationIndicator is 09 or 10. The following configuration settings will be populated with data from this error message:

ChallengeErrorReportingDSTransID:   Challenge Error Reporting DS Transaction ID.

The Directory Server Transaction ID field from the error message (Erro) reported during the challenge process.

ChallengeErrorReportingErrorCode:   Challenge Error Reporting Error Code.

The Error Code field from the error message (Erro) reported during the challenge process.

ChallengeErrorReportingErrorComponent:   Challenge Error Reporting Error Component.

The Error Component field from the error message (Erro) reported during the challenge process.

ChallengeErrorReportingErrorDescription:   Challenge Error Reporting Error Description.

The Error Description field from the error message (Erro) reported during the challenge process.

ChallengeErrorReportingErrorDetail:   Challenge Error Reporting Error Detail.

The Error Detail field from the error message (Erro) reported during the challenge process.

ChallengeErrorReportingErrorMessageType:   Challenge Error Reporting Error Message Type.

The Error Message Type field from the error message (Erro) reported during the challenge process.

ChallengeErrorReportingMessageType:   Challenge Error Reporting Message Type.

The Message Type field from the error message (Erro) reported during the challenge process.

ChallengeErrorReportingMessageVersion:   Challenge Error Reporting Message Version.

The Message Version field from the error message (Erro) reported during the challenge process.

ChallengeErrorReportingSDKTransID:   Challenge Error Reporting SDK Transaction ID.

The SDK Transaction ID field from the error message (Erro) reported during the challenge process.

ChallengeErrorReportingThreeDSServerTransID:   Challenge Error Reporting Server Transaction ID.

The 3DS Server Transaction ID field from the error message (Erro) reported during the challenge process.

ChallengeTimeRemaining:   Amount of time left to complete challenge.

This field contains the time remaining to complete the challenge. This is based on the SDKMaxTimeout set when issuing the initial Authorization Request Message.

CheckSPCTimeout:   Time remaining for SPC authentication to complete.

When SPC authentication is to be performed as indicated by a TransactionStatus value of S, the authenticaton must be complete within 9 minutes. The component will automatically start an internal timer that can be checked using this configuration setting. This will return the number of seconds left for SPC authentication to complete. When authentication is complete, the assertion data should be sent to the DS using a second AReq packet should be set to the server.

If the time has expired before receiving the Assertion Data from the 3DS Requestor, checking this configuration setting will cause the component to automatically send the second AReq message with an SPC Incompletion Indicator value of 03, indicating that SPC authentication timed out.

ClearCustomRequestFields:   Clear the custom request fields internal collection.

When PersistCustomRequestFields is true, the component will store request fields specified via the AddRequestField method to use for future generated requests. This configuration setting can be used to clear this internal collection.

ContinueParsingCardRangesOnError:   Whether or not to continue parsing card ranges when a validation error is encountered.

When RequestCardRanges is called, the class will parse the card ranges returned in the PRes response packet. By default, if an error is encountered, the component will stop parsing, send an Erro packet to the Directory Server, and throw an exception. This setting can be used to instruct the component to continue parsing the card ranges, and adding the ranges that do not fail validation to the CardRanges collection prior to raising the error. The default value is False.

DecoupledConfirmationIndicator:   ACS Decoupled Confirmation Indicator.

Returned in the authentication response, and indicates whether the ACS confirms utilization of Decoupled Authentication and agrees to utilize Decoupled Authentication to authenticate the Cardholder.

Possible values are:

Y Confirms decoupled authentication will be utilized.
N Decoupled authentication will not be utilized.

Note that if the 3DS Requestor decoupled request indicator = N, a value of Y cannot be returned. If the TransactionStatus is D, a value of N is not valid.

DecoupledMaxTimeout:   3DS Requestor Decoupled Max Time.

Indicates the maximum amount of time that the 3DS Requestor will wait for an ACS to provide the results of a Decoupled Authentication transaction (in minutes). Set prior to calling SendAuthRequest if allowing decoupled authentication.

DecoupledRequestIndicator:   3DS Requestor Decoupled Request Indicator.

Indicates whether the 3DS Requestor requests the ACS to utilize Decoupled Authentication and agrees to utilize Decoupled Authentication if the ACS confirms its use.

Possible values are:

Y Decoupled authentication is supported and preferred if challenge is necessary.
N Do not use decoupled authentication.
F Decoupled Authentication is supported and is to be used only as a fallback challenge method if a challenge is necessary (TransactionStatus = D in RReq).
B Decoupled Authentication is supported and can be used as a primary or fallback challenge method if a challenge is necessary (TransactionStatus = D in either ARes or RReq).
Note that if the element is not provided (default), the ACS should interpret this equivalent to a value of N.

DecoupledTimeRemaining:   Time remaining before a RReq should be received during a decoupled authentication.

When performing decoupled authentication, the 3DS Server will wait DecoupledMaxTimeout seconds for a Results Request (RReq) packet from the Directory Server indicating the results of the authentication. Generally, the ACS should send the RReq before the specified max time expires, even if authentication has not succeeded. If not successful, this would be indicated in the RReq. This config can be used to help track the time remaining before this RReq should be received, and is based on DecoupledMaxTimeout + 30 seconds.

DeliveryEmailAddress:   Merchandise Delivery Email Address.

The email address to which the merchandise was delivered for Electronic delivery.

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. The data elements making up the Indicator will be formatted into a JSON object prior to being placed into the Device Merchant Risk Indicator field of the message. The Indicator is the Merchant's assessment of the level of fraud risk for the specific authentication for both the cardholder and the authentication being conducted.

The complete list of elements (all available as config settings) comprising the Merchant Risk Indicator is:

  • DeliveryEmailAddress
  • DeliveryTimeframe
  • GiftCardAmount
  • GiftCardCount
  • GiftCardCurrency
  • PreOrderDate
  • PreOrderPurchaseIndicator
  • ReorderItemsIndicator
  • ShipIndicator

DeliveryTimeframe:   Merchandise Delivery Timeframe.

Indicates the merchandise delivery timeframe.

Possible values are:

01 Electronic Delivery
02 Same day shipping
03 Overnight shipping
04 Two-day or more shipping

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. See the DeliveryEmailAddress configuration setting for the complete list of elements (all available as config settings) comprising the Merchant Risk Indicator.

DeviceBindingStatus:   Device Binding Status.

Enables the communication of Device Binding Status between the ACS, DS, and the 3DS Requestor.

For bound devices (value = 11-14), this convest the type of binding that was performed.

01Device is not bound by Cardholder
02Not eligible as determined by issuer
03Pending confirmation by Cardholder
04Cardholder rejected
05Device Binding Status unknown, unavailable, or does not apply
06-10Reserved for EMVCo future use
11Device is bound by Cardholder (device is bound using hardware/SIM internal to the consumer device. For instance, keys stored in a secure element on the device)
12Device is bound by Cardholder (device is bound using hardware external to the consumers device. For example, an external FIDO authenticator)
13Device is bound by Cardholder (device is bound using data that includes dynamically generated data and could include a unique device ID)
14Device is bound by Cardholder (device is bound using static device data that has been obtained from the consumer's device)
15Device is bound by Cardholder (other method)
16-79Reserved for EMVCo future use
80-99Reserved for DS use

DeviceBindingStatusSource:   Device Binding Status Source.

Populated by the system setting Device Binding Status. Possible values are:

013DS Server
02DS
03ACS
04-79Reserved for EMVCo future use
80-99Reserverd for DS use
DeviceInfoRecognisedVersion:   Device Information Recognized Version.

Indicates the highest Data Version of the Device Information supported by the ACS.

DeviceRenderingInterface:   SDK Interface Device Rendering Types supported.

Types of SDK Interfaces that the device supports for displaying specific challenge user interfaces within the SDK.

Possible values are:

01 Native
02 HTML
03 Both

One of the elements comprising the Device Rendering Options which define the SDK UI types that the device supports (along with DeviceRenderingInterface). These Options are required in AReq messages.

DeviceRenderingUIType:   SDK UI Types supported.

UI types that the device supports for displaying specific challenge user interfaces within the SDK. Multiple values can be or-ed together to support multiple types. Possible values are:

01 Text
02 Single Select
04 Multi Select
08 OOB
16 HTML Other

Note that currently all SDKs need to support all UI types. In the future, however, this may change (for example, smart watches may support a UI Type not yet defined). In light of this, all UI types are enabled by default (31).

DSEndProtocolVersion:   DS End Protocol Version.

The most recent active protocol version that is supported for the directory server. This is the default value included in the PRes packet returned from the server during a call to RequestCardRanges. If the DSEndProtocolVersion is not specified (i.e. empty) at the CardRanges level, this should be utilized.

DSReferenceNumber:   DS Reference Number.

EMVCo-assigned unique identifier to track approved DS. The DS will populate the AReq with this element prior to passing to the ACS, and it will be returned in the ARes.

DSStartProtocolVersion:   DS Start Protocol Version.

The earliest (i.e. oldest) active protocol version that is supported for the directory server. This is the default value included in the PRes packet returned from the server during a call to RequestCardRanges. If the DSStartProtocolVersion is not specified (i.e. empty) at the CardRanges level, this should be utilized.

DSTransactionId:   Directory server transaction ID.

Universally unique transaction identifier assigned by the directory server to identify a single transaction.

EMVPaymentTokenIndicator:   EMV Payment Token Indicator.

A value of true indicates that the transaction was de-tokenised prior to being received by the ACS. This data element will be populated by the system residing in the 3-D Secure domain where the de-tokenization occurs (i.e., the 3DS Server or the DS). The Boolean value of true is the only valid response for this field when it is present. Required in CReq if there is a de-tokenization of an Account Number.

EMVPaymentTokenSource:   EMV Payment Token Source.

Indicates where the payment token was detokenized.

Valid values are:

01 3DS Server
02 DS

This is required to be set if EMVPaymentTokenIndicator is true.

EnableDownloadCardRangeDataFile:   Card Range Data Download Indicator.

Indicates if the 3DS Server supports Card Range Data from a file. This can be set to Yprior to calling RequestCardRanges to indicate that downloading a card range data file is supported.

If the DS supports this functinoality, the response packet (PRes) will include a URL from which the card range data maybe downloaded. The component will automatically download the data from this location and process the card ranges.

Available when ProtocolVersion is 2.3.1 only.

EncodedSessionData:   Encoded session data that is sent in the challenge request and returned in the challenge response.

This setting holds the encoded version of SessionData after GetChallengeRequest is called. This may be set in the threeDSSessionData form variable in the post made in the challenge window.

When the ACS POSTs the final challenge response to the NotificationURL this setting may be set to the threeDSSessionData form variable value, and SessionData setting may then be queried to return the decoded session data.

EncryptedDeviceInfo:   SDK Encrypted Data.

JWE Object (represented as a string) containing data encrypted by the 3DS SDK. Required for the app-based flow and sent in the AReq when the SendAuthRequest method is called.

ErrorCode:   Code from the last error message.

Code indicating the type of problem identified in the error message.

ErrorDescription:   Description from the last error message.

Text describing the problem identified in the error message.

ErrorDetail:   Additional details from the last error message.

Additional detail regarding the problem identified in the error message.

ExtractRReqServerTransactionId:   Extacts the ServerTransactionId from the RReq packet.

This setting can be used to extract the ServerTransactionId from the RReq packet. This field can then be used to look up details on the transaction prior to parsing the RReq packet using the CheckResponse method. Set this to the received RReq packet data and the ServerTransactionId will be returned from the Config method.

GiftCardAmount:   Total gift card(s) amount.

For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. See the DeliveryEmailAddress configuration setting for the complete list of elements (all available as config settings) comprising the Merchant Risk Indicator.

GiftCardCount:   Total number of gift cards purchased.

For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. See the DeliveryEmailAddress configuration setting for the complete list of elements (all available as config settings) comprising the Merchant Risk Indicator.

GiftCardCurrency:   Gift Card Currency.

For prepaid or gift card purchase, the currency code of the card.

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. See the DeliveryEmailAddress configuration setting for the complete list of elements (all available as config settings) comprising the Merchant Risk Indicator.

IncomingExtensionCount:   The number of extensions received from the directory server.

This setting holds the number of extensions received in the last message from the directory server. The individual extension data can be accessed via the IncomingExtensionId, $rcfgIncomingExtensionName;, IncomingExtensionCritical, and IncomingExtensionData settings.

IncomingExtensionCritical[Index]:   Whether the extension is critical.

This setting specifies whether the recipient must understand the contents of the extension to interpret the entire message.

IncomingExtensionData[Index]:   The extension data as JSON.

This setting specifies the JSON formatted extension data.

IncomingExtensionId[Index]:   The id of the specified extension.

This setting specifies a unique identifier for the extension.

IncomingExtensionName[Index]:   The extension name.

This setting specifies the name of the extension as defined by the extension owner.

IncomingRawExtensions:   The full JSON formatted extension data received from the directory server.

This setting holds the full JSON formatted extension data that was received in the last message from the directory server. This corresponds to the value for the messageExtension JSON object defined in the specification.

InstalmentPaymentData:   Max authorizations permitted for installment payments.

Indicates maximum number of authorizations permitted for installment payments. Required in AReq messages if the Merchant and Cardholder have agree to installment payments (AuthenticationIndicator = 03). Value must be greater than 1.

InteractionCounter:   Interaction Counter.

Indicates the number of authentication cycles attempted by the cardholder. Value to be tracked by the ACS and present in the Results Response Message (RRes).

LogLevel:   Level of logging enabled.

This config specifies the level of logging enabled in the component. Possible values include:

0 (None)No events are logged.
1 (Info - default)Informational events are logged.
2 (Verbose)Detailed data is logged.
3 (Debug)Debug data is logged.
This is set to 1 (Info) by default.
MaskSensitive:   Whether to mask sensitive data in the Log event.

This setting controls whether sensitive data is masked in the Log event. When set to True (default) the CardNumber value will be replaced with the value *************.

Note: DataPacketOut will always contain the raw unmasked value regardless of this setting. This setting only applies to the Log event.

The default value is True.

MessageType:   Type of message that is passed.

This field identifies the type of the message being transmitted.

Possible values include:

AReqAuthentication Request Message
AResAuthentication Response Message
CReqChallenge Request Message
CResChallenge Response Message
PReqPreparation Request Message
PResPreparation Response Message
RReqResults Request Message
RResResults Response Message
ErroError Message

This setting is read-only.

MethodCompletionIndicator:   3DS Method Completion Indicator.

Indicates whether the 3DS Method was successfully completed or not. This is included in the Authorization Request Message (AReq) sent by the SendAuthRequest method. Possible values are:

Y (default)Successfully completed.
NDid not successfully complete.
UUnavailable. 3DS Method URL was not present in the PRes message data for the card range associated with the Cardholder Account Number.
MultiTransactionAcquirerMerchantID:   Acquirer Merchant ID.

Acquirer-assigned Merchant Listed Identifier. Represented in ISO 8583-1 formatting requirements.

MultiTransactionAVNumberUse:   AV Number Use.

Number of times that the AV (Authentication Value) is valid.

MultiTransactionAVValidityTime:   AV Validity Time.

Number of days that the AV (Authentication Value) is valid.

MultiTransactionCount:   The total number of additional transactions specified.

The MultiTransaction configuration settings can be used to specify additional transaction information in case of multiple transactions or merchants. MultiTransactionCount indicates the number of additional transactions specified. Details on these transactions can be set using the following indexed configuration settings:

MultiTransactionMerchantAmount:   Merchant Amount.

Purchase amount for the merchant in minor units of currency with all punctuation removed.

MultiTransactionMerchantCurrencyCode:   Merchant Currency Code.

Currency Code in which purchase Merchant Amount is expressed.

MultiTransactionMerchantCurrencyExponent:   Merchant Currency Exponent.

Minor units of Merchant Currency as specified in the ISO 4217 currency exponent.

MultiTransactionMerchantName:   Merchant Name.

Name of the listed merchant.

MultiTransactionSellerID:   Seller ID.

Merchant-assigned Seller Identifier that links additinal Seller Information outlined in the SellerInfo config.

OutgoingRawExtensions:   The full JSON formatted extension data sent to the directory server.

This setting holds the full JSON formatted extension data that will be included in the next outgoing packet. This corresponds to the value for the messageExtension JSON object defined in the specification.

Note: When sending extension data it is generally recommended to use Extensions instead of this setting.

PaymentAccountAge:   Payment Account Age.

Date that the payment account was enrolled in the cardholder's account with the 3DS Requestor. Accepted date format is YYYYMMDD.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

PaymentAccountAgeIndicator:   Payment Account Age Indicator.

Indicates the length of time that the payment account was enrolled in the cardholder's account with the 3DS Requestor.

Possible values are:

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

PaymentToken:   EMV Payment Token.

Payment token used to initiate the EMV 3DS transaction.

PaymentTokenAdditionalData:   EMV Payment Token Additional Data.

Additional information about the Payment Token from the Token Service Provider.

PaymentTokenCryptogram:   EMV Payment Token Cryptogram.

A cryptogram, containing a transaction-unique value, typically generated using the Payment Token, Payment Token related data, and transaction data. Cryptogram derivation methods may vary by scenario and may be Payment System-specific.

PaymentTokenStatusIndicator:   EMV Payment Token Status Indicator.

Identifies the current status of the Payment token.

PersistCustomRequestFields:   Whether or not to store custom request fields for subsequent requests.

By default, fields added using the AddRequestField method are used once in the next generated requests and disposed of. When this configuration setting is set to true (false by default), the component will store these fields for use in subsequent requests. The ClearCustomRequestFields can then be used to clear the internal collection.

PreOrderDate:   Expected date pre-ordered purchase will be available.

For a pre-ordered purchase, the expected date that the merchandise will be available. Accepted date format is YYYYMMDD.

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. See the DeliveryEmailAddress configuration setting for the complete list of elements (all available as config settings) comprising the Merchant Risk Indicator.

PreOrderPurchaseIndicator:   Pre-Order Purchase Indicator.

Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.

Possible values are:

01 Merchandise available
02 Future availability

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. See the DeliveryEmailAddress configuration setting for the complete list of elements (all available as config settings) comprising the Merchant Risk Indicator.

ProtocolVersion:   Protocol version identifier.

This field indicates the protocol version. This should be the protocol version number of the specification utilized by the system creating this message.

Possible values are:

2.1.0 (Default)
2.2.0
2.3.1

RecurringAmount:   Recurring Amount.

Recurring amount in minor units of currency with all punctuation removed.

RecurringAmountIndicator:   Recurring Amount Indicator.

Indicates whether the recurring or installment payment has a fixed or variable amount. Possible values are:

01Fixed Purchase Amount
02Variable Purchase Amount
03-79Reserved for EMVCo future use
80-99Reserved for DS use
RecurringCurrency:   Recurring Currency.

Currency in which the RecurringAmount is expressed.

RecurringDate:   Recurring Date.

Effective date of the new authorized amount following the first/promotional payment in a recurring or installment transaction.

RecurringExponent:   Recurring Currency Exponent.

Minor units of currency as specified in the ISO 4217 currency exponent.

RecurringFrequencyIndicator:   Recurring Frequency Indicator.

Indicates whether the recurring or installment payment has a fixed or variable frequency.

01Fixed Frequency
02Variable or Unknown Frequency
03-79Reserved for EMVCo future use
80-99Reserved for DS use
ReorderItemsIndicator:   Reorder Items Indicator.

Indicates whether the cardholder is reordering previously purchased merchandise.

Possible values are:

01 First time ordered
02 Reordered

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. See the DeliveryEmailAddress configuration setting for the complete list of elements (all available as config settings) comprising the Merchant Risk Indicator.

ReportCardRangeError:   Report a Card Range Error to the DS.

This configuration setting can be used to actively report a card range error to the directory server. When set, the component will send an appropriate error packet (Erro) to the DirectoryServerURL.

When ProtocolVersion is 2.3.1, a reason can be provided. Possible values are:

1Overlap in the card ranges provided by the DS in the PRes message.
2Action is not possible for the card range.
When ProtocolVersion is not 2.3.1, this can be set to any integer value and a generic card range error will be transmitted.

ReqAuthCount:   Number of 3DS Requestor Authentication Data objects.

The ReqAuth* configuration settings can be used to specify information about how the 3DS Requestor authenticated the Cardholder before or during the transaction. ReqAuthCount indicates the number of pieces of 3DS Requestor Authentication Information are specified, details of which can be set using the following indexed configuration settings:

When ProtocolVersion is 2.3.1 up to 3 entries can be specified. For previous versions this is limited to 1.
ReqAuthData:   3DS Requestor Authentication Data.

Data that documents and supports a specific authentication process. In the current version of the specification, this data element is not defined in detail, however the intention is that for each 3DS Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process.

Part of the 3DS Requestor Authentication Information which contains optional information about how the cardholder authenticated during login to their 3DS Requestor account.

This is an indexed configuration setting, set using an index between 0 and ReqAuthCount - 1.

ReqAuthMethod:   3DS Requestor Authentication Method.

Method used by the Cardholder to authenticate to the 3DS Requestor.

Part of the 3DS Requestor Authentication Information which contains optional information about how the cardholder authenticated during login to their 3DS Requestor account.

Possible values are:

01 No 3DS Requestor authentication occurred (i.e. cardholder "logged in" as guest)
02 Login to the cardholder account at the 3DS Requestor system using 3DS Requestor's own credentials
03 Login to the cardholder account at the 3DS Requestor system using federated ID
04 Login to the cardholder account at the 3DS Requestor system using issuer credentials
05 Login to the cardholder account at the 3DS Requestor system using third-party authentication
06 Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator
07 Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator (FIDO Assertion or Attestation data signed)
08 SRC Assurance Data
09 SPC Authentication
10 Electronic ID Authentication Data
11-79 Reserved for EMVCo future use (values invalid until defined by EMVCo)
80-99 Reserved for future DS use

This is an indexed configuration setting, set using an index between 0 and ReqAuthCount - 1.

ReqAuthTimestamp:   3DS Requestor Authentication Timestamp.

Date and time in UTC of the cardholder authentication. Accepted date format is YYYYMMDDHHMM.

Part of the 3DS Requestor Authentication Information which contains optional information about how the cardholder authenticated during login to their 3DS Requestor account.

This is an indexed configuration setting, set using an index between 0 and ReqAuthCount - 1.

RequestorChallengeInd:   3DS Requestor Challenge Indicator.

Indicates whether a challenge is requested for this transaction. For example: For MessageCategory 01 (PA), a 3DS Requestor may have concerns about the transaction, and request a challenge. For 02 (NPA), a challenge may be necessary when adding a new card to a wallet. Allows 3DS Requestor to request a challenge such as to follow local/regional mandates or other variables.

Possible values are:

01 No preference
02 No challenge requested
03 Challenge requested: 3DS Requestor Preference
04 Challenge requested: Mandate
05 No challenge requested (transactional risk analysis is already performed). Valid for ProtocolVersion 2.2.0 and 2.3.1 only
06 No challenge requested (data share only). Valid for ProtocolVersion 2.2.0 and 2.3.1 only
07 No challenge requested (strong consumer authentication is already performed). Valid for ProtocolVersion 2.2.0 and 2.3.1 only
08 No challenge requested (utilize Trust List exemption if no challenge required). Valid for ProtocolVersion 2.2.0 and 2.3.1 only
09 Challenge requested (Trust List prompt requested if challenge required). Valid for ProtocolVersion 2.2.0 and 2.3.1 only
10 No challenge requested (utilize low value exemption). Valid for ProtocolVersion 2.3.1 only
11 No challenge requested (Secure corporate payment exemption). Valid for ProtocolVersion 2.3.1 only
12 Challenge requested (Device Binding prompt requested if challegnge required). Valid for ProtocolVersion 2.3.1 only
13 Challenge requested (Issuer requested). Valid for ProtocolVersion 2.3.1 only
14 Challenge requested (Merchant initiated transactions). Valid for ProtocolVersion 2.3.1 only
15-79 Reserved for EMVCo future use (values invalid until defined by EMVCo)
80-99 Reserved for DS use

If not provided, the ACS action would be identical to 01 (no preference).

ResendRequestCardRanges:   Whether or not to resend the card ranges request.

If an error is identified with the card range data received from the directory server when calling the RequestCardRanges method, this configuration setting will be true, indicating that the request should be resent. When resending, if SerialNumber was specified for the initial request, it should be set to an empty string before calling RequestCardRanges again. Otherwise, the request can be sent without the serial number again, but the server may respond with an error due to multiple requests within an hour.

SdkAppId:   SDK App ID.

Universally unique ID created upon all installations of the 3DS Requestor App on a Consumer Device. This will be newly generated and stored by the 3DS SDK for each installation.

SdkAuthenticationType:   SDK Authentication Type.

Authentication methods preferred by the 3DS SDK in order of preference. A comma separated list of the following possible values:

01Static Passcode
02SMS OTP
03Key fob or EMV card reader OTP
04App OTP
05OTP Other
06KBA
07OOB Biometrics
08OOB Login
09OOB Other
10Other
11Push Notification
SDKEphemeralPublicKey:   Public key component of the ephemeral key pair generated by the Client.

This setting holds the public key used to establish session keys between the 3DS SDK and ACS.

SDKMaxTimeout:   SDK Maximum Timeout.

Indicates the maximum amount of time (in minutes) for all exchanges. Included in the Authorization Request Message (AReq) sent to the directory server via the SendAuthRequest method. A value of 5 minutes is used by default. SDK Maximum Timeout.

Indicates the maximum amount of time (in minutes) for all exchanges. Included in the Authorization Request Message (AReq) sent to the directory server via the SendAuthRequest method. A value of 5 minutes is used by default.

SDKMaxTimeout:   SDK Maximum Timeout.

Indicates the maximum amount of time (in minutes) for all exchanges. Included in the Authorization Request Message (AReq) sent to the directory server via the SendAuthRequest method. A value of 5 minutes is used by default. SDK Maximum Timeout.

Indicates the maximum amount of time (in minutes) for all exchanges. Included in the Authorization Request Message (AReq) sent to the directory server via the SendAuthRequest method. A value of 5 minutes is used by default.

SDKReferenceNumber:   Assigned SDK reference number.

This setting specifies the SDK reference number assigned by EMVCo when the 3DS SDK is approved.

SDKServerSignedContent:   SDK Server Signed Content.

Contains the JWS object (represented as a string) created by the Split-SDK Server for the AReq message.

SDKTransactionId:   SDK Transaction ID.

Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction.

SDKWrapped:   Default-SDK Wrapped Indicator.

Set to Y to indicate if the Default-SDK is embedded as a wrapped component in the 3DS Requestor App.

SellerInfo:   Seller Information.

Contains details of each seller involved in the transaction. This is specified as a JSON array of objects containing the following fields:

sellerNameName of the Seller
sellerIdMerchant-assigned Seller identifier
sellerBusinessNameBusiness Name of the Seller
sellerAccDateDate converted into UTC that the Seller started using the Merchant's services.
sellerAddrLine1First line of the business or contact street address of the Seller
seerAddrLine2Second line of the business or contact street address of the Seller
sellerAddrLine3Third line of the business or contact street address of the Seller
sellerAddrCityBusiness or contact city of the Seller
sellerAddrStateBusiness or contact state or province of the Seller
sellerAddrPostCodeBusiness or contact ZIP or other postal code of the seller
sellerAddrCountryBusiness or contact country of the Seller
sellerEmailBusiness or contact email address of the Seller
sellerPhoneBusiness or contact phone number of the Seller
ServerOperatorId:   3DS Server identifier.

Directory server assigned 3DS Server identifier. This may be assigned by a directory server. If this is assigned it should be set here.

SessionData:   Session data that is sent in the challenge request and returned in the challenge response.

This setting specifies session information that may be used to associate the notification of challenge completion with the original transaction. This may be set before calling GetChallengeRequest.

When the ACS POSTs the final challenge response to the NotificationURL the EncodedSessionData may be set to the threeDSSessionData form variable value, and this setting may then be queried to return the decoded session data.

ShipAddressUsageDate:   Shipping address first usage date.

Date when the shipping address used for this transaction was first used with the 3DS Requestor. Accepted date format is YYYYMMDD.

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

ShipAddressUsageIndicator:   Shipping address usage indicator.

Indicates the length of time since the shipping address used for this transaction was first used with the 3DS Requestor.

Possible values are:

01 This transaction
02 Less than 30 days
03 30-60 days
04 More than 60 days

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

ShipIndicator:   Shipping method indicator.

Indicates shipping method chosen for the transaction. Merchants must choose the Shipping Indicator code that most accurately describes the cardholder's specific transaction, not their general business. If one or more items are included in the sale, the Shipping Indicator code for the physical goods is used, or if all digital goods, the Shipping Indicator code that describes the most expensive item.

Possible values are:

01 Ship to cardholder's billing address
02 Ship to another verified address on file with merchant
03 Ship to address that is different than the cardholder's billing address
04 "Ship to Store" / Pick-up at local store (Store address shall be populated in shipping address fields)
05 Digital goods (includes online services, electronic gift cards and redemption codes)
06 Travel and Event tickets, not shipped
07 Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.)
08 Pick-up and go delivery
09 Locker delivery (or other automated pick-up)

An element of the Merchant Risk Indicator applicable in AReq messages, which is optional but strongly recommended to include. See the DeliveryEmailAddress configuration setting for the complete list of elements (all available as config settings) comprising the Merchant Risk Indicator.

ShipNameIndicator:   Shipping Name Indicator.

Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.

Possible values are:

01 Account Name identical to shipping Name
02 Account Name different than shipping Name

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

SPCIncompletionIndicator:   SPC Incompletion Indicator.

Reason that the SPC authentication was not completed. Possible values are:

01SPC did not run or did not successfully complete
02Cardholder cancelled the SPC authentication
03SPC timed out
04-99Reserved for EMVCo future use
SPCTransactionAdditionalData:   SPC Transaction Additional Data.

For SPC API enhancement, to be defined in a future 3DS specification release.

SPCTransactionChallenge:   SPC Transaction Challenge.

Random string generated by the ACS to prevent replay attacks.

SPCTransactionChallengeInfoText:   SPC Transaction Challenge Information Text.

Text provided by the ACS to be displayed during the SPC authentication.

SPCTransactionCurrency:   SPC Transaction Currency.

Transaction amount currency to be displayed during the SPC authentication. In ISO 4217 three-character alphabetic format.

SPCTransactionDisplayName:   SPC Transaction Display Name.

Card or product name (Payment Instrument) to be displayed during the SPC authentication.

SPCTransactionExtensionIndicator:   SPC Transaction WebAuthn SPC Extension Indicator.

For SPC and WebAuthn API enhancement.

SPCTransactionIcon:   SPC Transaction Icon.

Card image (Payment Instrument) URL or Data URL to be displayed during the SPC authentication.

SPCTransactionIssuerImage:   SPC Transaction Issuer Default Image.

Default Issuer logo or image URL or Data URL to be displayed during the SPC authentication.

SPCTransactionIssuerImageDark:   SPC Transaction Issuer Dark Mode Image.

Dark mode Issuer logo or image URL or Data URL to be displayed during the SPC authentication.

SPCTransactionIssuerImageMonochrome:   SPC Transaction Issuer Monochrome Image.

Monochrome Issuer logo or image URL or Data URL to be displayed during the SPC authentication.

SPCTransactionPayeeName:   SPC Transaction Payee Name.

The display name of the payee that this SPC call is for (e.g. the merchant). Matches the Merchant Name from the AReq message.

SPCTransactionPayeeOrigin:   SPC Transaction Payee Origin.

The origin of the payee that this SPC call is for (e.g. the merchant).

SPCTransactionPSImage:   SPC Transaction Payment System Default Image.

Default Default Payment System logo or image URL to be displayed during the SPC authentication.

SPCTransactionPSImageDark:   SPC Transaction Payment System Dark Mode Image.

Dark mode Payment System logo or image URL to be displayed during the SPC authentication.

SPCTransactionPSImageMonochrome:   SPC Transaction Payment System Monochrome Image.

Monochrome Payment System logo or image URL to be displayed during the SPC authentication.

SPCTransactionTimeout:   SPC Transaction Transaction Timeout.

The number of milliseconds before the request to sign the transaction details times out.

SPCTransactionValue:   SPC Transaction Value.

Transaction amount as a decimal value to be displayed during the SPC authentication.

SplitSDKLimited:   Limited Split-SDK Indicator.

Set to Y to indicate if the Split-SDK client has limited capabilities.

SplitSDKVariant:   Split-SDK Variant.

Indicates the implementation characteristics of the Split-SDK client. Possible values are:

01Native Client
02Browser
03Shell
StoreCardRangeData:   Whether or not to store the card ranges in the CardRanges collection.

Indicates whether or not the component should store card ranges in the internal CardRanges collection after the RequestCardRanges method completes. When False, the card range data will only be available via the CardRange event. This can be useful in limiting memory usage of the component, especially when large amounts of ranges are returned.

The default value is True.

SuspiciousAccountActivity:   Suspicious account activity indicator.

Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.

Possible values are:

01 No suspicious activity has been observed
02 Suspicious activity has been observed

An element of the Cardholder Account Information provided by the 3DS Requestor in AReq messages, which is optional but strongly recommended to include. See the AccountAgeIndicator configuration setting for the complete list of elements (all available as config settings) comprising Cardholder Account Information.

TaxId:   Tax ID.

Cardholder's tax identification.

ThreeDSMethodId:   3DS Method ID.

Contains the 3DS Server Transaction ID used during the previous execution of the 3DS method. Required is the 3DS Requestor reuses previous 3DS Method execution.

ThreeDSRequestorSpcSupport:   3DS Requestor SPC Support.

Set to Y to indicate that the 3DS Requestor supports SPC authentication.

ThreeRIIndicator:   3RI Indicator.

Indicates the type of 3RI request. This data element provides additional information to the ACS to determine the best approach for handing a 3RI request. Included in the Authorization Request Message (ARes) sent by the SendAuthRequest. Valid when DeviceChannel is set to "03," indicating 3RI.

Possible values are:

01Recurring transaction
02Installment transaction
03Add card
04Maintain card information
05Account verification
06Split shipment
07Top-up
08Mail Order
09Telephone Order
10Trust List status check
11Other payment
12Billing Agreement
13Device Binding status check
14Card Security Code status check
15Delayed shipment
16Split payment
17FIDO credential deletion
18FIDO credential registration
19Decoupled authentication fallback
20-79Reserved for EMVCo future use
80-99Reserved for DS use
Values of 06-11 are only applicable when ProtocolVersion is > 2.2.0. Values of 12-14 are only applicable when ProtocolVersion is 2.3.1.

TransactionChallengeExemption:   Transaction Challenge Exemption.

Exemption applied by the ACS to authenticate the transaction without requesting a challenge.

05Transaction Risk Analysis exemption
08Trust List exemption
10Low Value exemption
11Secure Corporate Payments exemption
79No exemption applied
01-04, 06, 07, 09, and 12-78Reserved for EMVCo future use
80-99Reserved for DS use
TransactionCharacteristics:   Transaction Characteristics.

Indicates to the ACS specific transactions identified by the Merchant.

Multiple values can be or-ed together to support multiple types. Possible values are:

1Cryptocurrency transaction
2NFT transaction

TransactionStatusReason:   Reason for value of TransactionStatus.

Provides information on why the Transaction Status field has the specified value. For MessageCategory 01 (PA), always included when TransactionStatus = N, U, or R. For MessageCategory 02 (NPA), as defined by the DS.

Possible values are:

01 Card authentication failed
02 Unknown device
03 Unsupported device
04 Exceeds authentication frequency limit
05 Expired card
06 Invalid card number
07 Invalid transaction
08 No Card record
09 Security failure
10 Stolen card
11 Suspected fraud
12 Transaction not permitted to cardholder
13 Cardholder not enrolled in service
14 Transaction timed out at the ACS
15 Low confidence
16 Medium confidence
17 High confidence
18 Very high confidence
19 Exceeds ACS maximum challenges
20 Non-Payment transaction non supported
21 3RI transaction not supported
22 ACS technical issue
23 Decoupled Authentication required by ACS but not requested by 3DS Requestor
24 3DS Requestor Decoupled Max Expiry Time exceeded
25 Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt
26 Authentication attempted but not performed by the cardholder
27 Preferred Authentication Method not supported
28 Validation of content security policy failed
29 Authentication attempted but not completed by the Cardholder. Fall back to Decoupled Authentication
30 Authentication completed successfully but additional authentication of the Cardholder required. Reinitiate as Decoupled Authentication
31-79 Reserved for future EMVCo use (values invalid until defined by EMVCo)
80-99 Reserved for DS use

TransactionStatusReasonInfo:   Transaction Status Reason Information.

Provides additional information on the TransactionStatusReason.

TransactionType:   Transaction Type.

Identifies the type of transaction being authenticated. This field is required in AReq messages in some markets (e.g. for Merchants in Brazil). Otherwise, optional.

Possible values (derived from ISO Standard) are:

01 Goods/ Service Purchase
03 Check Acceptance
10 Account Funding
11 Quasi-Cash Transaction
28 Prepaid Activation and Load

TrustListStatus:   Trust List Status.

Enables the communication of trust list status between the ACS, the DS and the 3DS Requestor.

Y 3DS Requestor is trust listed by cardholder
N 3DS Requestor is not trust listed by cardholder
E Not eligible as determined by issuer
P Pending confirmation by cardholder
R Cardholder rejected
U Trust list status unknown, unavailable, or does not apply

This may be set prior to calling the SendAuthRequest method. In this case, only values of Y or N are valid. This may also be set when the Authentication Response message or Results Request messages are received, and will be set to the values received from the Directory Server.

TrustListStatusSource:   Trust List Status Source.

This data element will be populated by the system setting Trust List Status. When setting TrustListStatus prior to calling the SendAuthRequest method, this should be set to 01. Possible values are:

01 3DS Server
02 DS
03 ACS
04-79 Reserved for EMVCo future use
08-99 Reserved for DS use
UseAESGCM:   Whether or not to use AESGCM as the encryption algorithm.

By default, the component will use JWS_ENC_ALG_ID_A128CBC_HS256AES when encrypting packets to send to the ACS. Setting this to true will instruct the component to use JWE_ENC_ALG_ID_A128GCM instead.

UseJsonDOM:   Whether or not the component should build an internal DOM when parsing card ranges.

When the RequestCardRanges method is called, by default the component will construct an internal DOM (Document Object Model) when parsing the returned data. When set to False, this will instruct the component not to build this model, which can be useful in limiting memory usage of the component, especially when large amounts of ranges are returned.

The default value is True. Note that when False, the XPath settings will not be available.

WebAuthnCredentialListCount:   The total number of WebAuthen Credentials.

The WebAuthnCredentialList configuration settings can be used to access a list of enrolled FIDO credentials (WebAuthn Credentials) associated with the Cardholder Account Number as returned from the ACS in the ARes packet. WebAuthnCredentialListCount indicates the number of credentials specified. The Relying Party ID and Credential for each can be set using the following indexed configuration settings:

This data is only available when ProtocolVersion is 2.3.1, and only when the TransactionStatus is S.
WebAuthnCredentialListRelyingPartyId:   WebAuthn Credential List: Relying Party ID.

The Relying Party ID for the WebAuthn credential.

WebAuthnCredentialListWebAuthnCredential:   WebAuthn Credential List: WebAuthn Credential.

WebAuthn Credential.

WhitelistStatus:   Whitelist Status.

Enables the communication of trusted beneficiary/whitelist status between the ACS, the DS and the 3DS Requestor.

Y 3DS Requestor is whitelisted by cardholder
N 3DS Requestor is not whitelisted by cardholder
E Not eligible as determined by issuer
P Pending confirmation by cardholder
R Cardholder rejected
U Whitelist status unknown, unavailable, or does not apply

This may be set prior to calling the SendAuthRequest method. In this case, only values of Y or N are valid. This may also be set when the Authentication Response message or Results Request messages are received, and will be set to the values received from the Directory Server.

WhitelistStatusSource:   Whitelist Status Source.

The system setting the Whitelist Status. When setting WhitelistStatus prior to calling the SendAuthRequest method, this should be set to 01. Possible values are:

01 3DS Server
02 DS
03 ACS
04-79 Reserved for EMVCo future use
08-99 Reserved for DS use
XChildCount:   The number of child elements of the current element.

The number of child attributes of the current element. The XChild configuration settings will be indexed from 0 to (XChildCount - 1).

The current element is specified via the XPath configuration setting. This configuration setting is read-only.

XChildName[i]:   The name of the child element.

Provides the name of the i'th child element of the current element.

The current element is specified via the XPath configuration setting. This configuration setting is read-only.

XChildXText[i]:   The inner text of the child element.

Provides the inner text of the i'th child element of the current element.

The current element is specified via the XPath configuration setting. This configuration setting is read-only.

XElement:   The name of the current element.

Provides the name of the current element.

The current element is specified via the XPath configuration setting. This configuration setting is read-only.

XParent:   The parent of the current element.

Provides the parent of the current element.

The current element is specified via the XPath configuration setting. This configuration setting is read-only.

XPath:   Provides a way to point to a specific element in the returned XML or JSON response.

The XPath setting allows you to point to specific elements in the XML or JSON response.

When XPath is set to a valid path, XElement points to the name of the element, with XText, XParent, XSubTree, XChildCount, XChildName[i], and XChildXText[i] providing other properties of the element.

XPath Syntax

XPath syntax is available for both XML and JSON documents. An XPath is a series of one or more element accessors separated by the / character, for example: /A/B/C/D. An XPath can be absolute (i.e., it starts with /), or it can be relative to the current XPath location.

The following are possible values for an element accessor, which operates relative to the current location specified by the XPath accessors which proceed it in the overall XPath string:

Accessor Description
name The first element with a particular name. Can be *.
[i] The i-th element.
name[i] The i-th element with a particular name.
[last()] The last element.
[last()-i] The element i before the last element.
name[@attrname="attrvalue"]The first element with a particular name that contains the specified attribute-value pair.

Supports single and double quotes. (XML Only)

. The current element.
.. The parent element.
Note: XPath indices are 1-based.

XPath Examples

Assuming the following XML response:

<firstlevel>
  <one>value</one>
  <two>
    <item>first</item>
    <item>second</item>
  </two>
  <three>value three</three>
</firstlevel>

Or, alternatively, the following JSON response:

{
  "firstlevel": {
    "one": "value",
    "two": ["first", "second"],
    "three": "value three"
  }
}

Here are some examples of valid XPaths:

DescriptionXML XPath JSON XPath
Document root / /json
Specific element /firstlevel/one /json/firstlevel/one
i-th child /firstlevel/two/item[2]/json/firstlevel/two/[2]

This is not an exhaustive list by any means, but should provide a general idea of the possibilities.

XSubTree:   A snapshot of the current element in the document.

Provides the entirety of the current element (including its sub-elements).

The current element is specified via the XPath configuration setting. This configuration setting is read-only.

XText:   The text of the current element.

Provides the inner text of the current element.

The current element is specified in the XPath configuration setting. This configuration setting is read-only.

SSL Config Settings

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

When SSLProvider is set to Internal, this setting controls whether SSL packets should be logged. By default, this setting is False, as it is only useful for debugging purposes.

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

Enabling this setting has no effect if SSLProvider is set to Platform.

ReuseSSLSession:   Determines if the SSL session is reused.

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

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

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

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

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

SSLCheckCRL:   Whether to check the Certificate Revocation List for the server certificate.

This setting specifies whether the class will check the Certificate Revocation List specified by the server certificate. If set to 1 or 2, the class will first obtain the list of CRL URLs from the server certificate's CRL distribution points extension. The class will then make HTTP requests to each CRL endpoint to check the validity of the server's certificate. If the certificate has been revoked or any other issues are found during validation the class throws an exception.

When set to 0 (default) the CRL check will not be performed by the class. When set to 1, it will attempt to perform the CRL check, but will continue without an error if the server's certificate does not support CRL. When set to 2, it will perform the CRL check and will throw an error if CRL is not supported.

This configuration setting is only supported in the Java, C#, and C++ editions. In the C++ edition, it is only supported on Windows operating systems.

SSLCheckOCSP:   Whether to use OCSP to check the status of the server certificate.

This setting specifies whether the class will use OCSP to check the validity of the server certificate. If set to 1 or 2, the class will first obtain the OCSP URL from the server certificate's OCSP extension. The class will then locate the issuing certificate and make an HTTP request to the OCSP endpoint to check the validity of the server's certificate. If the certificate has been revoked or any other issues are found during validation the class throws an exception.

When set to 0 (default) the class will not perform an OCSP check. When set to 1, it will attempt to perform the OCSP check, but will continue without an error if the server's certificate does not support OCSP. When set to 2, it will perform the OCSP check and will throw an error if OCSP is not supported.

This configuration setting is only supported in the Java, C#, and C++ editions. In the C++ edition, it is only supported on Windows operating systems.

SSLCipherStrength:   The minimum cipher strength used for bulk encryption.

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

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

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

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

SSLContextProtocol:   The protocol used when getting an SSLContext instance.

Possible values are SSL, SSLv2, SSLv3, TLS and TLSv1. Use it only in case your security provider does not support TLS. This is the parameter "protocol" inside the SSLContext.getInstance(protocol) call.

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

The enabled cipher suites to be used in SSL negotiation.

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

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

Multiple cipher suites are separated by semicolons.

Note: This value must be set after SSLProvider is set.

Example values: obj.config("SSLEnabledCipherSuites=*"); obj.config("SSLEnabledCipherSuites=SSL_RSA_WITH_RC4_128_SHA"); obj.config("SSLEnabledCipherSuites=SSL_RSA_WITH_RC4_128_SHA; SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA"); Possible values when SSLProvider is set to latform include:

  • SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
  • SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
  • SSL_RSA_WITH_RC4_128_SHA
  • SSL_RSA_WITH_DES_CBC_SHA
  • SSL_RSA_EXPORT_WITH_DES40_CBC_SHA
  • SSL_DH_anon_WITH_DES_CBC_SHA
  • SSL_RSA_EXPORT_WITH_RC4_40_MD5
  • SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
  • SSL_DH_anon_EXPORT_WITH_RC4_40_MD5
  • SSL_DHE_DSS_WITH_DES_CBC_SHA
  • SSL_RSA_WITH_NULL_MD5
  • SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
  • SSL_DHE_RSA_WITH_DES_CBC_SHA
  • SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA
  • SSL_RSA_WITH_NULL_SHA
  • SSL_DH_anon_WITH_RC4_128_MD5
  • SSL_RSA_WITH_RC4_128_MD5
  • SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
  • SSL_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDH_ECDSA_WITH_NULL_SHA
  • TLS_DH_anon_WITH_AES_128_CBC_SHA256 (Not Recommended)
  • TLS_ECDH_anon_WITH_RC4_128_SHA
  • TLS_DH_anon_WITH_AES_128_CBC_SHA (Not Recommended)
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
  • TLS_KRB5_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
  • TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_KRB5_EXPORT_WITH_RC4_40_SHA
  • TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_RC4_128_SHA
  • TLS_ECDH_ECDSA_WITH_RC4_128_SHA
  • TLS_ECDH_anon_WITH_NULL_SHA
  • TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_RSA_WITH_NULL_SHA256
  • TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA
  • TLS_KRB5_WITH_RC4_128_MD5
  • TLS_ECDHE_ECDSA_WITH_NULL_SHA
  • TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDH_RSA_WITH_RC4_128_SHA
  • TLS_EMPTY_RENEGOTIATION_INFO_SCSV
  • TLS_KRB5_WITH_3DES_EDE_CBC_MD5
  • TLS_KRB5_WITH_RC4_128_SHA
  • TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDH_RSA_WITH_NULL_SHA
  • TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
  • TLS_KRB5_WITH_DES_CBC_MD5
  • TLS_KRB5_EXPORT_WITH_RC4_40_MD5
  • TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5
  • TLS_ECDH_anon_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_KRB5_WITH_DES_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA
  • TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_NULL_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA

Possible values when SSLProvider is set to Internal include:

  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_RSA_WITH_AES_256_GCM_SHA384
  • TLS_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_DSS_WITH_AES_256_GCM_SHA384
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_DSS_WITH_AES_128_GCM_SHA256
  • TLS_DH_RSA_WITH_AES_128_GCM_SHA256 (Not Recommended)
  • TLS_DH_RSA_WITH_AES_256_GCM_SHA384 (Not Recommended)
  • TLS_DH_DSS_WITH_AES_128_GCM_SHA256 (Not Recommended)
  • TLS_DH_DSS_WITH_AES_256_GCM_SHA384 (Not Recommended)
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
  • TLS_RSA_WITH_AES_256_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
  • TLS_RSA_WITH_AES_256_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_ECDH_RSA_WITH_AES_256_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
  • TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
  • TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
  • TLS_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_RSA_WITH_DES_CBC_SHA
  • TLS_DHE_RSA_WITH_DES_CBC_SHA
  • TLS_DHE_DSS_WITH_DES_CBC_SHA
  • TLS_RSA_WITH_RC4_128_MD5
  • TLS_RSA_WITH_RC4_128_SHA

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

  • TLS_AES_256_GCM_SHA384
  • TLS_CHACHA20_POLY1305_SHA256
  • TLS_AES_128_GCM_SHA256

SSLEnabledCipherSuites is used together with SSLCipherStrength.

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

Used to enable/disable the supported security protocols.

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

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

SSLEnabledProtocols - TLS 1.3 Notes

By default when TLS 1.3 is enabled the class will use the internal TLS implementation when the SSLProvider is set to Automatic for all editions.

In editions which are designed to run on Windows SSLProvider can be set to Platform to use the platform implementation instead of the internal implementation. When configured in this manner, please note that the platform provider is only supported on Windows 11 / Windows Server 2022 and up. The default internal provider is available on all platforms and is not restricted to any specific OS version.

If set to 1 (Platform provider) please be aware of the following notes:

  • The platform provider is only available on Windows 11 / Windows Server 2022 and up.
  • SSLEnabledCipherSuites and other similar SSL configuration settings are not supported.
  • If SSLEnabledProtocols includes both TLS 1.3 and TLS 1.2 the above restrictions are still applicable even if TLS 1.2 is negotiated. Enabling TLS 1.3 with the platform provider changes the implementation used for all TLS versions.

SSLEnableRenegotiation:   Whether the renegotiation_info SSL extension is supported.

This setting specifies whether the renegotiation_info SSL extension will be used in the request when using the internal security API. This setting is true by default, but can be set to false to disable the extension.

This setting is only applicable when SSLProvider is set to Internal.

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

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

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

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

SSLKeyLogFile:   The location of a file where per-session secrets are written for debugging purposes.

This setting optionally specifies the full path to a file on disk where per-session secrets are stored for debugging purposes.

When set, the class will save the session secrets in the same format as the SSLKEYLOGFILE environment variable functionality used by most major browsers and tools such as Chrome, Firefox, and cURL. This file can then be used in tools such as Wireshark to decrypt TLS traffice for debugging purposes. When writing to this file the class will only append, it will not overwrite previous values.

Note: This setting is only applicable when SSLProvider is set to Internal.

SSLNegotiatedCipher:   Returns the negotiated cipher suite.

Returns the cipher suite negotiated during the SSL handshake.

Note: For server components (e.g. TCPServer) this is a per-connection setting accessed by passing the ConnectionId. For example: server.Config("SSLNegotiatedCipher[connId]");

SSLNegotiatedCipherStrength:   Returns the negotiated cipher suite strength.

Returns the strength of the cipher suite negotiated during the SSL handshake.

Note: For server components (e.g.TCPServer) this is a per-connection setting accessed by passing the ConnectionId. For example: server.Config("SSLNegotiatedCipherStrength[connId]");

SSLNegotiatedCipherSuite:   Returns the negotiated cipher suite.

Returns the cipher suite negotiated during the SSL handshake represented as a single string.

Note: For server components (e.g. TCPServer) this is a per-connection setting accessed by passing the ConnectionId. For example: server.Config("SSLNegotiatedCipherSuite[connId]");

SSLNegotiatedKeyExchange:   Returns the negotiated key exchange algorithm.

Returns the key exchange algorithm negotiated during the SSL handshake.

Note: For server components (e.g. TCPServer) this is a per-connection setting accessed by passing the ConnectionId. For example: server.Config("SSLNegotiatedKeyExchange[connId]");

SSLNegotiatedKeyExchangeStrength:   Returns the negotiated key exchange algorithm strength.

Returns the strenghth of the key exchange algorithm negotiated during the SSL handshake.

Note: For server components (e.g. TCPServer) this is a per-connection setting accessed by passing the ConnectionId. For example: server.Config("SSLNegotiatedKeyExchangeStrength[connId]");

SSLNegotiatedVersion:   Returns the negotiated protocol version.

Returns the protocol version negotiated during the SSL handshake.

Note: For server components (e.g. TCPServer) this is a per-connection setting accessed by passing the ConnectionId. For example: server.Config("SSLNegotiatedVersion[connId]");

SSLServerCACerts:   A newline separated list of CA certificate to use during SSL server certificate validation.

This setting optionally specifies one or more CA certificates to be used when verifying the server certificate. When verifying the server's certificate the certificates trusted by the system will be used as part of the verification process. If the server's CA certificates are not installed to the trusted system store, they may be specified here so they are included when performing the verification process. This setting should only be set if the server's CA certificates are not already trusted on the system and cannot be installed to the trusted system store.

The value of this setting is a newline (CrLf) separated list of certificates. For instance:

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

SSLTrustManagerFactoryAlgorithm:   The algorithm to be used to create a TrustManager through TrustManagerFactory.

Possible values include SunX509. This is the parameter "algorithm" inside the TrustManagerFactory.getInstance(algorithm) call.

TLS12SignatureAlgorithms:   Defines the allowed TLS 1.2 signature algorithms when SSLProvider is set to Internal.

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

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

The format of this value is a comma separated list of hash-signature combinations. For instance: component.SSLProvider = TCPClientSSLProviders.sslpInternal; component.Config("SSLEnabledProtocols=3072"); //TLS 1.2 component.Config("TLS12SignatureAlgorithms=sha256-rsa,sha256-dsa,sha1-rsa,sha1-dsa"); The default value for this setting is sha512-ecdsa,sha512-rsa,sha512-dsa,sha384-ecdsa,sha384-rsa,sha384-dsa,sha256-ecdsa,sha256-rsa,sha256-dsa,sha224-ecdsa,sha224-rsa,sha224-dsa,sha1-ecdsa,sha1-rsa,sha1-dsa.

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

TLS12SupportedGroups:   The supported groups for ECC.

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

The default value is ecdhe_secp256r1,ecdhe_secp384r1,ecdhe_secp521r1.

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

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

TLS13KeyShareGroups:   The groups for which to pregenerate key shares.

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

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

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

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

The default value is ecdhe_x25519,ecdhe_secp256r1,ecdhe_secp384r1,ffdhe_2048,ffdhe_3072

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

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

TLS13SignatureAlgorithms:   The allowed certificate signature algorithms.

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

  • "ed25519" (default)
  • "ed448" (default)
  • "ecdsa_secp256r1_sha256" (default)
  • "ecdsa_secp384r1_sha384" (default)
  • "ecdsa_secp521r1_sha512" (default)
  • "rsa_pkcs1_sha256" (default)
  • "rsa_pkcs1_sha384" (default)
  • "rsa_pkcs1_sha512" (default)
  • "rsa_pss_sha256" (default)
  • "rsa_pss_sha384" (default)
  • "rsa_pss_sha512" (default)
The default value is rsa_pss_sha256,rsa_pss_sha384,rsa_pss_sha512,rsa_pkcs1_sha256,rsa_pkcs1_sha384,rsa_pkcs1_sha512,ecdsa_secp256r1_sha256,ecdsa_secp384r1_sha384,ecdsa_secp521r1_sha512,ed25519,ed448. This setting is only applicable when SSLEnabledProtocols includes TLS 1.3.
TLS13SupportedGroups:   The supported groups for (EC)DHE key exchange.

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

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

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

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

Trappable Errors (Server Class)

Server Errors

601   Could not create ephemeral key.
602   Invalid certificate.
603   Invalid operation.
604   Invalid ClientAuth data.
605   The errorCode element in Erro message is invalid.
606   Invalid index.
1101   Protocol error. Received invalid message.
1102   Protocol error. Invalid message version.
1201   Protocol error. Missing data element.
1202   Protocol error. Unrecognized critical extension.
1301   Protocol error. Unrecognized transaction Id.
1302   Decryption failed.

HTTP Errors

118   Firewall Error. Error description contains detailed message.
143   Busy executing current method.
151   HTTP protocol error. The error message has the server response.
152   No server specified in URL
153   Specified URLScheme is invalid.
155   Range operation is not supported by server.
156   Invalid cookie index (out of range).
301   Interrupted.
302   Can't open AttachedFile.

TCPClient Errors

100   You cannot change the RemotePort at this time. A connection is in progress.
101   You cannot change the RemoteHost (Server) at this time. A connection is in progress.
102   The RemoteHost address is invalid (0.0.0.0).
104   Already connected. If you want to reconnect, close the current connection first.
106   You cannot change the LocalPort at this time. A connection is in progress.
107   You cannot change the LocalHost at this time. A connection is in progress.
112   You cannot change MaxLineLength at this time. A connection is in progress.
116   RemotePort cannot be zero. Please specify a valid service port number.
117   You cannot change the UseConnection option while the class is active.
135   Operation would block.
201   Timeout.
211   Action impossible in control's present state.
212   Action impossible while not connected.
213   Action impossible while listening.
301   Timeout.
303   Could not open file.
434   Unable to convert string to selected CodePage.
1105   Already connecting. If you want to reconnect, close the current connection first.
1117   You need to connect first.
1119   You cannot change the LocalHost at this time. A connection is in progress.
1120   Connection dropped by remote host.

SSL Errors

270   Cannot load specified security library.
271   Cannot open certificate store.
272   Cannot find specified certificate.
273   Cannot acquire security credentials.
274   Cannot find certificate chain.
275   Cannot verify certificate chain.
276   Error during handshake.
280   Error verifying certificate.
281   Could not find client certificate.
282   Could not find server certificate.
283   Error encrypting data.
284   Error decrypting data.

TCP/IP Errors

10004   [10004] Interrupted system call.
10009   [10009] Bad file number.
10013   [10013] Access denied.
10014   [10014] Bad address.
10022   [10022] Invalid argument.
10024   [10024] Too many open files.
10035   [10035] Operation would block.
10036   [10036] Operation now in progress.
10037   [10037] Operation already in progress.
10038   [10038] Socket operation on non-socket.
10039   [10039] Destination address required.
10040   [10040] Message too long.
10041   [10041] Protocol wrong type for socket.
10042   [10042] Bad protocol option.
10043   [10043] Protocol not supported.
10044   [10044] Socket type not supported.
10045   [10045] Operation not supported on socket.
10046   [10046] Protocol family not supported.
10047   [10047] Address family not supported by protocol family.
10048   [10048] Address already in use.
10049   [10049] Can't assign requested address.
10050   [10050] Network is down.
10051   [10051] Network is unreachable.
10052   [10052] Net dropped connection or reset.
10053   [10053] Software caused connection abort.
10054   [10054] Connection reset by peer.
10055   [10055] No buffer space available.
10056   [10056] Socket is already connected.
10057   [10057] Socket is not connected.
10058   [10058] Can't send after socket shutdown.
10059   [10059] Too many references, can't splice.
10060   [10060] Connection timed out.
10061   [10061] Connection refused.
10062   [10062] Too many levels of symbolic links.
10063   [10063] File name too long.
10064   [10064] Host is down.
10065   [10065] No route to host.
10066   [10066] Directory not empty
10067   [10067] Too many processes.
10068   [10068] Too many users.
10069   [10069] Disc Quota Exceeded.
10070   [10070] Stale NFS file handle.
10071   [10071] Too many levels of remote in path.
10091   [10091] Network subsystem is unavailable.
10092   [10092] WINSOCK DLL Version out of range.
10093   [10093] Winsock not loaded yet.
11001   [11001] Host not found.
11002   [11002] Non-authoritative 'Host not found' (try again or check DNS setup).
11003   [11003] Non-recoverable errors: FORMERR, REFUSED, NOTIMP.
11004   [11004] Valid name, no data record (check DNS setup).