Getting Started with 3-D Secure 2.0

/n software 3-D Secure is a set of development libraries designed to make implementing support for 3-D Secure 2.0 as simple and quick as possible. 3-D Secure 2.0 offers two primary experiences for the user: browser and mobile. Each environment has specific requirements during processing, and different flows. /n software 3-D Secure provides functionality for both browser based (Server) and mobile based (Client) flows. The following sections provide guidance on how to use the /n software components to support each of the flows defined by 3-D Secure 2.0.

Contents

Caching CardRanges

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 number supported by the ACS and DS, and if one exists, any corresponding Method URL (used in the browser flow).

This is done by sending a Preparation Request Message (PReq) sent by the Server to the DS, which is implemented in the Server component via the RequestCardRanges method.

Results of this method should be cached in order to quickly look up information for subsequent 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. It must be called before any authentication flow is initiated so that the Server has the necessary Protocol Version information and 3DS Method URL (if one exists).

The first time this method is called, SerialNumber will be empty, indicating that all results should be returned. The CardRange event will fire for each result that is returned. Additionally, the results will be held in the CardRanges property.

The following properties are applicable when calling this method:

  • DirectoryServerURL (required) - URL by which to send PReq to DS
  • SerialNumber - include if this is not the first call to the method to return only ranges updated since the last call
  • ServerTransactionId - generated by component if not included
  • ServerOperatorId - set if optionally assigned by DS to 3DS Server

The following properties are populated after calling this method:

  • CardRanges - contains a collection of CardRange objects which contain a range of card numbers from Start to End, and an Action indicating whether the range should be added or deleted from the cache the user is maintaining
  • SerialNumber - indicates to DS the last time the range cache was updated
  • DSTransactionId - assigned by the DS to identify a single transaction

The following is an example of using the RequestCardRanges method:

// No SerialNumber specified; all results will be returned
Server.RequestCardRanges();

// Access results via event (fires once for each CardRange returned)
void server_OnCardRange(Object sender, ServerCardRangeEventArgs e) {
	String Start = e.RangeStart;
	String End = e.RangeEnd;
	String Action = e.RangeAction;
	String ACSStartProtocolVersion = e.ACSStartProtocolVersion;
	String ACSEndProtocolVersion = e.ACSEndProtocolVersion;
	String MethodURL = e.ThreeDSMethodURL;
	
	// ... cache results
}

// Access results via CardRanges property
CardRange FirstRange = Server.CardRanges[0];
String Start = FirstRange.Start;
// ... etc, cache results for all ranges returned

The component will not cache the returned values; it is up to the user to cache these values in an appropriate location. The SerialNumber will be populated after this method returns and should be saved to be used in the next call to this method.

When making subsequent calls to this method, set SerialNumber to the value received from the last response before calling RequestCardRanges. This is an offset the server will use to return only new updates (if any) to the card ranges since the last request.

Browser-Based Authentication

In the browser-based flow, a cardholder initiates a transaction on the merchant's website. Information about the cardholder's browser is collected so the ACS can make a determination when SendAuthRequest is called. In the case a challenge is required, communication between the cardholder and the ACS takes place within the customer's browser and the results are then communicated back to the merchant site.

Pre-Authentication Method Invocation

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

If the CardRanges.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:

  • MethodNotificationURL (required)

This method returns a string which contains encoded data to be sent to the ACS. This included 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 CardRanges.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 component 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.

After calling GetMethodData, a request is made to the CardRanges.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 the CheckResponse method. After calling this method, the following properties are populated:

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

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:

  • AcquirerBIN (required)
  • AcquirerMerchantId (required)
  • BrowserAcceptHeader (required)
  • BrowserLanguage (required)
  • BrowserScreenHeight (required)
  • BrowserScreenWidth (required)
  • BrowserTimeZone (required)
  • BrowserUserAgent (required)
  • CardholderName (required)
  • CardNumber (required)
  • DirectoryServerURL (required)
  • MerchantCategoryCode (required)
  • MerchantCountryCode (required)
  • MerchantName (required)
  • NotificationURL (required)
  • PurchaseAmount (required)
  • PurchaseDate (required)
  • RequestorId (required)
  • RequestorName (required)
  • RequestorURL (required)
  • ResultsURL (required)
  • AccountType
  • AuthenticationIndicator
  • BillingAddress
  • BrowserIPAddress
  • BrowserJavaEnabled
  • BrowserUserAgent
  • BrowserScreenColorDepth
  • CardholderEmail
  • CardholderHomePhone
  • CardholderMobilePhone
  • CardholderWorkPhone
  • DeviceChannel
  • MessageCategory
  • PurchaseCurrency
  • PurchaseExponent
  • ServerOperatorId
  • ServerTransactionId
  • ShippingAddress
  • ThreeRIIndicator

