SendChallengeRequest Method

Builds and sends the Challenge Request in an app-based challenge flow.

Syntax

client.sendChallengeRequest([callback])

Callback

The 'callback' parameter specifies a function which will be called when the operation completes (or an error is encountered). If the 'callback' parameter is not specified, then the method will block and will not return until the operation completes (or an error is encountered).

The callback for this method is defined as:

function(err){ }

'err' is the error that occurred. If there was no error, then 'err' is 'null'.

'err' has 2 properties which hold detailed information:

err.code
err.message

Remarks

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 EMV 3DS 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 EMV 3DS 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 EMV® 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 EMV 3DS 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 EMV 3DS specification for more details and guidance on this topic. This information is not meant to replace the text in the EMV 3DS 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 ChallengeSelectInfoName, 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.

Note: As part of the challenge completion the ACS also notifies the 3DS Server of the results. This is done by posting the results to the URL defined by the ResultsURL property of the 3DS Server class.