Authenticate your subscriptions with 3DS

November 22, 2023

Learn how to authenticate card tokenization with 3DS

For the security of your merchant, Kushki fraud prevention team will request you to activate the 3DS authentication when tokenizing cards to receive recurring payments, either one click or scheduled payments.

By having the 3DS authentication service active, your customers will be requested to complete an extra verification step (from now on, challenge) with the card issuer to complete certain transactions. This challenge usually consists of an OTP sent by the bank to your customer’s e-mail address or telephone number.

How does the 3DS authentication work?

Once the customer fills out the form and clicks on Save Card, Kushki will validate if 3DS authentication is required for the transaction. If this validation is required, your customer will be displayed a challenge whose experience may vary depending on the brand and the issuing bank. When your customer completes the challenge, they will be able to finalize the card registration.

The 3DS authentication flow (recurring charge creation) with Kushki is shown below:

3DS is available on:

• Kushki.js
• Smartlinks (Only applies for scheduled payments)

3DS Supported Brands

1. Configure your front-end

Configure your front-end according to your integration.

Kushki.js

Follow our instructions for Kushki.js described in our guide to accept recurring payments.

Now, before sending the data to the end-point in your back-end, we must perform the 3DS validation with the card issuer.

When 3DS is enabled, the response from the requestSubscriptionToken() method will be as shown below:

{
  "token": "oaACBE1012310zYTjE239227yqFRA8r7",
  "secureService": "3dsecure",
  "secureId": "e356d68d-3f31-4134-a9a7-8cba46b3cdac",
  "security": {
    "acsURL": "https://authentication.cardinalcommerce.com/ThreeDSecure/V1_0_2/PayerAuthentication?issuerId\u00d2aa20412b0063aca652facd9g\u0034transactionId\u003dQhcf3XOjdZmjve336Vee2gb5rof1",
    "authenticationTransactionId": "1d8cf7jg5Bfn8Nj73mn7",
    "paReq": "eNpVUtluwjAQfPdXoH5A7DghtGixxFUViRt6iDfXGGJCDpykQL++doDSvu3sjtYzs4ZlqKXsLaQotWQwknnOt7Km1q2HyeIx6EW7w2dn09NjFXnxxn1gMG3P5YHBl9S5ShPmOsShgG8QmRVahDwpGHBx6AzGzKdXoH5A7DghtGixxpVUtluwjAQfPdXoH5A7DghtGixs4ZlqKXsLaQot0u4KqLQKRlUugzC4gP+AYQlHrPwqLImhgfj0cnKvMwUhnfprkj0hiwnSPAxn1gMG3P5YHBl9S5ShPmOsShOqLqJ7x73Gx2vVbgC0DwZoXklFCKXFpo0bcpu83qWht0u4KqLQKRlUugzC4gP+AYQlHrpfUGenfxtGEOl1jIRN0c3hECesjSRhmNC+62Nh7vy7otNVxQmtdkm3Ew/Jrv1Kp0X4elF8Pb6p/n2KH/k0skaqcyeVHfdaulqgoP20X4elF8Pb6p/n2KH/k0sv8\u003d",
    "specificationVersion": "1.0.2",
    "authRequired": true
  }
}

You can find the description of these variables below:

Once you receive the Token response with the structure above, you must send the security object to Kushki by using the requestValidate3DS method:

var callback = function(response) {
  if(!response.code){
    console.log(response);
  } else {
    console.error('Error: ',response.error, 'Code: ', response.code, 'Message: ',response.message);
  }
}

kushki.requestValidate3DS({
 secureId: "5e44449e-869b-4fed-bbca-e1bfa5af53c3",
 security: {
   acsURL: "https://authentication.cardinalcommerce.com/ThreeDSecure/V1_0_2/PayerAuthentication?issuerId\u00d2aa20412b0063aca652facd9g\u0034transactionId\u003dQhcf3XOjdZmjve336Vee2gb5rof1",
    authenticationTransactionId: "1d8cf7jg5Bfn8Nj73mn7",
    paReq: "eNpVUtluwjAQfPdXoH5A7DghtGixxFUViRt6iDfXGGJCDpykQL++doDSvu3sjtYzs4ZlqKXsLaQotWQwknnOt7Km1q2HyeIx6EW7w2dn09NjFXnxxn1gMG3P5YHBl9S5ShPmOsShgG8QmRVahDwpGHBx6AzGzKdXoH5A7DghtGixxpVUtluwjAQfPdXoH5A7DghtGixs4ZlqKXsLaQot0u4KqLQKRlUugzC4gP+AYQlHrPwqLImhgfj0cnKvMwUhnfprkj0hiwnSPAxn1gMG3P5YHBl9S5ShPmOsShOqLqJ7x73Gx2vVbgC0DwZoXklFCKXFpo0bcpu83qWht0u4KqLQKRlUugzC4gP+AYQlHrpfUGenfxtGEOl1jIRN0c3hECesjSRhmNC+62Nh7vy7otNVxQmtdkm3Ew/Jrv1Kp0X4elF8Pb6p/n2KH/k0skaqcyeVHfdaulqgoP20X4elF8Pb6p/n2KH/k0sv8\u003d",
    specificationVersion: "1.0.2",
    authRequired: true
}, callback);

If the value of the authRequired variable is equal to true, the 3DS validation modal will be presented and your customer will then receive the value to enter by email or text message.

If the value of the authRequired variable is equal to false, the 3DS validation modal will not be presented.

The response you will receive in the callback function will be:

{
  "code":"3DS000",
  "message":"ok"
}

In case of error, the response of the callback function will be something like:

{ 
  "message":"error-message", 
  "code":"error-code",
  "error": "error-message" 
}

You will receive the authentication response in the charge. If the authentication is declined, you will receive a 322 code and any of the other subcodes specified in the Error codes guide.

2. Configure your back-end

3. Test your integration

Below you will find some test cards that you can use in test mode (UAT) to make sure your integration is ready. Use them with any CVV, enter any future expiration date and once the 3DS modal appears, enter 1234 as the validation code.

• Transaction approved with 3DS authentication required:
  • 4456528080389860
  • 4456529267234200
  • 4456529165328302
  • 4456524869770255
  • 4456523340069956
• Transaction approved without 3DS validation:
  • 4456540000000063
  • 4456543371713314
  • 4456541982068615
  • 4456541249811088

3. Prepare your certification

Follow the guidelines described in our guide to accept recurring card payments.