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: #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 SDK

Toolkit 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 SDK

note

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 application

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

A diagram explaining how the request and responses flow among the Web SDK and the servers involved in 3DS authentication of a transaction. The information in the diagram is the same as the textual explanation in this section.

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

messageVersionclientStartProtocolVersionclientEndProtocolVersion3DS Server Fallback Strategy
1.0.21.0.21.0.2Always use 3DS 1.0.2
1.0.21.0.22.1.0Always use 3DS 1.0.2
2.1.01.0.21.0.2Error response
2.1.01.0.22.1.0Check support for 3DS 2.1. If supported, use 3DS 2.1 and if not supported, fall back to 3DS 1.0.2.
2.1.02.1.02.1.0Check 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.

Related topics