Integrate using the Web SDK
note
EMV 3D Secure 2.1 is a new offering by Elavon. If you have identified any errors or gaps in the content, please contact: email#SEDevPortalSupport@elavon.com
On this page:
Web SDK Overview and Workflow
You can add 3D secure 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. Elavon’s Web SDK supports two different workflows for authenticating a transaction:
- All-in-one
- Toolkit
All-in-one workflow
Use the all-in-one workflow of the Web SDK when you want an easy way to add Elavon’s 3DS 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 workflows.
Use the all-in-one workflow of the SDKToolkit workflow
Use the toolkit workflow of the Web SDK for scenarios where you may have a mixed mode integration between the backend server environment and the client-side browser. 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 SDKnote
You cannot use the Web SDK or the Mobile SDKs to send a 3RI (merchant-initiated) authentication request (i.e. deviceChannel = 03
). For more details, see 3RI overview
Web SDK 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 applicationWeb SDK Workflow Diagram
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. The 3D Secure processing will end here for such a transaction and the flow will be classified as a frictionless flow.
But, 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. This flow is classified as a challenge flow.
Figure caption: Frictionless and challenge workflow in a Web SDK integration
Web SDK 3DS 1 Fallback Support
If you are an integrator who only supports 3D Secure 1 (3DS 1) or if the issuer does not support 3D Secure 2 (3DS 2), you can still integrate Elavon’s 3DS Web SDK to your website. With this release, transactions that need 3DS 1 authentication are appropriately redirected by the Web SDK to the 3DS 1 authentication flow. Table 1 shows how the following fields in the authenticate request help the 3DS Server decide whether to follow 3DS 2 or 3DS 1 authentication flow: messageVersion
, clientStartProtocolVersion
, and clientEndProtocolVersion
Table 1: 3DS Server Fallback Strategy
messageVersion | clientStartProtocolVersion | clientEndProtocolVersion | 3DS Server Fallback Strategy |
---|---|---|---|
1.0.2 | 1.0.2 | 1.0.2 | Always use 3DS 1.0.2 |
1.0.2 | 1.0.2 | 2.1.0 | Always use 3DS 1.0.2 |
2.1.0 | 1.0.2 | 1.0.2 | Error response |
2.1.0 | 1.0.2 | 2.1.0 | Check support for 3DS 2.1. If supported, use 3DS 2.1 and if not supported, fall back to 3DS 1.0.2. |
2.1.0 | 2.1.0 | 2.1.0 | Check support for 3DS 2.1. If supported, use 3DS 2.1 and if not supported, return an error. |
note
Currently, our 3DS Servers support 3DS 1 transactions for only MasterCard, VISA, and AMEX.
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 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 their payments 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 topics.