availability

This is a preview of the adoption guide for our upcoming 3D Secure 2.0 integration. Our SDKs are still under development and the implementation is subject to change.

We encourage you to begin testing now, but do not release your 3D Secure 2.0 integration in production at this time.

Start here

  • 3D Secure 2.0 (3DS 2.0) is the next iteration of the 3DS authentication protocol.
  • It satisfies the Strong Customer Authentication (SCA) requirements going into effect in 2019 for European merchants transacting with European customers.
  • We are currently updating the latest major versions of our client SDKs to support 3DS 2.0. Beta versions of our JavaScript v3 and iOS v4 SDKs are available now; an Android beta is coming soon.
  • This Adoption guide focuses on how our 3DS 2.0 implementation will differ from our original 3DS integration.

If you are based in Europe and already use 3DS

  1. Use this Adoption guide to update your existing 3DS integration to 2.0.
    • Although SCA requirements will not be enforced for merchants until September 14, 2019, we recommend integrating 3DS 2.0 by April 14, 2019, to meet card brand guidelines.
  2. If you integrate 3DS 2.0 using beta versions of our SDKs, be ready to update to a stable version once available and account for any breaking changes introduced.
    • In the meantime, if you have any feedback on our beta SDKs, please let us know!

If you are based in Europe and do not use 3DS yet

  1. Read our 3DS support article to get familiar with 3DS in general.
    • A conceptual understanding of 3DS will be helpful as you complete a 2.0 integration.
  2. Use both our original 3DS integration guide and this Adoption guide to add 3DS 2.0 to your Braintree integration.
    • Much of the original 3DS guide is still relevant for 3DS 2.0, except for the key differences covered on this page.
    • Although SCA requirements will not be enforced for merchants until September 14, 2019, we recommend integrating 3DS 2.0 by April 14, 2019, to meet card brand guidelines.
  3. If you integrate 3DS 2.0 using beta versions of our SDKs, be ready to update to a stable version once available and account for any breaking changes introduced.
    • In the meantime, if you have any feedback on our beta SDKs, please let us know!

If you are based outside Europe

While generally not required, you can most likely use 3DS 2.0, too! Right now we’re focused on helping European merchants integrate, but the same general steps will apply to any merchant who wants to use 3DS 2.0.

See the overall 3DS compatibility details in our support article, and contact us if you have questions about using 3DS outside of Europe.

About 3DS 2.0

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.0.

Getting ready for 3DS 2.0

To minimize the need for issuing banks to present authentication challenges to customers, update your integration to collect as many of these customer data fields as possible. These new fields are not strictly required, but without them, you and your customers won't get the most out of 3DS 2.0.

Field Name Description
billingGivenName Customer's first name.
billingSurname Customer's last name.
streetAddress Customer's billing street address.
extendedAddress Customer's billing extended address when available (e.g. Apt. #3).
locality Customer's billing city.
region Customer's billing state, county, or province, if applicable.
postalCode Customer's billing postal code.
countryCodeAlpha2 Customer's ISO 3166-1 alpha-2 country code for their billing address.
billingPhoneNumber Customer's billing phone number.
email Customer's email.

Enabling 3DS 2.0

In addition to collecting the customer data elements above, you'll need to update your Braintree client-side integration.

Update your SDK version

Add the beta SDK to your Podfile:

Ruby
Copy
Copied
pod 'Braintree', :git => 'https://github.com/braintree/braintree_ios.git', :branch => '3ds-2'

Set up your app

If you don't have an existing 3DS integration, you can follow the existing guide to get your app set up. Otherwise you can use your existing integration and add the new parameters described below.

important

It is important that you complete the 1.0 integration because the SDK will fall back to that flow when 3DS 2.0 is unavailable for the card being verified.

Add new parameters to request

To reduce the need for issuing banks to challenge cardholders to authenticate with 3DS 2.0, you'll need to add new parameters to BTThreeDSecureRequest:

  • versionRequested: Set to 2 to enable 3DS 2.0 support.
  • bin: The numeric Bank Identification Number (BIN) associated with the nonce. This should be on the BTCardNonce as the property bin.
  • additionalInformation: Additional customer data elements to pass to the issuing bank; see code snippet below for details. For best results, provide as many of these elements as possible. This may require updating your UI to collect more information.
  • threeDSecureRequestDelegate: Required A delegate to receive callbacks.
    • onLookupComplete:result:next:: A required protocol that is called after the lookup completes and before a challenge is initiated. You must call next() to continue the flow.
