Acepta pagos con 3DS vía API

22 noviembre 2023

Conoce cómo funciona el proceso de integración API para autenticar pagos con 3DS y garantizar la seguridad de tu comercio.

Esta funcionalidad se encuentra disponible para los siguientes modelos:

☑ Adquirente
☐ Agregador

Si eres un comercio certificado PSI, podrás integrar nuestros servicios directamente consumiendo nuestra API. Sin embargo, para la correcta implementación de 3DS deberás importar una funcionalidad de nuestra librería Kushki.js siguiendo los pasos que se muestran a continuación.

Proceso de instalación de Kushki.js

Opción 1 - CDN

Usa el siguiente tag script al final del <body> en tu página de pagos.

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

Opción 2 - NPM

Instala el paquete desde npm.

npm install --save @kushki/js

Luego impórtalo en tu código utilizando el siguiente código.

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

Configura el objeto Kushki

Añade el siguiente código a tu aplicación

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

Recoge la información del usuario y envíala a tu back-end

Primero, añade el formulario a tu página de pagos con los campos requeridos. Puedes diseñarlo de la forma que mejor te parezca.

Por ejemplo:

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

Consume el método requestSecureInit()

Usa el método requestSecureInit() enviando el número de la tarjeta, para obtener el 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);

Si la respuesta es exitosa te mostrará el jwt:

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

En caso contrario, te arrojará la siguiente respuesta de error:

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

Solicita el token de pago único

En este paso debes enviar el jwt obtenido en el paso anterior, en el endpoint Request a card token de la siguiente manera.

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

Obtén el token y las variables

Recibe el token y las variables secureService , secureId y el objeto security especificadas en la siguiente tabla.

Parámetro	Tipo	Descripción
`authRequired`	Booleana	Este campo te indica si se requiere o no challenge de 3DS.
`acsURL`	URL	Hace referencia a la URL de la página del reto que el usuario debe pasar (Access Control System).
`specificationVersion`	String	Se refiere a la versión de 3DS aplicable.
`authenticationTransactionId`	String	ID de la transacción verificada desde las marcas.
`paReq`	String	Significa Payer Authentication Request. Es un campo codificado en base64 que contiene información de tu comercio y del tarjetahabiente y que se envía al emisor para la autenticación Nota: en caso de estar haciendo pruebas en ambiente UAT, se debe enviar `sandbox`.

Cuando 3DS está activado la respuesta obtenida desde el método requestToken() se verá de esta manera:

{
  "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
  }
}

Consume el método requestValidate3DS

Una vez finalizado el paso anterior, deberás consumir el método requestValidate3DS para hacer la validación 3DS, enviando el objeto security entregado en la respuesta del Token .

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);

Si el valor de la variable authRequired es igual a true el modal para validación de 3DS será presentado y tu cliente entonces recibirá el valor a ingresar por correo electrónico o mensaje de texto.

Si el valor de la variable authRequired es igual a false no se presentará el modal para validación 3DS.

La respuesta que recibirás en la función callback será:

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

En caso de error, la respuesta de la función callback será algo como:

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

La respuesta de la autenticación la obtendrás en el cargo. Si la autenticación se declina, recibirás un código K322 y alguno de los subcódigos especificados en la guía de Códigos de error.

Configura tu back-end

Así se verá un pago con autenticación de 3DS:

3DS Overview

Prueba tu integración

Existen tarjetas de prueba que puedes utilizar en modo prueba para asegurarte que tu integración está lista. Úsalas con cualquier CVV, 1234 como código OTP y fecha de expiración futura.

Transacción aprobada con generación de modal 3DS:
- 4456528080389860
- 4456529267234200
- 4456529165328302
- 4456524869770255
- 4456523340069956
Transacción aprobada sin generación de modal 3DS:
- 4456540000000063
- 4456543371713314
- 4456541982068615
- 4456541249811088