Braintree's Drop-in UI offers a complete, ready-made payment UI for a quick and easy way to accept payments. It's equally as easy to maintain PCI compliance with Drop-in; it is eligible for SAQ A since Braintree hosts the form that captures customer payment information.

The UI includes a card entry form and, if enabled, Android Pay, Apple Pay, and PayPal/Venmo buttons (Venmo only on mobile). When a user completes the UI, your client code obtains a payment method nonce for use on your server.

The Drop-in UI is the quickest way to start accepting payments, but depending on your business's needs, it might not be the best choice for you. Here's a general overview of the differences between a custom integration and the Drop-in UI.

Drop-in UI Custom Integration
  • More developer work needed than Drop-in UI
  • Create your own payment form with custom colors and layout
  • Collect any customer information that you’d like
  • Translate payment form to any language you want
  • Typically qualifies you for the SAQ A PCI compliance form on mobile and the SAQ A-EP form on web (unless using Hosted Fields)

Demo

A correctly configured Drop-in UI integration with PayPal enabled is shown below:

note

To see an end-to-end implementation using the Drop-in UI, take a look at our example integrations.

Availability

Currently, the Drop-in option is available in 23 languages on iOS and Android, but only in English (US) on the web. We plan to add further multilingual support in future releases. Until then, if you wish to create a checkout in another language than English (US), we recommend using a custom client SDK integration.

Configuration

In order to use the Drop-in UI, you'll first need to generate a client token on your server.

Customer ID

If you pass a customer_id when generating the client token, the Drop-in will display that customer's saved payment methods and automatically add any newly-entered credit card payment methods to their Vault record.

Client-side implementation

Configure the container and form where the Drop-in UI will add the payment method nonce. Make sure to replace CLIENT-TOKEN-FROM-SERVER with your generated client token.

HTML
<form>
  <div id="dropin-container"></div>
</form>
JavaScript
braintree.setup('CLIENT-TOKEN-FROM-SERVER', 'dropin', {
  container: 'dropin-container'
});

braintree.setup requires Braintree.js, which adds a hidden input named payment_method_nonce to your form. As a result, it is required for container to be inside a form. When your user submits the form, you can use the nonce to create transactions or customers, or to store existing customers in the Vault. To learn more about client configuration, visit our setup guide.

PayPal

If you have PayPal configured, you will see a PayPal button with no additional configuration. By default, you will be setup to use our Vault flow. If you would like to use Checkout with PayPal you must pass in singleUse, amount and currency:

HTML
<form>
  <div id="dropin-container"></div>
</form>
JavaScript
braintree.setup('CLIENT-TOKEN-FROM-SERVER', 'dropin', {
  container: 'dropin-container',
  paypal: {
    singleUse: true,
    amount: 10.00,
    currency: 'USD'
  }
});

Fields

The Drop-in UI provides several fields.

  • Credit Card
  • Expiration Date
  • CVV
  • Postal Code
note

CVV and Postal Code are rendered conditionally according to your AVS and CVV Settings.

Options

Container

At a minimum, a container must be provided in order to display the inline form. This container may be an ID, DOM node, or jQuery object (such as $("#container")). Braintree.js will attach its behavior to the closest parent form. The container must be a child of a form.

HTML
<form>
  <div id="dropin-container"></div>
</form>
JavaScript
braintree.setup('CLIENT-TOKEN-FROM-SERVER', 'dropin', {
  container: 'dropin-container'
});

Form

If you want Braintree.js to attach its behavior to a form other than the closest parent form (default), you may specify the id of the target form in the options:

HTML
<div id="dropin-container"></div>
<form id="checkout-form">
  <input type='submit' value='Pay'/>
</form>
JavaScript
braintree.setup('CLIENT-TOKEN-FROM-SERVER', 'dropin', {
  container: 'dropin-container',
  form: 'checkout-form'
});

PayPal Checkout button

