Using the Toolkit Workflow of the Web SDK

On this page:

In the toolkit workflow of the Web SDK, you can call individual methods, and based on the response of the earlier method, you can call the next method.

Toolkit workflow has following methods that you can use as required:

Toolkit workflow has the following utility that you can use as required:

getBrowserInfo()

To test individual API calls, Elavon recommends that you run them in the following order: lookup(), deviceFingerprint(), authenticate(), and challenge(), if required. Review the following information before you make these calls:

If you don’t want to check the 3D Secure version the card supports, you can skip the lookup() method. If you skip the lookup() method, you cannot call the deviceFingerprint() method too because the request parameters depend on some response parameters of the lookup() method.
deviceFingerprint() is also an optional method, but in a production scenario, the device data fetched through this method provides additional contextual information to the issuer, which increases the chances of a frictionless authentication.
You must run the authenticate() method before the challenge() method. The request parameters of the challenge() method depend on some response parameters returned in the authenticate() method.

You can try the Web SDK demo application to understand more about these flows.

Initializing the Web SDK

To use any method in the toolkit workflow, you must initialize an authenticated instance of the Web SDK object.

Use the following URL to make the API requests:

Test environment: https://uat.gw.fraud.eu.elavonaws.com/3ds2/Link opens new window
Production environment: https://gw.fraud.elavon.com/3ds2/Link opens new window

The Web SDK also needs a token to communicate with the 3DS Server. For steps to get a token, see the Authentication topic.

Create an instance of the SDK using the base URL.

const sdk = new window.Elavon3DSWebSDK({
  baseUrl: 'https://uat.gw.fraud.eu.elavonaws.com/3ds2',
  token: 'eyJh...5QE1Q'});

sdk.lookup()

After setting up your credentials in the Web SDK, call the sdk.lookup() method. This method checks if the card used in the transaction supports 3D Secure.

lookup() sample request

{
    "messageId": "TEST-MSG_ID",		    //Optional. Unique message identifier assigned by client.
    "acctNumber": "4017730000000005",	   //Required. Account number/PAN of the card used for the transaction.
    "doBinLookup": true,		     //Optional. Set the value to true to retrieve additional details about the card.
    "clientStartProtocolVersion": "2.1.0",   //Optional. The earliest (i.e. oldest) active 3DS protocol version that is supported by the client. Valid values are 2.1.0 or 2.2.0. The default value is 2.1.0. See the 3DS Server Fallback decision matrix table in the Web SDK Overview topic for a list of possible fallback scenarios.
    "clientEndProtocolVersion": "2.2.0"   //Optional. The most recent active 3DS protocol version the client supports. Valid values are 2.1.0 or 2.2.0. The default value is 2.1.0. If this field is set to 2.2.0, the server first checks for 3DS 2.2 support. If 3DS 2.2 is not supported, then it checks for 3DS 2.1 support. 
}

For a detailed description of each parameter, see the Lookup parameters description

The sdk.lookup() method returns a promise. The response returns the threeDSServerTransId, threeDSMethodURL, and threeDSMethodData values. The SDK uses these values for device fingerprinting.

note

The SDK performs device fingerprinting only for transactions that support 3D Secure 2.

3DS 2 - lookup() Sample response

{
  "transactionId": "26002b7b-6a05-4c8b-9bae-50d4caf3f6d8",   //Unique ID of the transaction.
  "threeDSServerTransID": "26002b7b-6a05-4c8b-9bae-50d4caf3f6d8",   //Unique ID assigned by the 3DS Server to identify a single transaction.
  "dsStartProtocolVersion": "2.1.0",    // The earliest (i.e. oldest) active protocol version that is supported by the DS.
  "dsEndProtocolVersion": "2.2.0",    // The most recent active protocol version that is supported for the DS.
  "acsStartProtocolVersion": "2.1.0",     // The earliest (i.e. oldest) active protocol version that is supported by the ACS.
  "acsEndProtocolVersion": "2.1.0",   // The most recent active protocol version that is supported for the ACS URL.
  "serverStartProtocolVersion": "2.1.0",  // The earliest (i.e. oldest) active 3DS protocol version that is supported by the 3DS Server. 
  "serverEndProtocolVersion": "2.2.0",   // The most recent active 3DS protocol version that is supported by the 3DS Server.
  "threeDSMethodURL": "https://uat.gw.fraud.eu.elavonaws.com/acs/method/VISA?len=16",   //The ACS URL that is used by the 3DS Method.
  "threeDSMethodData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9kZXYuZ3cuZnJhdWQuZXUuZWxhdm9uYXdzLmNvbS9ub3RpZnkvbWV0aG9kX25vdGlmeSIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiMjYwMDJiN2ItNmEwNS00YzhiLTliYWUtNTBkNGNhZjNmNmQ4In0=",   //Conditional. Data elements sent in the threeDSMethodData field.
  "acsInfoInd": [ "01", "02", "03", "04" ],     // ACS Information Indicator. The 3DS Server uses the data in this field to identify the features that the Account Range supports. It lists all applicable values for the card range. Valid values: 01 = Authentication Available at ACS; 02 = Attempts Supported by ACS or DS; 03 = Decoupled Authentication Supported; 04 = Whitelisting Supported. 
  "binInfo":       // Optional. Additional information about the card used in the transaction retrieved from an internal repository.
  {
    "bin": "401773",    // Issuer bank identification number. Usually the initial four, six, or more digits that appear on a card.
      "scheme": "Visa",    // Card scheme. Payment network linked to payment cards. 
      "brand": "Visa Electron",       // Card brand. To distinguish different brands of the same card scheme. 
      "fundingSource": "prepaid",       // Card funding source.
      "issuingBank": "GVS PREPAID LIMITED",         // Issuing bank of the card.
      "issuingCountry": "IRL",       // Issuing country code as an ISO 3166-1 three-character alpha code.    
      "issuingCurrency": "EUR",       // Issuing country currency as an ISO 4217 three-character alpha code. 
      "isDebit": "true",         // If the card is a debit card. 
      "isCorporate": "false",        // Indicates the customer type of the card. 
      "isDccAllowed": "true"         // If DCC (dynamic currency conversion) is allowed for the card. Note: This parameter will only be true if the card belongs to a Visa or a MasterCard scheme.
  }
}

