availability

Our 3D Secure 2 integration is now available in production, and all merchants can integrate and test basic transaction processing flows using the latest versions of our client SDKs.

Minor changes were made to parameter names since the previous preview releases, so please make sure to verify your integration.

Some more advanced features documented on this page are still under development, and we'll continue to update our SDKs as issuing banks begin supporting 3DS 2. If you have questions about feature availability, contact us.

Start here

  • 3D Secure 2 (3DS 2) is the next iteration of the 3DS authentication protocol.
  • It satisfies the Strong Customer Authentication (SCA) requirements for European merchants transacting with European customers. In order to comply with SCA we recommend integrating 3DS 2 and testing as soon as possible.
  • 3DS 2 support is available in the latest major versions of our client SDKs: JavaScript v3, iOS v4, and Android v3.
  • 3DS 2 works on top of your existing 3DS 1 integration. The SDK will fall back to 3DS 1 when 3DS 2 is unavailable for the card being verified.
  • This migration guide will walk you through upgrading a legacy 3D Secure integration to 3DS 2.
important

If you don't have an existing 3DS integration, use our full, updated 3D Secure integration guide instead of this migration guide.

About 3DS 2

This new version of 3DS is designed to primarily do two things:

First and foremost, the protocol allows more data elements to be passed to issuing banks, which in turn allows them to perform a much more effective risk assessment of a given authentication. As a result, issuing banks will be able to allow more authentications to proceed without challenging the cardholder.

Second, the authentication challenges themselves are designed to be more effective and secure, especially for mobile devices, resulting in fewer authentication challenges and less friction during checkout workflows. You can find a lot more details and context in our blog post about 3DS 2.

Enabling 3DS 2

Drop-in UI

important

3DS 2 support requires Drop-in version 1.20.1 or higher.

To use 3DS, you will need to pass an object with relevant customer and transaction data into the threeDSecure field of the requestPaymentMethod options in order to minimize the need for issuing banks to present authentication challenges to customers. This object must contain an amount and should contain as many of the following fields as possible:

JavaScript
var threeDSecureParameters = {
  amount: '500.00',
  email: 'test@example.com',
  billingAddress: {
    givenName: 'Jill', // ASCII-printable characters required, else will throw a validation error
    surname: 'Doe', // ASCII-printable characters required, else will throw a validation error
    phoneNumber: '8101234567',
    streetAddress: '555 Smith St.',
    extendedAddress: '#5',
    locality: 'Oakland',
    region: 'CA',
    postalCode: '12345',
    countryCodeAlpha2: 'US'
  },
  additionalInformation: {
    workPhoneNumber: '8101234567',
    shippingGivenName: 'Jill',
    shippingSurname: 'Doe',
    shippingPhone: '8101234567',
    shippingAddress: {
      streetAddress: '555 Smith St.',
      extendedAddress: '#5',
      locality: 'Oakland',
      region: 'CA',
      postalCode: '12345',
      countryCodeAlpha2: 'US'
    }
  },
};

Then, create the Drop-in and pass in the 3DS parameters accordingly.

braintree.dropin.create({
    authorization: 'CLIENT_AUTHORIZATION',
    container: '#dropin-container',
    threeDSecure: true
}, function (err, dropinInstance) {
    if (err) {
        // Handle any errors that might've occurred when creating Drop-in
        console.error(err);
        return;
    }

    submitButton.addEventListener('click', function (e) {
        e.preventDefault();
        dropinInstance.requestPaymentMethod({
          threeDSecure: threeDSecureParameters
        }, function (err, payload) {
            if (err) {
                // Handle errors in requesting payment method
            }
            // Send payload.nonce to your server
        });
    });
});

Hosted Fields

important

3DS 2 support requires Braintree version 3.52.0 or higher.

To use 3DS, you will need to pass an object with relevant customer and transaction data into the threeDSecure field of the requestPaymentMethod options in order to minimize the need for issuing banks to present authentication challenges to customers.

This object must contain the following fields:

  • amount
  • bin
  • nonce

And should contain as many of the following fields as possible:

You will also need to implement the required callback onLookupComplete, which will be invoked after receiving the ThreeDSecure lookup response, before initializing the challenge and completing the flow.