If you're not a fan of the PayPal button that comes standard with Drop-in, there's another option: in JS versions 2.18.0+, you can use the PayPal Checkout button instead:

JavaScript
braintree.setup('CLIENT-TOKEN-FROM-SERVER', 'dropin', {
  container: 'dropin-container',
  paypal: {
    button: {
      type: 'checkout'
    }
  }
});

Callbacks

The callback options available in the Drop-in integration apply to all Braintree.js integrations. However, the payloads returned may differ slightly depending on the use case. For more information about these top-level callbacks, see the JavaScript SDK reference.

onPaymentMethodReceived

This is called when a payment_method_nonce has been generated by Drop-in (as the result of a form submission). It will be called with a paymentMethod object, which contains the nonce as a string. For more information on this callback and its payload, see Setup method options.

important

If onPaymentMethodReceived is defined, Braintree.js will not add a hidden input to your form, inject the nonce into that hidden input, or submit the form. Upon receiving a nonce, it is up to you to send data to your server as you see fit.

JavaScript
braintree.setup('CLIENT-TOKEN-FROM-SERVER', 'dropin', {
  container: 'dropin-container',
  onPaymentMethodReceived: function (obj) {
    // Do some logic in here.
    // When you're ready to submit the form:
    myForm.submit();
  }
});
onReady

onReady fires when the Braintree Drop-in has fully loaded and is ready to be interacted with by the user. Properties are available in the setup method options reference.

onError

As with onPaymentMethodReceived, the general usage of the onError callback is documented in the setup method options reference.

Validation errors

When client-side validation fails in Drop-in, onError will fire with a VALIDATION type. This error payload will also present information about which fields were invalid as well as whether or not they were empty.

Key Type Description
type String VALIDATION
message String 'Some payment method input fields are invalid.'
details Object An object containing specific details of the error.
Key Type Description
invalidFields Array A collection of field object references. See below for more information.

Error field objects

Key Type Description
fieldKey String A string representing the field which failed validation. It will match one of the following:
- number - cvv - expiration - postalCode
isEmpty Boolean This will be true if the associated input is empty.
Server-related errors

When a server-related error occurs, onError will fire with a SERVER type. Scenarios in which this may occur:

Server-related errors are provided to onError in version 2.23.0+ of our JavaScript SDK.

Key Type Description
type String SERVER
message String An error message returned by the server.
details Object An object containing specific details of the error. This will be passed directly from Braintree's gateway and varies depending on the error.
JavaScript
braintree.setup('CLIENT-TOKEN-FROM-SERVER', 'dropin', {
  container: 'dropin-container',
  onError: function (obj) {
    if (obj.type == 'VALIDATION') {
      // Validation errors contain an array of error field objects:
      obj.details.invalidFields;

    } else if (obj.type == 'SERVER') {
      // If the customer's browser cannot connect to Braintree:
      obj.message; // "Connection error"

      // If the credit card failed verification:
      obj.message; // "Credit card is invalid"
      obj.details; // Object with error-specific information
    }
  }
});

Advanced fraud tools

Enable fraud tools for your Drop-in form by including the loading and initializing script on the client side. Then, use the server side handling when making a Braintree library call.

Custom integration

If the Drop-in UI doesn't fit your needs, develop your own custom integration using our client SDKs to accept credit cards, Android Pay, Apple Pay, PayPal, and Venmo payments. This allows you full control over the checkout process.

Using our native mobile SDKs, you can typically qualify for the SAQ A PCI compliance form regardless of whether you use a Drop-in or custom integration. However, our JavaScript SDK for the web typically qualifies you for the SAQ A-EP form. If you want to provide a custom experience on the web without extra PCI burden, consider using Hosted Fields.

note

By choosing a custom integration you will be responsible for the tokenization process for both credit cards and PayPal.

See also

Still Have Questions?

If you can’t find an answer, give us a call at 877.434.2894 or contact our Support team