Integración 3DS con librería kushki.js

17 diciembre 2024

Usa esta opción si tienes implementado o piensas implementar kushki.js en tu front-end y deseas autenticar tus transacciones con 3DS.

Transacciones soportadas

Soporta ✅	No soporta ⛔️
Autenticación 3DS para cargos únicos con tarjeta

1. Configura tu front-end

Configura tu front-end de acuerdo a tu integración.

Kajita (formulario de pago)

Sigue nuestras instrucciones para Kajita descritas en nuestra guía para aceptar pagos con tarjeta.

Una vez que configures 3DS para tu comercio, Kajita solicitará la validación 3DS de manera automática para cada intento de pago en que se requiera autenticación. No es necesario que realices nada más.

Kushki.js

Sigue nuestras instrucciones para Kushki.js descritas en nuestra guía para aceptar pagos con tarjeta.

Ahora, antes de enviar los datos al endpoint en tu back-end debemos realizar la validación 3DS con el emisor.

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

A continuación la descripción de estas variables:

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

Una vez recibas la respuesta del Token con la estructura anterior, debes enviar el objeto security a Kushki consumiendo el método requestValidate3DS:

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

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.

Kushki.js Hosted Fields

Al momento de llamar al método requestToken() para solicitar un token, si existe una regla 3DS y se cumple la condición, el método requestToken() desplegará el modal para que el cliente pueda ingresar los datos de la validación 3DS.

Si la validación fue incorrecta, podrás recibir uno de los siguientes códigos de error:

CÓDIGO	MENSAJE	EJEMPLO	DESCRIPCIÓN
E004	Error en solicitud de JWT	{ code: “E004”, message: “Error en solicitud de JWT” }	Si el comercio tiene habilitada una regla para 3DS y hubo un error al solicitar el JWT, se regresará el código E004. Por favor, vuelve a intentar; si el error persiste, contacta a soporte de Kushki.
E005	Campos 3DS inválidos	{ code: “E005”, message: “Campos 3DS inválidos” }	Si el comercio tiene habilitada una regla para 3DS y hubo un error en la autenticación 3DS, se regresará el código E005. Por favor, vuelve a intentar asegurándote de ingresar correctamente los datos para la validación 3DS.
E006	Error en solicitud de validación de token	{ code: “E006”, message: “Error en solicitud de validación de token” }	Si el comercio tiene habilitada una regla 3DS y hubo un error en la sesión de validación 3DS, se regresará el código E006. Por favor, vuelve a intentar asegurándote de ingresar correctamente los datos para la validación 3DS; si el error persiste contacta a soporte de Kushki.

Consulta la referencia para más información sobre validación 3DS.

2. Configura tu back-end

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

4. Prepara tu certificación

Sigue las pautas descritas en nuestra guía para aceptar pagos con tarjeta.