JavaScript
var threeDSecureParameters = {
  amount: '500.00',
  nonce: NONCE_FROM_INTEGRATION, // Example: hostedFieldsTokenizationPayload.nonce
  bin: BIN_FROM_INTEGRATION, // Example: hostedFieldsTokenizationPayload.details.bin
  email: 'test@example.com',
  billingAddress: {
    givenName: 'Jill', // ASCII-printable characters required, else will throw a validation error
    surname: 'Doe', // ASCII-printable characters required, else will throw a validation error
    phoneNumber: '8101234567',
    streetAddress: '555 Smith St.',
    extendedAddress: '#5',
    locality: 'Oakland',
    region: 'CA',
    postalCode: '12345',
    countryCodeAlpha2: 'US'
  },
  additionalInformation: {
    workPhoneNumber: '8101234567',
    shippingGivenName: 'Jill',
    shippingSurname: 'Doe',
    shippingPhone: '8101234567',
    shippingAddress: {
      streetAddress: '555 Smith St.',
      extendedAddress: '#5',
      locality: 'Oakland',
      region: 'CA',
      postalCode: '12345',
      countryCodeAlpha2: 'US'
    }
  },
  onLookupComplete: function (data, next) {
    // use `data` here, then call `next()`
    next();
  }
};

Specify version: 2 in your options object when calling threeDSecure.create(). This allows your transactions to route through the 3DS 2 protocol whenever possible, and automatically fall back to 3DS 1 as needed.

var threeDSecure;

braintree.client.create({
  // Use the generated client token to instantiate the Braintree client.
  authorization: 'CLIENT_TOKEN_FROM_SERVER'
}, function (clientErr, clientInstance) {
  if (clientErr) {
    // Handle error in client creation
    return;
  }

  braintree.threeDSecure.create({
    version: 2, // Will use 3DS 2 whenever possible
    client: clientInstance
  }, function (threeDSecureErr, threeDSecureInstance) {
    if (threeDSecureErr) {
      // Handle error in 3D Secure component creation
      return;
    }

    threeDSecure = threeDSecureInstance;
  });
});

Then, call verifyCard, passing in the 3D Secure Parameters.

threeDSecure.verifyCard(threeDSecureParameters, function (err, response) {
  // Handle response
});

Client-side sandbox testing

The table below includes test cards for scenarios where the cardholder is given a challenge by their issuing bank (Challenge) or where the card issuer determines a challenge is not needed (No Challenge).

important

Use the card numbers below to test 3DS 2 on your client side in sandbox. Any other test cards will result in 3DS verification results that are not in the 3DS 2 format.

For expiration year values for all test cards in the table below, use the current year +3. The expiration month should always be 01. For example, if the current year is 2019, a valid test value for the expiration date would be 01/2022.

Status and Scenario Card brand specific test values
"Successful No-Challenge Authentication"
Cardholder enrolled, authentication successful, and signature verification successful.
Visa
  • 4000000000001000
  • 01/20**
Mastercard
  • 5200000000001005
  • 01/20**
Amex
  • 340000000001007
  • 01/20**
"Failed No-Challenge Authentication"
Cardholder enrolled, authentication unsuccessful. Merchants should prompt customers for another form of payment.
Visa
  • 4000000000001018
  • 01/20**
Mastercard
  • 5200000000001013
  • 01/20**
Amex
  • 340000000001015
  • 01/20**
"Attempt No-Challenge Authentication"
The provided card brand authenticated this 3D Secure transaction without password confirmation from the customer.
Visa
  • 4000000000001026
  • 01/20**
Mastercard
  • 5200000000001021
  • 01/20**
Amex
  • 340000000001023
  • 01/20**
"Unavailable No-Challenge Authentication from the Issuer"
Authentication unavailable for this transaction.
Visa
  • 4000000000001034
  • 01/20**
Mastercard
  • 5200000000001039
  • 01/20**
Amex
  • 340000000001031
  • 01/20**
"Rejected No-Challenge Authentication by the Issuer"
Authentication unsuccessful. Merchants should prompt customers for another form of payment.
Visa
  • 4000000000001042
  • 01/20**
Mastercard
  • 5200000000001047
  • 01/20**
Amex
  • 340000000001049
  • 01/20**
"Authentication Not Available on Lookup"
Authentication unavailable for this transaction.
Visa
  • 4000000000001059
  • 01/20**
Mastercard
  • 5200000000001054
  • 01/20**
Amex
  • 340000000001056
  • 01/20**
"Error on Lookup"
An error occurred while attempting to lookup enrollment.
Visa
  • 4000000000001067
  • 01/20**
Mastercard
  • 5200000000001062
  • 01/20**
Amex
  • 340000000001064
  • 01/20**
"Timeout on Lookup"
Attempting to lookup enrollment resulted in a timeout.
Visa
  • 4000000000001075
  • 01/20**
Mastercard
  • 5200000000001070
  • 01/20**
Amex
  • 340000000001072
  • 01/20**
"Bypassed Authentication"
Bypass used to simulate a scenario where merchant has elected to bypass the consumer authentication flow via CardinalCommerce Rules Engine configuration.
Visa
  • 4000000000001083
  • 01/20**
Mastercard
  • 5200000000001088
  • 01/20**
Amex
  • 340000000001080
  • 01/20**
