Client SDK

Migrationanchor

Javascript

Migrating from v2 to v3anchor

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 v3anchor

No dependency on form submissionanchor

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 formattinganchor

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

Smaller file sizeanchor

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

Improved error messaginganchor

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 UIanchor

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 iframeanchor

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 languagesanchor

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

Vault managementanchor

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 developmentanchor

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 v3anchor

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:

  1. JavaScript
var hostedFields = require('braintree-web/hosted-fields');

Accepting paymentsanchor

New Drop-in UIanchor

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

Custom UIanchor

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.

  1. Callbacks
  2. Promises
var braintree = require('braintree-web');

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

Credit cards with Hosted Fieldsanchor

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.

  1. Callbacks
  2. Promises
var form = document.querySelector('#my-form');

braintree.client.create({
  authorization: 'CLIENT_AUTHORIZATION'
}, function (clientErr, clientInstance) {
  braintree.hostedFields.create({
    client: clientInstance,
    fields: {
      number: {
        container: '#card-number'
      },
      cvv: {
        container: '#cvv'
      },
      expirationDate: {
        container: '#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);
  });
});

PayPalanchor

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

  1. HTML
<!-- You'll need a div that will become your PayPal button. -->
<div id="paypal-button"></div>
  1. Callbacks
  2. Promises
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;
    }

    paypalCheckoutInstance.loadPayPalSDK({
      // Add your config options here
    }, fuAction () {
      paypal.Buttons({
        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.
      });
    });
  });
});

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

  1. Callbacks
  2. Promises
paypalCheckoutInstance.loadPayPalSDK({
  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 componentsanchor

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

  1. Callbacks
  2. Promises
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 Premium Fraud Management Toolsanchor

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 don't need to pass any Kount-specific configuration to the data collector component in your client-side code.

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