This class represents a ThreeDSecure component produced by braintree.threeDSecure.create. Instances of this class have a method for launching a 3D Secure authentication flow.


new ThreeDSecure(options)

Do not use this constructor directly. Use braintree.threeDSecure.create instead.

Name Type Description
options object

3D Secure create options



cancelVerifyCard(callbackopt) → {Promise|void}

Cancel the 3DS flow and return the verification payload if available.

Name Type Attributes Description
callback callback <optional>

The second argument is a verifyPayload. If there is no verifyPayload (the initial lookup did not complete), an error will be returned. If no callback is passed, cancelVerifyCard will return a promise.

threeDSecure.cancelVerifyCard(function (err, verifyPayload) {
  if (err) {
    // Handle error
    console.log(err.message); // No verification payload available

  verifyPayload.nonce; // The nonce returned from the 3ds lookup call
  verifyPayload.liabilityShifted; // boolean
  verifyPayload.liabilityShiftPossible; // boolean

teardown(callbackopt) → {Promise|void}

Cleanly remove anything set up by create.

Name Type Attributes Description
callback callback <optional>

Called on completion. If no callback is passed, teardown will return a promise.


With callback

threeDSecure.teardown(function () {
  // teardown is complete

verifyCard(options, callbackopt) → {Promise|void}

Launch the 3D Secure login flow, returning a nonce payload.

Name Type Attributes Description
options object

Options for card verification.

Name Type Attributes Default Description
nonce string

A nonce referencing the card to be verified. For example, this can be a nonce that was returned by Hosted Fields.

amount number

The amount of the transaction in the current merchant account's currency. For example, if you are running a transaction of $123.45 US dollars, amount would be 123.45.

addFrame callback

This addFrameCallback will be called when the bank frame needs to be added to your page.

removeFrame callback

This removeFrameCallback will be called when the bank frame needs to be removed from your page.

customer.mobilePhoneNumber string <optional>

The mobile phone number used for verification. Only numbers; remove dashes, paranthesis and other characters. string <optional>

The email used for verification.

customer.shippingMethod string <optional>

The 2-digit string indicating the shipping method chosen for the transaction.

customer.billingAddress.firstName string <optional>

The first name associated with the address.

customer.billingAddress.lastName string <optional>

The last name associated with the address.

customer.billingAddress.streetAddress string <optional>

Line 1 of the Address (eg. number, street, etc).

customer.billingAddress.extendedAddress string <optional>

Line 2 of the Address (eg. suite, apt #, etc.).

customer.billingAddress.locality string <optional>

The locality (city) name associated with the address.

customer.billingAddress.region string <optional>

The 2 letter code for US states, and the equivalent for other countries.

customer.billingAddress.postalCode string <optional>

The zip code or equivalent for countries that have them.

customer.billingAddress.countryCodeAlpha2 string <optional>

The 2 character country code.

customer.billingAddress.phoneNumber string <optional>

The phone number associated with the address. Only numbers; remove dashes, paranthesis and other characters.

showLoader boolean <optional>

Whether to show the loader icon while the bank frame is loading.

callback callback <optional>

The second argument, data, is a verifyPayload. If no callback is provided, it will return a promise that resolves verifyPayload.


Verifying an existing nonce with 3DS

var my3DSContainer;

  nonce: existingNonce,
  amount: 123.45,
  addFrame: function (err, iframe) {
    // Set up your UI and add the iframe.
    my3DSContainer = document.createElement('div');
  removeFrame: function () {
    // Remove UI that you added in addFrame.
}, function (err, payload) {
  if (err) {

  if (payload.liabilityShifted) {
    // Liablity has shifted
  } else if (payload.liabilityShiftPossible) {
    // Liablity may still be shifted
    // Decide if you want to submit the nonce
  } else {
    // Liablity has not shifted and will not shift
    // Decide if you want to submit the nonce

Type Definitions

addFrameCallback(erropt, nullable, iframe) → {void}

The callback used for options.addFrame in verifyCard.

Name Type Attributes Description
err BraintreeError <optional>

null or undefined if there was no error.

iframe HTMLIFrameElement

An iframe element containing the bank's authentication page that you must put on your page.


removeFrameCallback() → {void}

The callback used for options.removeFrame in verifyCard.


verifyPayload :object

Name Type Description
nonce string

The new payment method nonce produced by the 3D Secure lookup. The original nonce passed into verifyCard was consumed. This new nonce should be used to transact on your server.

details object

Additional account details.

Name Type Description
cardType string

Type of card, ex: Visa, MasterCard.

lastFour string

Last four digits of card number.

lastTwo string

Last two digits of card number.

description string

A human-readable description.

binData object

Information about the card based on the bin.

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.

liabilityShiftPossible boolean

Indicates whether the card was eligible for 3D Secure.

liabilityShifted boolean

Indicates whether the liability for fraud has been shifted away from the merchant.