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. This will be your authorization
used when creating Drop-in.
Setup
Drop-in is available directly from our servers, which you can include on your site as a script tag or download the file and save it locally:
<script src="https://js.braintreegateway.com/web/dropin/1.27.0/js/dropin.min.js"></script>
This adds a global braintree
object which includes dropin
:
braintree.dropin.create({ /* options */ }, callback);
If you're using npm, install the latest version of the braintree-web-drop-in module:
npm install --save braintree-web-drop-in
The examples on this page reference braintree.dropin.create
, but if you're using the module from npm, create
will be on the top level of the object:
var dropin = require('braintree-web-drop-in');
dropin.create({ /* options */ }, callback);
Client-side implementation
To get started, you will need client authorization, a container where Drop-in will appear, and a button. When loaded, the UI will appear in the container.
Configure your button to call requestPaymentMethod
to retrieve the payment method object, including the payment method nonce. From there, you can submit the nonce to your server in whatever way you see fit.
<head>
<meta charset="utf-8">
<script src="https://js.braintreegateway.com/web/dropin/1.27.0/js/dropin.min.js"></script>
</head>
<body>
<div id="dropin-container"></div>
<button id="submit-button">Request payment method</button>
<script>
var button = document.querySelector('#submit-button');
braintree.dropin.create({
authorization: 'CLIENT_AUTHORIZATION',
container: '#dropin-container'
}, function (createErr, instance) {
button.addEventListener('click', function () {
instance.requestPaymentMethod(function (requestPaymentMethodErr, payload) {
// Submit payload.nonce to your server
});
});
});
</script>
</body>
See our reference documentation for more information about creating Drop-in.
Configuring payment methods
Additional steps are required for the Drop-in UI to accept payment methods other than cards. After completing the Drop-in setup instructions, follow the steps below for each payment method type.
Credit cards
By default, cards will be enabled when you configure Drop-in. CVV and Postal Code inputs are rendered conditionally according to your AVS and CVV settings.
Call requestPaymentMethod
to get a card payment method payload, which includes a payment method nonce to send to your server at payload.nonce
.
PayPal
If you have PayPal configured in your gateway, include a PayPal configuration object in your create call to render a PayPal option. To use our Vault flow, include flow: 'vault'
in your PayPal configuration:
braintree.dropin.create({
authorization: 'CLIENT_AUTHORIZATION',
container: '#dropin-container',
paypal: {
flow: 'vault'
}
}, callback);
To use Checkout with PayPal, include flow: 'checkout'
as well as an amount
and currency
.
braintree.dropin.create({
authorization: 'CLIENT_AUTHORIZATION',
container: '#dropin-container',
paypal: {
flow: 'checkout',
amount: '10.00',
currency: 'USD'
}
}, callback);
For other PayPal configuration options, see the createPayment
options in our PayPal client reference.
Call requestPaymentMethod
to get a PayPal payment method payload, which includes a payment method nonce to send to your server at payload.nonce
.
Venmo
Before including Venmo in Drop-in, complete the steps outlined in the Venmo configuration guide. Once you are configured to use Venmo, include a venmo
property in your Drop-in create
call to render a Venmo option on supported browsers (currently most Android and iOS mobile web browsers).
braintree.dropin.create({
authorization: 'CLIENT_AUTHORIZATION',
container: '#dropin-container',
venmo: {} // The `venmo` object requires no properties to instantiate.
}, callback);
On some browsers, Venmo may open a new tab, redirect back to your website, then refresh the page. This could break a single page app. To only present Venmo on browsers that support Venmo without a redirect, pass allowNewBrowserTab: false
in the configuration:
braintree.dropin.create({
authorization: 'CLIENT_AUTHORIZATION',
container: '#dropin-container',
venmo: {
allowNewBrowserTab: false
}
}, callback);
For more information, see the client-side details on verifying browser support.
To get a payment method nonce to send to your server, call requestPaymentMethod
. This returns a Venmo payment method payload with a nonce at payload.nonce
.
If using a client token with a customer id, the Venmo account will not automatically be vaulted. You can use the payment method nonce to create a payment method on your server.
Apple Pay
Before including Apple Pay in Drop-in, complete the steps outlined in the Apple Pay configuration guide. Once you are configured to use Apple Pay, include an applePay
property in your Drop-in create
call to render an Apple Pay option.
The applePay
object requires a displayName
and a paymentRequest
, which requires a total
with a label
and an amount
. The details provided in the paymentRequest
object are used to create an ApplePayPaymentRequest
to process the payment.
braintree.dropin.create({
authorization: 'CLIENT_AUTHORIZATION',
container: '#dropin-container',
applePay: {
displayName: 'My Store',
paymentRequest: {
total: {
label: 'My Store',
amount: '19.99'
},
// We recommend collecting billing address information, at minimum
// billing postal code, and passing that billing postal code with all
// Apple Pay transactions as a best practice.
requiredBillingContactFields: ["postalAddress"]
}
}
}, callback);
All ApplePayPaymentRequest
options are supported in paymentRequest
; Braintree will automatically supply all required values with the exception of total
.
Apple Pay is available in Safari on iOS version 10+ and macOS version 10.12+. If Apple Pay is not supported by the customer's browser, the options to select Apple Pay will not appear. For more information, see Apple's support articles on Apple Pay.
Call requestPaymentMethod
to get an Apple Pay payment method payload, which includes a payment method nonce to send to your server at payload.nonce
.
If using a client token with a customer id, the Apple Pay card will not automatically be vaulted. You can use the payment method nonce to create a payment method on your server.
Google Pay
Before including Google Pay in Drop-in, complete the steps outlined in the Google Pay configuration guide. Once you are configured to use Google Pay, include a googlePay
property in your Drop-in create
call to render a Google Pay option.
Google Pay is available in Google Chrome v61 or higher on Android. If Google Pay is not supported by the customer's browser, the option to select Google Pay will not appear. See Google's developer documentation on testing browser compatibility for more information.
The googlePay
object requires a merchantId
provided by Google (when in production) and a transactionInfo
object. All other GooglePayPaymentDataRequest
parameters are supplied by Braintree, but may be overwritten by passing them in the googlePay
object.
braintree.dropin.create({
authorization: 'CLIENT_AUTHORIZATION',
container: '#dropin-container',
googlePay: {
googlePayVersion: 2,
merchantId: 'merchant-id-from-google',
transactionInfo: {
totalPriceStatus: 'FINAL',
totalPrice: '123.45',
currencyCode: 'USD'
},
allowedPaymentMethods: [{
type: 'CARD',
parameters: {
// We recommend collecting and passing billing address information with all Google Pay transactions as a best practice.
billingAddressRequired: true,
billingAddressParameters: {
format: 'FULL'
}
}
}]
}
}, callback);
To get a payment method nonce to send to your server, call requestPaymentMethod
. This returns a Google Pay payment method payload with a nonce at payload.nonce
.
If using a client token with a customer id, the Google Pay card will not automatically be vaulted. You can use the payment method nonce to create a payment method on your server.
3D Secure
Drop-in supports 3D Secure 2 verification. To use 3D Secure in your integration, follow our implementation guide. Once you have added 3D Secure to Drop-in, you will need to complete the server-side implementation for 3D Secure.
Error handling
Errors in Drop-in should be handled in both the create
and requestPaymentMethod
callbacks in Drop-in.
braintree.dropin.create({
authorization: 'CLIENT_AUTHORIZATION',
container: '#dropin-container'
}, function (createErr, instance) {
if (createErr) {
// An error in the create call is likely due to
// incorrect configuration values or network issues.
// An appropriate error will be shown in the UI.
console.error(createErr);
return;
}
button.addEventListener('click', function () {
instance.requestPaymentMethod(function (requestPaymentMethodErr, payload) {
if (requestPaymentMethodErr) {
// No payment method is available.
// An appropriate error will be shown in the UI.
console.error(requestPaymentMethodErr);
return;
}
// Submit payload.nonce to your server
});
});
});
Select a supported language for your checkout form
Drop-in is available in 23 languages in JS v3. To use a locale, include it in your create
configuration:
braintree.dropin.create({
authorization: 'CLIENT_AUTHORIZATION',
container: '#dropin-container',
locale: 'de_DE'
}, callback);
You can also provide your own translations by including a translations
object as part of your create call. The following example changes the expiration date label to say "Expiry Date" instead of the default label, "Expiration Date":
braintree.dropin.create({
authorization: 'CLIENT_AUTHORIZATION',
container: '#dropin-container',
translations: {
expirationDateLabel: 'Expiry Date',
// Any other custom translation strings...
}
}, callback);
See our default translations for a full list of translation strings.
Next steps
- Read the Set Up Your Server guide to learn about our server SDKs and how to send a nonce to your server
- Explore the ways to customize the appearance and functionality of Drop-in
- Learn how to manage different payment methods