braintree-web-drop-in - Documentation

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:

index.js, line 2

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.41.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.41.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.41.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.41.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.41.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.41.0.

Source:

index.js, line 628

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.97.4/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

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

Source:

index.js, line 192

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

index.js, line 153

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

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

The Hosted Fields [fields options](http://braintree.github.io/braintree-web/3.97.4/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.97.4/module-braintree-web_hosted-fields.html#~field). selector cannot be modified.

overrides.styles

object

The Hosted Fields [styles options](http://braintree.github.io/braintree-web/3.97.4/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

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

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:

index.js, line 116

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:

index.js, line 129

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:

index.js, line 161

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

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

currency

string

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

buttonStyle

object

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

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

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:

index.js, line 142

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:

index.js, line 135

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:

index.js, line 187