For a detailed description of each parameter, see the Lookup parameters description

3DS 2 - lookup() example

const lookupresponse = await sdk.lookup({ 
  "messageId": "TEST-MSG_ID", "acctNumber": "4017730000000005", "doBinLookup": true, "clientStartProtocolVersion": "2.2.0", "clientEndProtocolVersion": "2.2.0"});

sdk.deviceFingerprint()

After the sdk.lookup() method, call the sdk.deviceFingerprint() method. This method helps to identify the device from which a request is sent to the 3DS Server. This method is optional; however, it provides extra information to the issuer to decide whether the issuer should challenge the user.

Internally, the sdk.deviceFingerprint() method will add an invisible iframe, submit the request, and remove the iframe after a response is received. You will receive a response with an object with a success property and a value of true or an error message.

3DS 2 - deviceFingerprint() sample request

{
  "threeDSMethodURL": "https://uat.acs.fraud.eu.elavonaws.com/acs/method/VISA",         //The ACS URL that is used by the 3DS Method. This value is populated by the threeDSMethodURL value received in the lookup response.
  "threeDSMethodData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cDovL2MyLWRldi1leHRlcm5hbC02NTY0ZDVlZDA2MjFjZjk0LmVsYi5ldS13ZXN0LTEuYW1hem9uYXdzLmNvbToxMDg1MC9ub3RpZnkvbWV0aG9kX25vdGlmeSIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiMTAyZjhmNmUtODQ3Mi00YWRhLThkZWItOTFkNWJkNTFkZTkwIn0="    //The value is populated by the Base 64 encoded data value received in the lookup response.
}

3DS 2 - deviceFingerprint() sample response

{ 
  "success": true 			//  true if the device fingerprinting was successful; otherwise, returns an error.
}

note

The deviceFingerprint response will return either a value of true or an error message. Even if you receive an error in the deviceFingerprint response, Elavon suggests that you can proceed with the 3DS authentication process. Sometimes, the error could be a result of a network issue.

deviceFingerprint() example

const fingerprintResponse = await sdk.deviceFingerprint({ 
      "threeDSMethodURL": versionResponse.threeDSMethodURL,
      "threeDSMethodData": versionResponse.threeDSMethodData 
  });
if  (fingerprintResponse.success) {
    // success
}

sdk.authenticate()

authenticate() sample request

After the device fingerprinting is complete, call the sdk.authenticate() method to submit a request to the authenticate payment method.

note

The Web SDK appends the required browser information to the request if it is not added in the initial request.

authenticate() sample request showing only required parameters

