3D secure 2.0 integration guide

The purpose of this guide is to provide you with the information you need to fully implement Strong Customer Authentication (SCA) using the 3-D Secure (3DS) protocol in order to satisfy the requirements of Payment Services Directive 2 (PSD2). If you haven’t already, we recommend that you read more about PSD2, 3DS, and SCA here before proceeding with this guide. You can also refer to the Key Terms and Glossary section of this guide to refresh your memory on any important definitions.

While SCA largely consists of an integration effort between you and your configured payment gateway(s), Recurly, as your billing solutions provider, is here to help make the integration as easy as possible. As such, we have made key updates to several of our existing platform components in order to help facilitate SCA requirements in relation to PSD2. This document is here to provide you with a high-level understanding SCA, the Recurly solution, and a step-by-step guide to help you complete the integration.

Estimated completion time

3 Hours

Key Terms / Glossary

Here are a few key terms that will be referenced throughout this guide.

• Access Control Server (ACS)

  A service either hosted or related to the Issuing bank. Responsible for issuing challenge URLs, generating device fingerprints, and verifying that the cardholder is non-fraudulent.

• Merchant plug-in (MPI)

  A module, designed to facilitate 3-D Secure verification and prevention of payment card fraud. Verifies the card number with the card issuing bank and checks if it is enrolled in the 3-D Secure program. Typically provided by your payment gateway and used to facilitate interactions between merchants and the issuing bank responsible for completing the SCA process. The Recurly SCA framework wraps MPI functionality provided by various payment gateways.

• Strong Customer Authentication (SCA)<

  Requirement mandated by the European Economic Area (EEA) that ensures electronic payments are performed with multi-factor authentication. For more details check out our docs.

• 3-D Secure (3DS)

  E-commerce authentication protocol that implements SCA. There are currently two versions of the protocol in effect, with 3DS 2.0 being the newest, and 3DS 1.0 used as a fallback until it is completely retired at a later date.

• Payment Services Directive 2 (PSD2)

  EEA directive that is enforced as of September 14, 2019 requiring SCA to be in place. For more details check out our docs.

Understanding the SCA Flows

SCA can be subdivided into a few different flows, each of which requires various degrees of engagement from your customers and/or a few extra steps from you in the implementation process. The Recurly SCA framework and this integration guide provides you with everything you need to account for each, but it is helpful to understand them and when they come into play.

Frictionless

Just as the name implies, this requires the least amount of effort from you and your customers. In fact, it is completely seamless and is the most ideal case if it can be facilitated. In this flow, the card Issuer determines that it has enough information to authenticate the transaction without any further verification steps. As part of the initial authentication attempt, Recurly will pass on any available customer details to your payment gateway via the provided MPI, which will work with the Issuers’ ACS to determine if a frictionless flow can be used for the transaction.

Fingerprint

In some cases, the Issuer may require a device fingerprint as additional verification data before it will authenticate the transaction. While this will not require any interaction from your customers, there are a few extra steps, detailed in the step-by-step guide below, that are required on your part to ensure this happens.

Challenge

This flow requires direct interaction between your customer and the Issuers’ ACS before authentication can be confirmed. If a challenge is requested, your customer will be prompted for extra information to further prove their identity.

The Recurly SCA Solution

The Recurly solution to SCA is comprehensive and designed to simplify the process for you as much as possible. Because most payment gateways have taken a slightly different approach to implementing their MPIs, integrations can be substantially different and could require heavy development effort on your part. As such, we have designed our SCA solution with the following as key design goals:

Simplify Complexity

Our solution minimizes the complexity and effort required for you to integrate by building high-level abstractions around the low-level functionality provided by many of the payment gateway MPIs.

Payment Gateway MPI Agnostic

The Recurly solution provides a one-to-many integration that normalizes payment gateway specific implementations, giving you the flexibility to use the solution that you need today, without being locked into it should your business needs evolve. This allows you to build your SCA flow once without the need to start from scratch if you decide to migrate to a different payment gateway.

Required Components and Prerequisites

Recurly.js

The existing Recurly.js JavaScript library has been enhanced to provide you with the functionality needed to implement the client side requirements of 3DS2 / SCA, such as device fingerprinting and rendering the challenge flows. This functionality is provided as a wrapper interface around the many client side libraries maintained by the various payment gateways. Recurly.js version 4 is required for 3DS2 / SCA

If you are not already using Recurly.js for other purposes, you can read more about it here, and / or follow this guide to get up and running.

Recurly API / Client Libraries

You will need to use version 2.21 (or higher) of the Recurly API or one of its associated client libraries for 3DS2 / SCA. Usage of Recurly API v3 is strongly encouraged.

If you are using our API or client libraries for the first time, you can get started here. If you are upgrading from an earlier version of the API or a client library you can use this upgrade guide.

Key Objects & Parameters

The following list provides a quick reference for several key objects and parameters that will be used in conjunction with Recurly.js and the Recurly API in order to implement SCA.

• Credit Card Token

  Secure token generated by Recurly.js to encapsulate sensitive billing information such as customer credit card numbers. Also includes additional customer / browser data collected by Recurly.js and used for SCA purposes.

• 3-D Secure Action Token

  Token generated by Recurly API to encapsulate data needed for Recurly.js to initiate the client-side authentication challenge and / or device fingerprinting.

• 3-D Secure Action Result Token

  Token generated by Recurly.js to encapsulate data captured as a result of the client-side authentication challenge and / or device fingerprinting.

• Recurly.js ThreeDSecure Class

  Recurly.js class that is instantiated to provide SCA-specific client-side functionality such as handling challenge flows.

Integration Guide

