ThreeDSecure

ThreeDSecure

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.

If you use the Braintree SDK from within an iframe, you must not use the sandbox attribute on your iframe or the 3D Secure modal will not function correctly.

Note: 3D Secure 2.0 is documented below and will become the default integration method in a future version of Braintree-web. Until then, version 1.0 will continue to be supported. To view 3D Secure 1.0 documentation, look at Braintree-web documentation from version 3.40.0 and earlier, or upgrade your integration by referring to the 3D Secure 2.0 adoption guide.

Constructor

new ThreeDSecure(options)

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

Parameters:
Name Type Description
options object

3D Secure create options

Source:

Methods

cancelVerifyCard(callbackopt) → {Promise|void}

Cancel the 3DS flow and return the verification payload if available. If using 3D Secure version 2, this will not close the UI of the authentication modal. It is recommended that this method only be used in the lookup-complete event or the onLookupComplete callback.

Parameters:
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.

Source:
Examples

Cancel the verification in `lookup-complete` event

// set up listener after instantiation
threeDSecure.on('lookup-complete', function (data, next) {
  // determine if you want to call next to start the challenge,
  // if not, call cancelVerifyCard
  threeDSecure.cancelVerifyCard(function (err, verifyPayload) {
    if (err) {
      // Handle error
      console.log(err.message); // No verification payload available
      return;
    }

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

// after tokenizing a credit card
threeDSecure.verifyCard({
  amount: '100.00',
  nonce: nonceFromTokenizationPayload,
  bin: binFromTokenizationPayload
  // other fields such as billing address
}, function (verifyError, payload) {
  if (verifyError) {
    if (verifyError.code === 'THREEDS_VERIFY_CARD_CANCELED_BY_MERCHANT ') {
      // flow was canceled by merchant, 3ds info can be found in the payload
      // for cancelVerifyCard
    }
  }
});

Cancel the verification in onLookupComplete callback

threeDSecure.verifyCard({
  amount: '100.00',
  nonce: nonceFromTokenizationPayload,
  bin: binFromTokenizationPayload,
  // other fields such as billing address
  onLookupComplete: function (data, next) {
    // determine if you want to call next to start the challenge,
    // if not, call cancelVerifyCard
    threeDSecure.cancelVerifyCard(function (err, verifyPayload) {
      if (err) {
        // Handle error
        console.log(err.message); // No verification payload available
        return;
      }

      verifyPayload.nonce; // The nonce returned from the 3ds lookup call
      verifyPayload.liabilityShifted; // boolean
      verifyPayload.liabilityShiftPossible; // boolean
    });
  }
}, function (verifyError, payload) {
  if (verifyError) {
    if (verifyError.code === 'THREEDS_VERIFY_CARD_CANCELED_BY_MERCHANT ') {
      // flow was canceled by merchant, 3ds info can be found in the payload
      // for cancelVerifyCard
    }
  }
});

Cancel the verification in 3D Secure version 1

// unlike with v2, this will not cause `verifyCard` to error, it will simply
// never call the callback
threeDSecure.cancelVerifyCard(function (err, verifyPayload) {
  if (err) {
    // Handle error
    console.log(err.message); // No verification payload available
    return;
  }

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

initializeChallengeWithLookupResponse(lookupResponse) → {Promise}

Launch the iframe challenge using a 3D Secure lookup response from a server side lookup.

Parameters:
Name Type Description
lookupResponse object | string

The lookup response from the server side call to lookup the 3D Secure information. The raw string or a parsed object can be passed.

Source:
Example
var my3DSContainer;

threeDSecure.initializeChallengeWithLookupResponse(lookupResponseFromServer).then(function (payload) {
  if (payload.liabilityShifted) {
    // Liability has shifted
    submitNonceToServer(payload.nonce);
  } else if (payload.liabilityShiftPossible) {
    // Liability may still be shifted
    // Decide if you want to submit the nonce
  } else {
    // Liability has not shifted and will not shift
    // Decide if you want to submit the nonce
  }
});

off(event, handler) → {void}

Unsubscribes the handler function to a named event.

Parameters:
Name Type Description
event string

The name of the event to which you are unsubscribing.

handler function

The callback for the event you are unsubscribing from.

Source:
Example

Subscribing and then unsubscribing from a 3D Secure eld event

braintree.threeDSecure.create({ ... }, function (createErr, threeDSecureInstance) {
  var lookupCallback = function (data, next) {
    console.log(data);
    next();
  };
  var cancelCallback = function () {
    // log the cancelation
    // or update UI
  };

  threeDSecureInstance.on('lookup-complete', lookupCallback);
  threeDSecureInstance.on('customer-canceled', cancelCallback);

  // later on
  threeDSecureInstance.off('lookup-complete', lookupCallback);
  threeDSecureInstance.off('customer-canceled', cancelCallback);
});

on(event, handler) → {void}

Subscribes a handler function to a named event. The following events are available:

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:
Example

Listening to a 3D Secure event

braintree.threeDSecure.create({ ... }, function (createErr, threeDSecureInstance) {
  threeDSecureInstance.on('lookup-complete', function (data, next) {
    console.log('data from the lookup', data);
    next();
  });
  threeDSecureInstance.on('customer-canceled', function () {
    console.log('log that the customer canceled');
  });
});

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

Gather the data needed for a 3D Secure lookup call.

Parameters:
Name Type Attributes Description
options object

Options for 3D Secure lookup.

Properties
Name Type Description
nonce string

The nonce representing the card from a tokenization payload. For example, this can be a tokenizePayload returned by Hosted Fields under payload.nonce.

bin string

The numeric Bank Identification Number (bin) of the card from a tokenization payload. For example, this can be a tokenizePayload returned by Hosted Fields under payload.details.bin.

callback callback <optional>

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

Source:
Example

Preparing data for a 3D Secure lookup

threeDSecure.prepareLookup({
  nonce: hostedFieldsTokenizationPayload.nonce,
  bin: hostedFieldsTokenizationPayload.details.bin
}, function (err, payload) {
  if (err) {
    console.error(err);
    return;
  }

  // send payload to server to do server side lookup
});

teardown(callbackopt) → {Promise|void}

Cleanly remove anything set up by create, with the exception that the Cardinal SDK, on window.Cardinal, will remain.

Parameters:
Name Type Attributes Description
callback callback <optional>

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

Source:
Examples
threeDSecure.teardown();

With callback

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

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

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

Parameters:
Name Type Attributes Description
options object

Options for card verification.

Properties
Name Type Attributes Description
nonce string

The nonce representing the card from a tokenization payload. For example, this can be a tokenizePayload returned by Hosted Fields under payload.nonce.

bin string

The numeric Bank Identification Number (bin) of the card from a tokenization payload. For example, this can be a tokenizePayload returned by Hosted Fields under payload.details.bin.

amount string

The amount of the transaction in the current merchant account's currency. This must be expressed in numbers with an optional decimal (using .) and precision up to the hundredths place. For example, if you're processing a transaction for 1.234,56 € then amount should be 1234.56.

accountType string <optional>

The account type for the card (if known). Accepted values: credit or debit.

cardAddChallengeRequested boolean <optional>

If set to true, a card-add challenge will be requested from the issuer. If set to false, a card-add challenge will not be requested. If the param is missing, a card-add challenge will only be requested for $0 amount. An authentication created using this flag should only be used for vaulting operations (creation of customers' credit cards or payment methods) and not for creating transactions.

cardAdd boolean <optional>

Deprecated: Use cardAddChallengeRequested instead.

challengeRequested boolean <optional>

If set to true, an authentication challenge will be forced if possible.

dataOnlyRequested boolean <optional>

Indicates whether to use the data only flow. In this flow, frictionless 3DS is ensured for Mastercard cardholders as the card scheme provides a risk score for the issuer to determine whether to approve. If data only is not supported by the processor, a validation error will be raised. Non-Mastercard cardholders will fallback to a normal 3DS flow.

exemptionRequested boolean <optional>

Deprecated: Use requestedExemptionType instead.

requestVisaDAF boolean <optional>

Request to use VISA Digital Authentication Framework. If set to true, a Visa DAF authenticated payment credential will be created and/or used for authentication if the merchant is eligible.

merchantName string <optional>

Allows to override the merchant name that is shown in the challenge.

requestedExemptionType string <optional>

If an exemption is requested and the exemption's conditions are satisfied, then it will be applied. The following supported exemptions are defined as per PSD2 regulation: low_value, transaction_risk_analysis

customFields object <optional>

Object where each key is the name of a custom field which has been configured in the Control Panel. In the Control Panel you can configure 3D Secure Rules which trigger on certain values.

onLookupComplete function <optional>

Deprecated: Use threeDSecureInstance.on('lookup-complete') instead. Function to execute when lookup completes. The first argument, data, is a verificationData object, and the second argument, next, is a callback. next must be called to continue.

email string <optional>

The email used for verification. (maximum length 255)

mobilePhoneNumber string <optional>

The mobile phone number used for verification. Only numbers; remove dashes, parenthesis and other characters. (maximum length 25)

billingAddress object <optional>

An billingAddress object for verification.

additionalInformation object <optional>

An additionalInformation object for verification.

collectDeviceData object <optional>

If set to true, device data such as browser screen dimensions, language and time zone is submitted with lookup data.

customer object <optional>

Deprecated Customer information for use in 3DS 1.0 verifications. Can contain any subset of a verifyCardCustomerObject. Only to be used for 3DS 1.0 integrations.

addFrame callback

Deprecated This addFrameCallback will be called when the bank frame needs to be added to your page. Only to be used for 3DS 1.0 integrations.

removeFrame callback

Deprecated For use in 3DS 1.0 Flows. This removeFrameCallback will be called when the bank frame needs to be removed from your page. Only to be used in 3DS 1.0 integrations.

callback callback <optional>

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

Source:
Examples

Verifying a payment method nonce with 3DS 2.0

var my3DSContainer;

// set up listener after initialization
threeDSecure.on(('lookup-complete', function (data, next) {
  // use `data` here, then call `next()`
  next();
});

// call verifyCard after tokenizing a card
threeDSecure.verifyCard({
  amount: '123.45',
  nonce: hostedFieldsTokenizationPayload.nonce,
  bin: hostedFieldsTokenizationPayload.details.bin,
  email: 'test@example.com'
  billingAddress: {
    givenName: 'Jill',
    surname: 'Doe',
    phoneNumber: '8101234567',
    streetAddress: '555 Smith St.',
    extendedAddress: '#5',
    locality: 'Oakland',
    region: 'CA',
    postalCode: '12345',
    countryCodeAlpha2: 'US'
  },
  additionalInformation: {
    workPhoneNumber: '5555555555',
    shippingGivenName: 'Jill',
    shippingSurname: 'Doe',
    shippingAddress: {
      streetAddress: '555 Smith st',
      extendedAddress: '#5',
      locality: 'Oakland',
      region: 'CA',
      postalCode: '12345',
      countryCodeAlpha2: 'US'
    }
    shippingPhone: '8101234567'
  }
}, function (err, payload) {
  if (err) {
    console.error(err);
    return;
  }

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

Verifying a payment method nonce with 3DS 2.0 with onLookupComplete callback

var my3DSContainer;

threeDSecure.verifyCard({
  amount: '123.45',
  nonce: hostedFieldsTokenizationPayload.nonce,
  bin: hostedFieldsTokenizationPayload.details.bin,
  email: 'test@example.com'
  billingAddress: {
    givenName: 'Jill',
    surname: 'Doe',
    phoneNumber: '8101234567',
    streetAddress: '555 Smith St.',
    extendedAddress: '#5',
    locality: 'Oakland',
    region: 'CA',
    postalCode: '12345',
    countryCodeAlpha2: 'US'
  },
  additionalInformation: {
    workPhoneNumber: '5555555555',
    shippingGivenName: 'Jill',
    shippingSurname: 'Doe',
    shippingAddress: {
      streetAddress: '555 Smith st',
      extendedAddress: '#5',
      locality: 'Oakland',
      region: 'CA',
      postalCode: '12345',
      countryCodeAlpha2: 'US'
    }
    shippingPhone: '8101234567'
  },
  onLookupComplete: function (data, next) {
    // use `data` here, then call `next()`
    next();
  }
}, function (err, payload) {
  if (err) {
    console.error(err);
    return;
  }

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

Handling 3DS lookup errors

var my3DSContainer;

// set up listener after initialization
threeDSecure.on(('lookup-complete', function (data, next) {
  // use `data` here, then call `next()`
  next();
});

// call verifyCard after tokenizing a card
threeDSecure.verifyCard({
  amount: '123.45',
  nonce: hostedFieldsTokenizationPayload.nonce,
  bin: hostedFieldsTokenizationPayload.details.bin,
  email: 'test@example.com',
  billingAddress: billingAddressFromCustomer,
  additionalInformation: additionalInfoFromCustomer
}, function (err, payload) {
  if (err) {
    if (err.code.indexOf('THREEDS_LOOKUP') === 0) {
      // an error occurred during the initial lookup request

      if (err.code === 'THREEDS_LOOKUP_TOKENIZED_CARD_NOT_FOUND_ERROR') {
        // either the passed payment method nonce does not exist
        // or it was already consumed before the lookup call was made
      } else if (err.code.indexOf('THREEDS_LOOKUP_VALIDATION') === 0) {
        // a validation error occurred
        // likely some non-ascii characters were included in the billing
        // address given name or surname fields, or the cardholdername field

        // Instruct your user to check their data and try again
      } else {
        // an unknown lookup error occurred
      }
    } else {
      // some other kind of error
    }
    return;
  }

  // handle success
});

Type Definitions

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

Deprecated The callback used for options.addFrame in 3DS 1.0's verifyCard.

Parameters:
Name Type Attributes Description
err BraintreeError <optional>
<nullable>

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.

Deprecated:
  • Yes

Source:

additionalInformation :object

Properties:
Name Type Attributes Description
workPhoneNumber string <optional>

The work phone number used for verification. Only numbers; remove dashes, parenthesis and other characters. (maximum length 25)

shippingGivenName string <optional>

The first name associated with the shipping address. (maximum length 50, ASCII characters)

shippingSurname string <optional>

The last name associated with the shipping address. (maximum length 50, ASCII characters)

shippingAddress object <optional>
Properties
Name Type Attributes Description
streetAddress string <optional>

Line 1 of the shipping address (eg. number, street, etc). (maximum length 50)

extendedAddress string <optional>

Line 2 of the shipping address (eg. suite, apt #, etc.). (maximum length 50)

line3 string <optional>

Line 3 of the shipping address if needed (eg. suite, apt #, etc). (maximum length 50)

locality string <optional>

The locality (city) name associated with the shipping address. (maximum length 50)

region string <optional>

This field expects an ISO3166-2 subdivision code. The subdivision code is what follows the hyphen separator in the full ISO 3166-2 code. For example, the state of Ohio in the United States we expect "OH" as opposed to the full ISO 3166-2 code "US-OH".

postalCode string <optional>

The zip code or equivalent for countries that have them. (maximum length 10)

countryCodeAlpha2 string <optional>

The 2 character country code. (maximum length 2)

shippingPhone string <optional>

The phone number associated with the shipping address. Only numbers; remove dashes, parenthesis and other characters. (maximum length 20)

shippingMethod string <optional>

The 2-digit string indicating the name of the shipping method chosen for the transaction. (maximum length 50) Possible values:

  • 01 Same Day
  • 02 Overnight / Expedited
  • 03 Priority (2-3 Days)
  • 04 Ground
  • 05 Electronic Delivery
  • 06 Ship to Store
shippingMethodIndicator string <optional>

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

  • 01 Ship to cardholder billing address
  • 02 Ship to another verified address on file with merchant
  • 03 Ship to address that is different from billing address
  • 04 Ship to store (store address should be populated on request)
  • 05 Digital goods
  • 06 Travel and event tickets, not shipped
  • 07 Other
productCode string <optional>

The 3-letter string representing the merchant product code. Possible values:

  • AIR Airline
  • GEN General Retail
  • DIG Digital Goods
  • SVC Services
  • RES Restaurant
  • TRA Travel
  • DSP Cash Dispensing
  • REN Car Rental
  • GAS Fuel
  • LUX Luxury Retail
  • ACC Accommodation Retail
  • TBD Other
deliveryTimeframe string <optional>

The 2-digit number indicating the delivery time frame. Possible values:

  • 01 Electronic delivery
  • 02 Same day shipping
  • 03 Overnight shipping
  • 04 Two or more day shipping
deliveryEmail string <optional>

For electronic delivery, email address to which the merchandise was delivered. (maximum length 254)

reorderindicator string <optional>

The 2-digit number indicating whether the cardholder is reordering previously purchased merchandise. possible values:

  • 01 First time ordered
  • 02 Reordered
preorderIndicator string <optional>

The 2-digit number indicating whether cardholder is placing an order with a future availability or release date. possible values:

  • 01 Merchandise available
  • 02 Future availability
preorderDate string <optional>

The 8-digit number (format: YYYYMMDD) indicating expected date that a pre-ordered purchase will be available.

giftCardAmount string <optional>

The purchase amount total for prepaid gift cards in major units. (maximum length 15)

giftCardCurrencyCode string <optional>

ISO 4217 currency code for the gift card purchased. (maximum length 3)

giftCardCount string <optional>

Total count of individual prepaid gift cards purchased. (maximum length 2)

accountAgeIndicator string <optional>

The 2-digit value representing the length of time cardholder has had account. Possible values:

  • 01 No Account
  • 02 Created during transaction
  • 03 Less than 30 days
  • 04 30-60 days
  • 05 More than 60 days
accountCreateDate string <optional>

The 8-digit number (format: YYYYMMDD) indicating the date the cardholder opened the account.

accountChangeIndicator string <optional>

The 2-digit value representing the length of time since the last change to the cardholder account. This includes shipping address, new payment account or new user added. Possible values:

  • 01 Changed during transaction
  • 02 Less than 30 days
  • 03 30-60 days
  • 04 More than 60 days
accountChangeDate string <optional>

The 8-digit number (format: YYYYMMDD) indicating the date the cardholder's account was last changed. This includes changes to the billing or shipping address, new payment accounts or new users added.

accountPwdChangeIndicator string <optional>

The 2-digit value representing the length of time since the cardholder changed or reset the password on the account. Possible values:

  • 01 No change
  • 02 Changed during transaction
  • 03 Less than 30 days
  • 04 30-60 days
  • 05 More than 60 days
accountPwdChangeDate string <optional>

The 8-digit number (format: YYYYMMDD) indicating the date the cardholder last changed or reset password on account.

shippingAddressUsageIndicator string <optional>

The 2-digit value indicating when the shipping address used for transaction was first used. Possible values:

  • 01 This transaction
  • 02 Less than 30 days
  • 03 30-60 days
  • 04 More than 60 days
shippingAddressUsageDate string <optional>

The 8-digit number (format: YYYYMMDD) indicating the date when the shipping address used for this transaction was first used.

transactionCountDay string <optional>

Number of transactions (successful or abandoned) for this cardholder account within the last 24 hours. (maximum length 3)

transactionCountYear string <optional>

Number of transactions (successful or abandoned) for this cardholder account within the last year. (maximum length 3)

addCardAttempts string <optional>

Number of add card attempts in the last 24 hours. (maximum length 3)

accountPurchases string <optional>

Number of purchases with this cardholder account during the previous six months.

fraudActivity string <optional>

The 2-digit value indicating whether the merchant experienced suspicious activity (including previous fraud) on the account. Possible values:

  • 01 No suspicious activity
  • 02 Suspicious activity observed
shippingNameIndicator string <optional>

The 2-digit value indicating if the cardholder name on the account is identical to the shipping name used for the transaction. Possible values:

  • 01 Account and shipping name identical
  • 02 Account and shipping name differ
paymentAccountIndicator string <optional>

The 2-digit value indicating the length of time that the payment account was enrolled in the merchant account. Possible values:

  • 01 No account (guest checkout)
  • 02 During the transaction
  • 03 Less than 30 days
  • 04 30-60 days
  • 05 More than 60 days
paymentAccountAge string <optional>

The 8-digit number (format: YYYYMMDD) indicating the date the payment account was added to the cardholder account.

acsWindowSize string <optional>

The 2-digit number to set the challenge window size to display to the end cardholder. The ACS will reply with content that is formatted appropriately to this window size to allow for the best user experience. The sizes are width x height in pixels of the window displayed in the cardholder browser window. Possible values:

  • 01 250x400
  • 02 390x400
  • 03 500x600
  • 04 600x400
  • 05 Full page
sdkMaxTimeout string <optional>

The 2-digit number of minutes (minimum 05) to set the maximum amount of time for all 3DS 2.0 messages to be communicated between all components.

addressMatch string <optional>

The 1-character value (Y/N) indicating whether cardholder billing and shipping addresses match.

accountId string <optional>

Additional cardholder account information. (maximum length 64)

ipAddress string <optional>

The IP address of the consumer. IPv4 and IPv6 are supported.

  • only one IP address supported
  • only numbers, letters, period '.' chars, or colons ':' are acceptable
orderDescription string <optional>

Brief description of items purchased. (maximum length 256)

taxAmount string <optional>

Unformatted tax amount without any decimalization (ie. $123.67 = 12367). (maximum length 20)

userAgent string <optional>

The exact content of the HTTP user agent header. (maximum length 500)

authenticationIndicator string <optional>

The 2-digit number indicating the type of authentication request. Possible values:

  • 01 Payment
  • 02 Recurring transaction
  • 03 Installment
  • 04 Add card
  • 05 Maintain card
  • 06 Cardholder verification as part of EMV token ID&V
installment string <optional>

An integer value greater than 1 indicating the maximum number of permitted authorizations for installment payments. (maximum length 3)

purchaseDate string <optional>

The 14-digit number (format: YYYYMMDDHHMMSS) indicating the date in UTC of original purchase.

recurringEnd string <optional>

The 8-digit number (format: YYYYMMDD) indicating the date after which no further recurring authorizations should be performed.

recurringFrequency string <optional>

Integer value indicating the minimum number of days between recurring authorizations. A frequency of monthly is indicated by the value 28. Multiple of 28 days will be used to indicate months (ex. 6 months = 168). (maximum length 3)

Source:

billingAddress :object

Properties:
Name Type Attributes Description
givenName string <optional>

The first name associated with the billing address. (maximum length 50, ASCII characters)

surname string <optional>

The last name associated with the billing address. (maximum length 50, ASCII characters)

phoneNumber string <optional>

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

streetAddress string <optional>

Line 1 of the billing address (eg. number, street, etc). (maximum length 50)

extendedAddress string <optional>

Line 2 of the billing address (eg. suite, apt #, etc.). (maximum length 50)

line3 string <optional>

Line 3 of the billing address if needed (eg. suite, apt #, etc). (maximum length 50)

locality string <optional>

The locality (city) name associated with the billing address.

region string <optional>

This field expects an ISO3166-2 subdivision code. The subdivision code is what follows the hyphen separator in the full ISO 3166-2 code. For example, the state of Ohio in the United States we expect "OH" as opposed to the full ISO 3166-2 code "US-OH".

postalCode string <optional>

The zip code or equivalent for countries that have them.

countryCodeAlpha2 string <optional>

The 2 character country code.

Source:

prepareLookupPayload :string

The client data to pass on when doing a server side lookup call.

Source:

removeFrameCallback() → {void}

Deprecated The callback used for options.removeFrame in 3DS 1.0's verifyCard.

Deprecated:
  • Yes

Source:

verificationData :object

Properties:
Name Type Description
requiresUserAuthentication boolean

When true, the user will be presented with a 3D Secure challenge when calling next in the lookup-complete event.

threeDSecureInfo object

Contains liability shift details.

Properties
Name Type Description
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.

paymentMethod object

A verifyPayload object.

lookup object

Details about the 3D Secure lookup.

Properties
Name Type Description
threeDSecureVersion string

The version of 3D Secure that will be used for the 3D Secure challenge.

Source:

verifyCardCustomerObject :object

Deprecated Optional customer information to be passed to 3DS 1.0 for verification.

Properties:
Name Type Attributes Description
customer.mobilePhoneNumber string <optional>

The mobile phone number used for verification. Only numbers; remove dashes, parenthesis and other characters.

customer.email 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 or an ISO-3166-2 country subdivision code of up to three letters.

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, parenthesis and other characters.

Deprecated:
  • Yes

Source:

verifyPayload :object

Properties:
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.

type string

The payment method type.

details object

Additional account details.

Properties
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.

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.

liabilityShiftPossible boolean

Deprecated: Use threeDSecureInfo.liabilityShiftPossible instead.

liabilityShifted boolean

Deprecated: Use threeDSecureInfo.liabilityShifted instead.

threeDSecureInfo object

3DS information about the card. Note: This information should be verified on the server by using the payment method nonce find method. The values provided here are merely for convenience. Only values looked up on the server should determine the logic about how to process a transaction.

Properties
Name Type Description
acsTransactionId string

The transaction identifier from the issuing bank.

cavv string

Cardholder authentication verification value or CAVV. The main encrypted message issuers and card networks use to verify authentication has occurred. Mastercard uses an AVV message and American Express uses an AEVV message, each of which should also be passed in the cavv parameter.

dsTransactionId string

Transaction identifier resulting from 3D Secure 2 authentication.

eciFlag string

The value of the electronic commerce indicator (ECI) flag, which indicates the outcome of the 3DS authentication. This will be a two-digit value.

enrolled boolean

Indicates the status of 3D Secure authentication eligibility with the card issuer.

liabilityShifted boolean

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

liabilityShiftPossible boolean

Indicates whether liability shift is still possible on a retry.

paresStatus string

Transaction status result identifier.

status string

Indicates the outcome of the 3D Secure event.

threeDSecureAuthenticationId string

ID of the 3D Secure authentication performed for this transaction. Do not provide this field as a transaction sale parameter if you are using the returned payment method nonce from the payload.

threeDSecureServerTransactionId string

Transaction identifier provided by the issuing bank who recieved the 3D Secure event.

threeDSecureVersion string

The version of 3D Secure authentication used for the transaction.

xid string

Transaction identifier resulting from 3D Secure authentication. Uniquely identifies the transaction and sometimes required in the authorization message. This is a base64-encoded value. This field will no longer be used in 3D Secure 2 authentications for Visa and Mastercard, however it will be supported by American Express.

lookup.transStatus string

Error code returned from the 3D Secure MPI provider.

lookup.transStatusReason string

Description correlating to the transStatus error code.

authentication.transStatus string

Error code returned from the 3D Secure MPI provider.

authentication.transStatusReason string

Description correlating to the transStatus error code.

rawCardinalSDKVerificationData object

The response back from the Cardinal SDK after verification has completed. See Cardinal's Documentation for more information. If the customer was not required to do a 3D Secure challenge, this object will not be available.

Source:

Events

authentication-iframe-available

This event is emitted when the 2-inline-iframe version is specified when creating the 3D Secure instance and the authentication iframe becomes available.

Source:
Example

Listening for the authentication iframe to be available

  threeDSecureInstance.on('authentication-iframe-available', function (event, next) {
    document.body.appendChild(event.element); // add iframe element to page

    next(); // let the SDK know the iframe is ready
  });
});

authentication-modal-close

This event is emitted when using the 3D Secure 2.0 flow and the authentication modal closes, either because the authentication was completed or because the customer canceled the process.

Source:
Example
braintree.threeDSecure.create({
  client: clientInstance,
  version: '2'
}, function (createErr, threeDSecureInstance) {
  threeDSecureInstance.on('authentication-modal-close', function () {
    // the modal was closed
  });
});

authentication-modal-render

This event is emitted when using the 3D Secure 2.0 flow and the authentication modal is rendered.

Source:
Example
braintree.threeDSecure.create({
  client: clientInstance,
  version: '2'
}, function (createErr, threeDSecureInstance) {
  threeDSecureInstance.on('authentication-modal-render', function () {
    // the modal was rendered, presenting the authentication form to the customer
  });
});

customer-canceled

This event is emitted when using the 3D Secure 2.0 flow and the customer cancels the 3D Secure challenge.

Source:
Example

Listening for when the customer cancels the 3D Secure challenge

braintree.threeDSecure.create({
  client: clientInstance,
  version: '2'
}, function (createErr, threeDSecureInstance) {
  threeDSecureInstance.on('customer-canceled', function () {
    // the customer canceled the 3D Secure challenge
  });
});

lookup-complete

This event is emitted when using the 3D Secure 2.0 flow and the initial lookup request completes. If this is not used, a onLookupComplete callback must be passed into the verifyCard method.

Source:
Example

Listening for when the lookup request is complete

braintree.threeDSecure.create({
  client: clientInstance,
  version: '2'
}, function (createErr, threeDSecureInstance) {
  threeDSecureInstance.on('lookup-complete', function (data, next) {
    // inspect the data

    // call next when ready to proceed with the challenge
    next();
  });
});