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
Copy
Copied
<script src="https://js.braintreegateway.com/web/dropin/1.9.0/js/dropin.min.js"></script>

This adds a global braintree object which includes dropin:

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

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

bash
Copy
Copied
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:

js
Copy
Copied
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.

You will then 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
Copy
Copied
<head>
  <meta charset="utf-8">
  <script src="https://js.braintreegateway.com/web/dropin/1.9.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:

js
Copy
Copied
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.

js
Copy
Copied
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:

js
Copy
Copied
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.

Apple Pay

Before including Apple Pay in Drop-in, you will need to complete the steps outlined in the Apple Pay configuration guide. Once you are configured to use Apply Pay, you will 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.

js
Copy
Copied
braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  applePay: {
    displayName: 'My Store',
    paymentRequest: {
      total: {
        label: 'My Store',
        amount: '19.99'
      }
    }
  }
}, 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.

Error handling

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

js
Copy
Copied
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:

js
Copy
Copied
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":

js
Copy
Copied
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: Customization →

Still have questions?

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