Use the Toolkit Workflow of the Web SDK

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

Use the following URL to make the API requests:

https://uat.gw.fraud.eu.elavonaws.com/3ds2

The Web SDK will need a token to communicate with the 3DS Server via the Fraud gateway. For steps to get a token, see Authentication

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'});

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

error_outline
note

If the transaction uses a 3DS 1 authentication flow, you do not need to use the sdk.deviceFingerprint() method.

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

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.

Sample lookup 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 1.0.2 and 2.1.0. Default value is 2.1.0. If set to 1.0.2, the Web SDK attempts 3DS 1 authentication when the integrator or the issuer does not support 3DS 2, or the card number is not enrolled for 3DS 2.
    "clientEndProtocolVersion": "2.1.0"   //Optional. The most recent active 3DS protocol version that is supported by the client. Valid values are 1.0.2 and 2.1.0. Default value is 2.1.0.
}

For detailed description of each parameter, see Lookup parameters description

The sdk.lookup() method returns a promise. The response returns the threeDSServerTransId, threeDSMethodURL, and threeDSMethodData values. These values are used for device fingerprinting.

error_outline
note

Device fingerprinting is performed only for transactions that support 3DS 2.1.0.

3DS 2 - sample lookup 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": "1.0.2",  // The earliest (i.e. oldest) active 3DS protocol version that is supported by the 3DS Server. Valid values are 1.0.2 and 2.1.0.
  "serverEndProtocolVersion": "2.1.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. The response returns this field only if the user is using a VISA card.
  "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 detailed description of each parameter, see Lookup parameters description

3DS 1 - Sample lookup 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": "1.0.2",          // The earliest (i.e. oldest) active protocol version that is supported by the DS.
    "dsEndProtocolVersion": "1.0.2",             // The most recent active protocol version that is supported for the DS.
    "acsStartProtocolVersion": "1.0.2",         // The earliest (i.e. oldest) active protocol version that is supported by the ACS.
    "acsEndProtocolVersion": "1.0.2",            // The most recent active protocol version that is supported for the ACS URL.
    "directoryServerId" : "DirectoryServerID-DEMO-MC", // ID of the Directory Server that acts as a conduit between the 3DS Server and the ACS (issuer).
    "serverStartProtocolVersion": "1.0.2",   // The earliest (i.e. oldest) active 3DS protocol version that is supported by the 3DS Server. Valid values are 1.0.2 and 2.1.0.
    "serverEndProtocolVersion": "2.1.0",    // The most recent active 3DS protocol version that is supported by the 3DS Server.
    "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 detailed description of each parameter, see Lookup parameters description

3DS 2 - lookup example

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

3DS 1 - lookup example

