Integration overview

On this page

3D Secure 2 (3DS 2) is the new authentication protocol for eCommerce card payments. Whether you are an existing Elavon customer or not, you can still add Elavon's 3D Secure (3DS) solution to your transaction authentication process. Merchants can use Elavon's 3DS 2 solution either as a standalone service or as a feature within an existing Elavon product. The best integration option for your business may depend on items such as your technical implementation, business model, and strategies for managing fraud.

Option 1 - 3DS 2 as a standalone service

To use the 3DS 2 solution as a standalone service, use one or a combination of these options:

  • Integrate directly with Elavon's 3DS Server
  • Integrate using Elavon's 3DS Web SDK
  • Integrate using Elavon's Mobile SDKs (iOS/Android) (Releasing soon)

This option is suitable for the following merchants:

  • Any merchant that processes their payments with Elavon or a certified third-party processor.
  • Merchants that use external or third-Party eCommerce solutions but process via Elavon.
  • Merchants that have multiple processors.

High-level features of the standalone integration options

Direct to 3DS Server

  • Direct communication between the merchant's server (backend) and the 3DS Server.
  • Merchant has more control over each part of the integration process.

    For example, you can control how to handle the challenge flow when the issuer returns the challenge response, you can set the preference to challenge the user or not, you can control where the authentication request should be called in the payment flow, and you can do an inventory check-in between a payment flow.

  • Requires extra development effort as compared to the other integration options.

    The development effort required for each merchant varies and depends on factors such as the technical expertise of the development team, understanding of the payment industry, and usage of similar products. However, Elavon's developer documentation guides you step-by-step in the deployment process with sample codes, requests, and responses.

Integration steps for direct integration to the 3DS Server

3DS Web SDK

  • A JavaScript library built on the Elavon 3DS Server API for an easy integration option to handle different 3DS authentication flows.
  • Ideal for merchants who want to add 3DS 2 support to their existing web-based checkout solution.
  • Minimal development effort required if using the all-in-one workflow of the Web SDK.

    The all-in-one workflow is prepackaged with all features and is ready to use once integrated with the merchant's payment page. It runs all steps in the 3DS payment processing with one function call.

  • For granular control over the 3DS flow, the Web SDK also provides individual 3DS steps as a "toolkit" of functions that merchants can call as required.
  • Once integrated into a merchant's website or checkout page, the Web SDK handles the communication with the 3DS server to complete the 3DS flow on behalf of the merchant.
  • Supports browsers on both mobile and desktop devices. Also, supports the use of the Web SDK (JavaScript) in a native mobile app through the use of a WebView.
  • Web SDK demo app available to understand the capabilities offered by the all-in-one and toolkit workflows of the Web SDK before actually integrating it into the payment page.
Integration steps for the Web SDK

Mobile SDKs (Releasing soon)

  • Ideal for merchants who have all or most transactions via their shopping app.
  • Built over the 3DS API for easy integration into a merchant's mobile app.
  • Initiates and handles the complete 3DS transaction flow on behalf of the merchant.
  • Sample apps available to understand the capabilities offered by the mobile SDKs before actually integrating them into the merchant's app.

Option 2 - 3DS 2 for Elavon merchants using Converge

Converge for merchants in European Union (EU)

Converge supports three integration methods: open_in_new

  1. Direct API - To use the 3DS 2 feature, you need to either integrate the 3DS Web SDK to your website or set a direct integration to the 3DS Server.

  2. Hosted Payments Page - To configure a hosted payments form, you can use one of the options.

    a. Lightbox - To use the 3DS 2 feature, when you create a payment session through the Converge API (POST /payment-sessions), set the doThreeDSecure field value to true. For details on the API call, see the Converge API Reference documentation open_in_new.

    b. Redirect - To use the 3DS 2 feature, when you create a payment session through the Converge API (POST /payment-sessions), set the doThreeDSecure field value to true.

    c. Payment Link - When you send a payment link via the Converge UI, the 3DS 2 authentication check is enabled by default.

  3. Shopping cart plugins - The shopping cart plugins built by Elavon support 3D Secure 2.0. For details, see the documentation for the supported plugins open_in_new.

Converge for merchants in North America (NA)

error_outline