"Successful Challenge Authentication"
Cardholder enrolled, authentication successful, and signature verification successful.
Visa
  • 4000000000001091
  • 01/20**
Mastercard
  • 5200000000001096
  • 01/20**
Amex
  • 340000000001098
  • 01/20**
"Failed Challenge Authentication"
Cardholder enrolled, authentication unsuccessful. Merchants should prompt customers for another form of payment.
Visa
  • 4000000000001109
  • 01/20**
Mastercard
  • 5200000000001104
  • 01/20**
Amex
  • 340000000001106
  • 01/20**
"Challenge Authentication is Unavailable"
Authentication unavailable for this transaction.
Visa
  • 4000000000001117
  • 01/20**
Mastercard
  • 5200000000001112
  • 01/20**
Amex
  • 340000000001114
  • 01/20**
"Error on Authentication"
An error occurred while attempting to authenticate. Alternatively, merchants can ask customers for an alternative form of payment.
Visa
  • 4000000000001125
  • 01/20**
Mastercard
  • 5200000000001120
  • 01/20**
Amex
  • 340000000001122
  • 01/20**

Server-side sandbox testing

If you call Transaction.Sale() without doing a 3DS authentication on the client-side, the issuing bank may return a soft decline indicating that the transaction requires 3DS authentication. In this case, 2099 - Cardholder Authentication Required will be returned. You can simulate this scenario by creating a test transaction in sandbox with an amount of 2099.

Verifications and recurring billing

Recurring transactions

The recommended flow for recurring billing would be to request a cardholder challenge to establish SCA when the card is first authorized as part of storing it to the Braintree vault. This can be with a verification, or the first transaction of a recurring billing event. By applying 3D Secure to the first transaction or verification, you signal to the card issuer that you have established a mandate between you and your customer to charge their payment method for subsequent recurring payments as detailed in your terms and conditions. Such subsequent transactions are exempt from PSD2 SCA requirements.

Establishing SCA on verifications will be useful for scenarios where the cardholder will not be present when the charge is issued, and the amount isn’t known when the payment method is stored. For example, if you have a metered billing flow and invoice customers at the end of a month based on their usage, you can use 3D Secure on your initial card verification to establish a mandate to create future merchant initiated transactions (MIT).

For subsequent transactions from that payment method, use the recurring value in the transaction_source parameter of the Transaction.Sale() API call.

Other merchant initiated transactions (MIT)

Other MIT transactions will be processed much the same way that recurring transactions would be. You would again request a cardholder challenge to establish SCA when the card is first authorized, establishing a mandate between you and your customer.

For subsequent transactions from that payment method, which would be out of scope for SCA, use the unscheduled value in the transaction_source parameter of the Transaction.Sale() API call.

Requesting a cardholder challenge

To override the default behavior of 3DS 2 and request the cardholder's bank to issue an authentication challenge, pass challengeRequested: true on the verifyCard() call.

Exceptions for already-stored payment methods

Exceptions would apply for payment methods stored before September 14, 2019, or subscriptions started before that date. For these payment methods, SCA would not have to be applied to the first authorization for subsequent transactions to be out of scope for PSD2.

As long as your payment methods are stored with Braintree, Braintree will automatically indicate to the card networks and issuers that these payment methods were stored before the PSD2 SCA enforcement date.

We expect, however, that you will have a lower decline rate if there has been at least one transaction or verification before September 14. This transaction history, in conjunction with the indicators Braintree will pass, will more clearly indicate to issuers that they will not be under regulatory pressure to decline recurring/MIT transactions from these payment methods. However, the transaction history is not expressly required.

What to expect after adopting 3DS 2

After adopting 3DS 2, you may still see 3DS 1 authentications using your updated integration. This is to be expected – 3DS 2 is an industry-wide initiative, requiring many parties' participation in order for a 3DS 2 authentication to be possible. Each party has steps to complete, and 3DS verification will use the 3DS 2 protocol once all parties involved in a given transaction have made the appropriate upgrades:

  1. You must update your integration to pass the necessary information to support 3DS 2 cardholder verifications.
  2. Braintree must work with acquirers to enable merchant accounts for 3DS 2.
  3. Cardholders' issuing banks must upgrade their systems to support 3DS 2 cardholder verifications.

By completing the steps in this guide, you ensure that everything on the merchant side is ready to go. You will start seeing 3DS 2 authentications as other parties complete their part of the protocol.

While the rest of the industry completes their work, Braintree’s integration will automatically fall back to a 3DS 1 authentication path on a transaction-by-transaction basis when 3DS 2 is not available from all parties involved.

Common questions

Do you have an example of how to integrate?

Yes, we have some examples in CodePen:

Can merchants customize the presentation of the bank challenge?

