3DS API integration plus kushki.js library

Important

This integration option requires PCI Compliance

If you have an API integration (backend) and need to authenticate payments using 3D Secure, it is necessary to implement any of the Kushki.js or Kushki.js Hosted Fields frontend libraries to initialize the 3D Secure service and display the authentication modal, if applicable.

Available transactions

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

Step 1. Get a Json Web Token (JWT)

It is necessary to implement the requestSecureInit() method from Kushki.js or Kushki.js Hosted Fields to obtain a Json Web Token (JWT), which will be necessary when generating a token.

Kushki.js

Use Kushki.js if you need more control over the "look & feel" or appearance of your payment form.

Import Kushki.js

You can import the Kushki.js library via CDN or as an NPM package.

Option 1 - CDN

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

Option 2 - NPM

Install the package from npm.

Then import it into your code using the following code.

Set up `Kushki` object

Add the following code to your application

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:

Check the complete reference in our Kushki.js reference

Consumes the requestSecureInit() method

Use the requestSecureInit() method sending the card number, to get the jwt.

If the request has been successful, a json object with the jwt will be returned:

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

Otherwise, it will give you the following error response:

{ 
  "mensaje" : "mensaje de error" , 
  "código" : "código de error" ,
  "error" : "mensaje de error" 
}

Kushki.js Hosted Fields

With Hosted Fields, included in Kushki.js, you can securely collect customer payment information through fields stored on Kushki infrastructure. Returns a token which allows the payment flow to continue from the back-end.

Import Kushki.js Hosted Fields into your app

Option 1 - CDN

Import the Kushki.js Hosted Fields library into your application using a <script> tag inside the <body> tag. Once imported, you will be able to access the resources described below to create a payment flow with Kushki.

