Configuration

In order to use the Drop-in UI, you'll first need to get a tokenization key from the Control Panel or generate a client token on your server. This will be your authorization used when creating Drop-in.

Setup

Drop-in is available directly from our servers, which you can include on your site as a script tag or download the file and save it locally:

HTML 
<script src="https://js.braintreegateway.com/web/dropin/1.20.0/js/dropin.min.js"></script>

This adds a global braintree object which includes dropin:

braintree.dropin.create({ /* options */ }, callback);

If you're using npm, install the latest version of the braintree-web-drop-in module:

bash 
npm install --save braintree-web-drop-in

The examples on this page reference braintree.dropin.create, but if you're using the module from npm, create will be on the top level of the object:

var dropin = require('braintree-web-drop-in');

dropin.create({ /* options */ }, callback);

Client-side implementation

To get started, you will need client authorization, a container where Drop-in will appear, and a button. When loaded, the UI will appear in the container.

Configure your button to call requestPaymentMethod to retrieve the payment method object, including the payment method nonce. From there, you can submit the nonce to your server in whatever way you see fit.

HTML 
<head>
  <meta charset="utf-8">
  <script src="https://js.braintreegateway.com/web/dropin/1.20.0/js/dropin.min.js"></script>
</head>
<body>
  <div id="dropin-container"></div>
  <button id="submit-button">Request payment method</button>
  <script>
    var button = document.querySelector('#submit-button');

    braintree.dropin.create({
      authorization: 'CLIENT_AUTHORIZATION',
      container: '#dropin-container'
    }, function (createErr, instance) {
      button.addEventListener('click', function () {
        instance.requestPaymentMethod(function (requestPaymentMethodErr, payload) {
          // Submit payload.nonce to your server
        });
      });
    });
  </script>
</body>

See our reference documentation for more information about creating Drop-in.

Configuring payment methods

Additional steps are required for the Drop-in UI to accept payment methods other than cards. After completing the Drop-in setup instructions, follow the steps below for each payment method type.

Credit cards

By default, cards will be enabled when you configure Drop-in. CVV and Postal Code inputs are rendered conditionally according to your AVS and CVV settings.

Call requestPaymentMethod to get a card payment method payload, which includes a payment method nonce to send to your server at payload.nonce.

PayPal

If you have PayPal configured in your gateway, include a PayPal configuration object in your create call to render a PayPal option. To use our Vault flow, include flow: 'vault' in your PayPal configuration:

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  paypal: {
    flow: 'vault'
  }
}, callback);

To use Checkout with PayPal, include flow: 'checkout' as well as an amount and currency.

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  paypal: {
    flow: 'checkout',
    amount: '10.00',
    currency: 'USD'
  }
}, callback);

For other PayPal configuration options, see the createPayment options in our PayPal client reference.

Call requestPaymentMethod to get a PayPal payment method payload, which includes a payment method nonce to send to your server at payload.nonce.

PayPal Credit

PayPal Credit is a customer credit offering from PayPal that can appear as an additional payment option in the Drop-in UI. If a customer qualifies, they will be offered financing options as part of the PayPal flow. If the customer isn't pre-approved for PayPal Credit, they will be prompted to apply for it.

To add PayPal Credit to the Drop-in UI, add a paypalCredit property. Choose the Vault flow or the one-time Checkout flow:

  1. Vault flow: Set flow: 'vault'
  2. Checkout flow: Set flow: 'checkout', an amount, and a currency

This example uses the Checkout flow:

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  paypalCredit: {
    flow: 'checkout',
    amount: '10.00',
    currency: 'USD'
  }
}, callback);

When the payment method is PayPal Credit, requestPaymentMethod will return an object with the same structure as the PayPal object documented above.

Venmo

Before including Venmo in Drop-in, complete the steps outlined in the Venmo configuration guide. Once you are configured to use Venmo, include a venmo property in your Drop-in create call to render a Venmo option on supported browsers (currently most Android and iOS mobile web browsers).

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  venmo: {} // The `venmo` object requires no properties to instantiate.
}, callback);

On some browsers, Venmo may open a new tab, redirect back to your website, then refresh the page. This could break a single page app. To only present Venmo on browsers that support Venmo without a redirect, pass allowNewBrowserTab: false in the configuration:

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  venmo: {
    allowNewBrowserTab: false
  }
}, callback);

For more information, see the client-side details on verifying browser support.

To get a payment method nonce to send to your server, call requestPaymentMethod. This returns a Venmo payment method payload with a nonce at payload.nonce.

If using a client token with a customer id, the Venmo account will not automatically be vaulted. You can use the payment method nonce to create a payment method on your server.

Apple Pay

note

Your website must be served over HTTPS for the Apple Pay option to appear in Drop-in.

Before including Apple Pay in Drop-in, complete the steps outlined in the Apple Pay configuration guide. Once you are configured to use Apple Pay, include an applePay property in your Drop-in create call to render an Apple Pay option.