note

At present, the 3D Secure 2 Service through Converge is available only for merchants in the United States (US).

Prerequisite

To enable the 3D Secure 2 feature as part of Converge,

  • new merchants should request the sales consultant to include 3DS 2 as part of their Converge integration

  • existing merchants should call Elavon support

Integration options

  • Hosted payments page (HPP) - automatically uses 3D Secure 2 for all transactions made using a terminal that meets the general requirements for using 3D Secure 2 with Converge.

  • Lightbox - automatically uses 3D Secure 2 for all transactions made using a terminal that meets the general requirements for using 3D Secure 2 with Converge.

  • Buy button / Payment link - automatically uses 3D Secure 2 for all transactions made using a terminal that meets the general requirements for using 3D Secure 2 with Converge.

  • Billing & Invoicing - automatically uses 3D Secure 2 for all transactions made using a terminal that meets the general requirements for using 3D Secure 2 with Converge.

  • Checkout.js - merchants can either embed the Web SDK in the checkout page or for granular control, manually implement a Checkout.js page with 3D Secure 2 flow. For more details about how to use this option, see this checkout.js example HTML form open_in_new.

  • XML API - Use one of the standalone options to use the 3D Secure 2 service. If you want to use the 3D Secure 2 Web SDK for an XML API integration, see this example code open_in_new.

For more details about these integration options for Converge NA, see 3D Secure 2 Integration options open_in_new.

Sample use cases for different integration options

These sample use cases are some examples of integrations that you can use. You can invent your own integration type that meets your requirement.

Integration type Features Sample use cases
Web SDK (JavaScript)
  • Easiest integration option to handle the 3DS 2 flow in browsers with minimal programming effort.
  • The all-in-one workflow handles the complete 3DS flow, 3DS 1 fallback (optional), and challenge (if required) with one function call.
  • Supports browsers on both mobile and desktop devices.
  • Supports hybrid integrations (see the last row in this table for example use cases).
  • You want an easy and quick way to integrate the 3DS 2 service.
  • Your platform is web-based or the processing is typically performed on the front-end (i.e., in the web browser).
  • You want to embed the JavaScript library directly in your payment page (website) and your app (via WebView).
  • You are a FuseBox or a viaConex customer and you want to use 3DS 2.
Direct integration (API)
  • Direct communication between the merchant's server (backend) and the 3DS Server.
  • More control over each part of the integration process.
  • Only integration option that supports 3RI i.e., merchant-initiated transactions. For example, calls for a recurring subscription payment every month can only be initiated by the merchant's server which communicates directly to the 3DS Server.
  • Only integration option that supports decoupled authentication. For example, the client SDKs can only help to initiate a decoupled authentication check, but it is the 3DS Server that sends notifications to the merchant's server (notification endpoint) when it receives the final authentication result from the issuer.
  • You want to have more control over the 3DS Secure authentication check process.
  • Your business is unable to use a website or an application-based integration.
  • You are capturing cardholder data on your website without any encryption and then passing the cardholder data to your server for authentication with the processor.
  • You want to use decoupled authentication or 3RI as the supported form of authentication.
  • You are a FuseBox or a viaConex customer and you want to use 3DS 2.
Native Mobile App SDK (iOS / Android) (Releasing soon)
  • Easy integration into a merchant's mobile app by importing the SDK within your application codebase.
  • Mobile SDKs initiate and handle the complete 3DS transaction flow.
  • All the features of 3D Secure 2 check optimized for native Android & iOS app, instead of the website.
  • You have a major share of the customer base who uses your native mobile app for Android and iOS.
  • You want to integrate the 3DS 2 features into your mobile app.
Converge for merchants in NA (US)
  • No extra development work is required for these integration options: Hosted payments page (HPP), lightbox, buy button or payment link, and billing & invoicing.
  • Minimal development effort if using the checkout.js option.
  • For customers using the converge API, integrate using either the direct integration to the 3DS Server or the Web SDK.
  • You are a merchant in NA (US) and you are already using Converge as your payment processing system.
  • You want all the features of 3D Secure 2 without the complexity of manual programming or integration.
