1. kushki.js-hosted-fields
Español
  • English
  • Español
  • Inicio
  • Integración con MCP
  • Libraries & SDKs (Online Payments)
    • Notas de versión
    • Mobile
      • Kushki Android
      • Kushki iOS 
      • Configuración ARM de Kushki iOS
    • Web
      • Kushki.js 🌐
      • kushki.js-hosted-fields
        • kushki.js Hosted Fields
        • Migrar a Kushki.js 2.0
        • Antifraud
          • Interfaces
            • SiftScienceObject
            • SecureInitRequest
            • SecureInitResponse
          • Methods
            • requestInitAntiFraud
            • requestSecureInit
            • requestValidate3DS
        • Card
          • CarApplePay interface
            • Interfaz ICardApplePay
          • Card-Interface
            • Interfaz ICard
            • Interfaz ICardSubscriptions
          • Errors
            • Lista de errores
          • Interfaces
            • MasterCardBrandingRequest
            • Interfaz ApplePayGetTokenOptions
            • Interfaz ApplePayOptions
            • ApplePayPaymentContact
            • AppleTokenResponse
            • CardFieldValues
            • CardOptions
            • DeviceTokenRequest
            • Fields
            • FormValidity
            • SecureDeviceTokenOptions
            • Styles
            • TokenResponse
            • Amount
            • Interfaz BrandByMerchantResponse
            • CardInfo
            • CardTokenResponse
            • DeferredByBinOptionsResponse
            • DeferredInputValues
            • DeferredValuesResponse
            • Field
            • FieldInstance
            • FieldValidity
            • VisaBrandingRequest
          • Methods
            • initApplePayButton
            • initCardToken
            • initSecureDeviceToken
            • Método requestBrandsByMerchant
            • Método requestDeviceToken
            • requestInitCardBrandingAnimation
          • Types
            • CssProperties
            • Moneda
            • FieldTypeEnum
        • Card Payouts
          • Card Payouts Interface
            • ICardPayouts
          • Enumerations
            • Enumeración `InputModelEnum`
          • Errors
            • Errores
          • Interfaces
            • CardPayoutOptions
            • CardPayoutSubscriptionTokenResponse
            • CardPayoutUniqueTokenResponse
            • Field
            • Fields
            • FieldValidity
            • Interfaz FormValidity
            • Interfaz `Styles`
          • Methods
            • initCardPayoutToken
          • Type Aliases
            • CardPayoutTokenResponse
            • InputTypeEnum
          • Types
            • CssProperties
        • Kushki
          • Methods
            • Función init
            • Función requestBankList
            • Función requestCommissionConfiguration
          • Classes
            • KushkiError
          • Interfaces
            • IKushki
            • KushkiOptions
            • CommissionConfigurationRequest
Home
Perú 🇵🇪México 🇲🇽Ecuador 🇪🇨Colombia 🇨🇴Chile 🇨🇱
Home
Perú 🇵🇪México 🇲🇽Ecuador 🇪🇨Colombia 🇨🇴Chile 🇨🇱
  1. kushki.js-hosted-fields

Migrar a Kushki.js 2.0

A continuación están los pasos y los servicios disponibles en kushki.js para migrar de la versión 1.0 a la versión 2.0.
Para más detalle, revisa la documentación de Kushki.js 1.0 y Kushki.js 2.0.

Servicios disponibles para migrar#

Estos son los servicios disponibles hoy en la versión 2.0 de la librería Kushki.js. Con el tiempo se irán agregando más servicios.
Nota
Antes de migrar la versión de la librería, asegúrate de que los servicios que tienes integrados estén disponibles para conservar la funcionalidad que ya implementaste.
SERVICIODISPONIBLE EN 2.0COMENTARIOS
Token de pago único✅
Validación OTP para pago único✅
Validación 3DS para pago único✅
Validación de Sift Science para pago único?
Opciones de diferido para pago único✅
Información de bin para pago único❌
Cargos recurrentes❌Los cargos recurrentes aún no están disponibles en la versión 2.0
Pagos ONE-CLICK❌No hay método disponible para esta operación
Web Pay (Chile)❌No hay método disponible para esta operación
Pagos con transferencia bancaria❌Los pagos con transferencia bancaria aún no están disponibles
Pagos en efectivo❌Los pagos en efectivo aún no están disponibles
Dispersiones en efectivo❌Las dispersiones en efectivo aún no están disponibles
Estado del gateway❌No hay método disponible para esta operación
Comisiones❌No hay método disponible para esta operación
Validación 3DS por API❌No hay método disponible para obtener el JWT
Cargos recurrentes por API❌No hay método disponible para obtener el JWT

Migrar el token de pago único#

Para migrar tu integración de Kushki.js 1.0 a 2.0, sigue estos pasos y obtén el token de pago único.

Paso 1. Actualiza la fuente de importación de la librería#

Actualiza la fuente desde la que importas la librería Kushki.js en tu aplicación.
Nota
No empaquetes ni alojes la librería por tu cuenta.
CDN
NPM
Si importas desde el CDN, actualiza el script de importación de
To

Paso 2. Inicialización de la librería#

