Prerequisites & limitations

• Your site must use a gateway that Recurly supports for 3-D Secure 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 a 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.enabled: false) only if you're certain no challenge will be required.
• Proactive 3-D Secure (authenticating 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, and 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.

Definition

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

Pre-flight 3-D Secure authentication

Recurly.js will perform some pre-flight authentication steps prior to tokenization. If you use a gateway that's compatible with this process, it happens automatically.

This process can be prevented with the following configuration value:

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

Re-authenticating existing billing information

You can collect device data to re-authenticate existing billing information by providing the billing info ID alongside the CVV element.

Below is an example of configuring preflight fingerprinting for existing billing infos for Cybersource and WorldPay gateways.

recurly.configure({
  // ...
  risk: {
    threeDSecure: {
      preflightDeviceDataCollector: {
        enabled: true,
        billingInfoId: "abc1234"
      },
    }
  }
  // ..
});

Proactive 3-D Secure

Recurly.js can perform Strong Customer Authentication prior to an initial transaction. This feature is currently available only if you are using a Braintree gateway.

Enable proactive 3-D Secure with the following configuration:

recurly.configure({
  // ...
  risk: {
    threeDSecure: {
      proactive: {
        enabled: true,
        gatewayCode: 'my-gateway-code',
        amount: 0.00
      },
    }
  }
  // ..
});

With proactive 3-D 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

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.

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.