Integración 100% API (opción 1)

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 3DS para preautorizaciones
- 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

  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.
ParámetroValores permitidos/tipo de datoDescripción
authValidationurlEnvía siempre url en este campo
callbackUrlstringEnvía la url a la que deberá retornarse el usuario cuando se complete la autenticación 3DS

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

ParámetroTipoDescripción
tokenstringEs el token que deberán usar para hacer el cargo, una vez finalice la validación de 3DS
urlURLEs la URL a la que deberás redirigir al usuario para la autenticación.
secureServiceStringTipo de autenticación, será 3dsecure en el caso de 3DS
secureIdStringEl secureId que se obtiene de la solicitud del token
  1. 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.
  1. 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:

PropiedadTipoDescripción
successbooleanoIndica si el proceso de validación de 3DS se completó y si se puede proseguir con el cargo o la preautorización.
tokenstringToken devuelto por Kushki para ser utilizado al momento de realizar un cargo en caso de que la autenticación 3D Secure haya sido exitosa.
messageStringMensaje 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 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).

Códigos de error 3DS

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