Converge for merchants in EU
  • 3DS Web SDK is now embedded in Converge EU and no extra integration effort is required.
  • All integrations options support 3DS: lightbox, redirect, or payment links.
  • You are a merchant in the EU and you are already using Converge as your payment processing system.
  • You want all the features of 3D Secure 2 without the complexity of manual programming or integration.
Hybrid integration A combination of one or more integration options. See the sample use case column for examples. Direct API + Web SDK (all-in-one workflow) example
You capture the cardholder data on your website (Web SDK integration), store the tokenized card details on your server, and then use the card-on-file details for subsequent subscription-based transactions (send a merchant-initiated request also called 3RI via Direct API).
In a reverse scenario, if the results of a 3RI transaction return that the card is no longer valid, you can direct the cardholder to authenticate a new card through your website (Web SDK integration).
Web SDK + Mobile SDK example
Your customer base equally uses your website and mobile app for shopping. In this scenario, you can integrate the Web SDK JavaScript file on your payment page and the Mobile SDKs into your native apps.
Web SDK + Converge (Checkout.js) example
For a simpler integration, you can embed the Web SDK into your checkout.js page. In this case, the Web SDK handles the complete 3D Secure 2 check for you.
Optionally, you can use the Web SDK to perform 3DS 2 authentication and then pass the authentication values into checkout.js for payment authorization. Your native app (mobile) users can use the same Web SDK integration in their mobile apps by using WebView components. This integration mode gives you more control over authentication errors.

High-level integration steps for developers

Use these high-level steps to guide you through the integration process.

Step 1: Review the 3D Secure solution integration options

Review the Getting Started page for a high-level detail of 3D Secure 2 and the different transaction authentication flows in 3DS 2 (frictionless and challenge). Once you are familiar with 3D Secure 2, review the supported integration options on this page to use Elavon's 3D Secure solution.

Step 2: Get authentication credentials

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

3D Secure 2 test credentials request form open_in_new

We will send you the credentials by the next business day. We will also send contact details to whom you can reach out for any assistance required during the integration and testing process.

Additional resource

Step 3a: Sandbox testing if integrating directly with the 3DS Server

Follow these high-level steps to test your server's integration with the 3DS Server.

Action 1: Collect the required cardholder and transaction details.

Action 2: (Optional) To verify if the cardholder's account number supports 3DS 2, send a /lookup request.

Action 3: To initiate a 3DS 2 authentication check, send all required and optional (if available) cardholder and transaction details in an /authenticate request.

Action 4: Verify the authentication response and use the information in the 3DS 2 test cards table for the next steps for the transaction status (transStatus) you received in the response.

Additional resource

A. Detailed steps to follow when integrating directly with the 3DS Server. (Action 1 - 4 in Step 3a)

B. Test card numbers to test different authentication scenarios with various card schemes.

Step 3b: Sandbox testing if using the Web SDK

Follow these high-level steps to test your integration through the Web SDK.

Action 1: Embed the Web SDK JavaScript file to your payment page.

Action 2: Access the Web SDK functionality from the window object (window.Elavon3DSWebSDK)

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

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

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

Action 5: Call the web3dsFlow method (sdk.web3dsFlow(data))

This method will run the 3DS flow and display and handle any cardholder challenges if required by the issuer.

Action 6: Use authentication values received from the issuer in Action 5 to confirm the order.

Additional resource

A. Detailed steps to follow when integrating using the all-in-one workflow of the Web SDK (Action 1- 6 in Step 3b)

B. Test card numbers to test different authentication scenarios with various card schemes.

Step 4: Begin the onboarding process

After you have tested the different integration options, work with the Elavon representative to begin the onboarding process.

Before you go live, check for the following:

  • You have the production endpoint and credentials.
  • You have run different test scenarios such as frictionless, challenge, 3DS 1 fallback, and 3RI in the UAT (sandbox) environment. This step will give you the confidence to handle different scenarios in a production environment.
  • You are boarded for all right card schemes. If you don't have the required details, check with your Elavon contact.
  • If you are using 3D Secure through Converge, then work with your Elavon contact to check that all required elements are enabled for your Converge environment.

Step 5: Go Live!

Action 1: Activate your production account.

Action 2: Connect your production environment to Elavon's production server.

Action 3: Go Live!

Related topics