Braintree Web Drop-in Reference v1.43.0

• Overview
• Setup
• Usage
  • Accepting cards
  • Accepting PayPal
  • Accepting Venmo
  • Accepting Apple Pay
  • Accepting Google Pay
  • Localization
  • Events
  • Styling
• Browser support
• Content Security Policy
• Additional resources

Overview

Drop-in is a pre-made payments UI for desktop and mobile browsers to be used with cards, PayPal, and PayPal Credit. It can be used as a one-time guest checkout or to offer saved payment methods with a client token created using a customer ID.

Test out our demo app with one of our test card numbers or a sandbox PayPal account.

If you have any feedback or questions, create a GitHub issue or contact Braintree support.

Setup

The Drop-in source is available from our CDN, that you can include in your project with a script tag:

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

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

You can also get Drop-in from npm.

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

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

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

Usage

Drop-in provides a payment method object containing the payment method nonce to send to your server. To get this object, use the requestPaymentMethod function.

If you are using a script tag integration, a hidden payment_method_nonce input will be added to the form with the nonce value. The following instructions specify usage of a JavaScript integration.

Accepting cards

By default, Drop-in is configured to accepted cards and does not require any additional parameters in the create call. If you are only accepting cards, Drop-in will appear as a card form. If you are accepting multiple payment options, Card will appear as an option in the list. CVV and Postal Code inputs are rendered conditionally based on AVS and CVV settings.

For credit cards, calling requestPaymentMethod will attempt to validate the card form and will call the supplied callback with a payload, including the payment method nonce, if successful. If not successful, an error will be shown in the UI and the callback will be called with an error. Errors include invalid card details as well as card types not enabled by your merchant account.

Use events to know when the card form could be considered valid. This does not necessarily mean the card form is complete, but it means it is considered valid by our client side validation.

Accepting PayPal

For PayPal and PayPal Credit, users will click the PayPal button and continue through the PayPal authentication flow. After successful completion, the PayPal account will be visible in the UI and that payment method can be requested. Use events to know when the authentication flow has been completed and the payment method can be requested.

More details about PayPal and PayPal Credit can be found in the Braintree developer docs.

Accepting Venmo

For Venmo, users will click the Venmo button on their mobile device, which will open up the Venmo app to authenticate the purchase and then return back to the webpage. After successful completion, the Venmo account will be visible in the UI and that payment method can be requested. Use events to know when the authentication flow has been completed and the payment method can be requested.

More details about Venmo can be found in the Braintree developer docs.

Accepting Apple Pay

For Apple Pay, users will click the Apple Pay button. After successful completion, the payment method can be requested. Use events to know when the authentication flow has been completed and the payment method can be requested.

More details about Apple Pay can be found in the Braintree developer docs.

Accepting Google Pay

For Google Pay, users will click the Google Pay button. After successful completion, the payment method can be requested. Use events to know when the authentication flow has been completed and the payment method can be requested.

More details about Google Pay can be found in the Braintree developer docs.

Localization

To translate Drop-in into different languages, pass a supported locale code in your create call:

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

Events

Use events to know whether or not a payment method is currently available from Drop-in. This can be used to dynamically enable and disable a submit button or automatically submit a nonce to your server after the PayPal flow has successfully completed.

See on for more details and an example of event usage.

Styling

The stylesheet for Drop-in will load automatically when Drop-in is initialized.

If you are using a custom build of Drop-in or would like to use an alternative stylesheet, you can provide a link tag on your page with the id braintree-dropin-stylesheet. This will prevent the external stylesheet from loading.

If you are using npm to manage your assets and would prefer to use a local version of the CSS, you can use the dropin.css file found in node_modules/braintree-web-drop-in/dropin.css and put it on your page in a link tag with the id braintree-dropin-stylesheet.

Browser support

Drop-in and the Braintree JS SDK have the same browser support.

Using braintree-web-drop-in with a Content Security Policy

Content Security Policy is a feature of web browsers that mitigates cross-site scripting and other attacks. By limiting the origins of resources that may be loaded on your page, you can maintain tighter control over any potentially malicious code. We recommend considering the implementation of a CSP when available.

Basic Directives

PayPal Specific Directives

If using PayPal, include these additional directives:

Google Pay Specific Directives

If using Google Pay, include these additional directives:

The style-src directive is required so that the styles for the Google Pay button can be generated by the Google Pay SDK. You may omit this directive, so long as you include style rules for the Google Pay button to satisfy Google's brand guidelines.

If Google adds redirects or changes URLs related to the Google Pay component, the domains or URLs in these directives may change.

3D Secure Specific Directives

If using 3D Secure, include these additional directives:

3D Secure 2 utilizes an iframe implementation that requires the use of the issuing bank's full ACS URL. In contrast to 3D Secure 1, the 3D Secure 2 core framework does not allow masked URLs or redirects. Given that the list of possible ACS URLs changes regularly and varies between issuers and ACS providers, there is not a strict CSP configuration available for 3D Secure 2.

Additionally, 3D Secure 2 includes a data collection flow called "3DS Method" or "Method URL Collection", which also utilizes the ACS URL directly. This process increases authentication success significantly and is considered mandatory by Visa. Blocking this process through a CSP can potentially result in authentication failures and increased friction within the checkout experience.

If maintaining a CSP in an integration that uses 3D Secure, merchants must set frame-src * to allowlist all potential ACS URLs that could be utilized during the 3D Secure authentication process.

Data Collector Specific Directives

If using Kount with Data Collector, adhere to the Kount CSP guide.

Additional resources

• Braintree Drop-in Payment UI guide
• braintree-web-drop-in GitHub repo