Integrate using the Web SDK
On this page
note
If you have identified any errors or gaps in the content, please contact: email#SEDevPortalSupport@elavon.com
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
important
Never expose your API key in the client-side code.
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:
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>
Access the Web SDK functionality from the window object.
`window.Elavon3DSWebSDK`
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. });
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
messageVersion | clientStartProtocolVersion | clientEndProtocolVersion | 3DS Server Fallback Strategy |
---|---|---|---|
1.0.2 | 1.0.2 | 1.0.2 | 3DS Server returns an error. |
1.0.2 | 1.0.2 | 2.1.0 or 2.2.0 | 3DS Server returns an error. |
2.1.0 or 2.2.0 | 1.0.2 | 1.0.2 | 3DS Server returns an error. |
2.1.0 | 1.0.2 | 2.1.0 or 2.2.0 | Check support for 3DS 2.1. If not supported, the 3DS Server returns an error. |
2.1.0 | 2.1.0 | 2.1.0 | Check support for 3DS 2.1. If not supported, return an error. |
2.1.0 | 2.1.0 | 2.2.0 | Check support for 3DS 2.1. If not supported, return an error. |
2.2.0 | 1.0.2 | 2.2.0 | Check support for 3DS 2.2 first. If not supported, check support for 3DS 2.1. If 3DS 2.1 is not supported, the 3DS Server returns an error. |
2.2.0 | 2.1.0 | 2.1.0 | Error response |
2.2.0 | 2.2.0 | 2.2.0 | Check support for 3DS 2.2. If not supported, return an error. |
2.2.0 | 2.1.0 | 2.2.0 | Check support for 3DS 2.2 first. If 3DS 2.2 is not supported, fall back to 3DS 2.1. If 3DS 2.1 is not supported, return an error. |
note
messageVersion
is an optional field and if you do not manually specify a value in the authenticate request, the 3DS Server sets its default value to2.1.0
.If the 3DS Server falls back the request to
2.1.0
, the issuer ignores all fields that are specific only to the 3D Secure2.2.0
spec.The request will not fallback from
2.2.0
to2.1.0
if you send a2.2.
0 specific value in a field that was present in the2.1.0
spec as well. For example, if you set the field value of thethreeDSRequestorAuthenticationInd
field (present in both the2.1.0
and the2.2.0
spec) to07
(billing agreement). Here the field value07
is available in the2.2.0
spec only.
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.
note
When you send an authenticate request on behalf of a service provider merchant, there are few extra required fields that you must send. For details on these fields, see the authenticate request sample in either the all-in-one workflow or the toolkit workflow topic.