{"id":12905,"library":"braintree-web-drop-in","title":"Braintree Web Drop-in UI","description":"Braintree Web Drop-in provides a pre-built, customizable user interface for accepting various payment methods (cards, Apple Pay, Google Pay, Venmo) in web applications. It simplifies the integration of Braintree's payment processing services by offering a ready-to-use UI component. The current stable version is 1.46.1. The library typically sees minor releases every few weeks, incorporating updates to the underlying Braintree JavaScript client SDK, adding new payment methods, improving accessibility, and fixing bugs. Key differentiators include its ease of integration for common payment flows, out-of-the-box support for multiple payment methods, localization into 23 languages, and its open-source nature, allowing for significant UI customization if needed, unlike traditional iframe-based solutions. It abstracts away much of the complexity of direct SDK integration for standard use cases, accelerating development.","status":"active","version":"1.46.1","language":"javascript","source_language":"en","source_url":"https://github.com/braintree/braintree-web-dropin","tags":["javascript"],"install":[{"cmd":"npm install braintree-web-drop-in","lang":"bash","label":"npm"},{"cmd":"yarn add braintree-web-drop-in","lang":"bash","label":"yarn"},{"cmd":"pnpm add braintree-web-drop-in","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Braintree JavaScript client SDK, providing payment processing logic.","package":"braintree-web","optional":false}],"imports":[{"note":"The library is primarily designed for direct browser inclusion via script tag or bundler. The `braintree` global is exposed for access to `dropin.create`. Direct ESM/CJS `import` of the top-level Drop-in is not the primary documented pattern for instantiation; instead, you interact with the `braintree` global object once the script is loaded.","wrong":"import Dropin from 'braintree-web-drop-in'","symbol":"braintree.dropin","correct":"braintree.dropin.create({ /* config */ })"},{"note":"This is the primary method to initialize and render the Drop-in UI. It requires an `authorization` (client token or client authorization) and a DOM `selector`.","symbol":"create","correct":"braintree.dropin.create({ authorization: clientToken, selector: '#dropin-container' }, callback)"},{"note":"Called on the created `dropinInstance` to retrieve the payment method nonce after the user has interacted with the UI. The `payload` contains the nonce and other payment details.","symbol":"requestPaymentMethod","correct":"dropinInstance.requestPaymentMethod(function (err, payload) { /* ... */ })"}],"quickstart":{"code":"import dropin from 'braintree-web-drop-in';\n\nconst clientAuthorization = process.env.BRAINTREE_CLIENT_AUTHORIZATION ?? 'YOUR_CLIENT_AUTHORIZATION_HERE';\n\ndocument.addEventListener('DOMContentLoaded', () => {\n  const dropinContainer = document.getElementById('dropin-container');\n  const submitButton = document.getElementById('submit-button');\n\n  if (!dropinContainer || !submitButton) {\n    console.error('Drop-in container or submit button not found.');\n    return;\n  }\n\n  dropin.create({\n    authorization: clientAuthorization,\n    selector: '#dropin-container',\n    paymentOptionTabbable: true, // Example: make payment options keyboard accessible\n    card: {\n      cardholderName: {\n        required: true\n      }\n    }\n  }, (err, dropinInstance) => {\n    if (err) {\n      console.error('Error creating Drop-in:', err);\n      // Implement robust error handling (e.g., inform user, log to server)\n      return;\n    }\n\n    submitButton.addEventListener('click', () => {\n      dropinInstance.requestPaymentMethod((err, payload) => {\n        if (err) {\n          console.error('Error requesting payment method:', err);\n          // Inform the user about the issue\n          return;\n        }\n        // Send payload.nonce to your server for transaction processing\n        console.log('Payment method nonce:', payload.nonce);\n        console.log('Payment method type:', payload.type);\n        console.log('Payment details:', payload.details);\n        // Example: AJAX call to your server\n        // fetch('/checkout', {\n        //   method: 'POST',\n        //   headers: { 'Content-Type': 'application/json' },\n        //   body: JSON.stringify({ nonce: payload.nonce })\n        // })\n        // .then(response => response.json())\n        // .then(data => console.log('Transaction response:', data))\n        // .catch(error => console.error('Transaction error:', error));\n      });\n    });\n  });\n});\n\n// Minimal HTML structure (add to your HTML body):\n// <div id=\"dropin-container\"></div>\n// <button id=\"submit-button\">Purchase</button>\n","lang":"javascript","description":"This quickstart demonstrates how to initialize the Braintree Drop-in UI, configure it to require a cardholder name, and retrieve a payment method nonce when a button is clicked, suitable for server-side processing."},"warnings":[{"fix":"Consult the `braintree-web` changelog and Braintree developer documentation for specific migration guides.","message":"Major version updates to `braintree-web` (the underlying SDK) can introduce breaking changes. Always review the Braintree JavaScript Client SDK release notes when `braintree-web-drop-in` updates its core `braintree-web` dependency to a new major version or a significant minor version jump.","severity":"breaking","affected_versions":">=1.0"},{"fix":"Ensure the `authorization` value (client token or client authorization) is fresh, valid, and generated securely on your server for the current session. Do not hardcode client tokens.","message":"Providing an invalid or expired `authorization` client token will prevent Drop-in from initializing correctly or making API calls, leading to errors in the `create` callback.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Ensure the `requestPaymentMethod` call is triggered by user interaction (e.g., clicking a 'Pay with Apple Pay' or 'Pay with Venmo' button within the Drop-in UI, or a submit button after the user has selected one of these methods).","message":"When integrating Apple Pay or Venmo, if `requestPaymentMethod` is called without the user first interacting with the respective payment button, an error message may appear prompting the customer to click the button. This is expected behavior for certain payment methods requiring user gesture.","severity":"gotcha","affected_versions":">=1.40.0"},{"fix":"Refer to the Braintree documentation for the most up-to-date and complete CSP directives required for all integrated payment methods. Specifically check `script-src`, `style-src`, `img-src`, `connect-src`, and `frame-src`.","message":"Drop-in requires specific Content Security Policy (CSP) directives, especially for payment methods like Google Pay, and for loading its assets. Incorrect CSP can lead to assets failing to load or payment methods not functioning.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Upgrade to the latest `braintree-web-drop-in` version (v1.x) for improved customization, modern UI, and better integration with site styling. Refactor any styling assumptions based on iframe encapsulation.","message":"Older versions of Drop-in (prior to v1) relied heavily on iframes and different styling paradigms. The current stable version is designed to be styled more freely.","severity":"deprecated","affected_versions":"<1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Regenerate a new client token on your server using your Braintree API keys and ensure it is passed correctly to the `authorization` option during Drop-in creation.","cause":"The client token provided for `authorization` is invalid, expired, or generated with incorrect credentials.","error":"Error: Braintree API: Authorization is not valid."},{"fix":"Update your server's CSP headers or `<meta>` tag to include the necessary domains for Braintree, Google Pay, Apple Pay, etc., as specified in the official Braintree documentation.","cause":"Your website's Content Security Policy (CSP) is too restrictive and prevents Braintree scripts, styles, or images from loading, or prevents API calls.","error":"Content Security Policy: The page's settings blocked the loading of a resource"},{"fix":"Verify that the HTML element specified by the `selector` (e.g., `<div id=\"dropin-container\"></div>`) exists in the DOM before `dropin.create` is called and that the selector string matches its ID or class.","cause":"The `selector` option passed to `dropin.create` does not point to an existing DOM element where Drop-in should render.","error":"Error: A `selector` must be a valid DOM element or a string CSS selector."},{"fix":"Ensure your development and production environments are served over HTTPS. For local development, enable specific browser flags or use tools that provide a secure local context if possible, though HTTPS is generally required for production.","cause":"You are attempting to use Apple Pay in an insecure context (HTTP) or localhost without specific developer setup.","error":"Error: Apple Pay requires a secure context (HTTPS)."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}