Accept payments with 3DS via API

November 22, 2023

Learn how the API integration process works to authenticate payments with 3DS and ensure the security of your merchant.

This functionality is available for the following models:

☑ Acquirer
☐ Aggregator

If you are a PSI certified merchant, you will be able to integrate our services using our API directly. However, to implement the 3DS correctly you must import a feature from our Kushki.js library following the steps below.

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

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": "1.0.2",
    "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: "1.0.2",
    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