Dropin

Dropin

This class represents a Drop-in component, that will create a pre-made UI for accepting cards and PayPal on your page. Instances of this class have methods for requesting a payment method and subscribing to events. For more information, see the Drop-in guide in the Braintree Developer Docs. To be used in conjunction with the Braintree Server SDKs.

Constructor

new Dropin(options)

Do not use this constructor directly. Use dropin.create instead.

Parameters:
Name Type Description
options object

For create options, see dropin.create.

Source:

Methods

clearSelectedPaymentMethod() → {void}

Removes the currently selected payment method and returns the customer to the payment options view. Does not remove vaulted payment methods.

Source:
Example
dropinInstance.requestPaymentMethod(function (requestPaymentMethodError, payload) {
  if (requestPaymentMethodError) {
    // handle errors
    return;
  }

  functionToSendNonceToServer(payload.nonce, function (transactionError, response) {
    if (transactionError) {
      // transaction sale with selected payment method failed
      // clear the selected payment method and add a message
      // to the checkout page about the failure
      dropinInstance.clearSelectedPaymentMethod();
      divForErrorMessages.textContent = 'my error message about entering a different payment method.';
    } else {
      // redirect to success page
    }
  });
});

getAvailablePaymentOptions() → {Array.<string>}

Get a list of the available payment methods presented to the user. This is useful for knowing if a paricular payment option was presented to a customer that is browser dependant such as Apple Pay, Google Pay and Venmo. Returns an array of strings. Possible values:

  • applePay
  • card
  • googlePay
  • paypalCredit
  • paypal
  • venmo
Source:
Example
var paymentOptions = dropinInstance.getAvailablePaymentOptions(); // ['card', 'venmo', 'paypal']

if (paymentOptions.includes('venmo')) {
  // special logic for when venmo is displayed
}

isPaymentMethodRequestable() → {Boolean}

Returns a boolean indicating if a payment method is available through requestPaymentMethod. Particularly useful for detecting if using a client token with a customer ID to show vaulted payment methods.

Source:

off(event, handler) → {void}

Unsubscribes a handler function to a named event.

Parameters:
Name Type Description
event string

The name of the event to which you are unsubscribing.

handler function

A callback to unsubscribe from the event.

Source:
Example

Subscribe and then unsubscribe from event

var callback = function (event) {
  // do something
};
dropinInstance.on('paymentMethodRequestable', callback);

// later on
dropinInstance.off('paymentMethodRequestable', callback);

on(event, handler) → {void}

Parameters:
Name Type Description
event string

The name of the event to which you are subscribing.

handler function

A callback to handle the event.

Source:
Examples

Dynamically enable or disable your submit button based on whether or not the payment method is requestable

var submitButton = document.querySelector('#submit-button');

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container'
}, function (err, dropinInstance) {
  submitButton.addEventListener('click', function () {
    dropinInstance.requestPaymentMethod(function (err, payload) {
      // Send payload.nonce to your server.
    });
  });

  if (dropinInstance.isPaymentMethodRequestable()) {
    // This will be true if you generated the client token
    // with a customer ID and there is a saved payment method
    // available to tokenize with that customer.
    submitButton.removeAttribute('disabled');
  }

  dropinInstance.on('paymentMethodRequestable', function (event) {
    console.log(event.type); // The type of Payment Method, e.g 'CreditCard', 'PayPalAccount'.
    console.log(event.paymentMethodIsSelected); // true if a customer has selected a payment method when paymentMethodRequestable fires

    submitButton.removeAttribute('disabled');
  });

  dropinInstance.on('noPaymentMethodRequestable', function () {
    submitButton.setAttribute('disabled', true);
  });
});

Automatically submit nonce to server as soon as it becomes available