const lookupresponse = await sdk.lookup({
   "acctNumber": "400000000000000022", "doBinLookup": true, "clientStartProtocolVersion": "1.0.2", "clientEndProtocolVersion": "2.1.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 additional information to the issuer to determine whether the issuer should challenge the user.

error_outline
note

Device fingerprinting is performed only for transactions that support 3DS 2. If the transaction authentication uses 3DS 1, the sdk.lookup() call does not return the threeDSMethodURL and threeDSMethodData fields in the response and you do not need call sdk.deviceFingerprint().

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.

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.
}

deviceFingerprint sample response

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

error_outline
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 you to 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()

Authentication sample request

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

error_outline
note

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

Sample request using only the required parameters

{
  "threeDSServerTransId": "102f8f6e-8472-4ada-8deb-91d5bd51de90",      // Required. Unique ID assigned by the 3DS Server to identify a single transaction. The value of this field is same as the threeDSServerTransId value received 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 numeric currency code.
  "purchaseExponent": "2",              //Required. Minor units of currency as specified in the ISO-4217 currency exponent. For example, 2 for USD, 0 for Yen, etc. 
  "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.
  "transType": "01",            // Required. Identifies the type of transaction being authenticated.
  "threeDSRequestorAuthenticationInd": "01"      // Required. Indicates type of transaction request.
}

For detailed description of each parameter, see Authentication parameters description

error_outline
note

To improve the chance of a successful authentication, include the additional parameters in the authentication request.

Sample authenticate request with all parameters that includes detailed cardholder information

{
  "messageId": "TEST-MESSAGE-ID",            // Optional. Unique message identifier assigned by client.
  "threeDSServerTransId": "102f8f6e-8472-4ada-8deb-91d5bd51de90",      // Required. Unique ID assigned by the 3DS Server to identify a single transaction. The value of this field is same as the threeDSServerTransId value received 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. 
  "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.
  "billAddrLine2": "Address Line 2",       // Conditional. Address line 2 of the billing address.
  "billAddrLine3": "Address Line 3",       // Conditional. Address line 3 of the billing address.
  "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": true,               // Optional. true if the cardholder Shipping Address and Cardholder Billing Address are the same.
  "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.
  "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.
  "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.
      "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 is supported by the client. Valid values are 1.0.2 and 2.1.0. Default is 2.1.0. If set to 1.0.2, the Web SDK attempts 3DS 1 authentication when the integrator or the issuer does not support 3DS 2.
  "clientEndProtocolVersion": "2.1.0",   //Optional. The most recent active 3DS protocol version that is supported by the client. Valid values are 1.0.2 and 2.1.0. Default is 2.1.0.
  "challengeWindowSize": "01",  // Optional. Size of the challenge iframe content. Default value is "05" i.e. full screen.
  "meta":
  {
    "displayMode": "lightbox"  // Optional. Default value is 'lightbox'. Other supported value is 'inline'. See the section on challenge window display options.
  }
}

For detailed description of each parameter, see 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.

{
  ... // Other params
  "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.

{
  ... // Other Params
  "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 full Screen. Valid values are:

  • 01 - 250 X 400
  • 02 - 390 X 400
  • 03 - 500 X 600
  • 04 - 600 X 400
  • 05 - full screen

3DS 2 - Sample authentication response (Frictionless flow)

If the issuer authenticates the cardholder data, the authentication response returns the issueChallenge value as false, also called as 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 a 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.
    "transStatus": "Y",           // Indicates the transaction status. Valid values: Y, N, U, A, C, R.
    "eci": "05",          // Electronic Commerce Indicator.
    "messageType": "ARes",                   // Type of message.
    "messageVersion": "2.1.0",               // Version of the 3DS message.
    "threeDSServerTransID": "TRANSACTION ID",       // 3DS Server Transaction ID.
    "dsTransID": "DS TRANS ID",              // Directory Server (DS) Transaction ID.
    "acsTransID": "ACS TRANS ID",             // 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 detailed description of each parameter, see Authentication parameters description

3DS 2 - Sample authentication 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 authenticate the transaction. It needs a challenge to confirm the cardholder’s identity.
    "authenticated": false,             //false for a transaction that 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 values: Y, N, U, A, C, R.
    "messageType": "ARes",                   // Type of message.
    "messageVersion": "2.1.0",               // Version of the 3DS message.
    "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 variable. 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 detailed description of each parameter, see Authentication parameters description

3DS 1 - Sample authentication 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 authenticate the transaction. It needs a challenge to confirm the cardholder’s identity.
    "authenticated": false,             //false for a transaction that needs a challenge by the issuer before authentication. 
    "messageType": "VERes",                   // Type of message.
    "messageVersion": "1.0.2",               // Version of the 3DS message.
    "threeDSServerTransID": "102f8f6e-8472-4ada-8deb-91d5bd51de90",       // 3DS Server Transaction ID.
    "acsURL": "https://uat.acs.fraud.eu.elavonaws.com/acs/challenge/VISA",           // URL of the ACS to be used for the challenge.
    "xid": "5916162493.D260DC-T1",      // Unique purchase ID. Returned from the 3DS Server.
    "enrolled": true,     //true if the acctNumber is enrolled in 3DS 1.
    "PaReq": "eJxlUtFu...fJFPdbjKCA==",     // It contains the data required to attempt cardholder authentication. 
    "MD": "eyJ0aH...jIwNDgifQ==",     // Merchant Data. A 64-bit encoded JSON unique reference to identify if the 3D Secure request is genuine.
    "TermUrl": "https://uat.gw.fraud.eu.elavonaws.com/notify/challenge_notify",  // Indicates the URL that will be notified of the challenge result by ACS. 
    "messageId": "621423ca-0ce2-4c26-89f8-aff6b913c653"   // Unique message identifier assigned by client.
}

For detailed description of each parameter, see 3DS 1 Response parameters description

error_outline
note

If the client supports 3DS 1 but the card does not support 3DS 1, the 3DS Server response mentions that the card is not enrolled for 3DS 1. In such scenarios, the integrator can still process the transaction at their own risk.

3DS 2 - Authentication request example

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

3DS 1 - Authentication request example

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

error_outline
note

You can test different authentication scenarios for supported cards 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 or 3DS 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 - Sample challenge request

For a 3DS 2 transaction, the threeDSServerTransId, acsURL, and the creq parameters in the challenge request must be 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 is same as the threeDSServerTransId value received in the lookup or authentication 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 1 - Sample challenge request

For a 3DS 1 transaction, pass in different fields in the challenge request. Instead of creq, the integrator will have to pass in PaReq, MD, and TermUrl.

error_outline
note

You must use the same TermUrl in the challenge request that you received in the authentication response.

{
  "threeDSServerTransID": "4934c009-a830-4139-b8e7-a0bc8c00a519",         // Required. Unique ID assigned by the 3DS Server to identify a single transaction. The value of this field is same as the threeDSServerTransId value received in the lookup or authentication response.
  "acsURL": "https://uat.acs.fraud.eu.elavonaws.com/acs/challenge/VISA",       //URL of the ACS to which the challenge request is sent.
  "PaReq": "eJx...Kew==",                   // It contains the data required to attempt cardholder authentication. 
  "MD": "eyJ0...jgifQ==",                  // Merchant Data. A 64bit encoded JSON unique reference to identify if the 3D Secure request is genuine. 
  "TermUrl": "https://uat.gw.fraud.eu.elavonaws.com/notify/challenge_notify"       // Indicates the URL that will be notified of the challenge result by ACS.
}

3DS 2 - Sample challenge response

{
  "messageType": "RReq",             //    Returned as RReq incase of a challenge flow.
  "messageVersion": "2.1.0",         //  3DS protocol version used to authenticate the authentication.
  "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 authenticated parameter is true.
  "eci": "05",                 // Electronic Commerce Indicator.
  "interactionCounter": "01",                 // Indicates the number of authentication cycles attempted by the Cardholder.
  "messageCategory": "01",              // Identifies the authentication type used in the transaction. 01- Payment authentication; 02 – Non payment authentication.
  "transStatus": "Y",                   // Indicates the transaction status. Valid values: Y, N, U, A, C, R.
  "authenticated": true,              // true if challenge credentials entered by the cardholder is authenticated.
  "message": "Account Verification Successful"            // Result of the authentication request in a descriptive text.  For example, ‘Authentication Successful’, ‘Authentication Rejected’, etc. 
}

For detailed description of each parameter, see Challenge parameters description

3DS 1 - Sample challenge response

{
  "messageId": "96dd9389-91ad-4d5b-974e-b6a5e432ae6f",
  "threeDSServerTransID": "96d3cfc8-97c4-4170-8dc7-31775c46565c",   // 3DS Server Transaction ID.
  "messageVersion": "1.0.2",              //  3DS protocol version used to authenticate the authentication.
  "xid": "58D82768FC.C75FB1-T1",            // Unique purchase ID. Returned from the 3DS Server.
  "status": "SUCCESS",                 // Authentication status of the transaction such as success, failed, attempted, unavailable.
  "transStatus": "Y",             // Transaction status returned by the issuer. Valid values are Y (authentication successful), N (transaction denied), U (authenciation could not be performed), R (authentication rejected), A (not authenticated but proof of authentication generated), C (challenge required).
  "cavv": "o8iH9rivgRSIGlK+bhV1kY7J00U=",             // Cardholder authentication verification value.
  "cavvAlgorithm": "2",               // Indicates the algorithm used to generate the cardholder authentication verification value.
  "eci": "05"                 // Electronic commerce indicator.
}

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 1 - Challenge request example

const challengeResult = await sdk.Challenge({
  "threeDSServerTransID": authResponse.threeDSServerTransID,
  "acsURL": authResponse. acsURL,
  "PaReq": authResponse. PaReq,
  "MD": authResponse.MD,
  "TermUrl": authResponse.TermUrl
})

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.2/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,
          })
          .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',
              messageCategory: '01',
              transType: '01',
              threeDSRequestorAuthenticationInd: '01',
              challengeParameters: { challengeWindowSize: '01'},
            });
          })
          .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>

