Integrate using the Web SDK

On this page

Overview

You can add 3D secure 2 capabilities to your checkout page by integrating Elavon’s 3DS Web SDK. The Web SDK reduces complex development work to integrate with Elavon’s 3DS Server. The Web SDK supports two different options for authenticating a transaction:

• All-in-one
• Toolkit

All-in-one

Use the all-in-one workflow of the Web SDK when you want an easy and quick option to add 3D Secure 2 capabilities into your website. To use this workflow, add the Web SDK JavaScript file to your website’s payment page. After the integration, the Web SDK handles lookup, authentication, and challenge (if required) methods by itself.

Use the all-in-one workflow of the SDK

Toolkit

Use the toolkit workflow of the Web SDK for scenarios where you may have a mixed-mode integration between the merchant’s server environment and the client-side browser or when you want additional control over each method called during the authentication process. For example, you can directly integrate with the 3DS Server to submit the authentication request while you use the challenge flow from the toolkit workflow to ease the client-side integration.

Use the toolkit workflow of the SDK

Workflow diagram

Frictionless flow: The Web SDK workflow diagram shows the transaction authentication process when the Web SDK is integrated to the merchant’s website. After the Web SDK gets authenticated, it initiates the versioning request to check the supported 3DS version. If the card used in the transaction supports 3DS, the Web SDK sends the authentication data to the 3DS Server and receives the authentication response. If the issuer deemed the cardholder information as correct, it authenticates the transaction and the 3D Secure processing will end here.

Challenge flow: If the issuer needs additional information to authenticate the cardholder, it will send authentication response with transStatus = C. In this case, the Web SDK will facilitate the challenge verification process between the issuer and the cardholder. Once the challenge is complete, it will retrieve the challenge result from the 3DS Server and the merchant can use this response to authenticate or decline the transaction.

Figure caption: Frictionless and challenge workflow in a Web SDK integration

Prerequisites

You must meet the following requirements to use the 3DS Web SDK.

Test credentials

To request authentication credentials that you would need to test the different integration options in the sandbox environment, fill in the information requested in this form.

open_in_new3D Secure 2 test credentials request formLink opens new window

For more details on authentication mechanisms supported by Elavon for 3D Secure, see Authentication.

IP range for test environment

Set up a test environment to test your integration. Before you begin the integration and testing process, provide the test environment IP address details to your Elavon sales contact. You can begin the testing process only after your test environment IP addresses are added to the allowed list of IP addresses in Elavon’s environment.

3DS Server URL

Use the following URLs to send API requests to the 3DS Server through the Fraud Services gateway:

Test environment: open_in_newhttps://uat.gw.fraud.eu.elavonaws.com/3ds2Link opens new window

Production environment: open_in_newhttps://gw.fraud.elavon.com/3ds2Link opens new window

Installation

To install the Web SDK, complete the following steps:

1. Embed the Web SDK JavaScript file to your page by adding the following code to your website’s payment page.

   <script type="text/javascript" src="https://libs.fraud.elavon.com/sdk-web-js/1.2.0/3ds2-web-sdk.min.js"></script>
   

2. Access the Web SDK functionality from the window object.

   `window.Elavon3DSWebSDK`
   

3. Make a call to your server to get an authentication token that you will need to use with the Web SDK. Note that the Web SDK only supports JWT tokens for authentication. For steps to get a token, review the Authentication topic.

   Use the following code to set up your credentials in the Web SDK.

   var sdk = new window.Elavon3DSWebSDK(
   {
    baseUrl: "https://uat.gw.fraud.eu.elavonaws.com/3ds2",  // Required. URL of Elavon’s 3DS Server.
    token: "JWT TOKEN"  // Generated by using the API key to send a request for a JWT token from the 3DS Server.
   });
   

4. Create a new instance of the object and assign it to your preferred variable.

   const sdk = new window.Elavon3DSWebSDK([options])
   

   Example:

   (`const sdk = new window.Elavon3DSWebSDK({baseUrl: 'https://baseUrl', token: 'authentication token from step 3'})`)
   

After you complete the installation, use either the all-in-one or the toolkit Web SDK workflow to initiate the 3D Secure authentication process.

Demo application

You can use the Web SDK demo application to understand how the Web SDK communicates with the 3DS Server through different API requests and responses. It shows the internal communication that happens when a merchant website sends a request to the 3DS Server to process a transaction and the further steps in the transaction authentication process. You can review the request and response body to see the information sent and received by the Web SDK.

Download the Web SDK demo application to understand more about these flows.

3DS 2.1 fallback support

If you are an integrator who only supports 3DS 2.1 or if the issuer does not support 3D Secure 2.2 (3DS 2.2), you can still integrate Elavon’s 3DS Web SDK to your website. Transactions that need 3DS 2.1 authentication are appropriately redirected by the Web SDK to the 3DS 2.1 authentication flow. The following table shows how these three fields in the authenticate request help the 3DS Server decide whether to follow 3DS 2.2 or 3DS 2.1 authentication flow: messageVersion, clientStartProtocolVersion, and clientEndProtocolVersion.

Table: 3DS Server fallback strategy

Web SDK for merchants who do not process with Elavon

Integrators can now choose Elavon to enable 3D Secure 2 capabilities in their payment services for all merchants even if they do not process their payments with Elavon. They can register such merchants as a “service provider merchant” in Elavon’s 3DS Solution. Once a merchant is registered, the integrator can send a request to create a merchant alias for the service provider merchant. The integrator will use the merchant alias and their API key (the integrator’s API key) to retrieve the authentication token and send 3DS 2 related API requests on behalf of the merchant.

For more information on creating a service provider merchant and an alias for such merchants, review the 3D Secure for merchants who do not process with Elavon topic.

Related topics

• 3D Secure 2 integration options

• 3D Secure 2 for merchants who do not process their payments with Elavon

• Use the all-in-one workflow of the SDK

• Use the toolkit workflow of the SDK

• Try the Web SDK demo application