Objective-C Swift
Copy
Copied
- (IBAction)tappedCheckout {
    // Create a BTCard based on the UI state
    BTCard *details = [[BTCard alloc] init];
    details.number = self.cardNumberField.text;
    details.expirationMonth = self.expirationMonthField.text;
    details.expirationYear = self.expirationYearField.text;

    // Tokenize the card
    [self.cardClient tokenizeCard:details completion:^(BTCardNonce *tokenizedCard, NSError *error) {
        if (error) {
          // Handle errors
          return;
        }

        BTThreeDSecureRequest *request = [[BTThreeDSecureRequest alloc] init];
        request.amount = [NSDecimalNumber decimalNumberWithString:@"10"];
        request.nonce = tokenizedCard.nonce;
        request.bin = tokenizedCard.bin;
        request.versionRequested = 2;

        BTThreeDSecureAdditionalInformation *info = [[BTThreeDSecureAdditionalInformation alloc] init];
        info.billingGivenName = @"Jill";
        info.billingSurname = @"Doe";
        info.billingPhoneNumber = @"5551234567";
        info.email = @"test@email.com";

        BTThreeDSecurePostalAddress *billingAddress = [BTThreeDSecurePostalAddress new];
        billingAddress.streetAddress = @"555 Smith St";
        billingAddress.extendedAddress = @"#2";
        billingAddress.locality = @"Chicago";
        billingAddress.region = @"IL";
        billingAddress.postalCode = @"12345";
        billingAddress.countryCodeAlpha2 = @"US";

        info.billingAddress = billingAddress;

        request.additionalInformation = info;
        // Make sure that self conforms BTThreeDSecureRequestDelegate
        request.threeDSecureRequestDelegate = self;

        [self.paymentFlowDriver startPaymentFlow:request completion:^(BTPaymentFlowResult * _Nonnull result, NSError * _Nonnull error) {
            if (error) {
                // Handle error
            } else if (result) {
                BTThreeDSecureResult *threeDSecureResult = (BTThreeDSecureResult *)result;

                if (threeDSecureResult.tokenizedCard.threeDSecureInfo.liabilityShiftPossible) {
                    if (threeDSecureResult.tokenizedCard.threeDSecureInfo.liabilityShifted) {
                        // 3D Secure authentication success
                    } else {
                        // 3D Secure authentication failed
                    }
                } else {
                    // 3D Secure authentication was not possible
                }

                // Use the `threeDSecureResult.tokenizedCard.nonce`
            }
        }];
    }];
}

- (void)onLookupComplete:(__unused BTThreeDSecureRequest *)request result:(__unused BTThreeDSecureLookup *)lookup next:(void (^)(void))next {
    // Optionally inspect the result and prepare UI if a challenge is required
    next();
}

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.0 on your client side in sandbox. Any other test cards will result in 3DS verification results that are not in the 2.0 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.

Recurring billing

Recurring transactions

The recommended flow for recurring billing would be to establish Strong Customer Authentication 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 3DS to the first transaction or verification this way, you message to issuers that you have established a mandate between you and your customer to charge their payment method as recurring “merchant initiated” transactions, which are exempt from SCA. 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

Other merchant-initiated transactions will be processed much the same way that recurring transactions would be. You would again establish Strong Customer Authentication 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.

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.0

After adopting 3DS 2.0, you may still see 3DS 1.0 authentications using your updated integration. This is to be expected – 3DS 2.0 is an industry-wide initiative, requiring many parties' participation in order for a 2.0 authentication to be possible. Each party has steps to complete, and 3DS verification will use the 2.0 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 2.0 cardholder verifications.
  2. Braintree must work with acquirers to enable merchant accounts for 2.0.
  3. Cardholders' issuing banks must upgrade their systems to support 2.0 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 2.0 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 1.0 authentication path on a transaction-by-transaction basis when 2.0 is not available from all parties involved.

Common questions

Can merchants customize the presentation of the bank challenge?

Currently, the presentation will be controlled by the issuing bank. For iOS challenge flows, we will be investigating customization options for future updates.

Will vaulted credit cards be supported?

Yes, the guide will be updated with additional directions for vaulted credit cards.

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.

Still have questions?

If you can’t find an answer, contact us