It is necessary to import the kushki.min.js library (which comes with the necessary code to store your merchant's credentials) and the antifraud.min.js library (which provides the necessary tools to perform security authentications).

Option 2 - NPM

Install the Kushki.js Hosted Fields library as an npm package inside your application with the following code:

Option 3 - YARN

Install the Kushki.js Hosted Fields library as a yarn package inside your application with the following code:

Create an instance of `KushkiOptions`

To use the Kushki.js Hosted Fields library, it is necessary to create an instance of KushkiOptions which allows you to set the public key of the work environment (test or production) through the init() method.

Note: When you are ready to accept real payments, you need to replace the test key with the production key.

Add the following code to your application:

Check the reference for more information about the KushkiOptions instance.

Initialize the 3D Secure authentication service

Consume the requestSecureInit() method by sending the card number to get a JWT.

If the request has been successful, a json object with the jwt will be returned:

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

Otherwise, it will give you one of the following errors:

CODE	MESSAGE	EXAMPLE	DESCRIPTION
E004	JWT request error	{ code: "E004", message: "Error en solicitud de JWT" }	If the merchant has a rule for 3DS enabled and there was an error requesting the JWT. Please try again; if the error persists, contact Kushki support.
E018	Invalid card length	{ code: "E018", message: "Longitud de tarjeta inválida" }	Please verify that the card length is correct.
E019	Merchant does not have active 3DS service	{ code: "E019", message: "Comercio no tiene activo 3DS" }	The merchant does not have the 3DS service active. To activate it, check out the guide fraud detection tools.

Step 2. Request a card token

Request a card token by sending the JWT obtained in the previous step.

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

If the merchant has active 3D Secure rules and 3D Secure was successfully initialized as described in step 1, in addition to the token, other properties will be returned that will be required in the next step.

If a transaction requires 3D Secure authentication by the cardholder, the authRequired property within the security object will be returned as true (security.authRequired).

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`.

Examples

Response object with 3D Secure authentication required

{
  "token": "g9m2XG100000uut73n085881SMOP3bP1",
  "secureService": "3dsecure",
  "secureId": "61efd064-b9df-4c0c-81fb-5b39a5d0cf9f",
  "security": {
    "acsURL": "https://merchantacsstag.cardinalcommerce.com/MerchantACSWeb/pareq.jsp?vaa=b&gold=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "authenticationTransactionId": "uvvZn0ND0ukTOJIfhfi0",
    "authRequired": true,
    "paReq": "eNpVUstuwjAQvPsrItRTD7HjhAjQYokWqQVUSksqKm5RYkiU5oFjE/j72iFAK/mws7Nr78wagkRwPl3zSAnO4I3XdbjnVhqPe+p43BZkOSUqC97ns12yS0mPwWryyQ8MjlzUaVkwxyY2BXyFSF8hoiQsJIMwOjzNlszzh9TxAXcQQc7FbMr6nksdAviCEBRhztlivXh8ScpaWitRxiqSpRXwWqYF4JZHEJWqkOLMfOIBvgIESvywRMpqhHHTNHam6iRLq3Bf1nZU5oANjwDfh1spE9Va8ymNWfy9pZvca4Lso4k38isg1XybJ3kYTMaATQWCOJScUUIp8cnAIu5IH1cP0eYRhLkZhj30hzbRsjqIoDIPTS6oPzTU34wWpITgRXRmA09zN4SAn6qy4LpG23uLtYb75M+vxuRIGjd9z3UpNS63uG1PtTXUJ07bn7Y+YdODux3ibt06+vcNfgHbNq5L",
    "specificationVersion": "2.2.0"
  }
}

Response object with 3D Secure authentication not required

{
  "token": "URkTD3100000aSfrJk085881gtsxGts6",
  "secureService": "3dsecure",
  "secureId": "9903cc36-6e9c-42b0-bb76-34c9c4dbaff5",
  "security": {
    "acsURL": "",
    "authenticationTransactionId": "",
    "authRequired": false,
    "paReq": "",
    "specificationVersion": "2.2.0"
  }
}

Response object without 3D Secure

{
  "token": "3c1518cf6f844e248880aad6187cf8d7"
}

Learn more about request a card token.

Step 3. Authenticate through 3D Secure.

In case the security.authRequired property obtained in the previous step comes with the value of true, it will be necessary to perform authentication through 3D Secure. To perform 3D Secure authentication, you must call the requestValidate3DS method in Kushki.js or Kushki.js Hosted Fields, sending the response object from the previous step.

Kushki.js

If the value of the authRequired property is equal to true, the 3DS validation modal will be displayed and your client will then receive the value to be entered via email or text message.

If the value of the authRequired property 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 callback function's response 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.

Kushki.js Hosted Fields

Product in beta version 🔐

We are working on our beta version. Stay tuned for its official release! You can also contact your account manager for more information.

The requestValidate3DS() method receives as a parameter the object obtained in the response from the previous step.

import { init, IKushki } from "@kushki/js-sdk";
import { CardTokenResponse, requestValidate3DS, TokenResponse } from "@kushki/js-sdk/Antifraud";

const on3DSValidation = async () => {
  try {
    const kushkiInstance = await init({
      inTest: true,
      publicCredentialId: merchantId
    });

    const cardTokenResponse: CardTokenResponse = {
      secureId: "secure_id",
      secureService: "secure_service",
      security: {
        acsURL: "https://kushki.com",
        authenticationTransactionId: "transaction_id",
        authRequired: true,
        paReq: "jwt",
        specificationVersion: "2.0.1"
      },
      token: "token"
    };

    const response: TokenResponse = await requestValidate3DS(kushkiInstance, cardTokenResponse);

    console.log(response);
  } catch (error: any) {
    console.log(error)
  }
};

PROPERTY	TYPE	REQUIRED	DESCRIPTION
kushkiInstance	IKushki	YES	Object with public merchant id and work environment
secureInitRequest	SecureInitRequest	YES	You must define this object in order to request the initialization of 3DS.

If the 3D Secure authentication has been successful, the same token from step 2 will be returned with the corresponding validations to continue with the payment flow.

{
  "token": "3c1518cf6f844e248880aad6187cf8d7"
}

In case of an error during authentication, one of the following messages will be returned:

CODE	MESSAGE	EXAMPLE	DESCRIPTION
E005	Campos 3DS inválidos (Invalid 3DS fields)	{ code: "E005", message: "Campos 3DS inválidos" }	If the merchant has a 3DS rule enabled and there was an error in the 3DS authentication, error code E005 will be returned. Please try again making sure to enter the data correctly for the 3DS validation.
E006	Error en solicitud de validación de token (Token validation request error)	{ code: "E006", message: "Error en solicitud de validación de token" }	If the merchant has a 3DS rule enabled and there was an error in the 3DS authentication, error code E005 will be returned. Please try again making sure to enter the data correctly for the 3DS validation.

Learn more about the requestValidate3DS() method.

The cardholder will have up to a maximum of 3 retries to complete 3DS authentication.

Step 4. Make a one-time payment or a recurring charge

Continue with the payment flow by generating a one-time payment or a recurring charge with the token validated in the previous step.

{
  "token": "f5c64f7ac8ea42d5a58dcdc74de973dc",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 16.98,
    "ice": 0,
    "iva": 0,
    "currency": "MXN"
  },
  "metadata": {
    "Referencia": "987654"
  },
  "contactDetails": {
    "documentType": "CC",
    "documentNumber": "1234567890",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+593912345678"
  },
  "orderDetails": {
    "siteDomain": "example.com",
    "shippingDetails": {
      "name": "John Doe",
      "phone": "+593912345678",
      "address1": "Eloy Alfaro 139 y Catalina Aldaz",
      "address2": "centro 123",
      "city": "Quito",
      "region": "Pichincha",
      "country": "Ecuador"
    },
    "billingDetails": {
      "name": "John Doe",
      "phone": "+593912345678",
      "address1": "Eloy Alfaro 139 y Catalina Aldaz",
      "address2": "centro 123",
      "city": "Quito",
      "region": "Pichincha",
      "country": "Ecuador"
    }
  },
  "productDetails": {
    "product": [
      {
        "id": "198952AB",
        "title": "eBook Digital Services",
        "price": 10000,
        "sku": "10101042",
        "quantity": 1
      },
      {
        "id": "198953AB",
        "title": "eBook Virtual Selling",
        "price": 6980,
        "sku": "004834GQ",
        "quantity": 1
      }
    ]
  },
  "fullResponse": "v2"
}

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

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

To enable 3DS in test mode in your merchant, an additional configuration by Kushki is required.

3DS API integration plus kushki.js library

Available transactions#

Step 1. Get a Json Web Token (JWT)#

Kushki.js#

Import Kushki.js#

Option 1 - CDN#

Option 2 - NPM#

Set up Kushki object#

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

Consumes the requestSecureInit() method#

Kushki.js Hosted Fields#

Import Kushki.js Hosted Fields into your app#

Option 1 - CDN#

Option 2 - NPM#

Option 3 - YARN#

Create an instance of KushkiOptions#

Initialize the 3D Secure authentication service#

Step 2. Request a card token#

Examples#

Response object with 3D Secure authentication required#

Response object with 3D Secure authentication not required#

Response object without 3D Secure#

Step 3. Authenticate through 3D Secure.#

Kushki.js#

Kushki.js Hosted Fields#

Step 4. Make a one-time payment or a recurring charge#

Test your integration#

Available transactions

Step 1. Get a Json Web Token (JWT)

Kushki.js

Import Kushki.js

Option 1 - CDN

Option 2 - NPM

Set up `Kushki` object

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

Consumes the requestSecureInit() method

Kushki.js Hosted Fields

Import Kushki.js Hosted Fields into your app

Option 1 - CDN

Option 2 - NPM

Option 3 - YARN

Create an instance of `KushkiOptions`

Initialize the 3D Secure authentication service

Step 2. Request a card token

Examples

Response object with 3D Secure authentication required

Response object with 3D Secure authentication not required

Response object without 3D Secure

Step 3. Authenticate through 3D Secure.

Kushki.js

Kushki.js Hosted Fields

Step 4. Make a one-time payment or a recurring charge

Test your integration