Integración 100% API de 3DS

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

Soporta ✅	No soporta ⛔️
- Autenticación 3DS para cargos únicos con tarjeta	- Autenticación en creación de suscripciones calendarizadas o bajo demanda. - Autenticación en ejecución de cargos one click (bajo demanda)

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

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.

Parámetro	Valores permitidos / tipo de dato	Descripción
`authValidation`	`url` o `iframe`	Define el tipo de integración deseado para autenticación 3DS. Usa `url` para redirección o `iframe` para embeber.
`callbackUrl`	`string`	URL a la que se retornará el usuario una vez completada la autenticación 3DS.

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.

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

Parámetro	Tipo	Descripción
`token`	string	Es el token que deberán usar para hacer el cargo, una vez finalice la validación de 3DS
`url`	URL	Es la URL a la que deberás redirigir al usuario para la autenticación.
`secureService`	String	Tipo de autenticación, será 3dsecure en el caso de 3DS
`secureId`	String	El secureId que se obtiene de la solicitud del token

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.

A tener en cuenta

En caso de que trates de utilizar el token para hacer el cargo, omitiendo la validación 3DS, recibirás una declinación con código K322 y subcódigo K328 (sin validación de seguridad).

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"

Producto en versión beta 🔐

Estamos trabajando en nuestra versión beta. ¡Manténte atento a su lanzamiento oficial! También puedes contactar a tu gerente de cuenta para más información.

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:

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:

Evento	Descripción
`INIT_VALIDATION`	Inicia el proceso de autenticación 3DS
`LAUNCH_VALIDATION`	Se lanza la pantalla de autenticación
`FAILED_VALIDATION`	La validación 3DS falló
`FINISH_VALIDATION`	Finalizó la validación (exitosa o no)

¿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

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

Campo	Tipo	Descripción	Valores posibles	Aplica a
`origin`	`string`	Fuente del mensaje.	`"KUSHKI"`	Ambos
`notificationType`	`string`	Tipo de notificación enviada.	`"FAILED_VALIDATION"` o `"FINISH_VALIDATION"`	Ambos
`success`	`boolean`	Indica si la validación 3DS fue exitosa.	`true` o `false`	Ambos
`message`	`string`	Mensaje de error asociado. Solo aparece en respuestas fallidas.	`"Error en la validación de 3DS"`	`FAILED_VALIDATION`
`token`	`string`	Identificador único de la transacción.	Ej: `"088...19b"`	Ambos
`callbackUrl`	`string`	URL a la que se debe redirigir o notificar el resultado de la validación.	Ej: `"https://tusitio.com/3ds-callback"`	Ambos

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:

Propiedad	Tipo	Descripción
`success`	booleano	Indica si el proceso de validación de 3DS se completó y si se puede proseguir con el cargo o la preautorización.
`token`	string	Token devuelto por Kushki para ser utilizado al momento de realizar un cargo en caso de que la autenticación 3D Secure haya sido exitosa.
`message`	String	Mensaje de error genérico.

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:

El challenge fue presentado al tarjetahabiente y este se autenticó de manera exitosa.

El proveedor de 3DS determinó que la tarjeta es confiable y no fue necesario presentar un challenge.

No fue posible presentar el challenge al tarjetahabiente. En este caso es probable que se rechace el charge o la preautorización.

El tarjetahabiente agotó el limite de 3 intentos permitidos para realizar la autenticación.

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

A tener en cuenta

Es posible que el cargo se rechace posteriormente, aún cuando el parámetro success tenga valor de true. Haz clic aquí para consultar el catálogo completo de códigos de rechazo de 3DS al realizar el cargo o la preautorización.

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:

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.

Activa 3D Secure de forma obligatoria en una transacción puntual

De forma predeterminada, Kushki decide si una transacción requiere autenticación 3D Secure según las reglas de riesgo configuradas para tu comercio. Si necesitas forzar la validación 3DS en una transacción específica, independientemente de esas reglas, envía el campo require3DS en la solicitud del token junto con authValidation y callbackUrl.

Parámetro	Tipo	Descripción
`require3DS`	boolean	Fuerza la autenticación 3D Secure en esta transacción. Debe enviarse junto con `authValidation` y `callbackUrl`.

Ejemplo de solicitud

{
  "card": {
    "name": "John Doe",
    "number": "4456528080389860",
    "expiryMonth": "02",
    "expiryYear": "32",
    "cvv": "200"
  },
  "totalAmount": 20,
  "currency": "USD",
  "require3DS": true,
  "authValidation": "url",
  "callbackUrl": "https://tucomercio.com/3ds/callback"
}

A tener en cuenta

Si envías require3DS sin incluir tanto authValidation como callbackUrl, la API devuelve el error K001.

Configura tus reglas de riesgo

require3DS solo afecta la transacción puntual donde lo envías. Para definir cuándo se solicita 3DS automáticamente en el resto de tus transacciones, coordina con el equipo de prevención de fraude de Kushki la configuración de tus reglas de riesgo.

Activa 3D Secure de forma obligatoria en una transacción puntual

Parámetro	Tipo	Descripción
`require3DS`	boolean	Fuerza la autenticación 3D Secure en esta transacción. Debe enviarse junto con `authValidation` y `callbackUrl`.

Ejemplo de solicitud

{
  "card": {
    "name": "John Doe",
    "number": "4456528080389860",
    "expiryMonth": "02",
    "expiryYear": "32",
    "cvv": "200"
  },
  "totalAmount": 20,
  "currency": "USD",
  "require3DS": true,
  "authValidation": "url",
  "callbackUrl": "https://tucomercio.com/3ds/callback"
}

A tener en cuenta

Si envías require3DS sin incluir tanto authValidation como callbackUrl, la API devuelve el error K001.

Configura tus reglas de riesgo

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

Códigos de error 3DS

Consulta los principales códigos de error cuando se rechazan transacciones debido a problemas con la autenticación 3DS.

Integración 100% API de 3DS

Transacciones soportadas con esta opción#

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

Opción 1: authValidation: "url"#

Opción 2: authValidation: "iframe"#

Eventos del iframe#

¿cómo capturar los eventos del iframe?#

Eventos antes de la validación 3DS#

INIT_VALIDATION#

LAUNCH_VALIDATION#

Eventos posteriores a la validación 3DS#

Respuesta en caso de validación fallida (FAILED_VALIDATION)#

Respuesta en caso de validación finalizada (FINISH_VALIDATION)#

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

Si success= true#

Si success= false#

Activa 3D Secure de forma obligatoria en una transacción puntual#

Ejemplo de solicitud#

Activa 3D Secure de forma obligatoria en una transacción puntual#

Ejemplo de solicitud#

Prueba tu integración#

Transacciones soportadas con esta opción

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

Opción 1: authValidation: "url"

Opción 2: authValidation: "iframe"

Eventos del iframe

¿cómo capturar los eventos del iframe?

Eventos antes de la validación 3DS

`INIT_VALIDATION`

`LAUNCH_VALIDATION`

Eventos posteriores a la validación 3DS

Respuesta en caso de validación fallida (`FAILED_VALIDATION`)

Respuesta en caso de validación finalizada (FINISH_VALIDATION)

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

Si `success`= `true`

Si `success`= `false`

Activa 3D Secure de forma obligatoria en una transacción puntual

Ejemplo de solicitud

Activa 3D Secure de forma obligatoria en una transacción puntual

Ejemplo de solicitud

Prueba tu integración