Client-Side Implementation

JavaScript v3SDK

• Current Braintree SDKs
• Android v4
• iOS v6
• JavaScript v3
• Previous Versions
• Android v3
• iOS v5
• JavaScript v2

note

We have upgraded our 3D Secure integration in preparation for 3DS2 and PSD2 Strong Consumer Authentication (SCA) compliance requirements in 2019.

This guide shows our legacy integration for 3D Secure. To use 3DS2 instead:

• If you've already integrated 3DS1, see our 3DS2 migration guide.
• If you don't use 3DS yet, see our full 3D Secure integration guide that we've updated for 3DS2.

Payment flow

• Generate a client token
• Render a checkout page to collect customer payment information
• Verify the credit card and amount via the verifyCard method
  • If the customer's card is enrolled in a 3D Secure program, the customer may be prompted to authenticate using their bank login credentials

Generate a client token

important

You must generate a client token if you want to use 3D Secure. Tokenization keys can't be used when processing 3D Secure transactions.

Before you can call the verifyCard method, you will need to generate a client token. The client_token is generated server-side and must be accessible from the JavaScript in your checkout page.

Specify a merchant account

If you would like to use a merchant account ID other than your default, specify the merchant_account_id when generating the client token.

note

This merchant account ID must match the merchant account ID used to create the transaction.

Render a checkout page

You can structure your native checkout flow however you'd like. If you don't already have a credit card form, consider our Drop-in UI.

Next, include the JS SDK on your page:

<script src="https://js.braintreegateway.com/web/3.97.2/js/client.min.js"></script>
<script src="https://js.braintreegateway.com/web/3.97.2/js/three-d-secure.min.js"></script>

Finally, create the configured client:

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({
    client: clientInstance
  }, function (threeDSecureErr, threeDSecureInstance) {
    if (threeDSecureErr) {
      // Handle error in 3D Secure component creation
      return;
    }

    threeDSecure = threeDSecureInstance;
  });
});

Verify a credit card

Once the 3D Secure client has been created, you can verify transactions by passing the NONCE_FROM_INTEGRATION and the amount to 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 server decides to challenge).

You must also pass in addFrame and removeFrame functions. The addFrame function will be called with the 3D Secure bank authorization iframe as a DOM node which you should insert into your page. The removeFrame function will be called when authorization is complete and the iframe should be removed from your page.

First, use Hosted Fields or raw tokenization to receive a nonce. Here's an example of using that nonce to verify the card with 3D Secure:

var my3DSContainer = document.createElement('div');

threeDSecure.verifyCard({
  amount: '500.00',
  nonce: NONCE_FROM_INTEGRATION,
  addFrame: function (err, iframe) {
    // Set up your UI and add the iframe.
    my3DSContainer.appendChild(iframe);
    document.body.appendChild(my3DSContainer);
  },
  removeFrame: function () {
    // Remove UI that you added in addFrame.
    document.body.removeChild(my3DSContainer);
  }
}, function (err, response) {
  // Send response.nonce to use in your transaction
});

The transaction amount is required at verification for two reasons. First of all, it's an additional check to make sure the transaction being verified is the same as the one that is eventually authorized and settled. For this reason, the amount submitted for verification must match the amount sent to the Braintree server for authorization. Additionally, some issuers use the amount to help determine whether they should challenge the user to authenticate.

After the cardholder has completed the 3D Secure process, either an error argument or a response argument will be populated in your callback. You should attempt to handle any errors (if present), and then create the transaction using the nonce returned in the response object. In the following example, transactions would employ response.nonce.

threeDSecure.verifyCard({
  amount: '500.00',
  nonce: NONCE_FROM_INTEGRATION
  // addFrame and removeFrame functions here
}, function (err, response) {
  if (err) {
    // Handle error
    return;
  }

  // Submit response.nonce to server
});

Verify a vaulted credit card

First, on the server, generate and return a payment method nonce for the vaulted credit card.

Then, on the client, you can use the same verifyCard method with the nonce from the server as with a nonce from a client-side integration.

threeDSecure.verifyCard({
  amount: '500.00',
  nonce: NONCE_FROM_SERVER
  // addFrame and removeFrame functions here
}, function (err, response) {
  // Send response.nonce to use in your transaction
});

Validation errors

Braintree will evaluate any fields passed against Cardinal's documentation. You will receive a validation error from Braintree if a field is incorrect.

American Express SafeKey

If you're a US-based merchant configured for Amex SafeKey, you need to pass additional parameters for the transaction to be evaluated for fraud.

We recommend passing most, if not all, of the parameters to qualify for Amex SafeKey. The more parameters you send, the more likely you are to successfully contest a chargeback.

threeDSecure.verifyCard({
  amount: '500.00',
  nonce: NONCE_FROM_INTEGRATION,
  customer: {
    mobilePhoneNumber: '8101234567',
    email: 'test@example.com',
    shippingMethod: '01',
    billingAddress: {
      firstName: 'Jill',
      lastName: 'Doe',
      streetAddress: '555 Smith St.',
      extendedAddress: '#5',
      locality: 'Oakland',
      region: 'CA', // ISO-3166-2 code
      postalCode: '12345',
      countryCodeAlpha2: 'US',
      phoneNumber: '1234567'
   }
  }
}, function (err, response) {
  // Handle response
});

Although these additional parameters are only necessary when using Amex SafeKey, you can safely pass them for other card brands as well.

Advanced client-side options

We expose additional information about the authentication request that you can use for more advanced UI flows or risk assessment. You should be aware that making such assessments may result in accepting the liability for fraudulent transactions.

These parameters pass through the client-side first and should not be trusted for your server-side risk assessment. They should be used for UI flow only.

threeDSecure.verifyCard({
  amount: '500.00',
  nonce: NONCE_FROM_INTEGRATION
  // addFrame and removeFrame functions here
}, function (err, response) {
  var liabilityShifted = response.liabilityShifted; // true || false
  var liabilityShiftPossible =  response.liabilityShiftPossible; // true || false
});

1. liabilityShifted indicates that 3D Secure worked and authentication succeeded. This will also be true if the issuing bank does not support 3D Secure, but the payment method does. In both cases, the liability for fraud has been shifted to the bank. You should go on creating a transaction using the new nonce.
2. liabilityShiftPossible indicates that the payment method was eligible for 3D Secure. If liabilityShifted is false, then the user failed 3D Secure authentication. In this situation, the card brands recommend asking the user for another form of payment. However, if you have server-side risk assessment processes that allow for it, you can still use the new nonce to create a transaction. If you want to use a nonce that did not pass 3D Secure authentication, you need to set the required option to false in your server integration.
3. If both of the above values are false then this card was ineligible for 3D Secure. You can continue to create the transaction with the new nonce. However, liability shift will not apply to this transaction. This case may be useful if you would like to ask the user for additional verification (AVS, etc).

important

For American Express SafeKey, liabilityShifted may be returned as true but Amex may later revoke the liability shift for the transaction based on your merchant behavior and fraud rate.