SendAuthRequest Example:

// Assign mandatory known values
server.RequestorId = "az0123456789"; // assigned by DS
server.RequestorName = "Example Requestor name"; // assigned by DS 
server.RequestorURL = "https://threedsrequestor.adomainname.net"; // URL of merchant site
server.AcquirerBIN = "868491"; // assigned by Acquirer
server.AcquirerMerchantId = "mGm6AJZ1YotkJJmOk0fx"; // assigned by Acquirer
server.MerchantName = "Example Merchant Name"; // assigned by Acquirer
server.MerchantCategoryCode = "5411"; // defined by DS
server.MerchantCountryCode = "840"; // defined in ISO 8583

// Browser Information
server.BrowserAcceptHeader = BrowserAcceptHeader;
server.BrowserScreenColorDepth = BrowserScreenColorDepth;
server.BrowserIPAddress = BrowserIPAddress;
server.BrowserJavaEnabled = BrowserJavaEnabled;
server.BrowserLanguage = BrowserLanguage;
server.BrowserScreenHeight = BrowserScreenHeight;
server.BrowserScreenWidth = BrowserScreenWidth;
server.BrowserTimeZone = BrowserTimeZone;
server.BrowserUserAgent = BrowserUserAgent;
server.NotificationURL = NotificationURL;

// Cardholder Information
server.CardExpiryDate = "1910";
server.CardNumber = "8944988785642183";
server.CardholderName = "John Doe";
server.BillingAddress.City = "Bill City Name"; 
server.BillingAddress.Line1 = "123 Fake St.";
server.BillingAddress.State = "CA";
server.BillingAddress.PostalCode = "90210";
server.BillingAddress.Country = "840"; // ISO 3166-1
// ... See documentation for additional cardholder properties

// Purchase Information
server.PurchaseAmount = "1000"; // Decimal is implied, this is $10.00
server.PurchaseCurrency = "840"; // USD
server.PurchaseExponent = "2"; // 2 decimal places
server.PurchaseDate = "20170316141312"; // YYYYMMDDHHmmSS

// Required URLs
server.ResultsURL = "https://threedsserver.adomainname.net"; // URL on merchant site where results will be posted
server.NotificationURL = "https://threesserver.adomainname.net/Notifications"; // Receives notification when challenge is complete
server.DirectoryServerURL = "https://directoryserver";

server.SendAuthRequest();

Authentication Response Handling

After calling SendAuthRequest, 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

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), 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:

  • AuthenticationECI
  • AuthenticationValue
  • TransactionStatus
  • TransactionStatusReason
  • CardholderInformation
  • ACSURL (if challenge required)
  • ACSChallengeMandatedIndicator (if challenge required)
  • AuthenticationType (if challenge required)

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 NotificationURL value that was specified when calling SendAuthRequest.

Challenge Interaction

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 also 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

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

Server Side Results Notification

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. Pass the body of the HTTP request received at ResultsURL to the CheckResponse 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:

  • AuthenticationECI
  • TransactionStatus
  • TransactionStatusReason
  • ChallengeCancellationIndicator
  • AuthenticationType
  • AuthenticationValue

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 for ResultsStatus 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 your 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

Final Challenge Response

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:

  • ServerTransactionId
  • TransactionStatus

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.

App-Based Authentication

In the app-based flow, a cardholder initiates a transaction on a mobile device (Android or iOS) from a 3DS-enabled app (the 3DS Requestor App).

The Client component of /n software 3-D Secure implements the protocol specific functionality to format requests, parse responses, communicate with the ACS as necessary, and providing all required security functionality.