Step 1: Collect payment data with Recurly.js

In most cases, credit card tokenization with Recurly.js is optional from a 3DS2 / SCA perspective (see the callout below for cases where it is required). However, you may want to consider using it as we have enhanced Recurly.js to collect additional customer data ( ie. browser info) as part of the credit card tokenization process. When possible, this data is passed on to the Issuers’ ACS via the payment gateway MPI in the initial authentication request, and could increase the chances that the transaction is approved in a frictionless manner.

If you are already using Recurly.js to tokenize customer credit cards then there is no additional action required, as the enhancement described above will work automatically once you’ve upgraded to Recurly.js version 4

If you’re interested in taking advantage of this feature, see this section of our documentation to get up and running with Recurly.js credit card tokenization. Again, this step is optional, but could lead to an increased number of transactions that are approved via the frictionless flow, which is beneficial from a customer experience and conversion perspective.

If you are using Cybersource or Worldpay as your payment gateway, they require an API call as apart of their device data collection. This can slow down your customers check out experience as it is an extra round trip through Recurly and the gateway. If you are confident the customer in session will not be challenged by their issuing bank, you can disable this call in your Recurly.js config to improve their customer experience.

Step 2: Submit a transaction request

If you have decided to tokenize the credit card as described in Step 1, you are now able to send it along to the appropriate Recurly API endpoint to initiate the payment transaction. Otherwise, the raw customer billing info can be passed instead. Transactions can be requested using the Create Purchase, Create Subscription, or Collect Invoice endpoints.

Similar to the previous step, this guide assumes that you are already using Recurly API or the client libraries to process payment transactions with Recurly. As such, there should be no additional work required for this step in the SCA flow aside from ensuring that you have upgraded to (at least) version 2.21 of the Recurly API.

See the ‘Under the Hood’ section below if you’d like to know more about the enhancements Recurly has made to facilitate this step in the SCA flow, otherwise continue on to Step 3.

Step 3: Process the response

If the transaction request is successful, Recurly API will return a success response code to your server and no additional action is needed from an authentication perspective.

However, if the payment gateway requires additional action as part of the SCA flow, Recurly will indicate this with a new error code, called three_d_secure_action_required, in the API response.

If this error code is returned, it will be accompanied with a three_d_secure_action_token_id, which references the 3-D Secure Action Token that encapsulates data required for the next steps in the authentication flow. See below for the example response XML.

<errors>
  <transaction_error>
    <error_code>three_d_secure_action_required</error_code>
    <three_d_secure_action_token_id>ABCDEFGHIJKL012345</three_d_secure_action_token_id>
    ...
  </transaction_error>
  <transaction href="..." type="credit_card">
    ...
  </transaction>
</errors>

For your part, you will need to pass the three_d_secure_action_token_id from your server to the client and instantiate a new instance of the Recurly.js ThreeDSecure class, passing in the three_d_secure_action_token_id as a parameter. See below for an example.

const risk = recurly.Risk();
const threeDSecure = risk.ThreeDSecure({ actionTokenId: 'ABCDEFGHIJKL012345' });

If you’d like to know more details about what’s going on under the hood, take a look below, otherwise proceed to Step 4.

Step 4: Setup event handlers and initiate Fingerprint / Challenge

Next, you’ll need to setup event handlers on the instance of the Recurly.js ThreeDSecure class that you created in the previous step. These event handlers will process the success and error responses related to the Fingerprint / Challenge results returned from the Issuers’ ACS.

threeDSecure.on('error', err => {
  // display an error message to your user requesting they retry
  // or use a different payment method
});

threeDSecure.on('token', token => {
  // send `token.id` to your server to retry your API request
});

If the Fingerprint or Challenge is successful and the ‘token’ handler is triggered, Recurly.js will pass in a three_d_secure_action_result_token_id, which references the 3-D Secure Action Result Token which in turn encapsulates data returned from the Issuers’ ACS. With this handler you should pass the token id back to your server and then retry the original purchase request via the Recurly API. Step 6 of this guide will provide further details on this.

Step 5: Initiate the Fingerprint / Challenge

Once your event handlers are setup, you’ll need to initiate the Fingerprint / Challenge flow by attaching a reference to an HTML element to your instance of the Recurly.js ThreeDSecure class. This HTML element is a container for Recurly.js to render UI elements related to the challenge.

threeDSecure.attach(document.querySelector('#my-container'));

Recurly.js will then initiate the Fingerprint / Challenge using the appropriate payment gateway provided JavaScript library. Once completed, the event handlers that you setup in the previous step will be called depending on if there’s a success or failure.

Of course, there’s a lot more going on behind the scenes. See below if you’d like to know more, or move on to step 6.

Step 6: Submit new purchase request

As part of the success event handler that you setup in step 4, initiate a new request to Recurly API from your server using the provided three_d_secure_action_result_token_id. Recurly will use this token id to unpack data from the 3-D Secure Action Result Token and pass it on to your payment gateway when it attempts to authenticate the transaction once again.

If the request is successful, then no further action is required. If the request results in an error, you should handle this per your current standard integration (ie. collect alternate payment from the customer and retry the transaction)

Step 7: Testing

Test that your integration can handle all SCA flows properly by using the Recurly Test Gateway and one of the following four test credit cards depending on the flow that you’d like to verify. Your Recurly site must be in ‘Sandbox’ mode in order to use the Test Gateway.

The following test credit card can be used to test recurring transaction challenges (dunning flow) as well as the ‘Update Subscription’ endpoint. It will simulate a 3DS2 challenge any time a transaction is attempted:

4000008400001629

Additional Support

If you need additional support with your SCA integration, do not hesitate to contact our support team.