recurly.Risk().ThreeDSecure() lets you trigger and complete Strong Customer Authentication (SCA) in-browser. Pass the three_d_secure_action_token_id (or proactive token) you received from the Recurly API, attach the component to an element on your page, and listen for either a token (success) or error event. The library handles device-fingerprinting, challenge display, and returns a three_d_secure_action_result token you can use in any subsequent API call (purchase, subscription, billing-info update, etc.).

Prerequisites & limitations

• Your site must use a gateway that Recurly supports for 3DS 2.x (e.g., Braintree, Cybersource, Worldpay, Adyen).
• You must already have an action token from the Recurly API (three_d_secure_action_token_id or proactive token).
• threeDSecure.attach() must be called from a user-initiated event such as click or touchend—otherwise browsers will block the pop-up/iframe.
• By default Recurly performs gateway device-data pre-flights; you may disable them (preflightDeviceDataCollector: false) only if you are certain no challenge will be required.
• Proactive 3DS (authenticate before the first transaction) is currently available only for Braintree; enable it via risk.threeDSecure.proactive in recurly.configure.
• Provide a visible container element (~250 × 400 px) for the challenge; remove or hide it only after a token or error event.
• The resulting three_d_secure_action_result token expires in 20 minutes and cannot be recovered after expiry.

Key details

Strong customer authentication for your users.

Recurly.js provides a set of utilities that allow you to support 3-D Secure authentication on your checkout page seamlessly. For more information on 3-D Secure, see our Introduction to Strong Customer Authentication.

Recurly's support for 3-D Secure utilizes both Recurly.js and our API. For a complete guide to this integration, start with our Strong Customer Authentication (SCA) Integration Guide.

Let's take a look at an example implementation.

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

threeDSecure.on('token', function (token) {
  // handle passing the action result
  // token back to your server

  // token.type => 'three_d_secure_action_result'
  // token.id

  // optionally, you may call threeDSecure.remove() to remove the element
});

threeDSecure.on('error', function (error) {
  // handle error scenarios.

  // error.code
  // error.message

  // optionally, you may call threeDSecure.remove() to remove the element
});

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

Additional Configuration

Preflights

Some gateways such as World Pay and Cybersouce, have API calls as a part of
their device fingerprinting required for 3DS2. By default if you have Cybersource or World Pay configured in Recurly to handle 3DS2 transactions Recurly.js will make this API calls by default to ensure your implementation is properly handling 3DS2 challenges.

Below is an example of disabling this preflight fingerprinting for said gateways
above.

recurly.configure({
  // ...
  risk: {
    threeDSecure: {
      preflightDeviceDataCollector: false,
    }
  }
  // ..
});

You may want to use the config above, if you are handling a transaction you are
confident will not be challenged. It is important to note, that if the issuing bank or gateway does request a challenge, you will not be able to handle the challenge if this configuration is in use.

Proactive 3D-Secure

You can take your customers through Strong Customer Authentication before their initial transaction to store their card details by enabling Proactive 3D-Secure.
This feature is currently available for the following gateways:

• Braintree

Below is an example for enabling this feature.

recurly.configure({
  // ...
  risk: {
    threeDSecure: {
      proactive: {
        enabled: true,
        gatewayCode: "abc123",
        amount: 0.00
      },
    }
  }
  // ..
});

With proactive 3D-Secure enabled, you will receive a three_d_secure_proactive_action_token when you
tokenize your billing information. This value can be passed in as an actionTokenId to the threeDSecure class to enable the Strong Customer Authentication flow.

Reference

fn recurly.Risk

Arguments

None.

Returns

A new Risk instance

fn recurly.ThreeDSecure

Arguments

Returns

A new ThreeDSecure instance.

fn threeDSecure.attach

Arguments

Returns

Nothing

events Emits

token

This event is fired when your customer has completed the 3-D Secure flow. Recurly has received the authentication details, and generated this token to be used in our API.

Signature

error

This event is emitted when any error is encountered, whether during setup of the 3-D Secure flow, or during authentication. It will be useful to display errors to your customer if a problem occurs during the 3-D Secure flow.

Signature