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.

Vault management

The newest versions of Drop-in now allow customers to delete saved payment methods, and you can enable this functionality with a simple boolean.

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:

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.

var braintree = require('braintree-web');

  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.

var form = document.querySelector('#my-form');

  authorization: 'CLIENT_AUTHORIZATION'
}, function (clientErr, clientInstance) {
    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) {

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


In version 3.63.0+, we provide a component to integrate with the PayPal JS SDK.

<!-- You'll need a div that will become your PayPal button. -->
<div id="paypal-button"></div>
}, function (clientErr, clientInstance) {
    client: clientInstance
  }, function (paypalCheckoutErr, paypalCheckoutInstance) {
    if (paypalCheckoutErr) {
      console.error('Error creating PayPal Checkout:', paypalCheckoutErr);

      // Add your config options here
    }, fuAction () {
        createOrder: function () {
          return paypalCheckoutInstance.createPayment({
            // Include your PayPal options here. For available options, see
            // http://braintree.github.io/braintree-web/current/PayPalCheckout.html#createPayment

        onApprove: function (data, actions) {
          return paypalCheckoutInstance.tokenizePayment(data, function (err, payload) {
            // Submit `payload.nonce` to your server
      }).render('#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.
This snippet uses the PayPal JS SDK. If you are using checkout.js, learn how to migrate to the PayPal JS SDK.

You can add your config options for loadPayPalSDK by passing a configuration object that overwrites the default properties for the PayPal JS SDK:

  intent: 'capture', // Braintree defaults this to 'authorize'
  currency: 'USD',
  commit: true,
  vault: true,
}, function (loadPayPalSDKErr) {
  // Adds https://www.paypal.com/sdk/js script to the page and
  // adds the paypal object to the window

  // Set up PayPal JS SDK (see next section)

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.

  authorization: 'CLIENT_AUTHORIZATION'
}, function (err, clientInstance) {
    client: clientInstance,
    fields: {
      // Your fields
  }, yourHostedFieldsCallback);

    client: clientInstance
  }, yourPayPalCheckoutCallback);

Using Premium Fraud Management Tools

The v3 SDK simplifies the Premium Fraud Management 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 us before migrating to v3 to ensure your Kount merchant ID is hard-coded into your Braintree gateway.

See also