var submitButton = document.querySelector('#submit-button');

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container'
}, function (err, dropinInstance) {
  function sendNonceToServer() {
    dropinInstance.requestPaymentMethod(function (err, payload) {
      if (err) {
        // handle errors
      }

      // send payload.nonce to your server
    });
  }

  // allows us to still request the payment method manually, such as
  // when filling out a credit card form
  submitButton.addEventListener('click', sendNonceToServer);

  dropinInstance.on('paymentMethodRequestable', function (event) {
    // if the nonce is already available (via PayPal authentication
    // or by using a stored payment method), we can request the
    // nonce right away. Otherwise, we wait for the customer to
    // request the nonce by pressing the submit button once they
    // are finished entering their credit card details. This is
    // particularly important if your credit card form includes a
    // postal code input. The `paymentMethodRequestable` event
    // could fire before the customer has finished entering their
    // postal code. (International postal codes can be as few as 3
    // characters in length)
    if (event.paymentMethodIsSelected) {
      sendNonceToServer();
    }
  });
});

Listen on various events from the card view

braintree.dropin.create({
  authorization: 'CLIENT_AUTHORIZATION',
  container: '#dropin-container'
}, function (err, dropinInstance) {
  dropinInstance.on('card:focus', function (event) {
    // a card field was focussed
  });
  dropinInstance.on('card:blur', function (event) {
    // a card field was blurred
  });
  dropinInstance.on('card:validityChange', function (event) {
    // the card form went from invalid to valid or valid to invalid
  });
});

requestPaymentMethod(optionsopt, callbackopt) → {void|Promise}

Requests a payment method object which includes the payment method nonce used by by the Braintree Server SDKs.

If a payment method is not available, an error will appear in the UI. When a callback is used, an error will be passed to it. If no callback is used, the returned Promise will be rejected with an error.

Parameters:
Name Type Attributes Description
options object <optional>

All options for requesting a payment method.

Properties
Name Type Attributes Description
threeDSecure object <optional>

Any of the options in the Braintree 3D Secure client reference except for nonce, bin, and onLookupComplete. If amount is provided, it will override the value of amount in the 3D Secure create options. The more options provided, the more likely the customer will not need to answer a 3DS challenge. When 3DS is enabled, both credit cards and non-network tokenized Google Pay cards will perform verfication. The recommended fields for achieving a 3DS v2 verification are:

  • email
  • mobilePhoneNumber
  • billingAddress

For an example of verifying 3D Secure within Drop-in, check out this codepen.

callback callback <optional>

May be used as the only parameter in requestPaymentMethod if no options are provided. The first argument will be an error if no payment method is available and will otherwise be null. The second argument will be an object containing a payment method nonce; either a cardPaymentMethodPayload, a paypalPaymentMethodPayload, a venmoPaymentMethodPayload, a googlePayPaymentMethodPayload or an applePayPaymentMethodPayload. If no callback is provided, requestPaymentMethod will return a promise.

Source:
Examples

Requesting a payment method

var form = document.querySelector('#my-form');
var hiddenNonceInput = document.querySelector('#my-nonce-input');

form.addEventListener('submit', function (event) {
 event.preventDefault();

 dropinInstance.requestPaymentMethod(function (err, payload) {
   if (err) {
     // handle error
     return;
   }
   hiddenNonceInput.value = payload.nonce;
   form.submit();
 });
});

Requesting a payment method with data collector

var form = document.querySelector('#my-form');
var hiddenNonceInput = document.querySelector('#my-nonce-input');
var hiddenDeviceDataInput = document.querySelector('#my-device-data-input');

form.addEventListener('submit', function (event) {
 event.preventDefault();

 dropinInstance.requestPaymentMethod(function (err, payload) {
   if (err) {
     // handle error
     return;
   }
   hiddenNonceInput.value = payload.nonce;
   hiddenDeviceDataInput.value = payload.deviceData;
   form.submit();
 });
});

Requesting a payment method with 3D Secure

var form = document.querySelector('#my-form');
var hiddenNonceInput = document.querySelector('#my-nonce-input');

