Migrating from v2 to v3

Great things are happening in version 3 of the Braintree JavaScript SDK!

As a new major version, the 3.0 release has a new API, requiring integration code changes when upgrading from 2.x. This release offers a more powerful, low-level abstraction, giving you more control over the mechanics of your Braintree integration.

Why upgrade to v3

No dependency on form submission

Previous versions of the SDK required a form submission for tokenization. Now we're giving you control of tokenization through a simple API call.

Hosted Fields formatting

This release introduces input formatting in Hosted Fields, creating a UX-friendly and PCI-compliant experience.

Smaller file size

Our new modular component structure means you can selectively include payment methods to fit your needs.

Improved error messaging

One of our main goals in this version of the SDK is to make error messaging much more transparent, giving you a clearer picture of what’s happening in your checkout flows.

Drop-in UI

A new version of Drop-in is powered by v3 of the Braintree JavaScript SDK.

This is a major version change for Drop-in and requires integration code changes when upgrading from previous versions.

No longer in an iframe

Previous versions of Drop-in were inside of an iframe and did not support custom styles. New Drop-in is added to a div on your page and can be styled with custom CSS!

Available in 23 languages

Drop-in is now available in 23 languages. Set the locale property to the language you want to use.

Open source, open development

Drop-in is open source on GitHub. Let us know if you have an issue, or open a pull request to improve Drop-in!

Getting v3

In version 2.x, Braintree.js is a single file that contains all the tools for any of our JS client-side integrations. With so many ways to integrate, we know that not every merchant needs every line of Braintree.js. Our new modular architecture allows you to pick and choose exactly which components you need.

Like in previous versions, you can get everything you need from npm or bower as well as using a direct link in a script tag. See Loading the SDK for details. Alternatively, you can now use require to pull in components directly. For example:

JavaScript
Click to copy
Copied
var hostedFields = require('braintree-web/hosted-fields');

Accepting payments

New Drop-in UI

To get started with Drop-in, see our Drop-in integration guide.

Custom UI

At the core of every component is an API client that communicates with our gateway. This means every integration begins with the instantiation of a client with a tokenization key or client token as well as a callback to be called when the client is created.

JavaScript
Click to copy
Copied
var braintree = require('braintree-web');

braintree.client.create({
  authorization: 'CLIENT_AUTHORIZATION'
}, function (err, clientInstance) {
  // Instantiate components here!
});

Credit cards with Hosted Fields

Hosted Fields is our credit card form offering that keeps merchants eligible for the easiest level of PCI compliance. Instead of using your own inputs, we'll host iframes on your page so you never have to worry about dealing with sensitive payment information.

In v3, we've made Hosted Fields much more customizable. In addition to the styling introduced in v2, we've introduced input formatting. This includes spacing in credit card numbers, automatic insertion of slashes in expiration dates, and restricted input to only applicable characters in all fields.

Another significant change is the movement away from tokenization on form submission. In version 2.x, Hosted Fields was instantiated with a form that, when submitted, prompted tokenization. Now, we're giving you control over when to tokenize through a function call.

JavaScript
Click to copy
Copied
var form = document.querySelector('#my-form');

braintree.client.create({
  authorization: 'CLIENT_AUTHORIZATION'
}, function (clientErr, clientInstance) {
  braintree.hostedFields.create({
    client: clientInstance,
    fields: {
      number: {
        selector: '#card-number'
      },
      cvv: {
        selector: '#cvv'
      },
      expirationDate: {
        selector: '#expiration-date'
      }
    }
  }, function (hostedFieldsErr, hostedFieldsInstance) {
    // Make tokenize call on form submission
    form.addEventListener('submit', function (event) {
      event.preventDefault();

      hostedFieldsInstance.tokenize(function (tokenizeErr, payload) {
        // Submit payload.nonce to your server
      });
    }, false);
  });
});

PayPal

In version 3.x, we provide a component to integrate with the PayPal Checkout.js library.

HTML
Click to copy
Copied
<!-- You'll need a div that will become your PayPal button. -->
<div id="paypal-button"></div>

<!-- Be sure to include checkout.js on your page. -->
<script src="https://www.paypalobjects.com/api/checkout.js" data-version-4 log-level="warn"></script>
JavaScript
Click to copy
Copied
braintree.client.create({
  authorization: CLIENT_AUTHORIZATION
}, function (clientErr, clientInstance) {
  braintree.paypalCheckout.create({
    client: clientInstance
  }, function (paypalCheckoutErr, paypalCheckoutInstance) {
    if (paypalCheckoutErr) {
      console.error('Error creating PayPal Checkout:', paypalCheckoutErr);
      return;
    }

    paypal.Button.render({
      env: 'production', // or 'sandbox'

      payment: function () {
        return paypalCheckoutInstance.createPayment({
          // your PayPal options here. For available options, See
          // http://braintree.github.io/braintree-web/current/PayPalCheckout.html#createPayment
        });
      },

      onAuthorize: function (data, actions) {
        return paypalCheckoutInstance.tokenizePayment(data)
          .then(function (payload) {
            // Submit `payload.nonce` to your server
          });
      },
    }, '#paypal-button').then(function () {
      // The PayPal button will be rendered in an html element with the id
      // `paypal-button`. This function will be called when the PayPal button
      // is set up and ready to be used.
    });
  });
});

Using multiple components

To keep things easy, all components can share a single client. This can be done by instantiating several components in your client.create() callback.

JavaScript
Click to copy
Copied
braintree.client.create({
  authorization: 'CLIENT_AUTHORIZATION'
}, function (err, clientInstance) {
  braintree.hostedFields.create({
    client: clientInstance,
    fields: {
      // Your fields
    }
  }, yourHostedFieldsCallback);

  braintree.payPalCheckout.create({
    client: clientInstance
  }, yourPayPalCheckoutCallback);
});

Using Advanced Fraud Tools

The v3 SDK simplifies the Advanced Fraud Tools integration by pulling your environment and Kount merchant ID (if applicable) directly from your gateway configuration. As a result, you'll only need to pass kount: true to the data collector component in your client-side code, instead of having to specify Kount details every time.

If you have a Kount Custom integration with your own Kount merchant ID, contact Support before migrating to v3 to ensure your Kount merchant ID is hard-coded into your Braintree gateway.

See also

Still have questions?

If you can’t find an answer, contact our Support team.