The user of the component must still gather all required device parameters before sending the authentication request. The user is also responsible for creating a UI to interact with the cardholder that adheres to the requirements outlined in the EMVCo 3-D Secure specification.

The design of the app-based authentication is to gather data on the mobile device, and transmit it to a merchant controlled server where an authentication request is made. In the components, this is done by preparing data in the Client component and transmitting it via some channel to the Server component for submission to the Directory Server. The creation and usage of the communication channel between the app on the mobile device and the merchant's server is outside the scope of the components.

Preparing the Authentication Request

To begin, device specific information must be collected and prepared for transmission to the directory server. This can be done by calling the AddDeviceParam method. Consult the EMVCo 3-D Secure Specifications for more details about applicable device parameters for your particular operating system.

Device Params Example:

client = new Client();

// add device parameters based on information from device, for example:

// four categories of device information parameters
const int DEVICE_PARAM_CATEGOTY_DV = 0; // Data Version
const int DEVICE_PARAM_CATEGORY_DD = 1; // Device Data
const int DEVICE_PARAM_CATEGORY_DPNA = 2; // Device Parameter Not Available
const int DEVICE_PARAM_CATEGORY_SW = 3; // Security Warning

// platform-common ("Cxxx") device parameters
client.AddDeviceParam("DV", "1.1", DEVICE_PARAM_CATEGORY_DV); // data version
client.AddDeviceParam("C001", Platform, DEVICE_PARAM_CATEGORY_DD); // platform ("Android", "iOS", or "Windows 10 Mobile")
client.AddDeviceParam("C002", DeviceModel, DEVICE_PARAM_CATEGORY_DD); // device model; DeviceModel set based on platform-specific method of determining model (such as Build.Model in Android)
client.AddDeviceParam("C003", OSName, DEVICE_PARAM_CATEGORY_DD); // OS name; OSName set based on platform-specific method of determining name of operating system
client.AddDeviceParam("C004", OSVersion, DEVICE_PARAM_CATEGORY_DD); // OS version; OSVersion set based on platform-specfic method of determining OS version
// ... continue setting platform-common device parameters
client.AddDeviceParam("C011", "RE03", DEVICE_PARAM_CATEGORY_DPNA); // latitude; Reason for parameter Unavailability Code "RE03" indicates that collection of the parameter is not possible without prompting the user for permission (such as location permissions being required for latitude)
client.AddDeviceParam("C012", "RE03", DEVICE_PARAM_CATEGORY_DPNA); // longitute; see latitude

// platform-specific device parameters
client.AddDeviceParam("A001", TelephonyManagerDeviceId, DEVICE_PARAM_CATEGORY_DD); // Android-ONLY example ("Axxx"); Telephony Manager provides access to information about telephony services on the device and is used to access DeviceId (unique device identity such as IMEI, MEID or ESN)
client.AddDeviceParam("I001", UIDeviceVendorIdentifier, DEVICE_PARAM_CATEGORY_DD); // iOS-ONLY example ("Ixxx"); UIDevice provides a singleton instance representing the current device and is used access Identifier For Vendor
client.AddDeviceParam("W001", GlobalizationPreferencesCalendars, DEVICE_PARAM_CATEGORY_DD) // Windows 10 Mobile-ONLY example ("Wxxx"); GlobalizationPreferences is used to obtain such preferences for the user, such as Calendars, the set of user-preferred calendars
// ... continue setting platform-specific device parameters

After collecting the device parameters, the GetAuthRequest method is used to obtain the request message to be send to the directory server. GetAuthRequest encrypts the device info and prepares all the data necessary to be sent by the Server component in the SendAuthRequest method.

After calling this method, the returned data must be transmitted via a separate secure channel to the server where Server is being used.

The following properties are required before calling the method:

PropertyDescription
DeviceParams Contains device information parameters. Add parameters via AddDeviceParam.
DirectoryServerCert Used to encrypt the device parameters.
DirectoryServerId Identifies the DirectoryServerCert within the directory server.
SDKAppId A UUID for the specific installation.
SDKReferenceNumber An Id assigned by EMVCo to identify the vendor and software version.

Calling this method returns required information used by Server to send the authentication request. Transmit the value returned by this method to the system where Server is used. The method used to transmit this value is outside the scope of the component.