form.addEventListener('submit', function (event) {
 event.preventDefault();

 dropinInstance.requestPaymentMethod(function (err, payload) {
   if (err) {
     // Handle error
     return;
   }

   if (payload.liabilityShifted || (payload.type !== 'CreditCard' && payload.type !== 'AndroidPayCard')) {
     hiddenNonceInput.value = payload.nonce;
     form.submit();
   } else {
     // Decide if you will force the user to enter a different payment method
     // if liability was not shifted
     dropinInstance.clearSelectedPaymentMethod();
   }
 });
});

teardown(callbackopt) → {void|Promise}

Cleanly remove anything set up by dropin.create. This may be be useful in a single-page app.

Parameters:
Name Type Attributes Description
callback callback <optional>

Called on completion, containing an error if one occurred. No data is returned if teardown completes successfully. If no callback is provided, teardown will return a promise.

Source:

updateConfiguration(property, key, value) → {void}

Modify your configuration initially set in dropin.create.

If updateConfiguration is called after a user completes the PayPal authorization flow, any PayPal accounts not stored in the Vault record will be removed.

Parameters:
Name Type Description
property string

The top-level property to update. Either paypal, paypalCredit, applePay, or googlePay.

key string

The key of the property to update, such as amount or currency.

value any

The value of the property to update. Must be the type of the property specified in dropin.create.

Source:
Example
dropinInstance.updateConfiguration('paypal', 'amount', '10.00');

Type Definitions

applePayPaymentMethodPayload :object

Properties:
Name Type Attributes Description
nonce string

The payment method nonce, used by your server to charge the Apple Pay provided card.

vaulted boolean <nullable>

If present and true, indicates that the payment method refers to a vaulted payment method.

details.cardType string

Type of card, ex: Visa, Mastercard.

details.cardHolderName string

The name of the card holder.

details.dpanLastTwo string

Last two digits of card number.

details.rawPaymentData external:ApplePayPayment

The raw response back from the Apple Pay flow, which includes billing/shipping address, phone and email if passed in as required parameters.

description string

A human-readable description.

type string

The payment method type, always ApplePayCard when the method requested is an Apple Pay provided card.

binData object

Information about the card based on the bin. Documented here.

deviceData string <nullable>

If data collector is configured, the device data property to be used when making a transaction.

Source:

binData :object

Information about the card based on the bin.

Properties:
Name Type Description
commercial string

Possible values: 'Yes', 'No', 'Unknown'.

countryOfIssuance string

The country of issuance.

debit string

Possible values: 'Yes', 'No', 'Unknown'.

durbinRegulated string

Possible values: 'Yes', 'No', 'Unknown'.

healthcare string

Possible values: 'Yes', 'No', 'Unknown'.

issuingBank string

The issuing bank.

payroll string

Possible values: 'Yes', 'No', 'Unknown'.

prepaid string

Possible values: 'Yes', 'No', 'Unknown'.

productId string

The product id.

Source:

cardPaymentMethodPayload :object

Properties:
Name Type Attributes Description
nonce string

The payment method nonce, used by your server to charge the card.

details object

Additional account details. See a full list of details in the Hosted Fields client reference.

description string

A human-readable description.

type string

The payment method type, always CreditCard when the method requested is a card.

binData object

Information about the card based on the bin. Documented here.

vaulted boolean <nullable>

If present and true, indicates that the payment method refers to a vaulted payment method.

deviceData string <nullable>

If data collector is configured, the device data property to be used when making a transaction.

liabilityShifted boolean <nullable>

If 3D Secure is configured, whether or not liability did shift.

liabilityShiftPossible boolean <nullable>

If 3D Secure is configured, whether or not liability shift is possible.

threeDSecureInfo object <nullable>

