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.

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.

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

The lookup response from the server side call to lookup the 3D Secure information.
Source:
Example
var my3DSContainer;

threeDSecure.initializeChallengeWithLookupResponse(lookupResponseFromServer).then(function (payload) {
  if (payload.liabilityShifted) {
    // Liablity has shifted
    submitNonceToServer(payload.nonce);
  } 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
  }
});

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 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 <optional>

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. Though not required to start the verification, it is required to receive a 3DS 2.0 lookup response.
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.

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 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.
challengeRequested boolean <optional>

If set to true, an authentication challenge will be forced if possible.
exemptionRequested boolean <optional>

If set to true, an exemption to the authentication challenge will be requested.
onLookupComplete function

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.
mobilePhoneNumber string <optional>

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

An billingAddress object for verification.
additionalInformation object <optional>

An additionalInformation object for verification.
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;

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) {
    // Liablity has shifted
    submitNonceToServer(payload.nonce);
  } 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
  }
});

Deprecated: Verifying an existing nonce with 3DS 1.0 

var my3DSContainer;

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

  if (payload.liabilityShifted) {
    // Liablity has shifted
    submitNonceToServer(payload.nonce);
  } 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}

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 number <optional>

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

The first name associated with the shipping address.
shippingSurname string <optional>

The last name associated with the shipping address.
shippingAddress object <optional>
Properties
Name Type Attributes Description
streetAddress string <optional>

The first name associated with the shipping address.
extendedAddress string <optional>

The last name associated with the shipping address.
line3 string <optional>

Line 3 of the shipping address if needed (eg. suite, apt #, etc).
locality string <optional>

The locality (city) name associated with the shipping address.
region string <optional>

The 2 letter code for US states, and the equivalent for other countries.
postalCode string <optional>

The zip code or equivalent for countries that have them.
countryCodeAlpha2 string <optional>

The 2 character country code.
shippingPhone number <optional>

The phone number associated with the shipping address. Only numbers; remove dashes, parenthesis and other characters.
shippingMethod string <optional>

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

  • 01 Same Day
  • 02 Overnight / Expedited
  • 03 Priority (2-3 Days)
  • 04 Ground
  • 05 Electronic Delivery
  • 06 Ship to Store
shippingMethodIndicator number <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 than 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 Fueld
  • LUX Luxury Retail
  • ACC Accommodation Retail
  • TBD Other
deliveryTimeframe number <optional>

The 2-digit number indicating the delivery timeframe. 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.
reorderindicator number <optional>

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

  • 01 First time ordered
  • 02 Reordered
preorderIndicator number <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 number <optional>

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

The purchase amount total for prepaid gift cards in major units.
giftCardCurrencyCode number <optional>

ISO 4217 currency code for the gift card purchased.
giftCardCount number <optional>

Total count of individual prepaid gift cards purchased.
accountAgeIndicator number <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 number <optional>

The 8-digit number (format: YYYYMMDD) indicating the date the cardholder opened the account.
accountChangeIndicator number <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 number <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 number <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 number <optional>

The 8-digit number (format: YYYYMMDD) indicating the date the cardholder last changed or reset password on account.
shippingAddressUsageIndicator number <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 number <optional>

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

Number of transactions (successful or abandoned) for this cardholder account within the last 24 hours.
transactionCountYear number <optional>

Number of transactions (successful or abandoned) for this cardholder account within the last year.
addCardAttempts number <optional>

Number of add card attempts in the last 24 hours.
accountPurchases number <optional>

Number of purchases with this cardholder account during the previous six months.
fraudActivity number <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 number <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 number <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 number <optional>

The 8-digit number (format: YYYYMMDD) indicating the date the payment account was added to the cardholder account.
acsWindowSize number <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 number <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 number <optional>

The 1-character value (Y/N) indicating whether cardholder billing and shipping addresses match.
accountId string <optional>

Additional cardholder account information.
ipAddress string <optional>

The IP address of the consumer. IPv4 and IPv6 are supported.
orderDescription string <optional>

Brief description of items purchased.
taxAmount number <optional>

Unformatted tax amount without any decimalization (ie. $123.67 = 12367).
userAgent string <optional>

The exact content of the HTTP user agent header.
authenticationIndicator number <optional>

The 2-digit number indicating the type of authentication request. This field is required if a recurring or installment transaction request. Possible values:

  • 02 Recurring
  • 03 Installment
installment number <optional>

An integer value greater than 1 indicating the maximum number of permitted authorizations for installment payments. Required for recurring and installement transaction requests.
purchaseDate number <optional>

The 14-digit number (format: YYYYMMDDHHMMSS) indicating the date in UTC of original purchase. Required for recurring and installement transaction requests.
recurringEnd number <optional>

The 8-digit number (format: YYYYMMDD) indicating the date after which no further recurring authorizations should be performed. Required for recurring and installement transaction requests.
recurringFrequency number <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). Required for recurring and installement transaction requests.
Source:

billingAddress :object

Properties:
Name Type Attributes Description
givenName string <optional>

The first name associated with the billing address.
surname string <optional>

The last name associated with the billing address.
phoneNumber number <optional>

The phone number associated with the billing address. Only numbers; remove dashes, paranthesis and other characters.
streetAddress string <optional>

Line 1 of the billing address (eg. number, street, etc).
extendedAddress string <optional>

Line 2 of the billing address (eg. suite, apt #, etc.).
line3 string <optional>

Line 3 of the billing address if needed (eg. suite, apt #, etc).
locality string <optional>

The locality (city) name associated with the billing address.
region string <optional>

The 2 letter code for US states, and the equivalent for other countries.
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
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, paranthesis 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, 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.
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.
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.

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