3DS backend and frontend integration

February 29, 2024

This integration option is also suitable for merchants that obtain the token for card charges from their backend. However, it also requires implementing our Kushki.js library following the steps shown below.

Available transactions

Available ✅	Not available ⛔️
3DS authentication for one-time card charges
3DS authentication for preauthorizations

Kushki.js Installation Process

Option 1 - CDN

Use the following tag script at the end of the <body> in your payment page.

<script src="https://cdn.kushkipagos.com/kushki.min.js"></script>

Option 2 - NPM

Install the package from npm.

npm install --save @kushki/js

Then import it into your code using the following code.

import { Kushki } from “@kushki/js”;

Configure the Kushki object

Add the following code to your application.

const kushki = new Kushki({
  merchantId: 'public-merchant-id', // Your public merchant id 
  inTestEnvironment: true,
});

Collect the user information and send it to your back-end

First, add the form to your payment page with the required fields. You can design it in any way you like.

For example:

<form id="payment-form">
  <input placeholder="Card Number" type="text" name="number">
  <input placeholder="Full Name" type="text" name="name">  
  <input placeholder="MM" type="text" name="expiry_month">
  <input placeholder="YY" type="text" name="expiry_uear">
  <input placeholder="CVC" type="text" name="cvc">

  <button id="submit">Pay $49.99</button>
</form>

Use the requestSecureInit() method

Use the requestSecureInit() method by sending the card number to obtain the jwt.

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

If the response is successful you will get the jwt:

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NTQ2NTY4ODYsImlhdCI6MTY1NDY0OTY4NiwiaXNzIjoiNWVhMzJmZDJmZjQ2NDU2OTY3YjUyNDliIiwianRpIjoiMDFhZTQyYWUtYzMyZS00YWRjLWFmOWQtZWVhMmFlNjRkMDkxIiwiT3JnVW5pdElkIjoiNWVhMzJmZDJhZDA3ZDIxYTM2OTc4OGFlIiwiUmVmZXJlbmNlSWQiOiI3ZjY1NzM5NS0yMDIwLTQ1ZjEtOTY4Mi05MzJiNTU5YWYzMWIifQ.JUkk70Kg4KlUYW7eIvsW8LoDhxJeG8P00VrJH9oQipc"
}

Otherwise, you will get the following error response:

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

Request a one-time payment token

In this step you have to send the jwt obtained in the previous step, in the endpoint Request a card token in the following way.

{
  "card": {
    "name": "John Doe",
    "number": "4000000000000002",
    "expiryMonth": "01",
    "expiryYear": "28",
    "cvv": "123"
  },
  "totalAmount": 59,
  "currency": "USD",
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NTQ2NTg0ODgsImlhdCI6MTY1NDY1MTI4OCwiaXNzIjoiNWVhMzJmZDJmZjQ2NDU2OTY3YjUyNDliIiwianRpIjoiZjc4NzQzNTctMmY2Zi00OTExLTg3MDctZDBmN2RlYTZlNTk4IiwiT3JnVW5pdElkIjoiNWVhMzJmZDJhZDA3ZDIxYTM2OTc4OGFlIiwiUmVmZXJlbmNlSWQiOiIyZDdhOTA2OS04MjhjLTQxNDItYWYwNC1hMjZjNWI4YzQ3MjMifQ.5nmFrf3sOAxKNIcJTzc5i2GNY5ALABpu42YsrHIibio"
}

Get the token and variables

Receive the token and the variables secureService , secureId and the security object specified in the following table.

Parameter	Type	Description
`authRequired`	Booleana	This field indicates whether or not a 3DS challenge is required.
`acsURL`	URL	Refers to the URL of the challenge page that the user must pass (Access Control System).
`specificationVersion`	String	Refers to the applicable 3DS version.
`authenticationTransactionId`	String	Verified transaction ID from brands
`paReq`	String	Stands for Payer Authentication Request. It is a base64 encoded field containing your merchant and cardholder information that is sent to the issuer for authentication Note: in case you are testing in a UAT environment, you must send `sandbox`.

When 3DS is activated the response obtained from the requestToken() method will look like this:

{
  "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": "2.2.0",
    "authRequired": true
  }
}

Use the requestValidate3DS method

Once you have finished the previous step, you must use the requestValidate3DS method to validate 3DS, sending the security object delivered in the Token response .

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: "2.2.0",
    authRequired: true
}, callback);

If the value of the authRequired variable is equal to true the modal for 3DS validation 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 modal will not be presented for 3DS validation.

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 K322 code and any of the other subcodes specified in the Error codes guide.

Configure your back-end

This is what a payment with 3DS authentication will look like:

3DS Overview

Test your integration

We have test cards that you can use during the test mode to ensure that your integration is ready. You can use them with any CVV, 1234 as OTP code and future expiration date.

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