If 3D Secure is configured, the threeDSecureInfo documented in the [Three D Secure client reference](http://braintree.github.io/braintree-web/3.68.0/ThreeDSecure.html#~verifyPayload)

Source:

googlePayPaymentMethodPayload :object

Properties:
Name Type Attributes Description
nonce string

The payment method nonce, used by your server to charge the Google Pay card.

vaulted boolean <nullable>

If present and true, indicates that the payment method refers to a vaulted payment method.

details.cardType string

Type of card, ex: Visa, Mastercard.

details.lastFour string

The last 4 digits of the card.

details.lastTwo string

The last 2 digits of the card.

details.isNetworkTokenized boolean

True if the card is network tokenized. A network tokenized card is a generated virtual card with a device-specific account number (DPAN) that is used in place of the underlying source card.

details.bin string

First six digits of card number.

details.rawPaymentData external:GooglePayPaymentData

The raw response back from the Google Pay flow, which includes shipping address, phone and email if passed in as required parameters.

type string

The payment method type, always AndroidPayCard when the method requested is a Google Pay Card.

binData object

Information about the card based on the bin. Documented here.

deviceData string <nullable>

If data collector is configured, the device data property to be used when making a transaction.

Source:

paymentMethodRequestablePayload :object

The event payload sent from on with the paymentMethodRequestable event.

Properties:
Name Type Description
type string

The type of payment method that is requestable. Either CreditCard or PayPalAccount.

paymentMethodIsSelected boolean

A property to determine if a payment method is currently selected when the payment method becomes requestable.

This will be true any time a payment method is visibly selected in the Drop-in UI, such as when PayPal authentication completes or a stored payment method is selected.

This will be false when requestPaymentMethod can be called, but a payment method is not currently selected. For instance, when a card form has been filled in with valid values, but has not been submitted to be converted into a payment method nonce.

Source:

paymentOptionSelectedPayload :object

The event payload sent from on with the paymentOptionSelected event.

Properties:
Name Type Description
paymentOption string

The payment option view selected. Either card, paypal, or paypalCredit.

Source:

paypalPaymentMethodPayload :object

Properties:
Name Type Attributes Description
nonce string

The payment method nonce, used by your server to charge the PayPal account.

vaulted boolean <nullable>

If present and true, indicates that the payment method refers to a vaulted payment method.

details object

Additional PayPal account details. See a full list of details in the PayPal client reference.

type string

The payment method type, always PayPalAccount when the method requested is a PayPal account.

deviceData string <nullable>

If data collector is configured, the device data property to be used when making a transaction.

Source:

venmoPaymentMethodPayload :object

Properties:
Name Type Attributes Description
nonce string

The payment method nonce, used by your server to charge the Venmo account.

vaulted boolean <nullable>

If present and true, indicates that the payment method refers to a vaulted payment method.

details.username string

The Venmo username.

type string

The payment method type, always VenmoAccount when the method requested is a Venmo account.

deviceData string <nullable>

If data collector is configured, the device data property to be used when making a transaction.

Source:

Events

card:binAvailable :Dropin~card:binAvailable

Source:

card:blur :Dropin~card:blur

The underlying hosted fields blur event.

Source:

card:cardTypeChange :Dropin~card:cardTypeChange

Source:

card:empty :Dropin~card:empty

The underlying hosted fields empty event.

Source:

card:focus :Dropin~card:focus

The underlying hosted fields focus event.

Source:

card:inputSubmitRequest :Dropin~card:inputSubmitRequest

Source:

card:notEmpty :Dropin~card:notEmpty

Source:

card:validityChange :Dropin~card:validityChange

Source:

noPaymentMethodRequestable

This event is emitted when there is no payment method available in Drop-in. This event is not fired if there is no payment method available on initialization. To check if there is a payment method requestable on initialization, use isPaymentMethodRequestable. No payload is available in the callback for this event.

Source:

paymentMethodRequestable :Dropin~paymentMethodRequestablePayload

This event is emitted when the payment method available in Drop-in changes. This includes when the state of Drop-in transitions from having no payment method available to having a payment method available and when the kind of payment method available changes. This event is not fired if there is no payment method available on initialization. To check if there is a payment method requestable on initialization, use isPaymentMethodRequestable.

Source:

paymentOptionSelected :Dropin~paymentOptionSelectedPayload

This event is emitted when the customer selects a new payment option type (e.g. PayPal, PayPal Credit, credit card). This event is not emitted when the user changes between existing saved payment methods. Only relevant when accepting multiple payment options.

Source: