braintree-web-drop-in

There are two ways to integrate Drop-in into your page: a script tag integration and a JavaScript integration using dropin.create.

The script tag integration is the fastest way to integrate. All you need to do is add the Drop-in script inside your form element where you want Drop-in to appear and include a data-braintree-dropin-authorization property with your tokenization key or client token.

When your form is submitted, Drop-in will intercept the form submission and attempt to tokenize the payment method. If the tokenization is successful, it will insert the payment method nonce into a hidden input with the name payment_method_nonce and then submit your form. If the tokenization is unsuccessful, a relevant error will be shown in the UI.

If you have data collector enabled, the device data will be injected into a hidden input with the name device_data before form submission.

Specify creation options as data attributes in your script tag, as shown in the examples below. The following configuration properties may be set:

  • data-locale
  • data-card.cardholder-name.required
  • data-payment-option-priority
  • data-data-collector.kount
  • data-data-collector.paypal
  • data-paypal.amount
  • data-paypal.currency
  • data-paypal.flow
  • data-paypal-credit.amount
  • data-paypal-credit.currency
  • data-paypal-credit.flow

For more control and customization, use dropin.create instead.

See our demo app for an example of using our script tag integration.

Source:
Examples

A full example accepting only cards

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Checkout</title>
  </head>
  <body>
    <form id="payment-form" action="/" method="post">
      <script src="https://js.braintreegateway.com/web/dropin/1.43.0/js/dropin.min.js"
       data-braintree-dropin-authorization="CLIENT_AUTHORIZATION"
      ></script>
      <input type="submit" value="Purchase"></input>
    </form>
  </body>
</html>

A full example accepting cards, PayPal, and PayPal credit

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Checkout</title>
  </head>
  <body>
    <form id="payment-form" action="/" method="post">
      <script src="https://js.braintreegateway.com/web/dropin/1.43.0/js/dropin.min.js"
       data-braintree-dropin-authorization="CLIENT_AUTHORIZATION"
       data-paypal.flow="checkout"
       data-paypal.amount="10.00"
       data-paypal.currency="USD"
       data-paypal-credit.flow="vault"
      ></script>
      <input type="submit" value="Purchase"></input>
    </form>
  </body>
</html>

Specifying a locale and payment option priority

<form id="payment-form" action="/" method="post">
  <script src="https://js.braintreegateway.com/web/dropin/1.43.0/js/dropin.min.js"
   data-braintree-dropin-authorization="CLIENT_AUTHORIZATION"
   data-locale="de_DE"
   data-payment-option-priority='["paypal","card", "paypalCredit"]'
   data-paypal.flow="checkout"
   data-paypal.amount="10.00"
   data-paypal.currency="USD"
   data-paypal-credit.flow="vault"
  ></script>
  <input type="submit" value="Purchase"></input>
</form>

Including an optional cardholder name field in card form

<form id="payment-form" action="/" method="post">
  <script src="https://js.braintreegateway.com/web/dropin/1.43.0/js/dropin.min.js"
   data-braintree-dropin-authorization="CLIENT_AUTHORIZATION"
   data-card.cardholder-name.required="false"
  ></script>
  <input type="submit" value="Purchase"></input>
</form>

Including a required cardholder name field in card form

<form id="payment-form" action="/" method="post">
  <script src="https://js.braintreegateway.com/web/dropin/1.43.0/js/dropin.min.js"
   data-braintree-dropin-authorization="CLIENT_AUTHORIZATION"
   data-card.cardholder-name.required="true"
  ></script>
  <input type="submit" value="Purchase"></input>
</form>

Members

(static) VERSION :string

The current version of Drop-in, i.e. 1.43.0.

Source:

Methods

(static) create(options, callbackopt) → {void|Promise}

This function is the entry point for braintree.dropin. It is used for creating Dropin instances.

Parameters:
Name Type Attributes Description
options object

Object containing all Dropin options:

Properties
Name Type Attributes Default Description
authorization string

A tokenization key or a client token. If authorization is a client token created with a customer ID, Drop-in will render saved payment methods and automatically store any newly-added payment methods in their Vault record.

container string | HTMLElement

A reference to an empty element, such as a <div>, where Drop-in will be included on your page or the selector for the empty element. e.g. #dropin-container.

selector string

Deprecated: Now an alias for options.container.

locale string <optional>
`en_US`

Use this option to change the language, links, and terminology used throughout Drop-in. Supported locales include: ar_EG, cs_CZ, da_DK, de_DE, el_GR, en_AU, en_GB, en_IN, en_US, es_ES, es_XC, fi_FI, fr_CA, fr_FR, fr_XC, he_IL, hu_HU, id_ID, it_IT, ja_JP, ko_KR, nl_NL, no_NO, pl_PL, pt_BR, pt_PT, ru_RU, sk_SK, sv_SE, th_TH, zh_CN, zh_HK, zh_TW, zh_XC.

translations object <optional>

To use your own translations, pass an object with the strings you wish to replace. This object must use the same structure as the object used internally for supported translations, which can be found here. Any strings that are not included will be those from the provided locale or en_US if no locale is provided. See below for an example of creating Drop-in with custom translations.

paymentOptionPriority Array.<string> <optional>

Use this option to indicate the order in which enabled payment options should appear when multiple payment options are enabled. By default, payment options will appear in this order: ['card', 'paypal', 'paypalCredit', 'venmo', 'applePay', 'googlePay']. Payment options omitted from this array will not be offered to the customer.

hiddenVaultedPaymentMethodTypes Array.<string> <optional>

Use this option to hide certain types of vaulted payment methods from being displayed to the customer. Apple Pay, Google Pay and Venmo are always hidden (as those payment methods are only availabe as vaulted payment methods for existing subscriptions, new transactions or subscriptions must be newly authorized). Available options:

  • 'card'
  • 'paypal'
  • 'paypalCredit' (same as PayPal)
card boolean | object <optional>

The configuration options for cards. See cardCreateOptions for all card options. If this option is omitted, cards will still appear as a payment option. To remove cards, pass false for the value.

paypal object <optional>

The configuration options for PayPal. To include a PayPal option in your Drop-in integration, include the paypal parameter and enable PayPal in the Braintree Control Panel. To test in Sandbox, you will need to link a PayPal sandbox test account to your Braintree sandbox account.

Some of the PayPal configuration options are listed here, but for a full list see the PayPal Checkout client reference options.

paypalCredit object <optional>

The configuration options for PayPal Credit. To include a PayPal Credit option in your Drop-in integration, include the paypalCredit parameter and enable PayPal in the Braintree Control Panel.

Some of the PayPal Credit configuration options are listed here, but for a full list see the [PayPal Checkout client reference options](http://braintree.github.io/braintree-web/3.103.0/PayPalCheckout.html#createPayment). For more information on PayPal Credit, see the Braintree Developer Docs.

venmo object | boolean <optional>

The configuration options for Pay with Venmo. To include a Venmo option in your Drop-in integration, include the venmo parameter and follow the documentation for setting up Venmo in the Braintree control panel. If a user's browser does not support Venmo, the Venmo option will not be rendered.

See venmoCreateOptions for venmo options.

applePay object <optional>

The configuration options for Apple Pay. To include an Apple Pay option in your Drop-in integration, include the applePay parameter and enable Apple Pay in the Braintree Control Panel. If a user's browser does not support Apple Pay, the Apple Pay option will not be rendered. See Apple's documentation for browser and device support.

See applePayCreateOptions for applePay options.

googlePay object <optional>

The configuration options for Google Pay. To include a Google Pay option in your Drop-in integration, include the googlePay parameter and enable Google Pay in the Braintree Control Panel. If a user's browser does not support Google Pay, the Google Pay option will not be rendered. See Google's documentation for browser and device support.

See googlePayCreateOptions for googlePay options.

dataCollector object | boolean <optional>

If true is passed, Drop-in will be configured to collect data for use with Advanced Fraud Protection. If collecting data via Kount, pass a dataCollectorOptions object with kount: true instead. If Data Collector is configured and fails to load, Drop-in creation will fail.

threeDSecure boolean | object <optional>

When true is passed, the 3D Secure module will be created with a default configuration. See threeDSecureOptions for additional create options. If 3D Secure is configured and fails to load, Drop-in creation will fail.

vaultManager boolean <optional>
false

Whether or not to allow a customer to delete saved payment methods when used with a client token with a customer id. Note: Deleting a payment method from Drop-in will permanently delete the payment method, so this option is not recommended for merchants using Braintree's recurring billing system.

preselectVaultedPaymentMethod boolean <optional>
true

Whether or not to initialize Drop-in with a vaulted payment method pre-selected. Only applicable when using a client token with a customer id and a customer with saved payment methods.

showDefaultPaymentMethodFirst boolean <optional>
true

When true or left out, the customer's default payment method will be displayed first in the list of vaulted payment methods. When false, the order of the displayed payment methods is not guaranteed. Only applicable when using a client token with a customer id and a customer with saved payment methods.

callback function <optional>

The second argument, data, is the Dropin instance. Returns a promise if no callback is provided.

Source:
Examples

A full example of accepting credit cards with callback API

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Checkout</title>
  </head>
  <body>
    <div id="dropin-container"></div>
    <button id="submit-button">Purchase</button>

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

    <script>
      var submitButton = document.querySelector('#submit-button');

      braintree.dropin.create({
        authorization: 'CLIENT_AUTHORIZATION',
        container: '#dropin-container'
      }, function (err, dropinInstance) {
        if (err) {
          // Handle any errors that might've occurred when creating Drop-in
          console.error(err);
          return;
        }
        submitButton.addEventListener('click', function () {
          dropinInstance.requestPaymentMethod(function (err, payload) {
            if (err) {
              // Handle errors in requesting payment method
            }

            // Send payload.nonce to your server
          });
        });
      });
    </script>
  </body>
</html>

A full example of accepting credit cards with promise API

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Checkout</title>
  </head>
  <body>
    <div id="dropin-container"></div>
    <button id="submit-button">Purchase</button>

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

    <script>
      var submitButton = document.querySelector('#submit-button');

      braintree.dropin.create({
        authorization: 'CLIENT_AUTHORIZATION',
        container: '#dropin-container'
      }).then(function (dropinInstance) {
        submitButton.addEventListener('click', function () {
          dropinInstance.requestPaymentMethod().then(function (payload) {
            // Send payload.nonce to your server
          }).catch(function (err) {
            // Handle errors in requesting payment method
          });
        });
      }).catch(function (err) {
        // Handle any errors that might've occurred when creating Drop-in
        console.error(err);
      });
    </script>
  </body>
</html>

Setting up a Drop-in instance to accept credit cards, PayPal, PayPal Credit, Venmo, and Apple Pay

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  applePay: {
    displayName: 'Merchant Name',
    paymentRequest: {
      total: {
        label: 'Localized Name',
        amount: '10.00'
      }
    }
  },
  paypal: {
    flow: 'checkout',
    amount: '10.00',
    currency: 'USD'
  },
 paypalCredit: {
   flow: 'checkout',
   amount: '10.00',
   currency: 'USD'
  },
  venmo: true
}, function (err, dropinInstance) {
  // Set up a handler to request a payment method and
  // submit the payment method nonce to your server
});

Setting up a Drop-in instance to accept Venmo with restricted browser support

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  venmo: {
    allowNewBrowserTab: false
  }
}, function (err, dropinInstance) {
  // Set up a handler to request a payment method and
  // submit the payment method nonce to your server
});

Submitting the payment method nonce to the server using a form

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Checkout</title>
  </head>
  <body>
    <form id="payment-form" action="/" method="post">
      <div id="dropin-container"></div>
      <input type="submit" value="Purchase"></input>
      <input type="hidden" id="nonce" name="payment_method_nonce"></input>
    </form>

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

    <script>
      var form = document.querySelector('#payment-form');
      var nonceInput = document.querySelector('#nonce');

      braintree.dropin.create({
        authorization: 'CLIENT_AUTHORIZATION',
        container: '#dropin-container'
      }, function (err, dropinInstance) {
        if (err) {
          // Handle any errors that might've occurred when creating Drop-in
          console.error(err);
          return;
        }
        form.addEventListener('submit', function (event) {
          event.preventDefault();

          dropinInstance.requestPaymentMethod(function (err, payload) {
            if (err) {
              // Handle errors in requesting payment method
              return;
            }

            // Send payload.nonce to your server
            nonceInput.value = payload.nonce;
            form.submit();
          });
        });
      });
    </script>
  </body>
</html>

Use your own translations

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  translations: {
    payingWith: 'You are paying with {{paymentSource}}',
    chooseAnotherWayToPay: 'My custom chooseAnotherWayToPay string',
    // Any other custom translation strings
  }
}, callback);

Customizing Drop-in with card form overrides

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  card: {
    overrides: {
      fields: {
        number: {
          placeholder: '1111 1111 1111 1111' // Update the number field placeholder
        },
        postalCode: {
          minlength: 5 // Set the minimum length of the postal code field
        },
        cvv: null // Remove the CVV field from your form
      },
      styles: {
        input: {
          'font-size': '18px' // Change the font size for all inputs
        },
        ':focus': {
          color: 'red' // Change the focus color to red for all inputs
        }
      }
    }
  }
}, callback);

Mask Card Inputs

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  card: {
    overrides: {
      fields: {
        number: {
          maskInput: {
            showLastFour: true
          }
        },
        cvv: {
          maskInput: true
        }
      }
    }
  }
}, callback);

Including a cardholder name field

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  card: {
    cardholderName: true
  }
}, callback);

Including a required cardholder name field

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  card: {
    cardholderName: {
      required: true
    }
  }
}, callback);

Enabling 3D Secure

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container',
  threeDSecure: true
}, function (err, dropinInstance) {
  // setup payment button
  btn.addEventListener('click', function (e) {
    e.preventDefault();

    dropinInstance.requestPaymentMethod(|
      threeDSecure: {
        amount: '100.00',
        billingAddress: {
          givenName: 'Jill', // ASCII-printable characters required, else will throw a validation error
          surname: 'Doe', // ASCII-printable characters required, else will throw a validation error
          phoneNumber: '8101234567',
          streetAddress: '555 Smith St.',
          extendedAddress: '#5',
          locality: 'Oakland',
          region: 'CA',
          postalCode: '12345',
          countryCodeAlpha2: 'US'
        },
        // additional 3ds params
      }
    }, function (err, payload) {
      // inspect payload.liablityShifted
      // send payload.nonce to server
    });
  });
});

Enabled Vault Manager

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

Type Definitions

applePayCreateOptions :object

The configuration options for Apple Pay.

Parameters:
Name Type Attributes Default Description
buttonStyle string <optional>
black

Configures the Apple Pay button style. Valid values are black, white, white-outline.

displayName string

The canonical name for your store. Use a non-localized name. This parameter should be a utf-8 string that is a maximum of 128 characters. The system may display this name to the user.

applePaySessionVersion number <optional>
2

The version of the ApplePaySession to use. It's recommended to use the lowest version that contains all the features you need for your checkout to maximize compatibility.

paymentRequest external:ApplePayPaymentRequest

The payment request details to apply on top of those from Braintree.

Source:

cardCreateOptions :object

The configuration options for cards. Internally, Drop-in uses Hosted Fields to render the card form. The overrides.fields and overrides.styles allow the Hosted Fields to be customized.

Parameters:
Name Type Attributes Default Description
cardholderName boolean | object <optional>

Will enable a cardholder name field above the card number field. If set to an object, you can specify whether or not the field is required. If set to a true, it will default the field to being present, but not required.

Properties
Name Type Attributes Default Description
required boolean <optional>
false

When true, the cardholder name field will be required to request the payment method nonce.

overrides.fields object <optional>