See the documentation for the SendAuthRequest method for details on sending the authentication request after transmitting the data to Server.

Calling this method also populates SDKTransactionId, which uniquely identifies this transaction and must be used in subsequent calls relating to this transaction, such as SendChallengeRequest.

GetAuthRequest Example:

client.SDKAppId = SDKAppId;
client.SDKReferenceNumber = SDKReferenceNumber;
client.DirectoryServerId = DirectoryServerId; 
client.DSCert = DirectoryServerCert;

String clientAuthRequest = client.GetAuthRequest(); 

//Transmit clientAuthRequest to the Server component via a secure channel

Interaction With the Server Component

As mentioned above, the request to the Directory Server must be made by the Server component which resides on a server under control of the merchant. A web server is required even for app-based authentication both to send the authentication request and to be notified of authentication results later in the flow.

It is expected that a secure channel can be established between the app using the Client component and the server where the Server component resides in order to transfer information freely.

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:

  • AcquirerBIN (required)
  • AcquirerMerchantId (required)
  • CardholderName (required)
  • CardNumber (required)
  • DirectoryServerURL (required)
  • MerchantCategoryCode (required)
  • MerchantCountryCode (required)
  • MerchantName (required)
  • PurchaseAmount (required)
  • PurchaseDate (required)
  • RequestorId (required)
  • RequestorName (required)
  • RequestorURL (required)
  • ResultsURL (required)
  • AccountType
  • AuthenticationIndicator
  • BillingAddress
  • CardholderEmail
  • CardholderHomePhone
  • CardholderMobilePhone
  • CardholderWorkPhone
  • DeviceChannel
  • MessageCategory
  • PurchaseCurrency
  • PurchaseExponent
  • ServerOperatorId
  • ServerTransactionId
  • ShippingAddress
  • ThreeRIIndicator

In the app-based flow, device specific information is prepared by the Client component on the customer's device. The Client's GetAuthRequest method returns a string that should be transmitted to the Server component. Set ClientAuthRequest to this data prepared by the Client component.

SendAuthRequest Example:

// ClientAuthRequest was received from Client via secure channel
server.ClientAuthRequest = ClientAuthRequest;

// Assign mandatory known values
server.RequestorId = "az0123456789"; // assigned by DS
server.RequestorName = "Example Requestor name"; // assigned by DS 
server.RequestorURL = "https://threedsrequestor.adomainname.net"; // URL of merchant site
server.AcquirerBIN = "868491"; // assigned by Acquirer
server.AcquirerMerchantId = "mGm6AJZ1YotkJJmOk0fx"; // assigned by Acquirer
server.MerchantName = "Example Merchant Name"; // assigned by Acquirer
server.MerchantCategoryCode = "5411"; // defined by DS
server.MerchantCountryCode = "840"; // defined in ISO 8583


// Cardholder Information
server.CardExpiryDate = "1910";
server.CardNumber = "8944988785642183";
server.CardholderName = "John Doe";
server.BillingAddress.City = "Bill City Name"; 
server.BillingAddress.Line1 = "123 Fake St.";
server.BillingAddress.State = "CA";
server.BillingAddress.PostalCode = "90210";
server.BillingAddress.Country = "840"; // ISO 3166-1
// ... See documentation for additional cardholder properties

// Purchase Information
server.PurchaseAmount = "1000"; // Decimal is implied, this is $10.00
server.PurchaseCurrency = "840"; // USD
server.PurchaseExponent = "2"; // 2 decimal places
server.PurchaseDate = "20170316141312"; // YYYYMMDDHHmmSS

// Required URLs
server.ResultsURL = "https://threedsserver.adomainname.net"; // URL on merchant site where results will be posted
server.DirectoryServerURL = "https://directoryserver";

server.SendAuthRequest();

Authentication Response Handling

After calling SendAuthRequest 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

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), 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:

  • AuthenticationECI
  • AuthenticationValue
  • TransactionStatus
  • TransactionStatusReason
  • CardholderInformation
  • ACSURL (if challenge required)
  • ACSChallengeMandatedIndicator (if challenge required)
  • AuthenticationType (if challenge required)

ClientAuthResponse is populated with data to be transmitted back to the Client component.

