3D Secure

Step by Step Integrationanchor

Table of Contentsanchor

3DS Client side flowanchor

Generate a client tokenanchor

Before you can initialize the JavaScript SDK, you will need to generate a client token. The client_token is generated on your server and must be accessible from the JavaScript in your checkout page.

If you would like to use a merchant account ID other than your default, specify the merchant_account_id when generating the client token. The merchant account ID used to create the client token must match the merchant account ID used to create the subsequent transaction or verification.

Verify a card using 3DSanchor

To use 3DS, you will need to create an object with relevant customer and transaction data in order to minimize the need for issuing banks to present authentication challenges to customers.

The object should contain as many of the following fields as possible. The full list of fields is described in the SDK documentation.

  1. 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', // ISO-3166-2 code
      postalCode: '12345',
      countryCodeAlpha2: 'US'
    },
    collectDeviceData: true,
    additionalInformation: {
      workPhoneNumber: '8101234567',
      shippingGivenName: 'Jill',
      shippingSurname: 'Doe',
      shippingPhone: '8101234567',
      shippingAddress: {
        streetAddress: '555 Smith St.',
        extendedAddress: '#5',
        locality: 'Oakland',
        region: 'CA', // ISO-3166-2 code
        postalCode: '12345',
        countryCodeAlpha2: 'US'
      }
    },
  };
important

As of Braintree version 3.94.0 an option to submit additional device settings to 3D Secure is available. Submitting this data may reduce lookup failures and/or authentication challenges for customers. Set the collectDeviceData option to true to enable collection of additional device data.

Drop-in UIanchor

important

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

note

If you are using the Drop-In UI to tokenize cards, you have CVV rules enabled and you run 3D Secure verifications, the default setting to vault cards on your client will result in a processor error. Instead, you should disable vaulting via the Drop-In UI and vault the card on your server. You can do so by setting vaultCard to false when initializing the Drop-In UI and include the vault_on_success=true parameter when creating a transaction using transaction:sale or a GraphQL mutation from your server.

To add our Drop-in UI to your checkout page, include the dropin script:

  1. JavaScript
<!-- Load the Drop-in component -->
<script src="https://js.braintreegateway.com/web/dropin/1.43.0/js/dropin.min.js"></script>

The threeDSecureParameters object must contain the amount field.

  1. JavaScript
var threeDSecureParameters = {
    amount: '500.00',
    
    //Pass other 3DS parameters here
  };

Then, create the Drop-in and pass in the threeDSecureParameters object into the threeDSecure field of the requestPaymentMethod.

  1. Callback
  2. Promise
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
              // The 3D Secure Authentication ID can be found
              //  at payload.threeDSecureInfo.threeDSecureAuthenticationId
          });
      });
  });

Hosted Fieldsanchor

 

important

3DS support requires Braintree SDK version 3.92.0 or higher.

To use 3DS with Hosted Fields, include the client, three-d-secure, and hosted-fields scripts:

  1. HTML
<!-- Load the client component. -->
https://js.braintreegateway.com/web/3.103.0/js/client.min.js
<!-- Load the 3D Secure component. -->
https://js.braintreegateway.com/web/3.103.0/js/three-d-secure.min.js
<!-- Load the Hosted Fields component. -->
https://js.braintreegateway.com/web/3.103.0/js/hosted-fields.min.js

The threeDSecureParameters object must contain the following fields:

  • amount
  • nonce
  • bin
  1. JavaScript
var threeDSecureParameters = {
    amount: '500.00',
    nonce: NONCE_FROM_INTEGRATION, // Example: hostedFieldsTokenizationPayload.nonce
    bin: BIN_FROM_INTEGRATION, // Example: hostedFieldsTokenizationPayload.details.bin
    
    //Pass other 3DS parameters here
  };
note

To verify vaulted cards, you would need to first generate the nonce on the server and then pass it in the threeDSecureParameters.

Handle Lookup Responseanchor

It is required to implement the callback onLookupComplete, which will be invoked after receiving the 3D Secure lookup response, before initializing the challenge and completing the flow.

  1. JavaScript