{
  "purchaseAmount": "200",			    // Purchase amount in minor units of currency with all punctuation removed.
  "purchaseCurrency": "840",		     // ISO-4217 three-digit numeric currency code.
  "purchaseExponent": "2", 			    // Minor units of currency as specified in the ISO-4217 currency exponent. For example, 2 for USD, 0 for Yen, etc. 
  "purchaseDate": "20170316141312",            // Purchase date and time expressed in UTC. 
  "cardholderName": "Cardholder Name",             // Name of the cardholder.
  "acctNumber": "4017730000000005",	          // Account number/PAN of the card used in the transaction.
  "cardExpiryDate": "YYMM",		      // Expiration date of the card used in the transaction.
  "transType": "01",            // Identifies the type of transaction being authenticated.
  "threeDSRequestorAuthenticationInd": "01",      // Indicates type of transaction request.
  "acquirerBin": "761018452",    // Conditional. Acquiring institution identification code as assigned by the DS receiving the AReq message. Required only if you are sending the request for a service provider merchant (a merchant not acquired by Elavon). For other merchants, the 3DS Server auto-populates and appends the field value in the authentication request it sends to the ACS (issuer).
  "acquirerMerchantID": "445842",    //Conditional. Acquirer-assigned Merchant identifier. Required only if you are sending the request for a service provider merchant (a merchant not acquired by Elavon). For other merchants, the 3DS Server auto-populates and appends the field value in the authentication request it sends to the ACS (issuer).
  "threeDSRequestorID": "1002475300000000080340007",    // Conditional. DS assigned 3DS Requestor identifier. Required only if you are sending the request for a service provider merchant (a merchant not acquired by Elavon). For other merchants, the 3DS Server auto-populates and appends the field value in the authentication request it sends to the ACS (issuer). Required only for 3DS 2.1/2.2 transactions.
  "threeDSRequestorName": "Test007"    //Conditional. DS assigned 3DS Requestor name. Required only if you are sending the request for a service provider merchant (a merchant not acquired by Elavon). For other merchants, the 3DS Server auto-populates and appends the field value in the authentication request it sends to the ACS (issuer). Required only for 3DS 2.1/2.2 transactions.
}

For a detailed description of each parameter, see the Authentication parameters description

For more details about service provider merchants, see 3D Secure 2 for merchants who do not process payments with Elavon

note

To improve the chance of successful authentication, include all required and optional parameters in the authentication request.

authenticate() sample request showing all parameters either required or optional

