Drop-in UI

Setup and Integrationanchor

Configurationanchor

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

Setupanchor

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:

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

This adds a global braintree object which includes dropin:

  1. Callback
  2. Promise
braintree.dropin.create({
  authorization: "CLIENT_AUTHORIZATION"
}, callback);
note

By default the credit card is the only payment method enabled with the Drop-in UI. If you want to add more payment methods or options you can visit the web-drop-in reference.

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

  1. 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:

  1. Callback
  2. Promise
var dropin = require('braintree-web-drop-in');

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

Client-side implementationanchor

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.

  1. HTML
<head>
  <meta charset="utf-8">
  <script src="https://js.braintreegateway.com/web/dropin/1.43.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 methodsanchor

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 cardsanchor

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.

  1. Callback
  2. Promise
braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
}, callback);

PayPalanchor

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:

  1. Callback
  2. Promise
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.

  1. Callback
  2. Promise
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.

In addition to what we've seen before you could also add custom actions on events.

  1. Callback
  2. Promise
braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  paypal: {
    flow: 'vault'
  }
}, function (err, dropinInstance) {
    dropinInstance.on('changeActiveView', function() {
      alert('activeView changed!');
    })
});

Venmoanchor

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).

availability

This integration is a sample only, scanning the QR code will not work.

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

The behavior of the Venmo payment method may vary and may look different on mobile devices, previous example is only for javascript on the web. If you want to explore more options available for the venmo object please check out reference.

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:

  1. Callback
  2. Promise
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.

For more information about Venmo component attributes and configuration, see Client-Side Implementation.

Apple Payanchor

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.

  1. Callback
  2. Promise
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 Payanchor

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.

  1. Callback
  2. Promise
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'
    },
    allowedPaymentMethods: [{
      type: 'CARD',
      parameters: {
        // We recommend collecting and passing billing address information with all Google Pay transactions as a best practice.
        billingAddressRequired: true,
        billingAddressParameters: {
          format: 'FULL'
        }
      }
    }]
  }
}, 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 Secureanchor

Drop-in supports 3D Secure 2 verification. To use 3D Secure in your integration, follow our implementation guide. Once you have added 3D Secure to Drop-in, you will need to complete the server-side implementation for 3D Secure.

Error handlinganchor

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

  1. Callback
  2. Promise
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 formanchor

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

  1. Callback
  2. Promise
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":

  1. Callback
  2. Promise
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 stepsanchor


Next Page: Customization →