Our Drop-in UI is a complete, ready-made payment UI that offers 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 we host the form that captures customer payment information.

The UI includes a card entry form and, if enabled, a PayPal button. When a user successfully completes the UI, your client code obtains a payment method nonce for use on your server.

Drop-in UI vs. custom integration

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
  • Translate payment form to any language you want
  • Collect any customer information that you’d like
  • Using Hosted Fields typically qualifies you for the SAQ A PCI compliance form (if not using Hosted Fields, custom web integrations typically qualify for SAQ A-EP)

Demo

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

Availability

Drop-in is only available in English.

Upgrade to the latest versions of our iOS, Android, and JavaScript SDKs for additional language support.

Configuration

In order to use the Drop-in UI, you'll first need to get a tokenization key from the Control Panel or generate a client token on your server.

Upgrade to iOS SDK v4, Android SDK v2, or JS SDK v3 to use a tokenization key, a static form of client authorization obtained from the Control Panel.

Customer ID

If you pass a customer_id when generating a client token, Drop-in will display that customer's saved payment methods and automatically add any newly-entered 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
Click to copy
Copied
<form>
  <div id="dropin-container"></div>
</form>
JavaScript
Click to copy
Copied
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
Click to copy
Copied
<form>
  <div id="dropin-container"></div>
</form>
JavaScript
Click to copy
Copied
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
Click to copy
Copied
<form>
  <div id="dropin-container"></div>
</form>
JavaScript
Click to copy
Copied
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
Click to copy
Copied
<div id="dropin-container"></div>
<form id="checkout-form">
  <input type='submit' value='Pay'/>
</form>
JavaScript
Click to copy
Copied
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
Click to copy
Copied
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
Click to copy
Copied
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
Click to copy
Copied
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:

  1. Updating your client-side integration to collect device data
  2. Updating your server-side integration to pass device data on transaction and verification requests
  3. Enabling Advanced Fraud Tools in your Braintree Control Panel

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, PayPal, and other available payment method types. 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, contact our Support team.