{
  "messageId": "TEST-MESSAGE-ID",	         // Optional. Unique message identifier assigned by client.
  "threeDSServerTransId": "102f8f6e-8472-4ada-8deb-91d5bd51de90",	   // Optional. Unique ID assigned by the 3DS Server to identify a single transaction. The value of this field must be same as the value returned in the lookup response.
  "purchaseAmount": "200",			// Required. Purchase amount in minor units of currency with all punctuation removed. 
  "purchaseCurrency": "840",		     // Required. ISO 4217 three-digit currency code of the currency used in the transaction. For example, 840 for USD, 972 for Euro, 392 for Yen, etc. 
  "purchaseExponent": "2", 		 // Required. ISO-4217 currency exponent. For example, 2 for USD, 0 for Yen,etc. 
  "purchaseDate": "20170316141312",            // Purchase date and time expressed in UTC. 
  "cardholderName": "Cardholder Name",       // Required. Name of the cardholder.
  "acctNumber": "4017730000000005",      // Required. Account number/PAN of the card used in the transaction.
  "cardExpiryDate": "YYMM",	      // Required. Expiration date of the card used in the transaction.
  "shipAddrLine1": "Address Line 1",        // Conditional. Address line 1 of the shipping address.
  "shipAddrLine2": "Address Line 2",        // Conditional. Address line 2 of the shipping address.
  "shipAddrLine3": "Address Line 3",        // Conditional. Address line 3 of the shipping address.
  "shipAddrCity": "Atlanta",			  // Conditional. City of the shipping address.
  "shipAddrState": "GA",       // Conditional. State of the shipping address. Should be the country subdivision code defined in ISO 3166-2.
  "shipAddrPostCode": "30303",        // Conditional. Postal code of the shipping address.
  "shipCountry": "840",			  // Conditional. Country of the shipping address. Shall be the ISO 3166-1 numeric three-digit country code.
  "billAddrLine1": "Address Line 1",       // Conditional. Address line 1 of the billing address. Required (if available) unless market or regional mandate restricts sending this information.
  "billAddrLine2": "Address Line 2",       // Conditional. Address line 2 of the billing address. Required (if available) unless market or regional mandate restricts sending this information.
  "billAddrLine3": "Address Line 3",       // Conditional. Address line 3 of the billing address. Required (if available) unless market or regional mandate restricts sending this information.
  "billAddrCity": "Athens",			 // Conditional. City of the billing address.
  "billAddrState": "GA",		   // Conditional. State of the billing address. Should be the country subdivision code defined in ISO 3166-2.
  "billAddrPostCode": "30603",	    // Conditional. Postal code of the billing address.
  "billAddrCountry": "840",	       // Conditional. Country of the billing address. Shall be the ISO 3166-1 numeric three-digit country code.
  "homePhone": {			  // Conditional. Refer to ITU-E.164 for additional information on format and length.
    "cc": "230",			 // Country code of the home phone.
    "subscriber": "1234567"	      // Home phone number of the cardholder.
   },
  "workPhone": {			 // Conditional. Refer to ITU-E.164 for additional information on format and length.
    "cc": "230",			 // Country code of the work phone.
    "subscriber": "1234567"	      // Work phone number of the cardholder.
   },
  "mobilePhone": {	  // Conditional. Refer to ITU-E.164 for additional information on format and length.
    "cc": "230",			// Country code of the mobile phone.
    "subscriber": "51234567"	     // Mobile phone number of the cardholder.
   },
  "email": "example@example.com",	       // Conditional. Email address of the cardholder.
  "addrMatch": "Y",			   // Optional. Y if the cardholder Shipping Address and Cardholder Billing Address are the same; otherwise, N.
  "transType": "01",			   // Conditional. Identifies the type of transaction being authenticated.
  "threeDSRequestorAuthenticationInd": "01",      // Required. Indicates the type of authentication request.
  "threeDSRequestorAuthenticationInfo":       // Optional. Information about how the 3DS Requestor authenticated the cardholder before or during the transaction.
    {
      "threeDSReqAuthMethod": "01",		    // Mechanism used by the cardholder to authenticate to the 3DS Requestor.
      "threeDSReqAuthTimestamp": "YYYYMMDDHHmm",      // Date and time in UTC of the cardholder authentication.
      "threeDSReqAuthData": "cKTYtrvvKU7gUoiqbbO7Po"      // Data that documents and supports a specific authentication process.
    },
  "threeDSRequestorChallengeInd": "01",        // Optional. Indicates whether a challenge is requested for this transaction. Valid 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), 06 - No challenge requested (Data share only), 07 - No challenge requested (strong consumer authentication is already performed). The default is 01. The response returns the transStatus = I only if the value in this field is set to 05, 06, or 07. 
  "threeDSRequestorPriorAuthenticationInfo":       // Optional. Information about how the 3DS Requestor authenticated the cardholder as part of a previous 3DS transaction.
    {
      "threeDSReqPriorRef": "d7c1ee99-9478-44a6-b1f2-391e29c6b340",     // 3DS Requestor Prior Transaction Reference. An ACS Transaction ID for a prior authenticated transaction.
      "threeDSReqPriorAuthMethod": "01",		    // Mechanism used by the cardholder to previously authenticate to the 3DS Requestor.
      "threeDSReqPriorAuthTimestamp": "YYYYMMDDHHmm",         // Date and time in UTC of the prior cardholder authentication.
      "threeDSReqPriorAuthData": "cKTYtrvvKU7gUoiqbbO7Po"      // 3DS Requestor Prior Transaction Authentication Data.
    },
  "acctType": "01",				  // Conditional. Indicates the type of account.
  "acctID": "personal account",  			  //Optional. Cardholder account identifier.
  "acctInfo": "03",             // Optional. Additional cardholder account information.  
   {
 	   "chAccAgeInd": "01",              // Length of time that the cardholder has had the account with the merchant.
	   "chAccDate": "20140328",          // Date that the cardholder opened the account with the merchant. Format - YYYYMMDD
	   "chAccChangeInd": "04",        // Length of time since the cardholder’s account information with the merchant was last changed, including Billing or Shipping address, new payment account, or new user(s) added.
	   "chAccChange": "20160712",          // Date that the cardholder’s account with the merchant was last changed, including Billing or Shipping address, new payment account, or new user(s) added. Format - YYYYMMDD
	   "chAccPwChangeInd": "02",           // Indicates the length of time since the cardholder’s account with the merchant had a password change or account reset.
	   "chAccPwChange": "20170328",    // Date that cardholder’s account with the merchant had a password change or account reset. Format - YYYYMMDD
	   "shipAddressUsageInd": "04",  // Indicates when the shipping address used for this transaction was first used with the merchant.
	   "shipAddressUsage": "20160714",  // Date when the shipping address used for this transaction was first used with the merchant. Format - YYYYMMDD
	   "txnActivityDay": "01",          // Number of transactions for this cardholder in last 24 hours.
	   "txnActivityYear": "21",         // Number of transactions for this cardholder in the previous 12 months.
	   "provisionAttemptsDay": "0",     // Number of Add Card attempts in last 24 hours.
	   "nbPurchaseAccount": "11",      // Number of purchases with this cardholder account during the previous six months.
	   "suspiciousAccActivity": "01",     // Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.
	   "shipNameIndicator": "02",       // Indicates if the cardholder name on the account is identical to the shipping name used for this transaction.
	   "paymentAccInd": "04",          // Indicates the length of time that the payment account was enrolled in the cardholder’s account with the merchant.
	   "paymentAccAge": "20160917",    // Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor. Format - YYYYMMDD
	 }
  "purchaseInstalData": "1",			  // Conditional. Indicates the maximum number of authorizations permitted for installment payments.
  "merchantRiskIndicator": 			  //Optional. Merchant’s assessment of the level of fraud risk.
    {
      "shipIndicator": "01",				 // Shipping method chosen for the transaction.
      "deliveryTimeframe": "01",			  // The merchandise delivery timeframe.
      "deliveryEmailAddress": "example1@example.com",		 // For electronic delivery, the email address to which the merchandise was delivered.
      "reorderItemsInd": "01",			   // Whether the cardholder is reordering previously purchased merchandise.
      "preOrderPurchaseInd": "01",			  // Whether the cardholder is placing an order for merchandise with a future availability or release date.
      "preOrderDate": "YYYYMMDD",			  // For a pre-ordered purchase, the expected date that the merchandise will be available.
      "giftCardAmount": "123",			   // Gift card amount in major units.
      "giftCardCurr": "870",			   // The currency code of the gift card as defined in ISO 4217.
      "giftCardCount": "1"		    // Total count of individual prepaid or gift cards/codes purchased.
    },
  "messageExtension":	[		    // Conditional. Data necessary to support requirements not otherwise defined in the 3D Secure message.
    {
      "name": "msgextname",				  // The name of the extension data set as defined by the extension owner.
      "id": "501341592B_0001_4567",			    // A unique identifier for the extension.
      "criticalityIndicator": true,		      // true if the recipient must understand the contents of the extension to interpret the entire message; otherwise, false.
      "data":         // The data carried in the extension.
        {
          "valueOne": "messageextensiondata",
          "valueTwo": "moremessageextensiondata"
        }				   
    }],
  "recurringExpiry": "YYYYMMDD",			    // Conditional. Date after which no further authorizations shall be performed.
  "recurringFrequency": "30",			     // Conditional. Indicates the minimum number of days between authorizations.
  "broadInfo": 					  // Conditional. Broadcast Information.
    {
      "message": "Sample message"			   // Broadcast message content.
    },
  "clientStartProtocolVersion": "2.1.0",   //Optional. The earliest (i.e. oldest) active 3DS protocol version that the client supports. Valid values are 2.1.0 and 2.2.0. The default is 2.1.0. See the 3DS Server Fallback decision matrix table in the Web SDK Overview topic for a list of possible fallback scenarios.
  "clientEndProtocolVersion": "2.2.0",   //Optional. The most recent active 3DS protocol version that the client supports. Valid values are 2.1.0 and 2.2.0. The default is 2.1.0. If this field is set to 2.2.0, the server first checks for 3DS 2.2 support. If 3DS 2.2 is not supported, then it checks for 3DS 2.1 support. 
  "acquirerBin": "761018452",    //Conditional. Acquiring institution identification code as assigned by the DS receiving the AReq message. Required only if you are sending the request for a service provider merchant (a merchant not acquired by Elavon)
  "acquirerMerchantID": "445842",    //Conditional. Acquirer-assigned Merchant identifier. Required only if you are sending the request for a service provider merchant (a merchant not acquired by Elavon)
  "threeDSRequestorID": "1002475300000000080340007",    //Conditional. DS assigned 3DS Requestor identifier. Required only if you are sending the request for a service provider merchant (a merchant not acquired by Elavon). Required only for 3DS 2 transactions.
  "threeDSRequestorName": "Test007",    //Conditional. DS assigned 3DS Requestor name. Required only if you are sending the request for a service provider merchant (a merchant not acquired by Elavon). Required only for 3DS 2 transactions.
  "challengeWindowSize": "01",  // Optional. Size of the challenge iframe content. The default value is "05" i.e. fullscreen.
  "meta":
  {
    "displayMode": "lightbox",  // Optional. Default value is 'lightbox'. Other supported value is 'inline'. For more details, see the section on challenge window display options.
    "challengeIframeElement": null   // Optional. Container element where challenge content will be displayed within the UI.
  }
}

