SendAuthRequest Method

Sends the authentication request to the directory server.

Syntax

server.sendAuthRequest([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

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
• DecoupledMaxTimeout
• DecoupledRequestIndicator
• DeviceChannel
• MessageCategory
• PurchaseCurrency
• PurchaseExponent
• ServerOperatorId
• ServerTransactionId
• ShippingAddress*
• ThreeRIIndicator

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 CardRangeMethodURL has been set by the ACS. Card range data may be retrieved by calling RequestCardRanges.

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

If a CardRangeMethodURL 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:

• NotificationURL (required)
• BrowserAcceptHeader (required in 2.1.0 and 2.2.0)
• BrowserLanguage (required in 2.1.0 and 2.2.0)
• BrowserScreenHeight (required in 2.1.0, required in 2.2.0 if BrowserJavaScriptEnabled is true)
• BrowserScreenWidth (required in 2.1.0, required in 2.2.0 if BrowserJavaScriptEnabled is true)
• BrowserTimeZone (required in 2.1.0, required in 2.2.0 if BrowserJavaScriptEnabled is true)
• BrowserUserAgent (required in 2.1.0 and 2.2.0)
• BrowserIPAddress (conditional in 2.1.0 and 2.2.0)
• BrowserJavaEnabledVal (required in 2.1.0, required in 2.2.0 if BrowserJavaScriptEnabled is true)
• BrowserJavaScriptEnabledVal (not valid in 2.1.0, required in 2.2.0)
• BrowserScreenColorDepth (required in 2.1.0, required in 2.2.0 if BrowserJavaScriptEnabled is true)

Response Handling

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

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 or D), 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)
• DecoupledConfirmationIndicator

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.