En la versión 2.0 cambian tanto el objeto donde se inicializa la configuración del comercio como sus atributos. Estos son los detalles entre versiones:
KUSHKI.JS 1.0KUSHKI.JS 2.0COMENTARIOS
KushkiKushkiOptionsEl nombre del objeto que se instancia para inicializar con la información del comercio cambió de Kushki a KushkiOptions
merchantIdpublicCredentialIdEl nombre de la propiedad que guarda la llave pública del comercio cambió de merchantId a publicCredentialId
inTestEnvironmentinTestEl nombre de la propiedad que indica el ambiente de trabajo cambió de inTestEnvironment a inTest
regionalNo disponibleLa propiedad regional ya no está disponible en Kushki.js 2.0
En tu aplicación, crea una instancia del objeto KushkiOptions, que reemplaza a la instancia Kushki anterior.

Kushki.js 1.0#

Kushki.js 2.0#

Paso 3. Actualiza el formulario de pago#

Como Kushki.js 2.0 implementa hosted fields, debes hacer los siguientes cambios en tu formulario de pago.
Reemplaza los campos del formulario de tu aplicación por los siguientes:
Review all available fields here.
Nota
Si usas estilos personalizados en tu formulario de pago actual, revisa cómo dar estilo a los hosted fields.

Paso 4. Solicitud del token#

Para solicitar el token en Kushki.js 2.0, debes crear un objeto CardOptions que contendrá la información del pago y los datos de la transacción (monto, moneda, etc.), en vez de pasar estos datos directamente al método requestToken() como en la versión 1.0. Luego, debes crear una instancia de card con el método initCardToken.

Kushki.js 1.0#

El método requestToken() se llama sobre la instancia de Kushki creada antes, con la información de la tarjeta y los datos de la transacción (monto, moneda, etc.).

Kushki.js 2.0#

Luego, llama al método requestToken() disponible en la instancia de card creada antes.

Respuesta#

La información que devuelve la respuesta cambió en Kushki.js 2.0. Abajo puedes ver qué información se devuelve en cada versión:
KUSHKI.JS 1.0KUSHKI.JS 2.0COMENTARIOS
tokentokenToken con la información de la transacción
secureIdNo disponibleLas validaciones OTP y 3DS ahora se hacen internamente en el método requestToken()
secureServiceNo disponibleLas validaciones OTP y 3DS ahora se hacen internamente en el método requestToken()
securityNo disponibleLas validaciones OTP y 3DS ahora se hacen internamente en el método requestToken()
No disponibledeferredObjeto con la información de pago diferido que devuelve Kushki.js 2.0 (si está disponible para el comercio)

Paso 5. Certificación#

Cuando termines los cambios en tu aplicación para migrar a Kushki.js 2.0, debes completar una certificación que valide que todo funciona correctamente.

Validación OTP para pago único#

En Kushki.js 2.0 ya no necesitas hacer la validación OTP enviando la información que obtuviste del token. Esa validación ahora se hace automáticamente al llamar al método requestToken(), que renderiza el modal para que el cliente ingrese el OTP. Puedes revisar el estado de la validación OTP con el método onOTPValidation(). Si tienes habilitada la validación OTP, sigue estos pasos para migrar a Kushki.js 2.0.
Nota
La implementación anterior del método requestSecureServiceValidation() de Kushki.js 1.0 ya no se necesita en la versión 2.0, así que solo tienes que revisar el estado de la validación.
Para implementar OTP en Kushki.js, sigue estos pasos:

Paso 1. Agrega el hosted field para OTP#

Agrega un <div> con el id id_otp al formulario de pago para que el campo OTP se renderice cuando sea necesario.

Paso 2. Identifica el estado del OTP#

Para revisar el estado del OTP de la transacción y ver si es necesario, puedes llamar al método onOTPValidation(), que devuelve tres callbacks (onSuccess, onError, onRequired) que indican si el campo OTP es obligatorio, si se completó con éxito o si hubo un error. Si se devuelve el callback onRequired, tendrás que mostrar el campo para ingresar el OTP en el formulario de pago al llamar al método requestToken() para solicitar un token.

Paso 3. Vincula el div de OTP en la instancia de CardOptions#

Si al revisar el estado del OTP se devuelve un callback onRequired, tendrás que vincular el <div> del OTP al crear una instancia de CardOptions. Para hacerlo, agrega la propiedad otp al objeto fields como se muestra abajo:
Next, request a token.

Paso 4. Certificación#

Cuando termines los cambios en tu aplicación para migrar a Kushki.js 2.0, debes completar una certificación que valide que todo funciona correctamente.

Validación 3DS para pago único#

Paso 1. Solicitud del token#

En Kushki.js 2.0 la validación 3DS se hace automáticamente al llamar al método requestToken(), que muestra el modal 3DS y ejecuta las validaciones necesarias: devuelve una respuesta exitosa si se ingresa un código válido, o un mensaje de error si hubo un problema durante la validación. No necesitas hacer nada más.
Nota
En Kushki.js 2.0 ya no se devuelve la información adicional de 3DS (secureId, secureService, security) al generar el token, como sí pasaba en Kushki.js 1.0.

Opciones de diferido para pago único#

Paso 1. Solicitud del token#

En Kushki.js 2.0, cuando llamas al método requestToken() este devuelve, junto con el token, las opciones de diferido disponibles para el comercio (si aplica), como se ve abajo. No necesitas hacer nada más.
Nota
El método requestDeferred() de Kushki.js 1.0 ya no se necesita en la versión 2.0.
Modified at 2026-09-11 14:38:07
Previous
kushki.js Hosted Fields
Next
SiftScienceObject
Built with