note

Merchants who operate in the travel industry can send additional travel-related data in the messageExtension object of the /authenticate request. For a sample of the messageExtension object and field details, see message extension elements for the travel industry
To send the data only for information purposes and no authentication required (i.e. to receive transStatus = I in the response), you must send a value of either 05, 06, or 07 in the threeDSRequestorChallengeInd field.
For more details about service provider merchants, see 3D Secure 2 for merchants who do not process payments with Elavon
To understand the fallback strategy of the 3DS Server, review the 3DS Server Fallback decision matrix table.

For a detailed description of each parameter, see the Authentication parameters description

Challenge Window Display Options

When a customer receives a challenge from the issuer, the SDK displays an iframe for them to enter information. There are two display types for the challenge window: lightbox or inline. The challengeWindowSize property works in conjunction with the challengeIframeElement and displayMode properties to display the challenge window during a challenge flow.

Lightbox

Lightbox displays a challenge window as a modal over the top of the user’s current screen. It is the default mode of presentation. You can set the lightbox display with the following settings.

{
  // example to show the display mode set to lightbox
  "meta":
  {
    "displayMode": "lightbox",        // Default display mode is lightbox
    "challengeIframeElement": null   // Optional. Container element where challenge content will be displayed within the UI. 
  }
}

Inline

Inline display injects the challenge window iframe into the existing page. You can set the challenge window display to inline with the following settings.