The applePay object requires a displayName and a paymentRequest, which requires a total with a label and an amount. The details provided in the paymentRequest object are used to create an ApplePayPaymentRequest to process the payment.

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  applePay: {
    displayName: 'My Store',
    paymentRequest: {
      total: {
        label: 'My Store',
        amount: '19.99'
      },
      // We recommend collecting billing address information, at minimum
      // billing postal code, and passing that billing postal code with all
      // Apple Pay transactions as a best practice.
      requiredBillingContactFields: ["postalAddress"]
    }
  }
}, callback);

All ApplePayPaymentRequest options are supported in paymentRequest; Braintree will automatically supply all required values with the exception of total.

Apple Pay is available in Safari on iOS version 10+ and macOS version 10.12+. If Apple Pay is not supported by the customer's browser, the options to select Apple Pay will not appear. For more information, see Apple's support articles on Apple Pay.

Call requestPaymentMethod to get an Apple Pay payment method payload, which includes a payment method nonce to send to your server at payload.nonce.

If using a client token with a customer id, the Apple Pay card will not automatically be vaulted. You can use the payment method nonce to create a payment method on your server.

Google Pay

note

Your website and any assets must be served over HTTPS (or localhost if testing in sandbox) for the Google Pay option to appear in Drop-in.

Before including Google Pay in Drop-in, complete the steps outlined in the Google Pay configuration guide. Once you are configured to use Google Pay, include a googlePay property in your Drop-in create call to render a Google Pay option.

Google Pay is available in Google Chrome v61 or higher on Android. If Google Pay is not supported by the customer's browser, the option to select Google Pay will not appear. See Google's developer documentation on testing browser compatibility for more information.

The googlePay object requires a merchantId provided by Google (when in production) and a transactionInfo object. All other GooglePayPaymentDataRequest parameters are supplied by Braintree, but may be overwritten by passing them in the googlePay object.

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  googlePay: {
    googlePayVersion: 2,
    merchantId: 'merchant-id-from-google',
    transactionInfo: {
      totalPriceStatus: 'FINAL',
      totalPrice: '123.45',
      currencyCode: 'USD'
    },
    cardRequirements: {
      // We recommend collecting and passing billing address information with all Google Pay transactions as a best practice.
      billingAddressRequired: true
    }
  }
}, callback);

To get a payment method nonce to send to your server, call requestPaymentMethod. This returns a Google Pay payment method payload with a nonce at payload.nonce.

If using a client token with a customer id, the Google Pay card will not automatically be vaulted. You can use the payment method nonce to create a payment method on your server.

3D Secure

Drop-in supports 3D Secure verification. If you're using 3D Secure, include threeDSecure in your create call and set an amount:

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

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  threeDSecure: {
    amount: '10.00',
  }
}, function (err, dropinInstance) {
   form.addEventListener('submit', function (event) {
    event.preventDefault();

    dropinInstance.requestPaymentMethod(function (err, payload) {
      if (err) {
        // Handle error
        return;
      }

      if (payload.liabilityShifted || payload.type !== 'CreditCard') {
        hiddenNonceInput.value = payload.nonce;
        form.submit();
      } else {
        // Decide if you will force the user to enter a different
        // payment method if liablity was not shifted
        dropinInstance.clearSelectedPaymentMethod();
      }
    });
  });
});

When you call requestPaymentMethod, a 3D Secure flow will appear for the user to complete if they have entered valid card details.

The requestPaymentMethod payload will return liabilityShifted, indicating whether or not liability shifted, and liabilityShiftPossible, indicating whether or not a liability shift is possible. For more information on liability shift, see the advanced client-side options in the 3D Secure guide.

Once you have added 3D Secure to Drop-in, you will need to complete the server-side implementation for 3D Secure.

Error handling

Errors in Drop-in should be handled in both the create and requestPaymentMethod callbacks in Drop-in.

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container'
}, function (createErr, instance) {
  if (createErr) {
    // An error in the create call is likely due to
    // incorrect configuration values or network issues.
    // An appropriate error will be shown in the UI.
    console.error(createErr);
    return;
  }

  button.addEventListener('click', function () {
    instance.requestPaymentMethod(function (requestPaymentMethodErr, payload) {
      if (requestPaymentMethodErr) {
        // No payment method is available.
        // An appropriate error will be shown in the UI.
        console.error(requestPaymentMethodErr);
        return;
      }

      // Submit payload.nonce to your server
    });
  });
});

Select a supported language for your checkout form

Drop-in is available in 23 languages in JS v3. To use a locale, include it in your create configuration:

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  locale: 'de_DE'
}, callback);

You can also provide your own translations by including a translations object as part of your create call. The following example changes the expiration date label to say "Expiry Date" instead of the default label, "Expiration Date":

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  translations: {
    expirationDateLabel: 'Expiry Date',
    // Any other custom translation strings...
  }
}, callback);

See our default translations for a full list of translation strings.

Next steps

Next Page: Customization →