var threeDSecureParameters = {
  // Pass 3DS parameters here
  onLookupComplete: function (data, next) {
    // use 'data' here, then call 'next()'
    next();
  }
};

Specify version: 2 in your options object when calling threeDSecure.create().

  1. Callback
  2. Promise
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 3DS2 whenever possible
    client: clientInstance
  }, function (threeDSecureErr, threeDSecureInstance) {
    if (threeDSecureErr) {
      // Handle error in 3D Secure component creation
      return;
    }

    threeDSecure = threeDSecureInstance;
  });
});

Once the 3D Secure client has been created, you can verify cards by passing the threeDSecureParameters object into verifyCard(). This call may challenge the cardholder to authenticate (if the card is enrolled in a 3D Secure program, such as Verified by Visa, and the cardholders issuing bank decides to challenge).

  1. Callback
  2. Promise
threeDSecure.verifyCard(threeDSecureParameters, function (err, response) {
  if (err) {
    // Handle error
    return;
  }
  // Send response.nonce to your server for use in your integration
  // The 3D Secure Authentication ID can be found
  //  at response.threeDSecureInfo.threeDSecureAuthenticationId
});

A validation error from Braintree will be returned if a field does not follow Cardinal's documentation.

3DS Server side flowanchor

An alternative way of performing 3DS is to make the 3DS call from the server instead of from the client machine.

To meet the device data collection requirements for 3DS, merchants must either make a prerequisite prepareLookup call in the client SDK or pass in the browser fields directly as input parameters.

Prepare the 3DS lookupanchor

The prepareLookup call will return the data needed to perform a 3D Secure lookup call. This call is triggered from the client's device. The payload returned by this call should be passed on to the server so a 3DS lookup can be done from there.

  1. JavaScript
threeDSecure.prepareLookup({
    nonce: hostedFieldsTokenizationPayload.nonce,
    bin: hostedFieldsTokenizationPayload.details.bin
  }, function (err, payload) {
    if (err) {
      console.error(err);
      return;
    }

    // send payload to server to do server side lookup
  });

Make the 3DS lookup callanchor

Use the GraphQL mutation performThreeDSecureLookup to attempt to perform 3D Secure Authentication on credit card payment method. This may consume the payment method and return a new single-use payment method.

Including device data is mandatory. This can be done either by passing along the dfReferenceId or browserInformation.

  1. Mutation
mutation PerformThreeDSecureLookup($input: PerformThreeDSecureLookupInput!) {
    performThreeDSecureLookup(input: $input) {
      clientMutationId
      threeDSecureLookupData {
        authenticationId
      }
      paymentMethod {
        id
        details {
          ... on CreditCardDetails {
            bin
            threeDSecure {
              authentication {
                cavv
                eciFlag
                liabilityShifted
                liabilityShiftPossible
              }
            }
          }
        }
      }
    }
  }
  1. Variables
{
    input: {
      paymentMethodId: single_use_payment_method_id,
      amount: "10.00",
      transactionInformation: {
        browserInformation: 
          {
            javaEnabled: false,
            acceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
            language: "en-GB",
            colorDepth: 24,
            screenHeight: 720,
            screenWidth: 1280,
            timeZone: "0",
            userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safar  i/537.36",
            javascriptEnabled: true,
          }
        ipAddress: "82.34.105.112",
        deviceChannel: "BROWSER",
      },
    }
  }

Trigger 3DS challengeanchor

This call will launch the iframe challenge using a 3D Secure lookup response from a server side lookup. This call is only necessary if a challenge is required.

  1. JavaScript
threeDSecure.initializeChallengeWithLookupResponse(lookupResponseFromServer).then(function (payload) {
    if (payload.liabilityShifted) {
      // Liability has shifted
      submitNonceToServer(payload.nonce);
    } else if (payload.liabilityShiftPossible) {
      // Liability may still be shifted
      // Decide if you want to submit the nonce
    } else {
      // Liability has not shifted and will not shift
      // Decide if you want to submit the nonce
    }
  });

See also


Next Page: Applying 3DS to Transactions and Verifications →