No. The presentation will be controlled by the issuing bank. This means that unlike prior versions, you will not need to provide the iframe or utilize the addFrame and removeFrame callbacks.

What happens if some of the additional parameters are not present?

The bank will decide if a challenge is necessary. Sending all additional parameters will result in the best chance for a frictionless experience.

Will vaulted credit cards be supported?

Yes, create a nonce from a vaulted credit card as usual.

Advanced features

Authentication Insight

availability

Authentication Insight is currently available in the Java server SDK for vaulted payment methods.

Support for other server SDKs, as well as client SDKs and support for non-vaulted payment methods, is currently under development.

Authentication Insight provides you with more details about the regulatory environment and applicable customer authentication regulation for a potential transaction. This empowers you to make an informed decision whether to perform 3D Secure authentication.

When you have a customer's payment method stored in your vault, you can request it on the server-side via the Java server SDK.

You can use the regulation environment information contained in the Authentication Insight to make a decision about whether to perform a 3D Secure verification, or continue without a verification. If you choose to perform a 3D Secure verification, proceed as usual using the payment method nonce.

The regulation environment field currently has three possible values:

Regulation Environment Description
psd2 The impending transaction (when using the provided payment method nonce and merchant account) is believed to be within scope of PSD2 SCA regulations, and requires 3D Secure authentication.
unregulated The impending transaction is not believed to be within scope of any SCA regulations, PSD2 or otherwise.
unavailable The impending transaction’s SCA regulation environment could not be determined.

As global regulations evolve, these values will continue to be updated.

To retrieve the Authentication Insight for a nonce, on the PaymentMethodNonceRequest, set the authenticationInsight boolean option to true and specify your merchantAccountId.

Java
PaymentMethodNonceRequest createRequest = new PaymentMethodNonceRequest()
.paymentMethodToken(PAYMENT_METHOD_TOKEN)
.merchantAccountId(MERCHANT_ACCOUNT_ID)
.authenticationInsight(new Boolean(true));

Result<PaymentMethodNonce> result = gateway.paymentMethodNonce().create(createRequest);

if (result.isSuccess()) {
  PaymentMethodNonce nonce = result.getTarget();
  AuthenticationInsight authenticationInsight = 
    nonce.getAuthenticationInsight();
  String customerAuthenticationRegulationEnvironment =   
    authenticationInsight.getRegulationEnvironment();
}

Access the AuthenticationInsight object on the nonce by calling nonce.getAuthenticationInsight(); access the regulation environment value by calling getRegulationEnvironment() on the AuthenticationInsight object.

Testing

Currently, we have test cards available that can return the various regulation environment values when authentication insight is requested on tokenization, depending on the merchant account that is specified:

Test Value Card Information Regulation Environment Value
4012000033330620 country of issuance = "USA" unregulated
4023490000000008 country of issuance = "IRL"
  • psd2 if using a merchant account acquired in the EEA
  • unregulated if using a merchant account acquired outside the EEA
  • unavailable if using a merchant account where acquirer country is unknown or has not been specified

    PSD2 SCA exemptions

    Merchants can request exemptions for certain transactions from requiring SCA. Exemptions are granted completely at the discretion of the issuer, and are never guaranteed. If an exemption is requested, and then granted by the issuer, authentication will not be required. However, in this case, the liability remains with the merchant and is not shifted to the issuer.

    Braintree's client SDKs provide the ability to request an exemption for a given authentication. If you request an exemption, Braintree will automatically request the most appropriate exemption from the issuer.

    Please note that issuers are currently upgrading their systems to support 3DS 2 as well as PSD2 SCA exemptions; many issuers may not support some or all exemptions until well into 2020.

    For more information on exemptions, please read our blog on PSD2 SCA exemptions.

    Client-side implementation

    To request an exemption, set exemptionRequested: true in the verifyCard() parameters.

    Server-side implementation

    If you perform a 3D Secure authentication, the exemption request along with any exemption granted by the issuer will automatically be applied to the associated transaction; no exemption information is then required in the Transaction.sale() call.

    In the future we will expand the options to allow you to specify the particular exemption you are requesting. This will be primarily useful for Forward API merchants.

    Using your own 3D Secure MPI provider

    If you perform a 3D Secure authentication with your own MPI provider and receive an SCA exemption from the issuer via 3D Secure, you'll need to specify which exemption was obtained in the Transaction.sale() call. This feature is currently under development and not yet available.

    Recurring billing with an external vault

    If you maintain your own vault, you will be able to provide a static network transaction identifier (NTI) in the previous_network_transaction_id field. You'll use a static NTI field in subsequent transactions in order to indicate that the initial transaction occurred before September 14, 2019, the PSD2 SCA enforcement date. We are currently working with the card networks to obtain the proper static NTI values and we will provide them when they are available.