3D Secure
Step by Step Integration
Table of Contents
3DS Client side flow
Generate a client token
Before you can initialize the JavaScript SDK, you will need to generate a client token. The client_token
is generated on your server and must be accessible from the JavaScript in your checkout page.
If you would like to use a merchant account ID other than your default, specify the merchant_account_id
when generating the client token. The merchant account ID used to create the client token must match the merchant account ID used to create the subsequent transaction or verification.
Verify a card using 3DS
To use 3DS, you will need to create an object with relevant customer and transaction data in order to minimize the need for issuing banks to present authentication challenges to customers.
The object should contain as many of the following fields as possible. The full list of fields is described in the SDK documentation.
- JavaScript
var threeDSecureParameters = {
amount: '500.00',
email: 'test@example.com',
billingAddress: {
givenName: 'Jill', // ASCII-printable characters required, else will throw a validation error
surname: 'Doe', // ASCII-printable characters required, else will throw a validation error
phoneNumber: '8101234567',
streetAddress: '555 Smith St.',
extendedAddress: '#5',
locality: 'Oakland',
region: 'CA', // ISO-3166-2 code
postalCode: '12345',
countryCodeAlpha2: 'US'
},
collectDeviceData: true,
additionalInformation: {
workPhoneNumber: '8101234567',
shippingGivenName: 'Jill',
shippingSurname: 'Doe',
shippingPhone: '8101234567',
shippingAddress: {
streetAddress: '555 Smith St.',
extendedAddress: '#5',
locality: 'Oakland',
region: 'CA', // ISO-3166-2 code
postalCode: '12345',
countryCodeAlpha2: 'US'
}
},
};
Drop-in UI
To add our Drop-in UI to your checkout page, include the dropin
script:
- JavaScript
<!-- Load the Drop-in component -->
<script src="https://js.braintreegateway.com/web/dropin/1.43.0/js/dropin.min.js"></script>
The threeDSecureParameters object must contain the amount
field.
- JavaScript
var threeDSecureParameters = {
amount: '500.00',
//Pass other 3DS parameters here
};
Then, create the Drop-in and pass in the threeDSecureParameters
object into the threeDSecure
field of the requestPaymentMethod
.
- Callback
- Promise
braintree.dropin.create({
authorization: 'CLIENT_AUTHORIZATION',
container: '#dropin-container',
threeDSecure: true
}, function (err, dropinInstance) {
if (err) {
// Handle any errors that might've occurred when creating Drop-in
console.error(err);
return;
}
submitButton.addEventListener('click', function (e) {
e.preventDefault();
dropinInstance.requestPaymentMethod({
threeDSecure: threeDSecureParameters
}, function (err, payload) {
if (err) {
// Handle errors in requesting payment method
}
// Send payload.nonce to your server
// The 3D Secure Authentication ID can be found
// at payload.threeDSecureInfo.threeDSecureAuthenticationId
});
});
});
Hosted Fields
To use 3DS with Hosted Fields, include the client
, three-d-secure
, and hosted-fields
scripts:
- HTML
<!-- Load the client component. -->
https://js.braintreegateway.com/web/3.109.0/js/client.min.js
<!-- Load the 3D Secure component. -->
https://js.braintreegateway.com/web/3.109.0/js/three-d-secure.min.js
<!-- Load the Hosted Fields component. -->
https://js.braintreegateway.com/web/3.109.0/js/hosted-fields.min.js
The threeDSecureParameters object must contain the following fields:
amount
nonce
bin
- JavaScript
var threeDSecureParameters = {
amount: '500.00',
nonce: NONCE_FROM_INTEGRATION, // Example: hostedFieldsTokenizationPayload.nonce
bin: BIN_FROM_INTEGRATION, // Example: hostedFieldsTokenizationPayload.details.bin
//Pass other 3DS parameters here
};
Handle Lookup Response
It is required to implement the callback onLookupComplete
, which will be invoked after receiving the 3D Secure lookup response, before initializing the challenge and completing the flow.
- JavaScript
var threeDSecureParameters = {
// Pass 3DS parameters here
onLookupComplete: function (data, next) {
// use 'data' here, then call 'next()'
next();
}
};
Specify version: 2
in your options object when calling threeDSecure.create()
.
- Callback
- Promise
var threeDSecure;
braintree.client.create({
// Use the generated client token to instantiate the Braintree client.
authorization: 'CLIENT_TOKEN_FROM_SERVER'
}, function (clientErr, clientInstance) {
if (clientErr) {
// Handle error in client creation
return;
}
braintree.threeDSecure.create({
version: 2, // Will use 3DS2 whenever possible
client: clientInstance
}, function (threeDSecureErr, threeDSecureInstance) {
if (threeDSecureErr) {
// Handle error in 3D Secure component creation
return;
}
threeDSecure = threeDSecureInstance;
});
});
Once the 3D Secure client has been created, you can verify cards by passing the threeDSecureParameters
object into verifyCard()
. This call may challenge the cardholder to authenticate (if the card is enrolled in a 3D Secure program, such as Verified by Visa, and the cardholders issuing bank decides to challenge).
- Callback
- Promise
threeDSecure.verifyCard(threeDSecureParameters, function (err, response) {
if (err) {
// Handle error
return;
}
// Send response.nonce to your server for use in your integration
// The 3D Secure Authentication ID can be found
// at response.threeDSecureInfo.threeDSecureAuthenticationId
});
A validation error from Braintree will be returned if a field does not follow Cardinal's documentation.
3DS Server side flow
An alternative way of performing 3DS is to make the 3DS call from the server instead of from the client machine.
To meet the device data collection requirements for 3DS, merchants must either make a prerequisite prepareLookup
call in the client SDK or pass in the browser fields directly as input parameters.
Prepare the 3DS lookup
The prepareLookup
call will return the data needed to perform a 3D Secure lookup call. This call is triggered from the client's device. The payload returned by this call should be passed on to the server so a 3DS lookup can be done from there.
- JavaScript
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
});
Make the 3DS lookup call
Use the GraphQL mutation performThreeDSecureLookup
to attempt to perform 3D Secure Authentication on credit card payment method. This may consume the payment method and return a new single-use payment method.
Including device data is mandatory. This can be done either by passing along the dfReferenceId
or browserInformation
.
- Mutation
mutation PerformThreeDSecureLookup($input: PerformThreeDSecureLookupInput!) {
performThreeDSecureLookup(input: $input) {
clientMutationId
threeDSecureLookupData {
authenticationId
}
paymentMethod {
id
details {
... on CreditCardDetails {
bin
threeDSecure {
authentication {
cavv
eciFlag
liabilityShifted
liabilityShiftPossible
}
}
}
}
}
}
}
- Variables
{
input: {
paymentMethodId: single_use_payment_method_id,
amount: "10.00",
transactionInformation: {
browserInformation:
{
javaEnabled: false,
acceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
language: "en-GB",
colorDepth: 24,
screenHeight: 720,
screenWidth: 1280,
timeZone: "0",
userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safar i/537.36",
javascriptEnabled: true,
}
ipAddress: "82.34.105.112",
deviceChannel: "BROWSER",
},
}
}
Trigger 3DS challenge
This call will launch the iframe challenge using a 3D Secure lookup response from a server side lookup. This call is only necessary if a challenge is required.
- JavaScript
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
}
});
See also
- 3D Secure component reference
- 3D Secure 2 with Hosted Fields integration example
- 3D Secure 2 with Drop-in integration example
Next Page: Applying 3DS to Transactions and Verifications →