The Hosted Fields [fields options](http://braintree.github.io/braintree-web/3.103.0/module-braintree-web_hosted-fields.html#~fieldOptions). Only number, cvv, expirationDate and postalCode can be configured. Each is a [Hosted Fields field object](http://braintree.github.io/braintree-web/3.103.0/module-braintree-web_hosted-fields.html#~field). selector cannot be modified.

overrides.styles object <optional>

The Hosted Fields [styles options](http://braintree.github.io/braintree-web/3.103.0/module-braintree-web_hosted-fields.html#~styleOptions). These can be used to add custom styles to the Hosted Fields iframes. To style the rest of Drop-in, review the documentation for customizing Drop-in.

clearFieldsAfterTokenization boolean <optional>
true

When false, the card form will not clear the card data when the customer returns to the card view after a successful tokenization.

vault object <optional>

Configuration for vaulting credit cards. Only applies when using a client token with a customer id.

Properties
Name Type Attributes Default Description
allowVaultCardOverride boolean <optional>
false

When true, the card form will include an option to let the customer decide not to vault the credit card they enter.

vaultCard boolean <optional>
true

Whether or not to vault the card upon tokenization. When set to false with allowVaultCardOverride set to false, then cards will not be vaulted.

Source:

dataCollectorOptions :object

The configuration options for Data Collector. Requires advanced fraud protection to be enabled in the Braintree gateway. If using Kount, contact our support team to configure your Kount ID. The device data will be included on the requestPaymentMethod payload.

Parameters:
Name Type Attributes Description
kount boolean <optional>

If true, Kount fraud data collection is enabled.

Source:

googlePayCreateOptions :object

The configuration options for Google Pay. Additional options from the few listed here are available, many have default values applied based on the settings found in the Braintree Gateway. For more information, see Google's Documentation.

Parameters:
Name Type Attributes Default Description
merchantId string

The ID provided by Google for processing transactions in production. Not necessary for testing in sandbox.

googlePayVersion string <optional>
1

The version of the Google Pay API to use. Defaults to 1, but 2 can be passed in.

transactionInfo external:GooglePayTransactionInfo

The transaction details necessary for processing the payment.

button external:GooglePayButtonOptions <optional>

The button options for configuring the look of the Google Pay button. The onClick property cannot be overwritten.

Source:

paypalCreateOptions :object

The configuration options for PayPal and PayPalCredit. For a full list of options see the PayPal Checkout client reference options.

Parameters:
Name Type Attributes Description
flow string

Either checkout for a one-time Checkout with PayPal flow or vault for a Vault flow. Required when using PayPal or PayPal Credit.

amount string | number <optional>

The amount of the transaction. Required when using the Checkout flow.

currency string <optional>

The currency code of the amount, such as USD. Required when using the Checkout flow.

buttonStyle object <optional>

The style object to apply to the PayPal button. Button customization includes color, shape, size, and label. The options found here are available.

commit boolean <optional>

The user action to show on the PayPal review page. If true, a Pay Now button will be shown. If false, a Continue button will be shown.

vault object <optional>

Configuration for vaulting PayPal accounts. Only applies when using a client token with a customer id.

Properties
Name Type Attributes Default Description
vaultPayPal boolean <optional>
true

Whether or not to vault the PayPal account upon tokenization.

Source:

threeDSecureOptions :object

Configuration options to pass when creating the 3D Secure module used in Drop-in. amount for 3D Secure verification can be passed here, but it's recomended that it and all other 3D Secure verification options be passed to the requestPaymentMethod options instead. Any cardinalSDKConfig options must be passed here when creating Drop-in.

Parameters:
Name Type Description
cardinalSDKConfig options

A configuration object to adjust the configuration for the underlying Cardinal SDK (Braintree's 3D Secure provider). See cardinalSDKConfig options for all options.

amount string

Deprecated The amount to verify with 3D Secure. Set amount in the requestPaymentMethod options instead.

Source:

venmoCreateOptions :object|boolean

The configuration options for Venmo. If true is passed instead of a configuration object, the default settings listed will be used.

Parameters:
Name Type Attributes Default Description
allowNewBrowserTab boolean <optional>
true

If false, it restricts supported browsers to those that can app switch to the Venmo app without opening a new tab.

Source: