Integración 100% API de 3DS

16 abril 2025

Autentica tus cobros con 3DS usando la API de Kushki

Si eres un comercio con certificado PCI, podrás autenticar tus cobros únicos con tarjeta con 3DS consumiendo nuestra API como se indica a continuación.

Transacciones soportadas con esta opción

Recoge la información del usuario y solicita un token de pago único

1. Cuando recojas la información de pago del usuario y los datos de tarjeta, asegúrate de incluir los parámetros authValidation y callbackUrl en la solicitud de token. Estos parámetros son obligatorios para realizar la autenticación 3DS en caso de que se requiera.

Opción 1: authValidation: “url”

Usa esta opción si deseas que Kushki redireccione al usuario a una nueva ventana.

A continuación un ejemplo de la solicitud del token con authValidation: url`

{
  "card": {
    "name": "John Doe",
    "number": "5451951574925480",
    "expiryMonth": "08",
    "expiryYear": "28",
    "cvv": "121"
  },
  "totalAmount": 160000,
  "currency": "COP",
  "authValidation": "url",
  "callbackUrl": "https://www.tutienda.com"
}

En caso de que no se requiera validación 3DS, recibirás el token como único parámetro y podrán proceder a realizar el cargo o la preautorización.

En caso de que sí se requiera validación de 3DS, recibirás como respuesta el token, la url y las variables secureService y secureId especificadas como en el siguiente ejemplo:

{
  "token": "g9m2XG100000uut73n085881SMOP3bP1",
  "url": "https://merchantacsstag.cardinalcommerce.com/MerchantACSWeb/pareq.jsp?vaa=b&gold=A",
  "secureService": "3dsecure",
  "secureId": "61efd064-b9df-4c0c-81fb-5b39a5d0cf9f",
}

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

2. Asegúrate de abrir en tu navegador la url obtenida en url para que el pagador realice la autenticación 3DS en caso de que se requiera.

3. Una vez el usuario complete la autenticación, se retornará el cliente con una llamada GET a la callbackUrl que hayas especificado al solicitar el token.

Opción 2: authValidation: “iframe”

Usa esta opción si deseas mantener la autenticación embebida dentro de tu sitio o aplicación.

Ejemplo con iframe

{
  "card": {
    "name": "John Doe",
    "number": "5451951574925480",
    "expiryMonth": "08",
    "expiryYear": "28",
    "cvv": "121"
  },
  "totalAmount": 160000,
  "currency": "COP",
  "authValidation": "iframe",
  "callbackUrl": "https://www.tutienda.com"
}

Respuesta cuando se usa iframe:

{
  "token": "437...8fe",
  "url": "https://{env}.kushkipagos.com?token=437...8fe&merchantId=097...df6&bin=NDAwMDAwMDA=&callbackUrl=https://www.tutienda.com&isSandbox=true&authValidation=iframe",
  "secureService": "3dsecure",
  "secureId": "46433785-...-9449ad2f120f"
}

Coloca esta URL en un iframe visible dentro de tu aplicación para permitir al tarjetahabiente completar la autenticación:

<iframe id="authFrame" src="{tokenResponse.url}" style="width:100%; height:500px; border:none;"></iframe>

Eventos del iframe

Cuando uses authValidation = “iframe” se emiten eventos vía postMessage desde Kushki para informar sobre el estado del proceso de autenticación. A continuación los tipos de eventos:

¿cómo capturar los eventos del iframe?

Cuando integras la autenticación 3DS en un iframe, Kushki enviará eventos usando la API de postMessage. Estos eventos son esenciales para que tu aplicación pueda:

• Saber en qué estado se encuentra la autenticación del tarjetahabiente.

• Reaccionar visualmente ante una validación exitosa o fallida.

• Ocultar o eliminar el iframe una vez completado el proceso.

Para capturar estos eventos, debes usar window.addEventListener("message", ...) en tu frontend. Todos los eventos enviados por Kushki incluyen la propiedad origin con valor "KUSHKI".

Ejemplo

window.addEventListener("message", (event) => {
  // Verifica que el mensaje provenga de Kushki
  if (event.data.origin === "KUSHKI") {
    console.log("Evento recibido de Kushki:", event.data);

    const iframe = document.getElementById("authFrame");

    // Validación exitosa: puedes continuar con el cargo o preautorización
    if (
      event.data.success === true &&
      event.data.notificationType === "FINISH_VALIDATION"
    ) {
      iframe.style.display = "none";
      alert("Validación 3DS completada correctamente");
    }

    // Validación fallida: debes generar un nuevo token
    else if (
      event.data.success === false &&
      event.data.notificationType === "FAILED_VALIDATION"
    ) {
      iframe.style.display = "none";
      alert("La validación 3DS falló. Intenta nuevamente.");
    }

    // Otros tipos de evento: opcionalmente puedes actuar sobre ellos
    else {
      console.log("Evento intermedio recibido:", event.data.notificationType);
    }
  }
});

Eventos antes de la validación 3DS

Antes de que inicie la autenticación como tal, Kushki emitirá los siguientes eventos vía postMessage:

INIT_VALIDATION

Este evento indica que se ha iniciado el proceso de autenticación 3DS. Siempre se emite al comenzar la validación.

{
  "origin": "KUSHKI",  
  "notificationType": "INIT_VALIDATION",
  "token": "0889...e19b"
}

LAUNCH_VALIDATION

Este evento indica que se requiere mostrar el modal o interfaz de autenticación 3DS al tarjetahabiente. No siempre se emite; solo aplica si el emisor solicita un challenge.

{
  "origin": "KUSHKI",  
  "notificationType": "LAUNCH_VALIDATION",
  "token": "088...19b"
}

Eventos posteriores a la validación 3DS

Estos son los mensajes que Kushki enviará al finalizar el proceso de validación 3DS, ya sea exitosamente (FINISH_VALIDATION) o con error (FAILED_VALIDATION). Ambos mensajes incluyen información clave para identificar el resultado y continuar el flujo correspondiente.

Respuesta en caso de validación fallida (FAILED_VALIDATION)

{
  "origin": "KUSHKI",  
  "notificationType": "FAILED_VALIDATION",
  "success": false,
  "message": "Error en la validación de 3DS",
  "token": "088...19b",
  "callbackUrl": "{callbackUrl}"
}

Respuesta en caso de validación finalizada (FINISH_VALIDATION)

{
  "origin": "KUSHKI",  
  "notificationType": "FINISH_VALIDATION",
  "success": true | false,
  "token": "088...19b",
  "callbackUrl": "{callbackUrl}"
}

Luego, deberás redirigir al usuario al callbackUrl para especificar el resultado de la autenticación y proceder a ejecutar el cargo.

¿Qué hace la callbackUrl? (Solo para el flujo 1. authValidation = url )

La función callback te permitirá saber si el proceso de validación 3D Secure finalizó correctamente o si hubo algún problema durante el proceso. Dicha url será llamada automáticamente después de realizar la autenticación mediante un redireccionamiento 301 haciendo una petición GET a la url enviada en el campo callbackUrl mandando los parámetros de la respuesta en la url (path parameters).

A continuación la descripción de los parámetros de esta función:

Si success= true

El parámetro de tipo booleano success=true, se retornará en los siguientes escenarios, en todos los cuales se puede proceder a realizar el cargo o la preautorización:

1. El challenge fue presentado al tarjetahabiente y este se autenticó de manera exitosa.
2. El proveedor de 3DS determinó que la tarjeta es confiable y no fue necesario presentar un challenge.
3. No fue posible presentar el challenge al tarjetahabiente. En este caso es probable que se rechace el charge o la preautorización.
4. El tarjetahabiente agotó el limite de 3 intentos permitidos para realizar la autenticación.

https://www.tutienda.com/?success=true&token=cfa0bfec88324bd7a5c6c1ad9135a846

Nota: Recibirás los parámetros como query params

Si success= false

En caso de que el parámetro success se retorne como false es posible que sea debido a que el tarjetahabiente ingresó incorrectamente el challenge.

Ejemplo de un callback con problema en la autenticación:

https://www.tutienda.com/?success=false&message=Error%20en%20la%20validación%20de%203DS&token=cfa0bfec88324bd7a5c6c1ad9135a846

Si este parámetro continúa como false, se deberá en cualquier caso generar nuevamente el token enviando los datos de la tarjeta ya que si se realiza un cargo o preautorización, estas se declinarán.

Prueba tu integración

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

Auth required false - cargo aprobado

• 4456540000000063
• 4456543371713314
• 4456541982068615
• 4456541249811088

Auth required true - cargo declinado

• 4456530000000031
• 4456530000000106
• 4456536583667765
• 4456536501449767
• 4456532705848821

Auth required true - cargo aprobado

• 4456528080389860
• 4456529267234200
• 4456529165328302
• 4456524869770255
• 4456523340069956

Autenticación de 3DS fallida:

• 9999 (ingresa este valor cuando se muestre el modal).