Note: The TransactionStatus is also populated in the Server component and may be inspected prior to transmitting ClientAuthResponse back to the Client component.

After the response to the authentication request is send from the Server component to the Client, call CheckAuthResponse on the Client to verify and parse the response.

Before calling this method, ACSRootCerts must be populated with the root certificates used by the ACS to sign the response. This method will validate the signature of the signed content, if present.

After calling this method, inspect TransactionStatus to determine if the transaction requires a challenge. If TransactionStatus is C, a challenge is required and SendChallengeRequest should be called to proceed with the challenge flow.

If TransactionStatus is Y or A, the transaction is complete.

Challenge Interaction

SendChallengeRequest sends the Challenge Request to the ACS when a challenge is required.

When the TransactionStatus is C after calling CheckAuthResponse, a challenge to the cardholder is required. This method sends the challenge request and parses the response. The ACS may provide multiple challenges to the cardholder during this process. As a result this method may need to be called multiple times throughout the authentication process.

After this method is called, check ChallengeComplete to determine if the challenge process is complete. If it is complete (True), check TransactionStatus to determine the outcome. If ChallengeComplete is False, additional challenge interaction is required.

First Request

The first time this method is called, information about the required challenge is obtained from the ACS. The ACS connection information is automatically set when CheckAuthResponse is called; there is no need to specify any ACS connection information.

All required properties for the first call to this method are automatically set after CheckAuthResponse is called. If the transaction has been canceled, set ChallengeCancellationIndicator to inform the ACS.

After calling this method, the ACS will respond with details about the challenge to be presented to the cardholder. The ACSUIType property indicates the way the ACS will interact with the cardholder. The ChallengeComplete property will be False after the first call to this method since the challenge interaction is not yet complete.

The following properties are applicable when ACSUIType is Text (01), Single-Select (02), or Multi-Select (03):

  • ChallengeSelectInfo
  • ChallengeInfoHeader
  • ChallengeInfoLabel
  • ChallengeInfoText
  • ChallengeInfoTextIndicator
  • ExpandableInformationLabel
  • ExpandableInformationText
  • IssuerImageExtraHigh
  • IssuerImageHigh
  • IssuerImageMedium
  • PaymentSystemImageExtraHigh
  • PaymentSystemImageHigh
  • PaymentSystemImageMedium
  • ResendInformationLabel
  • SubmitAuthenticationLabel
  • WhyInformationLabel
  • WhyInformationText

Use the values in the above properties to populate values in the native UI in the app. The UI must follow the guidelines defined in the EMVCo 3-D Secure specification.

The following properties are applicable when ACSUIType is Out-of-Band (04):

  • ChallengeAdditionalInformation
  • ChallengeInfoHeader
  • ChallengeInfoLabel
  • ChallengeInfoText
  • ChallengeInfoTextIndicator
  • ExpandableInformationLabel
  • ExpandableInformationText
  • IssuerImageExtraHigh
  • IssuerImageHigh
  • IssuerImageMedium
  • OOBContinueLabel
  • PaymentSystemImageExtraHigh
  • PaymentSystemImageHigh
  • PaymentSystemImageMedium
  • ResendInformationLabel
  • WhyInformationLabel
  • WhyInformationText

Use the values in the above properties to populate values in the native UI in the app. The UI must follow the guidelines defined in the EMVCo 3-D Secure specification.

The following properties are applicable when ACSUIType is HTML (05):

  • ACSHTML
  • ACSHTMLRefresh

In the case of an HTML interaction, the app should create a webview and populate this with the HTML in ACSHTML.

As per the EMVCo 3-D Secure specification, the HTML UI is presented to the cardholder via a web view which remains in control of the app. The app must intercept any remote URL requests made from within the web view, and instead handle them within the app. Preventing the cardholder from making requests in the web view to another server is critical to the security of the environment. According to the EMVCo specification, intercepting these requests has two effects:

  • Prevents malicious HTML from redirecting a user to a phishing site.
  • Conceptually puts the web view form under the control of the ACS, rather than the app.

The following are key points mentioned in the EMVCo 3-D Secure specification:

  • Navigation attempts from within the web view must be captured by the app and handled internally. This includes all requests including images, javascript files, css, etc.
  • The web view element is not utilized as a browser, but as a UI element whose content is provided by the ACS.