3DS 1 - 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.2/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...7yzSA',
        });
        const acctNumber = '4000000000000022';
        sdk
          .lookup({
            acctNumber,
            doBinLookup: true,
            clientStartProtocolVersion: '1.0.2',
            clientEndProtocolVersion: '2.1.0',
          })
          .then((response) => {
            console.log('lookup response', response);
            return sdk.authenticate({
              threeDSServerTransID: response.threeDSServerTransID,
              acctNumber: '4000000000000022',
              cardExpiryDate: '2412',
              purchaseCurrency: '840',
              purchaseExponent: '2',
              purchaseAmount: '150',
              messageCategory: '01',
              transType: '01',
              threeDSRequestorAuthenticationInd: '01',
              challengeParameters: { challengeWindowSize: '01' },
              clientStartProtocolVersion: '1.0.2',
              clientEndProtocolVersion: '2.1.0',
            });
          })
          .then((response) => {
            console.log('authenticate response', response);
            return sdk.challenge({
              threeDSServerTransID: response.threeDSServerTransID,
              acsURL: response.acsURL,
              PaReq: response.PaReq,
              MD: response.MD,
              TermUrl: response.TermUrl,
              challengeIframeElement: document.getElementById('holder'),
            });
          })
          .then((response) => {
            console.log('challenge response', response);
            showResult(response);
          });
      }
    </script>
  </head>
  <body id="body">
    <h3 class="content-title">Elavon 3DS1 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,
  "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"
}

Related topics