• Content

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

Merchant Initiated Transactions (MIT) and Dunning

For recurring, Merchant Initiated Transactions (MIT), SCA should not be required. However, there will be scenarios where a SCA challenge may still be presented by a customer’s issuing bank, which will require customer authentication. In order to assist you in recovering revenue that may be lost from failed MITs, Recurly has built support for a flow to complete a SCA challenge for re-authentication. Please see setup instructions for our fully hosted dunning solution here

If you’d like to implement your own dunning solution, you can listen for the new dunning event webhook which will be sent when a recurring payment fails due to an Issuers request for 3DS2 authentication. The payload will indicate that the failure type is three_d_secure_action_required and provide the relevant invoice number. The Collect Invoice endpoint can then used to finalize the transaction. The guide below, starting at step 2 can be used for reference.

The 3DS2 dunning flow, hosted or custom, can be tested with the following test credit card: 4000008400001629

PSD2 Exemptions for Mail Order Telephone Order (MOTO) Transactions

This guide is focused on helping you to support 3DS2 integrations for scenarios where your customers are ‘in session’ and directly interacting with the transaction flow online. If you are supporting or building a solution that is used by call center agents who complete transactions on behalf of customers over the phone, you can bypass 3DS2 / SCA as these types of transactions are exempt from PSD2. This is done by passing an exemption flag via the Recurly API. See the reference documentation for more details.

Please be aware that certain payment gateways require additional configuration in order for MOTO exemptions to work properly. See our gateway specific documentation for details.

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.


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.


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.


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


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

See the Recurly.js 3-D Secure documentation for a complete reference.

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 using the Wirecard, Sagepay, Cybersource or Worldpay gateways, credit card tokenization with Recurly.js is required for all 3DS2 flows. These gateways require device data to be sent with the initial transaction.

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.

if you are using Cybersource or Worldpay and disable preflight device data collection, and the customers issuing bank issues a challenge. Your customer will not be able to complete their transaction.

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.

Under the Hood

Once your request is received by the Recurly platform, billing info details, including the browser-level details required for SCA, will be extracted from the Credit Card Token and passed through to your payment gateway. If you are not tokenizing your credit cards with Recurly, we will use the raw credit card / billing info passed in the request to initiate the SCA process via the payment gateway.

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.

  <transaction href="..." type="credit_card">

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.

Under the Hood

When you instantiate the Recurly.js ThreeDSecure class with the three_d_secure_action_token_id, Recurly.js unpacks the associated 3-D Secure Action Token in order to extract several details required to execute the next steps in the SCA flow on your behalf. For instance, one data point instructs Recurly.js as to which type of challenge to present to the customer (i.e. fingerprint, etc.), while another data point tells it which payment gateway MPI to leverage in order to complete the challenge.

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.


The UI elements that Recurly.js injects will size to the dimensions of your container. Since the flow itself must be contained within an iframe controlled by your customer’s bank, we are unable to dynamically size the flow. Thus, we recommend that your container have specific dimensions set at a minimum of 250px (W) x 400px (H), and contain an interstitial message to explain that 3-D Secure authentication will be required to complete the transaction.

Certain payment gateways (e.g. Stripe) will render the challenge frame as a modal interface, therefore it is advised that you do not place your container in a modal of your own.

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.

Under the Hood

Because every payment gateway provides a different JavaScript library to complete the Fingerprint / Challenge step in the SCA flow, Recurly.js implements several different wrapper components and then leverages the correct one based on information encapsulated in the 3-D Secure Action Token. However, it does this without requiring your code to know the difference or couple itself to any specific integration.

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.

The three_d_secure_action_result_token_id is a valid parameter on the Create Billing Info endpoint and on any Recurly API endpoint that accepts a Billing Info, including Create Purchase, Create Subscription, Update Subscription, Create Account, Collect Invoice, Create Gift Card.

When you submit the new request it is essential that the Account / billing info / credit card token match that of the previous request as the authentication data encapsulated in the 3-D Secure Action Result Token is tightly coupled to the payment information and customer account. Changing the Account / billing info / credit card token between requests will result in a token mismatch error.

It is also invalid to mix and match 3DS Action Result Token Ids between different API endpoints. For example, A 3DS Action Result Token Id obtained as part of the authentication process with the Create Account / Billing Info endpoint, can not be passed into the Create Subscription endpoint. A new token must be generated in this case if the endpoint requires 3DS2 authentication.

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)

Note: It is possible to get 3DS2 / SCA challenge requests on an Account / Billing Info that has been previously authenticated when you make subsequent API calls at a later date/time. For example, an API call to update a subscription could result in a new authentication challenge even if the initial action to create the subscription passed authentication.

Under the Hood

When your server submits the new purchase request to Recurly API along with the three_d_secure_action_result_token_id, Recurly unpacks the authentication data returned from the Issuers’ ACS and then reattempts the authentication with your payment gateway based on their specific schema and API. The response data is then normalized and returned to your server per the Recurly spec.

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.

Card Number Behavior
4000000000003220 challenge flow
4000000000003063 (device) fingerprint flow
4222222222222220 approved fraud review ( frictionless flow)

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:


When you are ready to test the integration with your payment gateway, contact the Recurly support team for assistance in configuring your site in ‘Development’ mode. You’ll need to contact your gateway in order to obtain their specific set of test credit cards for 3DS2. Please also see our guide on gateway specific configurations here.

SagePay is not supported for testing in Development mode at this time due to requirements that cannot be implemented outside of Production mode. Testing will need to be performed in Sandbox mode, using the Recurly Test Gateway and test credit cards.

Braintree supports 3DS2 testing in Development mode, but an amount of ‘2099.00’ must be used to trigger the 3DS2 challenge frame. Also note that it is not possible to complete the authentication beyond the initial display of the challenge frame.

When updating subscriptions it is important to ensure that this configuration option is checked:

Configuration > Invoice Templates > Invoice Settings > Upgrades and Downgrades > Upgrades require paid invoice and successful transaction

Otherwise, the response will be a success even if the payment required a new 3DS challenge. Here you can find more details about this option.

Additional Support

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