Integración 100% API de 3DS

08 enero 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.

A continuación un ejemplo de la solicitud del token incluyendo estos campos

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

Función callbackUrl

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

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