ThreeDSecure

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
});

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
  }
});

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);
});

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');
  });
});

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
});

Examples

threeDSecure.teardown();

With callback

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

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
  }
});
<caption>Verifying a payment method nonce with 3DS 2.0 with onLookupComplete callback</caption>
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
});

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) {
    // 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
  }
});

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
  });
});

Example

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

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
  });
});

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
  });
});

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();
  });
});