{
  // example to show the display mode set to inline
  "meta":
  {
    "displayMode": "inline",
    "challengeIframeElement": document.getElementById('iframe-container') // Optional. Container element where challenge content will be displayed within the UI. 
  }
}

The challengeWindowSize value defines the width and height (in pixels) of a container that will hold the iframe containing a challenge if requested. The default value is 05, which means the challenge window will occupy the fullscreen. Valid values of challenge window size are:

01 - 250 X 400
02 - 390 X 400
03 - 500 X 600
04 - 600 X 400
05 - fullscreen

3DS 2 - authenticate() sample response (Frictionless flow)

If the issuer authenticates the cardholder data, the authentication response returns the issueChallenge value as false, also called frictionless flow.

{
    "issueChallenge": false,		      //false for a successful authentication; otherwise true for a transaction where the issuer needs more data to validate the cardholder’s identity.
    "authenticated": true,		        //true for successful authentication, which indicates that the transaction can be classified as a frictionless flow. 
    "message": "Account Verification Successful",	          // Result of the authentication request in a descriptive text.  For example, 'Authentication Successful', 'Authentication Rejected', etc.
    "authenticationValue": "lIZK0RcpcDZ83vutqkwrZqJ0fl4=",           // Authentication value returned by the issuer. For transStatus = I, this field is conditional based on DS rules.
    "transStatus": "Y",           // Indicates the transaction status. Valid values for a frictionless authentication response are: Y, N, U, A, I, R.
    "eci": "05",          // Electronic Commerce Indicator.
    "messageType": "ARes",                   // Type of message.
    "messageVersion": "2.2.0",               // Version of the 3DS message. Valid values are 2.2.0 and 2.1.0. Default is 2.1.0.
    "threeDSServerTransID": "102f8f6e-8472-4ada-8deb-91d5bd51de90",       // 3DS Server Transaction ID.
    "dsTransID": "d9efdb88-2277-408b-859a-a16ec843395b",              // Directory Server (DS) Transaction ID.
    "acsTransID": "7a3378fe-cea0-4762-8035-c0b91d7e7d0e",             // Access Control Server (ACS) Transaction ID.
    "acsReferenceNumber": "ELAVON_ACS_EMULATOR_REF_NUMBER32", // Unique identifier assigned by the EMVCo Secretariat upon Testing and Approval.
    "acsOperatorID": "ELAVON_ACS_EMULATOR_OPERATOR_ID1",  // DS assigned ACS identifier.
    "dsReferenceNumber": "ELAVON_3DS_DS_EMULATOR_REF_NUM32"  // EMVCo-assigned unique identifier to track approved DS.
}

For a detailed description of each parameter, see the Authentication parameters description

note

If transStatus = Y and eci and authenticationValue field values are present, the transaction is authenticated and the liability shifts to the issuer. The authenticated field is also set to true.
If transStatus = A and eci and authenticationValue field values are present, the transaction attempted an authentication, and the liability shifts to the issuer. The authenticated field is set to false because only an authentication attempt was made; however, the presence of eci and authenticationValue field values guarantees liability shift.
If transStatus = I and eci and authenticationValue field values are present, the transaction is authenticated and the liability shifts to the issuer. The authenticated field is also set to true. For transStatus = I, the authenticationValue field is conditional based on DS rules.
Any other transStatus result does not result in a liability shift.

3DS 2 - authenticate() sample response (Challenge flow)

If the issuer needs more information from the cardholder to authenticate the cardholder, the authentication response returns the issueChallenge value as true.

{
    "issueChallenge": true,	          // true if the issuer needs more data to confirm the cardholder’s identity to authenticate the transaction. 
    "authenticated": false,		        //false if the transaction needs a challenge by the issuer before authentication. 
    "message": "Challenge Required. Additional authentication is required",	          // Result of the authentication request in a descriptive text.  For example, 'Authentication Successful', 'Authentication Rejected', etc.
    "transStatus": "C",           // Indicates the transaction status. Valid value in case of a challenge flow: C
    "messageType": "ARes",                   // Type of message.
    "messageVersion": "2.2.0",               // Version of the 3DS message. Valid values are 2.2.0 and 2.1.0. Default value is 2.1.0
    "threeDSServerTransID": "102f8f6e-8472-4ada-8deb-91d5bd51de90",       // 3DS Server Transaction ID.
    "dsTransID": "d9efdb88-2277-408b-859a-a16ec843395b",              // Directory Server (DS) Transaction ID.
    "acsTransID": "7a3378fe-cea0-4762-8035-c0b91d7e7d0e",             // Access Control Server (ACS) Transaction ID.
    "acsReferenceNumber": "ELAVON_ACS_EMULATOR_REF_NUMBER32", // Unique identifier assigned by the EMVCo Secretariat upon Testing and Approval.
    "acsOperatorID": "ELAVON_ACS_EMULATOR_OPERATOR_ID1",  // DS assigned ACS identifier.
    "dsReferenceNumber": "ELAVON_3DS_DS_EMULATOR_REF_NUM32",  // EMVCo-assigned unique identifier to track approved DS.
    "authenticationType": "01",     // Indicates the type of authentication method the issuer will use to challenge the cardholder. Valid values: 01 - Static; 02 - Dynamic; 03 - OOB.
    "acsChallengeMandated": "Y",   // Indication of whether a challenge is required for the transaction to be authorized due to local/regional mandates or other variables. Valid values: Y - Challenge is mandated; N - Challenge is not mandated.
    "acsURL": "https://uat.acs.fraud.eu.elavonaws.com/acs/challenge/VISA",	         // URL of the ACS to be used for the challenge.
    "creq": "BASE64 ENCODED DATA"	            // Base64 encoded challenge request message.
}

For a detailed description of each parameter, see the Authentication parameters description

3DS 2 - authenticate() request example

const authResponse = await sdk.authenticate({
  "threeDSServerTransId": lookupResponse.transactionId,
  "acctNumber": "4100012356995210",
  "cardExpiryDate": "2021",
  "purchaseAmount": "10",
  "purchaseCurrency": "840",
  "purchaseExponent": "2",
  "purchaseDate": "20170316141312",
  "messageCategory": "01",
  "transType": "01",
  "threeDSRequestorAuthenticationInd": "01",
  "clientStartProtocolVersion": "2.1.0",
  "clientEndProtocolVersion": "2.2.0"
});
if (authResponse.issueChallenge) {
    // Challenge
} else {
    // Authentication Complete
}

note

You can test different authentication scenarios for supported card schemes using the test card numbers on the Test scenarios page.

sdk.challenge()

Challenge request

If you receive issueChallenge: true in the authentication response, request a challenge by calling the sdk.challenge() method. See the value of the messageVersion field in the authenticate response to determine if the transaction is being authenticated using 3DS 2.2 or 3DS 2.1 protocol.

The challenge method will add an iframe to the bottom of the page or use the given container element that the iframe will be loaded into and display the contents from the issuer. The Web SDK adds an event handler to wait until the challenge is complete and returns a response as an object.

3DS 2 - challenge() sample request

For a 3DS 2 transaction, the threeDSServerTransId, acsURL, and the creq parameters in the challenge request must be the same as the values returned in the authentication response.

{
  "threeDSServerTransId": "102f8f6e-8472-4ada-8deb-91d5bd51de90",	   // Required. Unique ID assigned by the 3DS Server to identify a single transaction. The value of this field must be same as the value returned in the lookup() or authenticate() response.
  "acsURL": "https://uat.acs.fraud.eu.elavonaws.com/acs/challenge/VISA",	// Required. URL of the ACS to which the challenge request is sent.
  "creq": "eyJtZXNzYWdlVHlwZSI6IkyLTgwMzUtYzBiOTFkN2U3ZDBlIn0=",	       // Required. The Base 64 encoded data value is populated by the data value received in the authenticate response.
  "challengeIframeElement": document.getElementById('iframe-container')      // Optional but recommended. The HTML element where the challenge UI will display. 
}

3DS 2 - challenge() sample response

{
  "messageType": "RReq",             //    Returned as RReq incase of a challenge flow.
  "messageVersion": "2.2.0",         //  3DS protocol version used to authenticate the authentication. Valid values could be 2.2.0 or 2.1.0. Default is 2.1.0.
  "threeDSServerTransID": "bf167a7b-e80e-47ec-a17e-b60b3987d8f8",             // 3DS Server Transaction ID.
  "dsTransID": "6d439447-1022-4cbb-b35c-c36a0bee98cb",          // Directory Server (DS) Transaction ID.
  "acsTransID": "7a9346ca-e2af-4577-86d9-6584cb13f2f9",         // Access Control Server (ACS) Transaction ID.
  "authenticationType": "01",            // Indicates the type of authentication method the issuer will use to challenge the cardholder. Valid values: 01 - Static; 02 - Dynamic; 03 - OOB.
  "authenticationValue": "o0JPKK16Qw9UAhZMBfEzjTRyW1g=",             // Authentication value returned by the user. This field is returned in the response only when the field value of the authenticated parameter is true. Returned only for transStatus = Y.
  "eci": "05",                 // Electronic Commerce Indicator. Returned only for transStatus = Y.
  "interactionCounter": "01",                 // Indicates the number of authentication cycles attempted by the Cardholder.
  "transStatus": "Y",                   // Indicates the transaction status. The final challenge response returns a value of either: Y or N.
  "authenticated": true,              // true if challenge credentials entered by the cardholder is authenticated; otherwise, false.
  "messageCategory": "01",    //Identifies the category of the message for a specific use case. Valid values:01 = PA or 02 = NPA.
  "message": "Account Verification Successful"            // Result of the authentication request in a descriptive text.  For example, ‘Authentication Successful’, ‘Authentication Rejected’, etc. 
}

