Guía de migración a Kushki.js 2.0
A continuación, los pasos y servicios que están disponibles en kushki.js para realizar la migración desde la versión 1.0 a la versión 2.0.Servicios disponibles para migrar#
Estos son los servicios actualmente disponibles en la versión 2.0 de la biblioteca Kushki.js. Más servicios se irán agregando con el tiempo.NOTA: Antes de realizar una migración de la versión de la biblioteca asegúrate que los servicios integrados estén disponibles para mantener las funcionalidades implementadas.
| SERVICIO | DISPONIBLE EN 2.0 | COMENTARIOS |
|---|
| Token pago único | ✅ | |
| Validación OTP pago único | ✅ | |
| Validación 3DS pago único | ✅ | |
| Validación Sift Science pago único | ? | |
| Diferidos pago único | ✅ | |
| Bin info pago único | ❌ | |
| Cargos recurrentes | ❌ | Aún no disponible cargos recurrentes en la versión 2.0 |
| Pagos ONE-CLICK | ❌ | No disponible método para esta operación |
| Web Pay (Chile) | ❌ | No disponible método para esta operación |
| Pagos con transferencia | ❌ | Aún no disponible pagos por transferencia |
| Pagos en efectivo | ❌ | Aún no disponible pagos en efectivo |
| Dispersiones en efectivo | ❌ | Aún no disponible dispersiones en efectivo |
| Gateway Status | ❌ | No disponible método para esta operación |
| Commissions | ❌ | No disponible método para esta operación |
| Validación de 3DS por API | ❌ | No disponible método para obtener el JWT |
| Cargos recurrentes por API | ❌ | No disponible método para obtener el JWT |
Migración token pago único#
Para migrar tu integración de la versión 1.0 a la 2.0 de Kushki.js, sigue los siguientes pasos para obtener el token para pago únicoPaso 1. Actualizar la fuente de importación de la biblioteca#
Actualiza la fuente desde donde importas la biblioteca de Kushki.js a tu aplicación.NOTA: No empaques o alojes tú mismo la biblioteca.
Si realizas la importación desde CDN, actualiza el script de importación deSi realizas la importación desde NPM, instala la versión 2.0 con el siguiente comando:Luego, actualiza la importación en tu aplicación de las funcionalidades dePaso 2. Inicialización de la biblioteca#
En la versión 2.0 cambia el objeto donde se inicializa la configuración del comercio así como sus atributos. A continuación los detalles entre versiones| KUSHKI.JS 1.0 | KUSHKI.JS 2.0 | COMENTARIOS |
|---|
| Kushki | KushkiOptions | El nombre del objeto a instanciar para la inicialización con la información del comercio ha cambiado de Kushki a KushkiOptions |
| merchantId | publicCredentialId | El nombre de la propiedad para colocar la llave pública del comercio ha cambiado de merchantId a publicCredentialId |
| inTestEnvironment | inTest | El nombre de la propiedad para especificar el ambiente de trabajo ha cambiado deinTestEnvironment a inTest |
| regional | No disponible | La propiedad regional ya no está disponible en Kushki.js 2.0 |
En tu aplicación, crea una instancia del objeto KushkiOptions la cuál reemplazará la instancia Kushki anterior.Kushki.js 1.0#
Kushki.js 2.0#
Debido a que Kushki.js 2.0 implementa campos de lado del servidor, es necesario realizar las siguientes modificaciones en el formulario de pago.Reemplazar los campos del formulario de tu aplicación por los siguientesRevisa todos los campos disponibles aquí.NOTA: Si utilizas estilos personalizados en tu formulario de pagos actual, revisa cómo darle estilos a los campos de lado del servidor.
Paso 4. Solicitud de token#
Para realizar la solicitud del token en Kushki.js 2.0, es necesario crear un objeto de CardOptions en donde se guardará la información de pago así como los datos de la transacción (monto, moneda, etc) en lugar de colocar estos datos directamente en el método requestToken() como en la versión 1.0. Después, es necesario crear una instancia de la tarjeta con el método initCardToken.NOTA: Si utilizas diferidos en Chile…
Kushki.js 1.0#
Se manda a llamar el método requestToken() de la instancia Kushki creada anteriormente con la información de la tarjeta y los datos de la transacción (monto, moneda, etc).Kushki.js 2.0#
Después, se manda a llamar el método requestToken() que está disponible en la instancia de tarjeta creada anteriormente.Respuesta#
La información devuelta en la respuesta en Kushki.js 2.0 ha cambiado. A continuación. podrás ver la información devuelta entre versiones:| KUSHKI.JS 1.0 | KUSHKI.JS 2.0 | COMENTARIOS |
|---|
| token | token | Token con información de la transacción |
| secureId | No disponible | Las validaciones OTP y 3DS ahora se hacen internamente en el método requestToken() |
| secureService | No disponible | Las validaciones OTP y 3DS ahora se hacen internamente en el método requestToken() |
| security | No disponible | Las validaciones OTP y 3DS ahora se hacen internamente en el método requestToken() |
| No disponible | deferred | Objeto con información de diferidos devuelto en Kushki.js 2.0 (Si están disponibles para el comercio) |
Paso 5. Certificación#
Una vez realizados los cambios en tu aplicación para migrar a Kushki.js 2.0, es necesario realizar una certificación para validar que todo funcione correctamente.Sigue los siguientes pasosValidación OTP pago único#
En Kushki.js 2.0 ya no es necesario que se realice la validación de OTP enviando información obtenida en el token. Ahora, esta validación se hace de manera automática al llamar al método requestToken() el cuál renderizará el modal para que el cliente ingrese el OTP. Puedes saber el estado de la validación de OTP con el método onOTPValidation(). Si tienes la validación OTP activada, sigue los siguientes pasos para realizar la migración hacía Kushki.js 2.0.NOTA: La implementación anterior que se encontraba en Kushki.js 1.0 del método requestSecureServiceValidation() ya no es necesaria en la versión 2.0, por lo cuál ahora solo debes consultar el estado de la validación.
Para implementar OTP en Kushki.js sigue estos pasos:Paso 1. Agrega el campo de lado del servidor para OTP#
Añade un <div> con el id id_otp en el formulario de pago para que el campo de OTP sea renderizado si es requerido.Paso 2. Identifica el estatus de OTP#
Para validar el estatus de OTP de la transacción y ver si este es requerido, puedes llamar al método onOTPValidation() el cuál regresará tres callbacks (onSuccess, onError, onRequired) indicando si el campo OTP es requerido, si se completó con éxito o si hubo algún error. Si se regresa el callback onRequired, entonces será necesario desplegar el campo para ingresar el OTP en el formulario de pago al momento de llamar al método requestToken() para solicitar un token.Paso 3. Enlazar el div de OTP en la instancia de CardOptions#
Si al momento de validar el status del OTP regresa un callback onRequired, será necesario enlazar el <div> del OTP al momento de crear una instancia de CardOptions. Para ello, en el objeto fields añade la propiedad otp como se muestra a continuaciónPaso 4. Certificación#
Una vez realizados los cambios en tu aplicación para migrar a Kushki.js 2.0, es necesario realizar una certificación para validar que todo funcione correctamente.Sigue los siguientes pasosValidación 3DS pago único#
Paso 1. Solicitud de token#
En Kushki.js 2.0 la validación 3DS se hace automáticamente al momento de llamar el método requestToken() el cuál desplegará el modal 3DS y realizará las validaciones necesarias devolviendo una respuesta exitosa en caso de ingresar un código válido o un mensaje de error si hubo algún problema durante la validación, por lo cual no es necesario realizar alguna otra acción adicional.NOTA: En Kushki.js 2.0 ya no se regresará información adicional sobre 3DS al momento de generar el token como se hacía en la versión 1.0 de Kushki.js (secureId, secureService, security)
Diferidos pago único#
Paso 1. Solicitud de token#
En Kushki.js 2.0 al momento de llamar al método requestToken() este regresará junto al token la información de diferidos disponibles al comercio (si aplica) como se muestra a continuación, por lo cual no es necesario realizar alguna otra acción adicionalNOTA: En Kushki.js 1.0 está disponible el método requestDeferred() el cuál ya no es necesario en la versión 2.0.
Modified at 2026-03-13 14:08:17