Please refer to the EMVCo 3-D Secure specification for more details and guidance on this topic. This information is not meant to replace the text in the EMVCo 3-D Secure specification.

Second Request

The second time this method is called, the purpose is to provide a response to the ACS. At this point the customer should have responded to the challenge provided by the ACS in the response to the first call. If the transaction has been canceled, set ChallengeCancellationIndicator to inform the ACS. The following properties are applicable when calling this method the second time:

  • ChallengeDataEntry
  • OOBContinuationIndicator

When ACSUIType is Text (01) or HTML (05), set ChallengeDataEntry to the data exactly as it was specified by the cardholder. Do not format or otherwise change the data.

When ACSUIType is Single-Select (02), set ChallengeDataEntry to the name of the selected option. For instance the ACS may provide the user with a selection like:

mobile: **** **** 329
email: s******k**@g***.com
The value to provide in ChallengeDataEntry is the ChallengeSelectInfo.Name, i.e. mobile.

When ACSUIType is Multi-Select (03), set ChallengeDataEntry to a comma-separated list of names of the selected options. For instance if ChallengeSelectInfo contains elements with names like chicago_illinois, st_louis_missouri, and portland_oregon, and the user chose two options, the value specified in ChallengeDataEntry would be chicago_illinois,portland_oregon.

When ACSUIType is OOB (04), set OOBContinuationIndicator to True to indicate the cardholder has pressed the button signaling their completing of the OOB process.

Completing the Challenge

After calling SendChallengeRequest a second time with the cardholder's responses, the ACS may require additional challenges. Check the ChallengeComplete property to determine if the challenge is complete. If False, more challenges are required by the ACS and the same process of displaying the challenge info, collecting the response, and submitting it to the ACS should be performed again.

If ChallengeComplete is True, the challenge interaction is complete and TransactionStatus can be inspected to determine whether the transaction was successful.

Server Side Results Notification

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. Pass the body of the HTTP request received at ResultsURL to the CheckResponse 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:

  • AuthenticationECI
  • TransactionStatus
  • TransactionStatusReason
  • ChallengeCancellationIndicator
  • AuthenticationType
  • AuthenticationValue

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 for ResultsStatus 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 your 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

Additional Functionality

The components provide a number of methods and settings designed to make the process of integrating support for 3-D Secure 2.0 as easy as possible. Below are some of the additional features offered by the components.

Resetting Transaction Info

ResetTransactionInfo must be called between transactions when using the same component 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.

See the documentation for a complete list of values that are reset.

Logging with Server and Client

The Server and Client components each have Log events that fire for various occurrences. Anytime a message is built or a response is parsed (including Error Messages), the Log event is fired and the message is available in the Message event argument. Properties such as EphemeralKey and DeviceParams are also available when they are gathered by the Client. The other event arguments are LogLevel and LogType.

LogLevel indicates the level of the message. Possible values are 0 (None), 1 (Info - default), 2 (Verbose), and 3 (Debug).

LogType identifies the type of log entry. Possible values include types corresponding to the message or property being logged, such as "AReq", "ARes", "CReq", "CRes", "RReq", "RRes", "PReq", "PRes", "Erro", "EphemeralKey" and "DeviceParams".

The following code example demonstrates how information about messages and properties may be gathered using the Log event:

void server_OnLog(Object sender, ServerLogEventArgs e)
{
	String message;
	if(e.LogType=="AReq")
	{
		// logged when AReq built by server.SendAuthRequest()
		message = e.Message;
	} else if(e.LogType=="ARes")
	{
		// logged when ARes received and parsed after calling server.SendAuthRequest();
		message = e.Message;
	}
}

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 event argument DataPacket. This parameter may be inspected for advanced troubleshooting, or to extract additional response properties beyond the scope of this component. For example:

void server_OnDataPacketIn(Object sender, ServerDataPacketInEventArgs e)
{
	String dataPacket = e.DataPacket;
	// note: the event fires before the component parses the data, so accessing Server properties populated during parsing is not available
}
void server_OnDataPacketOut(Object sender, ServerDataPacketOutEventArgs e)
{
	String dataPacket = e.DataPacket;
}


We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.