For a detailed description of each parameter, see the Challenge parameters description

3DS 2 - challenge() request example

const challengeResult = await sdk.Challenge({
  "threeDSSeverTransId": authResponse.threeDSServerTransID,
  "acsURL":  authResponse. acsURL,
  "creq":  authResponse.creq,
  "challengeIframeElement": document.getElementById('iframe-container')  
})

3DS 2 - Complete example of the toolkit flow

<!DOCTYPE>
<html>
  <head>
    <meta charset="utf-8">
    <title>Elavon 3DS Web SDK</title>
    <script src="https://uat.gw.fraud.eu.elavonaws.com/sdk-web-js/0.13.10/3ds2-web-sdk.min.js"></script>
    <script>
      const baseUrl = 'https://uat.gw.fraud.eu.elavonaws.com/3ds2';
      function showResult(result) {
        document.getElementById('holder').innerHTML = `<pre>${JSON.stringify(
          result,
          null,
          2,
        )}</pre>`;
      }
      function handleToolkitFlow() {
        const sdk = new window.Elavon3DSWebSDK({
          baseUrl,
          token:
            'eyJhb...QkvWgQro_yw',
        });
        const acctNumber = '4100012356995210';
        sdk
          .lookup({
            messageId: 'test-msg-id',
            acctNumber,
            doBinLookup: true,
            clientStartProtocolVersion: '2.1.0',
            clientEndProtocolVersion: '2.2.0',
          })
          .then((response) => {
            console.log('lookup response', response);
            return sdk
              .deviceFingerprint({
                threeDSMethodURL: response.threeDSMethodURL,
                threeDSMethodData: response.threeDSMethodData,
              })
              .then(() => response);
          })
          .then((response) => {
            console.log(
              'deviceFingerprint response',
              deviceFingerprintResponse,
            );
            return sdk.authenticate({
              threeDSServerTransID: response.threeDSServerTransID,
              acctNumber: '4100012356995210',
              cardExpiryDate: '2412',
              purchaseCurrency: '840',
              purchaseExponent: '2',
              purchaseAmount: '150',
              purchaseDate: '20170316141312',
              messageCategory: '01',
              transType: '01',
              threeDSRequestorAuthenticationInd: '01',
              challengeParameters: { challengeWindowSize: '01'},
              clientStartProtocolVersion: '2.1.0',
              clientEndProtocolVersion: '2.2.0',
            });
          })
          .then((response) => {
            console.log('authenticate response', response);
            if (response.issueChallenge) {
              return sdk
                .challenge({
                  threeDSServerTransID: response.threeDSServerTransID,
                  acsURL: response.acsURL,
                  creq: response.creq,
                  challengeIframeElement: document.getElementById('holder'),
                })
                .then((response) => {
                  console.log('challenge response', response);
                  return response;
                });
            } else {
              return response;
            }
          })
          .then((response) => {
            showResult(response);
          });
      }
    </script>
  </head>
  <body id="body">
    <h3 class="content-title">Elavon 3DS Toolkit Flow</h3>
    <div id="buttons">
      <button onclick="handleToolkitFlow()">Toolkit Flow</button>
    </div>
    <div
      id="holder"
      style="border: 1px solid #ddd; min-height: 100px; margin: 10px;"
    ></div>
  </body>
</html>

Web SDK Utilities

getBrowserInfo

Use the getBrowserInfo method to get browser information that is required for authentication request.

sdk.getBrowserInfo()

getBrowserInfo response

{
  "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
  "browserJavaEnabled": true,
  "browserJavascriptEnabled": true,
  "browserLanguage": "en",
  "browserColorDepth": "48",
  "browserScreenHeight": "600",
  "browserScreenWidth": "1080",
  "browserTZ": "-240",
  "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36"
}

Using the Toolkit Workflow of the Web SDK

Initializing the Web SDK

sdk.lookup()

lookup() sample request

3DS 2 - lookup() Sample response

3DS 2 - lookup() example

sdk.deviceFingerprint()

3DS 2 - deviceFingerprint() sample request

3DS 2 - deviceFingerprint() sample response

deviceFingerprint() example

sdk.authenticate()

authenticate() sample request

authenticate() sample request showing only required parameters

authenticate() sample request showing all parameters either required or optional

Challenge Window Display Options

Lightbox

Inline

3DS 2 - authenticate() sample response (Frictionless flow)

3DS 2 - authenticate() sample response (Challenge flow)

3DS 2 - authenticate() request example

sdk.challenge()

Challenge request

3DS 2 - challenge() sample request

3DS 2 - challenge() sample response

3DS 2 - challenge() request example

3DS 2 - Complete example of the toolkit flow

Web SDK Utilities

getBrowserInfo

getBrowserInfo response

Related topics