kushki.js Hosted Fields

La nueva versión de nuestra biblioteca de Javascript es mucho más ligera, segura, personalizable y fácil de implementar. Con Kushki.js Hosted Fields, crea un flujo de pago de forma sencilla implementando los campos alojados en los servidores de Kushki, lo que le da al comercio el control del diseño del formulario de pago, mayor seguridad y facilidad de implementación con métodos optimizados dentro de la biblioteca.

A continuación puedes ver las diferencias entre cada versión:

Característica	Kushki.js	Kushki.js Hosted Fields	Detalles
Tamaño	~2.7 MB	~307* KB
Modularidad	No	Sí
Importación vía CDN	Sí	Sí
Importación vía NPM	Sí	Sí
Importación vía YARN	No	Sí
Configuración de la biblioteca	instancia del objeto `Kushki()`	instancia del objeto `KushkiOptions()`
Token para pago único	`requestToken()`	`requestToken()`	En Kushki.js Hosted Fields debes crear un objeto de tipo `CardOptions()`, que contendrá la información del monto, el tipo de moneda y otros datos de la transacción.
Propiedad amount en el token para pago único	String. Monto sin desglose	Object. Permite desglosar el monto de la compra en iva, ice, subtotaliva y subtotaliva0.	Monto de la transacción.
Propiedad months en el token para pago único	Integer	No disponible	En Kushki.js Hosted Fields, los diferidos ahora se devuelven en el token (si están disponibles para el comercio).
Propiedad currency en el token para pago único	String	String	Monedas disponibles por país.
Objeto card dentro del token para pago único	Object. Información de la tarjeta como nombre del tarjetahabiente, número de tarjeta, cvc, etc.)	No disponible	En Kushki.js Hosted Fields, el comercio ya no necesita manipular datos sensibles de la tarjeta.
Propiedad callback en el token para pago único	Function	No disponible
Objeto fields dentro del token para pago único	No disponible	Mediante la instancia del objeto `CardOptions`	El objeto fields permite relacionar las etiquetas div de html con los ids correspondientes de los hosted fields que se van a renderizar.
Propiedad isSubscription en el token para pago único	No disponible	Boolean. Permite indicar si el token generado es para una suscripción o no	En Kushki.js Hosted Fields, la propiedad `isSubscription` reemplaza la implementación del método `requestSubscriptionToken()`.
Propiedad preventAutofill en el token para pago único	No disponible	Boolean. Permite evitar que los hosted fields se llenen automáticamente.
Propiedad styles en el token para pago único	No disponible	Object. Permite modificar los estilos de los hosted fields.	En Kushki.js Hosted Fields, la biblioteca permite un mayor control de los estilos en los campos.
Validación mediante OTP para pago único	método `requestSecureServiceValidation()`	Validación automática (si aplica) en el método `requestToken()`.
Obtención del JWT para la validación 3D Secure en pago único	método `requestSecureInit()`	Validación automática (si aplica) en el método `requestToken()`.
Validación mediante 3D Secure para pago único	método `requestValidate3DS()`	Validación automática (si aplica) en el método `requestToken()`.
Diferido para pago único	método `requestDeferred()`	Se devuelve automáticamente al consumir el método `requestToken()` (si está disponible para el comercio).
Información del bin para pago único	método `requestBinInfo()`	No disponible	En Kushki.js Hosted Fields no es necesario obtener el bin, porque las validaciones se hacen automáticamente en el método `requestToken()`.
Token de suscripción	`requestSubscriptionToken()`	Al llamar al método `requestToken()` puedes enviar la propiedad `isSubscription` como `true` para indicar que el token será de una suscripción.
Propiedad currency en el token para suscripción	String	String	Monedas disponibles por país.
Objeto card del token para suscripción	Object. Información de la tarjeta como nombre del tarjetahabiente, número de tarjeta, cvc, etc.)	No disponible	En Kushki.js Hosted Fields, el comercio ya no necesita manipular datos sensibles de la tarjeta.
Propiedad callback en el token para suscripción	Function	No disponible
Objeto fields del token para suscripción	No disponible	Mediante la instancia del objeto `CardOptions`	El objeto fields permite relacionar las etiquetas div de html con los ids correspondientes de los hosted fields que se van a renderizar.
Propiedad isSubscription en el token para suscripción	No disponible	Boolean. Permite indicar si el token generado es para una suscripción o no	En Kushki.js Hosted Fields, la propiedad `isSubscription` reemplaza la implementación del método `requestSubscriptionToken()`.
Propiedad preventAutofill en el token para suscripción	No disponible	Boolean. Permite evitar que los hosted fields se llenen automáticamente.
Propiedad styles en el token para suscripción	No disponible	Object. Permite modificar los estilos de los hosted fields	En Kushki.js Hosted Fields, la biblioteca permite un mayor control de los estilos en los campos.
Validación OTP para suscripción	No disponible	Validación automática (si aplica) en el método `requestToken()`
Obtención del JWT para la validación 3D Secure en suscripción	método `requestSecureInit()`	Validación automática (si aplica) en el método `requestToken()`
Validación mediante 3D Secure para suscripción	método `requestValidate3DS()`	Validación automática (si aplica) en el método `requestToken()`
Obtención del device token para pagos One-click	`requestDeviceToken()`	`requestDeviceToken()`
Card Async	Sí	No disponible
Transfer In	Sí	No disponible
Cash In	Sí	No disponible
Payouts	Sí (transfer, cash)	Solo para card payouts

* Tamaño estimado de las bibliotecas card.min.js y kushki.min.js.

Nota

Con el tiempo se irán agregando nuevos servicios y funcionalidades.

Kushki ofrece un SDK web para facilitar la recolección segura de los datos de la tarjeta sin manipular información sensible, mediante hosted fields en los servidores de Kushki. Este SDK permite obtener el token desde el frontend para luego enviarlo al backend y continuar con el flujo de pago.

Importing Kushki.js Hosted Fields

Incluye el script de Kushki.js Hosted Fields en tu aplicación directamente desde las siguientes opciones de instalación; no lo empaquetes ni lo alojes por tu cuenta.

CDN

NPM

YARN

Importa la biblioteca de Kushki.js Hosted Fields en tu aplicación mediante una etiqueta <script>. Una vez importada, podrás acceder a los recursos que se describen a continuación para crear un flujo de pago con Kushki.

Es necesario importar las bibliotecas kushki.min.js (que trae el código necesario para almacenar las credenciales de tu comercio) y card.min.js (el módulo que trae las funcionalidades necesarias para el flujo con pagos con tarjeta).

Inicializar Kushki.js Hosted Fields

Para usar la biblioteca de Kushki.js, primero es necesario crear una instancia de tipo KushkiOptions, que te permite declarar la clave pública de tu comercio y seleccionar el ambiente (prueba o producción) mediante el método init().

La clave pública se obtiene al crear una cuenta y es necesaria al llamar a este método, ya que se genera una instancia que permite identificar a tu comercio ante Kushki.

Nota

Cuando tu comercio esté listo para aceptar pagos reales, es importante que reemplaces la clave de prueba por la clave de producción.

TypeScript

JavaScript

Parámetros de configuración

Propiedad	Tipo	Requerido	Descripción	Por defecto	Valores permitidos
publicCredentialId	`string`	Sí	ID público creado para tu comercio.
inTest	`boolean`	No	Permite indicar el ambiente de trabajo entre prueba o producción.	`false`	`true`, `false`

Inicialización del formulario

Los siguientes pasos describen cómo puedes inicializar una instancia de token de tarjeta.

Paso 1. Define los contenedores para los hosted fields

Antes de llamar al método initCardToken(), es necesario incluir los elementos <div> requeridos para renderizar cada hosted field.

Propiedad	Requerido	Descripción
cardholderName_id	Sí	Hosted field para el nombre del tarjetahabiente.
cardNumber_id	Sí	Hosted field para el número de tarjeta.
cvv_id	Sí	Hosted field para el CVV.
expirationDate_id	Sí	Hosted field para la fecha de expiración.
deferred_id	No	Hosted field para pagos diferidos.
otp_id	No	Hosted field para la validación OTP.

Para un token de pago único, los campos requeridos son:

cardholderName

cardNumber

expirationDate

cvv

Para un token de suscripción, los campos requeridos son:

cardholderName

cardNumber

expirationDate

Paso 2. Crea una instancia de CardOptions

Crea una instancia de CardOptions con la información de la transacción, como el monto, la moneda y otros parámetros.

TypeScript

JavaScript

Parámetros de CardOptions

Propiedad	Tipo	Requerido	Descripción	Valores permitidos
amount	`object`	Sí (para pagos únicos)	Objeto con la información detallada del monto de la transacción.
currency	`string`	Sí	Monedas disponibles por país: MX 🇲🇽: `MXN` · CO 🇨🇴: `COP` · CL 🇨🇱: `CLP`, `UF` · PE 🇵🇪: `PEN`, `USD` · EC 🇪🇨: `USD`
fields	`object`	Sí	Objeto para enlazar los contenedores de tu sitio web con los hosted fields.
fields.cardNumber.selector	`string`	Sí	Se enlaza con el contenedor `cardNumber_id` y renderiza el campo del número de tarjeta.
fields.cardholderName.selector	`string`	Sí	Se enlaza con el contenedor `cardholderName_id` y renderiza el campo del nombre del tarjetahabiente.
fields.cvv.selector	`string`	Sí	Se enlaza con el contenedor `cvv_id` y renderiza el campo del CVV. Puedes omitir el CVV.
fields.cvv.isRequired	`boolean`	No	Configura si el ingreso del CVV es obligatorio o no. Aplica solo a suscripciones.
fields.deferred	`string`	No	Se enlaza con el contenedor `deferred_id` y renderiza el campo de pagos diferidos (si aplica).
fields.expirationDate	`string`	Sí	Se enlaza con el contenedor `expirationDate_id` y renderiza el campo de la fecha de expiración.
fields.otp.selector	`string`	No	Se enlaza con el contenedor `otp_id` y renderiza el campo del OTP (si aplica).
isSubscription	`boolean`	No	Permite identificar si es una suscripción o no. Ponlo en `true` para generar un token de pago programado o de pago One-click.	`true`, `false`
preventAutofill	`boolean`	No	Permite evitar el autocompletado de los hosted fields.	`true`, `false`
styles	`object`	No	Objeto para declarar estilos personalizados para los hosted fields.
styles.cardNumber	CssProperties	No	Estilos del campo del número de tarjeta.
styles.cardholderName	CssProperties	No	Estilos del campo del nombre del tarjetahabiente.
styles.container	CssProperties	No	Estilos del contenedor del input.
styles.cvv	CssProperties	No	Estilos del campo del CVV.
styles.deferred	CssProperties	No	Estilos del campo de pagos diferidos.
styles.expirationDate	CssProperties	No	Estilos del campo de la fecha de expiración.
styles.focus	CssProperties	No	Estilos que se aplican cuando el campo tiene el foco.
styles.input	CssProperties	No	Estilos del elemento input.
styles.invalid	CssProperties	No	Estilos que se aplican cuando un campo es inválido.
styles.label	CssProperties	No	Estilos de la etiqueta del input.
styles.otp	CssProperties	No	Estilos del campo del OTP.
styles.valid	CssProperties	No	Estilos que se aplican cuando un campo es válido.
fullResponse	`boolean`	No	Devuelve información adicional de la tarjeta al generar un token de suscripción.

Paso 3. Renderiza los hosted fields con el método initCardToken()

Después de crear una instancia de CardOptions, llama a la función initCardToken() para inicializar una instancia de ICard. Esta función recibe como parámetros la instancia de Kushki de la sección Inicializar Kushki.js Hosted Fields y la instancia de CardOptions del Paso 2. Devuelve una promesa de ICard.

TypeScript

JavaScript

Parámetros

Propiedad	Tipo	Requerido	Descripción
kushkiInstance	IKushki	Sí	Instancia con la clave pública del comercio y el ambiente de trabajo.
options	CardOptions	Sí	Debe definir la configuración de los campos de tarjeta (monto, moneda, estado de suscripción, prevención de autocompletado, estilos CSS personalizados, campos).

Errores

Estos son los posibles errores que puede devolver la función initCardToken():

Código	Mensaje	Ejemplo	Descripción
E012	Error en inicialización de campos	`{ code: "E012", message: "Error en inicialización de campos" }`	Returned if `options` or `kushkiInstance` are null or undefined.
E013	El Id del contenedor de un input no fue encontrado	`{ code: "E013", message: "El Id del contenedor de un input no fue encontrado" }`	Returned if any field references a selector that does not exist in the DOM.

Tokenización

Solicita un token de pago con tarjeta que podrás usar después para cobrarle a un cliente con el endpoint de pago único, crear un cargo recurrente o hacer un pago One-click.

requestToken()

Para obtener un token de pago con tarjeta, llama al método requestToken() en la instancia de card inicializada previamente. Este método también valida todos los campos; de lo contrario, arroja una excepción.

Este método devuelve un objeto TokenResponse que debes enviar a tu backend para continuar con el flujo de pago.

Nota

Revisa la sección Suscripciones para solicitar un token de suscripción.

Si tu comercio tiene habilitadas reglas de validación de OTP, 3D Secure o Sift Science, este método ejecuta automáticamente las validaciones de cada regla y renderiza los modales correspondientes.

Ejemplo de respuesta del token:

{
  "token": "a2b74b7e3cf24e368a20380f16844d16"
}

Pagos diferidos

Si tu comercio tiene habilitada la opción de pagos diferidos, el método requestToken() devuelve datos adicionales según el país de tu comercio:

México y Ecuador

Además del token, el método devuelve los siguientes campos dentro del objeto deferred:

creditType: Tipo de transacción.

graceMonths: Meses de gracia.

months: Meses para diferir la transacción.

Valores de creditType disponibles por país:

Ecuador 🇪🇨

Cuota fija con intereses.

Meses de gracia con intereses.

Pago mes a mes con intereses.

Cuota fija sin intereses.

Meses de gracia sin intereses.

Pago mes a mes sin intereses.

Especial sin intereses.

Promoción Supermaxi.

México 🇲🇽

"03" = Meses sin intereses.

Para los meses sin intereses en México, aplica un monto mínimo según el plan de diferido:

3 meses: $300 MXN

6 meses: $600 MXN

9 meses: $900 MXN

12 meses: $1,200 MXN

18 meses: $1,800 MXN

Ejemplo de respuesta con el objeto deferred para México y Ecuador:

{
  "token": "a2b74b7e3cf24e368a20380f16844d16",
  "deferred": {
    "creditType": "03",
    "graceMonths": 2,
    "months": 12
  }
}

Chile, Colombia y Perú

Además del token, el método devuelve un objeto deferred. La estructura depende del modelo de integración configurado para el comercio:

{
  "token": "a2b74b7e3cf24e368a20380f16844d16",
  "deferred": {
    "months": 12
  }
}

Chile: Cuotas Comercio (Merchant Installments)

🚀 Funcionalidad en Beta

La funcionalidad Merchant Installments (Cuotas Comercio) está actualmente en Beta. Esta estructura de respuesta aplica solo cuando el pagador selecciona una opción de Cuotas Comercio disponible para la configuración de tu comercio.

Cuando se selecciona una Cuota Comercio, el objeto deferred incluye parámetros adicionales:

creditType: Devuelve "03" (valor fijo para Cuotas Comercio).

graceMonths: Devuelve 0 (valor fijo).

months: El número de meses que seleccionó el pagador.

Ejemplo de respuesta:

{
  "token": "a2b74b7e3cf24e368a20380f16844d16",
  "deferred": {
    "creditType": "03",
    "graceMonths": 0,
    "months": 6
  }
}

Respuesta

Propiedad	Tipo	Descripción
`token`	`String`	Token para hacer un cargo.
`deferred`	`Object`	Opcional. Se devuelve si el BIN y el comercio tienen diferidos habilitados.
`deferred.creditType`	`String`	Opcional. Tipo de crédito solicitado. Para Chile Cuotas comercio será `03`.
`deferred.graceMonths`	`String`	Opcional. Meses de gracia. Ecuador: comportamiento estándar. Chile Cuotas comercio: se devuelve solo para el modelo de adquirencia Kushki con un valor fijo de `0`. Más información en el endpoint Hacer un cargo o cargo diferido.
`deferred.months`	`Integer`	Opcional. Número de cuotas.

Errores

Esta es la lista de errores que el método requestToken() puede devolver como un objeto KushkiError:

Código	Mensaje	Ejemplo	Descripción
E002	Error en solicitud de token	`{ code: "E002", message: "Error en solicitud de token" }`	Error al solicitar un token. Valida que la información requerida se haya enviado correctamente.
E003	Error en solicitud de datos del comercio	`{ code: "E003", message: "Error en solicitud de datos del comercio" }`	Error al solicitar la información del comercio. Inténtalo de nuevo; si el error persiste, contacta al soporte de Kushki.
E004	Error en solicitud de JWT	`{ code: "E004", message: "Error en solicitud de JWT" }`	Error en la solicitud del JWT de 3D Secure. Inténtalo de nuevo; si el error persiste, contacta al soporte de Kushki.
E005	Campos 3DS inválidos	`{ code: "E005", message: "Campos 3DS inválidos" }`	Error de autenticación 3D Secure. Verifica los datos ingresados para la validación 3D Secure.
E006	Error en solicitud de validación de token	`{ code: "E006", message: "Error en solicitud de validación de token" }`	Error en la sesión de validación de 3D Secure. Inténtalo de nuevo; si el error persiste, contacta al soporte de Kushki.
E007	Error en la validación del formulario	`{ code: "E007", message: "Error en la validación del formulario" }`	Uno o más hosted fields son inválidos. Verifica los datos ingresados.
E008	Error en la validación de OTP	`{ code: "E008", message: "Error en la validación de OTP" }`	La validación OTP falló. Inténtalo de nuevo con el OTP correcto.

Ejemplos

Cargo único o suscripción sin pagos diferidos

TypeScript

JavaScript

Cargo único con pagos diferidos

Suscripción con fullResponse en true

Seguridad

OTP

Una contraseña de un solo uso (OTP) se usa cuando es necesario validar la identidad del tarjetahabiente, confirmando que quien realiza la transacción es el dueño de la tarjeta. Esto ayuda a reducir el fraude y mejora la seguridad de las transacciones en línea de tu comercio.

Considera usar OTP cuando tu comercio tenga un volumen considerable de fraude o para transacciones especialmente sensibles o de montos altos. Ten en cuenta que esto puede bajar la tasa de conversión, porque agrega pasos adicionales al proceso de pago.

Puedes configurar para qué tipos de transacciones se pedirá la validación OTP, por ejemplo cuando el monto de la transacción supere cierto umbral.

Nota

Esta funcionalidad está disponible solo para integraciones web en pagos únicos con tarjeta.

Importante

Ten en cuenta que, por nuestras políticas de riesgo, los métodos de pago disponibles y el tipo de integración pueden variar al formalizar la afiliación. Te guiaremos sobre cómo proceder si este proceso aplica a tu comercio.

Para más información sobre OTP, visita nuestra página aceptar pagos únicos con OTP.

onOTPValidation()

Si necesitas validar el flujo de OTP, puedes usar el método onOTPValidation() en la instancia de card creada previamente. Se dispara cuando se ingresa un valor en el campo del OTP. Este método devuelve tres callbacks (onSuccess, onError y onRequired) que te permiten identificar el estado de la validación OTP.

Nota

El usuario tendrá 3 intentos para ingresar un OTP válido.

Esta validación solo se ejecuta si el comercio tiene configurada la regla de seguridad asociada a OTP.

La validación OTP se activa cuando se ingresa el tercer dígito en el hosted field. Cada evento de validación se activará y puedes capturar estos eventos con los callbacks onError u onSuccess.

Parámetros

onRequired (() => void): Se ejecuta cuando el token creado requiere validación OTP.

onError ((error) => void): Se ejecuta cuando la validación OTP devuelve un error.

onSuccess (() => void): Se ejecuta cuando la validación OTP es exitosa.

Errores

Código	Mensaje	Ejemplo	Descripción
E008	Error en la validación de OTP	`{ code: "E008", message: "Error en la validación de OTP" }`	OTP validation failed. Please try again with the correct OTP.

Ejemplo

3D Secure

Por defecto, la autenticación 3D Secure se realiza automáticamente al generar un token y, si es necesario, se muestra un modal para que el tarjetahabiente complete los desafíos requeridos. La autenticación se ejecuta según las reglas de seguridad establecidas en la configuración de tu comercio.

Opcional: autenticación 3D Secure manual

Nota

El flujo de autenticación 3DS manual es opcional y aplica solo a estos dos escenarios específicos:

Cuando obtienes el token desde tu backend con el método Crear un token de tarjeta.

Para hacer la validación 3DS de suscripciones al momento de tokenizar la tarjeta para cargos futuros.

Para estos casos específicos, puedes hacer la autenticación 3D Secure manual con el método requestSecureInit(). Este método te permite obtener un JSON Web Token (JWT), que es necesario para obtener un token de tarjeta. Después, llama al método requestValidate3DS(), que mostrará un modal para que el tarjetahabiente complete los desafíos solicitados.

A continuación, los pasos para hacer la autenticación 3D Secure manual.

requestSecureInit()

Consume el método requestSecureInit() enviando el número de tarjeta para obtener un JWT.

Propiedad	Tipo	Requerido	Descripción
kushkiInstance	IKushki	Sí	Objeto con el id público del comercio y el ambiente de trabajo.
secureInitRequest	SecureInitRequest	Sí	Objeto para solicitar la inicialización de 3D Secure.

Errores

Esta es la lista de errores que el método requestSecureInit() puede devolver como un objeto KushkiError:

Código	Mensaje	Ejemplo	Descripción
E004	Error en solicitud de JWT	`{ code: "E004", message: "Error en solicitud de JWT" }`	Error al solicitar el JWT de 3D Secure. Inténtalo de nuevo; si el error persiste, contacta al soporte de Kushki.
E018	Longitud de tarjeta inválida	`{ code: "E018", message: "Longitud de tarjeta inválida" }`	Verifica que la longitud de la tarjeta sea correcta.
E019	Comercio no tiene activo 3DS	`{ code: "E019", message: "Comercio no tiene activo 3DS" }`	El comercio no tiene habilitada la autenticación 3D Secure.

Si la solicitud fue exitosa, recibirás el JWT:

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Una vez obtenido el JWT, consume el endpoint para solicitar un token de tarjeta enviando el JWT en el cuerpo de la solicitud:

{
  "card": {
    "name": "John Doe",
    "number": "4000000000000002",
    "expiryMonth": "01",
    "expiryYear": "28",
    "cvv": "123"
  },
  "totalAmount": 59,
  "currency": "USD",
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Nota

Si la propiedad authRequired dentro del objeto security (security.authRequired) devuelve true, debes consumir el método requestValidate3DS() para mostrar el modal de autenticación.

Si la solicitud fue correcta, recibirás el token junto con las propiedades de validación de 3D Secure:

{
  "token": "g9m2XG100000uut73n085881SMOP3bP1",
  "secureService": "3dsecure",
  "secureId": "61efd064-b9df-4c0c-81fb-5b39a5d0cf9f",
  "security": {
    "acsURL": "https://merchantacsstag.cardinalcommerce.com/MerchantACSWeb/pareq.jsp?...",
    "authenticationTransactionId": "uvvZn0ND0ukTOJIfhfi0",
    "authRequired": true,
    "paReq": "eNpVUstuwjAQ...",
    "specificationVersion": "2.2.0"
  }
}

Más información en la definición del método requestSecureInit.

requestValidate3DS()

Consume el método requestValidate3DS() cuando la transacción necesite autenticación 3D Secure. Este método recibe el objeto que se obtiene al solicitar un token de tarjeta.

Propiedad	Tipo	Requerido	Descripción
kushkiInstance	IKushki	Sí	Objeto con el id público del comercio y el ambiente de trabajo.
cardTokenResponse	CardTokenResponse	Sí	El objeto de respuesta del proceso de tokenización de tarjeta con la API.

Errores

Esta es la lista de errores que el método requestValidate3DS() puede devolver como un objeto KushkiError:

Código	Mensaje	Ejemplo	Descripción
E005	Campos 3DS inválidos	`{ code: "E005", message: "Campos 3DS inválidos" }`	3D Secure authentication error. Verify the data entered.
E006	Error en solicitud de validación de token	`{ code: "E006", message: "Error en solicitud de validación de token" }`	3D Secure validation session error. Please try again; if the error persists, contact Kushki support.

Si la autenticación fue correcta, se devolverá el token generado previamente:

{
  "token": "g9m2XG100000uut73n085881SMOP3bP1"
}

Si hubo un problema durante la autenticación:

{
  "code": "E012",
  "message": "Error en inicialización de campos"
}

Si la autenticación fue exitosa, continúa con el flujo de pago consumiendo el endpoint para hacer un cargo. De lo contrario, reinicia el flujo de pago llamando de nuevo a requestSecureInit().

Más información en la definición del método requestValidate3DS.

Sift

Protege la integridad de tus transacciones en línea y resguarda la confianza de tus clientes con Sift, la herramienta de detección de fraude con inteligencia artificial. Con Sift podrás detectar y prevenir actividades fraudulentas en tiempo real, reduciendo pérdidas financieras y protegiendo tu reputación, para asegurar a tus clientes una experiencia de compra segura y sin fricción.

Por defecto, la autenticación de Sift se realiza automáticamente al generar un token según las reglas de seguridad establecidas en la configuración de tu comercio.

También puedes hacer la autenticación manual de Sift con el método requestInitAntiFraud(), que te permite obtener un JSON Web Token (JWT) necesario para obtener un token de tarjeta.

requestInitAntiFraud()

Llama al método requestInitAntiFraud() enviando una instancia de Kushki con la configuración de tu comercio y el ID del cliente.

Propiedad	Tipo	Requerido	Descripción
kushkiInstance	IKushki	Sí	Objeto con el id público del comercio y el ambiente de trabajo.
userId	`String`	Sí	ID del cliente. Puede ser un email, un número de teléfono, una dirección o estar vacío.

Errores

Esta es la lista de errores que el método requestInitAntiFraud() puede devolver como un objeto KushkiError:

Código	Mensaje	Ejemplo	Descripción
E003	Error en solicitud de datos del comercio	`{ code: "E003", message: "Error en solicitud de datos del comercio" }`	Error requesting merchant information. Please try again; if the error persists, contact Kushki support.
E023	Error al configurar sesión de Sift	`{ code: "E023", message: "Error al configurar sesión de Sift" }`	Sift configuration error. Please check your Sift settings and try again.

Más información en la definición del método requestInitAntiFraud.

Suscripciones

Puedes generar un token de suscripción para ejecutar un cargo recurrente o un pago One-click.

Para generar un token de suscripción, pon la propiedad isSubscription en true al crear una instancia de CardOptions.

TypeScript

JavaScript

Next, request a card token.

Omitir el CVV

Puedes omitir, marcar como requerido o marcar como opcional el campo del CVV durante la creación de un token de suscripción.

Importante

Disponible solo en Colombia para el modelo agregador. Antes de omitir el CVV o hacer opcional su ingreso, valida la funcionalidad con tu ejecutivo de cuenta.

Para que el ingreso del CVV sea opcional, envía isRequired: false dentro de la configuración del campo del CVV:

Para omitir por completo el campo del CVV, no incluyas la configuración de cvv en el objeto fields:

Luego, sigue los siguientes pasos para obtener un token.

Cargo recurrente

Después de solicitar un token de suscripción, llama al endpoint Crear un cargo recurrente con la información requerida.

Nota

Recuerda definir la frecuencia con la que se ejecutará el cargo automático.

Si la información enviada es válida, la suscripción se creará y se ejecutará según la periodicidad establecida.

Pagos One-click

Kushki te permite hacer pagos One-click almacenando la información de la tarjeta de forma segura para después cobrar bajo demanda.

Para hacer un pago One-click, primero crea una suscripción enviando la propiedad periodicity con el valor custom para obtener un subscriptionId.

Luego, llama a uno de los siguientes métodos según si necesitas validar el CVV al ejecutar un cargo bajo demanda.

requestDeviceToken()

Se requiere un subscriptionId. Debe haberse creado previamente con la API de cargos recurrentes usando un token obtenido de requestToken con isSubscription en true.

Nota

Este método se usa directamente, sin validar el CVV en un hosted field.

Más información en la definición del método requestDeviceToken.

Ejemplo

Errores

Esta es la lista de errores que el método requestDeviceToken() puede devolver como un objeto KushkiError:

Código	Mensaje	Ejemplo	Descripción
E003	Error en solicitud de datos del comercio	`{ code: "E003", message: "Error en solicitud de datos del comercio" }`	Error al solicitar la información del comercio. Inténtalo de nuevo; si el error persiste, contacta al soporte de Kushki.
E004	Error en solicitud de JWT	`{ code: "E004", message: "Error en solicitud de JWT" }`	Error del JWT de 3D Secure. Inténtalo de nuevo; si el error persiste, contacta al soporte de Kushki.
E005	Campos 3DS inválidos	`{ code: "E005", message: "Campos 3DS inválidos" }`	Error de autenticación 3D Secure. Verifica los datos ingresados.
E006	Error en solicitud de validación de token	`{ code: "E006", message: "Error en solicitud de validación de token" }`	Error en la sesión de validación de 3D Secure. Inténtalo de nuevo; si el error persiste, contacta al soporte de Kushki.
E016	Error en solicitud de UserId para suscripción	`{ code: "E016", message: "Error en solicitud de UserId para subscripción" }`	El comercio tiene Sift Science configurado y no se encontró el `subscriptionId` o la solicitud falló.
E020	Error en solicitud de datos del comercio	`{ code: "E020", message: "Error, configuración de campos requeridos no encontrada" }`	El cuerpo `DeviceTokenRequest` no está definido.

Después de obtener el token, llama al endpoint hacer un pago One-click desde tu backend.

Secure DeviceToken

Si necesitas validar el CVV al hacer un pago One-click, usa el método Secure DeviceToken. Este método usa un hosted field para validar el CVV de la tarjeta.

Nota

Puedes omitir el ingreso del CVV al obtener un token y pedirlo al momento de cobrar bajo demanda. Más información en la referencia de CardOptions.

Si tu comercio tiene habilitadas reglas de validación de 3D Secure o Sift Science, este método ejecuta automáticamente las validaciones de cada regla.

Paso 1 — Define el contenedor del CVV:

Paso 2 — Crea una instancia de SecureDeviceTokenOptions:

Propiedad	Tipo	Requerido	Descripción	Valores permitidos
fields.cvv.selector	`string`	Sí	Se enlaza con el contenedor `cvv_id` y renderiza el campo del CVV.
preventAutofill	`boolean`	No	Permite evitar el autocompletado de los hosted fields.	`true`, `false`
styles	Styles	No	Objeto para declarar estilos personalizados para los hosted fields.

Paso 3 — Llama a initSecureDeviceToken():

Llama al método initSecureDeviceToken(), que renderiza el hosted field del CVV e inicializa una instancia de ICardSubscriptions.

Propiedad	Tipo	Requerido	Descripción
kushkiInstance	IKushki	Sí	Objeto con el id público del comercio y el ambiente de trabajo.
options	SecureDeviceTokenOptions	Sí	Objeto para obtener el device token del pago One-click.

Errores de initSecureDeviceToken()

Código	Mensaje	Ejemplo	Descripción
E012	Error en inicialización de campos	`{ code: "E012", message: "Error en inicialización de campos" }`	`options` or `kushkiInstance` are null or undefined.
E013	El Id del contenedor de un input no fue encontrado	`{ code: "E013", message: "El Id del contenedor de un input no fue encontrado" }`	A field references a non-existing selector.

Paso 4 — Llama a requestDeviceToken():

Respuesta

Propiedad	Tipo	Descripción
token	`String`	Token para hacer un cargo.
cardInfo	`Object`	Opcional. Se devuelve si `fullResponse` es `true` al instanciar CardOptions.
cardInfo.bin	`String`	Opcional. El BIN de la tarjeta (8 dígitos).
cardInfo.brand	`String`	Opcional. La marca de la tarjeta.
cardInfo.expirationDate	`String`	Opcional. La fecha de expiración de la tarjeta.
cardInfo.lastFourDigits	`String`	Opcional. Los últimos cuatro dígitos de la tarjeta.

Example response:

{
  "token": "a2b74b7e3cf24e368a20380f16844d16"
}

Example response with cardInfo:

{
  "token": "a2b74b7e3cf24e368a20380f16844d16",
  "cardInfo": {
    "bin": "42424242",
    "brand": "visa",
    "expirationDate": "11/27",
    "lastFourDigits": "4242"
  }
}

Card Payouts

El proceso de Card Payouts te permite capturar de forma segura los datos del tarjetahabiente y de la tarjeta para generar un token de pago único. Este token se puede usar para:

Payouts únicos: Envía dinero a una tarjeta una sola vez con un token de pago de un solo uso.

Payouts recurrentes: Obtén un token de suscripción para enviar dinero varias veces a la misma tarjeta tokenizada.

Inicialización del formulario

Define los contenedores para los hosted fields requeridos:

Luego, define un objeto CardPayoutOptions y llama al método initCardPayoutToken. Esto renderizará los hosted fields de tu lado y permitirá al usuario ingresar los datos de su tarjeta y completar el proceso de tokenización. Más ejemplos aquí.

Estilos

Usa la misma metodología que en Card Token Styles. La diferencia es que estos estilos aplican específicamente a los campos requeridos por este método de tokenización. Ten en cuenta que el campo isSubscription es un checkbox, así que hay que aplicar estilos específicos a ese tipo de input. Para más detalles, revisa la interfaz Card Payouts Styles.

Eventos

Usa la misma metodología que en Eventos (opcional). La diferencia es que estos eventos aplican específicamente a los campos requeridos por este método de tokenización. Para más detalles, revisa los ejemplos de initCardPayoutToken.

Obtener un token de Card Payout

Llama al método requestCardPayoutToken en la instancia de card payout inicializada previamente. Este método valida que todos los campos tengan valores válidos; de lo contrario, arroja una excepción.

This method returns a CardPayoutTokenResponse object:

Si isSubscription está marcado → devuelve un CardPayoutSubscriptionTokenResponse con un subscriptionId.

Si no → devuelve un CardPayoutUniqueTokenResponse con un token de un solo uso.

Ejemplo

Integración con Apple Pay

¡Ten en cuenta!

La funcionalidad de Apple Pay está actualmente en fase de pruebas. Solo está disponible para comercios de Chile 🇨🇱, Colombia 🇨🇴, México 🇲🇽 y Perú 🇵🇪, y admite tarjetas Visa y Mastercard.

Ten en cuenta que esta funcionalidad puede cambiar sin previo aviso.

Obtener un token de tarjeta desde Apple Pay

El método initApplePayButton te permite renderizar el botón de Apple Pay e inicializar una sesión de pago con la API de Kushki.

Requisitos previos

Dominio seguro (HTTPS): Tu sitio web debe servirse sobre una conexión HTTPS segura.

Verificación del dominio: Debes verificar con Kushki que el dominio es tuyo antes de integrar.

Obtén el archivo: Solicita el archivo apple-developer-merchantid-domain-association al Soporte de Kushki (indica UAT o Producción).

Aloja el archivo: Sube el archivo a tu servidor en: https://{your-domain}/.well-known/apple-developer-merchantid-domain-association

Registra el dominio: Ingresa a la Kushki Console, ve a Configuration > Integrations > Apple Pay y registra la URL de tu dominio.

Contenedor HTML: Agrega un elemento contenedor donde se renderizará el botón de Apple Pay:

Disponibilidad del dispositivo: El usuario debe estar en un dispositivo compatible (iOS o macOS) con Safari y tener una tarjeta válida en su Apple Wallet.

Pago único

Primero, agrega el contenedor HTML donde aparecerá el botón de Apple Pay:

Este bloque inicializa Kushki.js, configura el botón de Apple Pay y define la lógica para solicitar el token de tarjeta de Kushki al hacer clic:

Suscripción

El flujo de inicialización es idéntico al de un pago único. La única diferencia es la bandera isSubscription: true que se pasa a requestApplePayToken, que le indica a Kushki que genere un token de suscripción en vez de un token de pago único.

Nota

El token de suscripción devuelto se usa para crear un cargo recurrente con la API de suscripciones de Kushki.

Notas importantes

El botón de Apple Pay se renderiza automáticamente dentro del contenedor indicado por su ID (#kushki-apple-pay-button).

El token que devuelve requestApplePayToken es un token de tarjeta de Kushki, no un token de Apple. Viene preprocesado y listo para usarse directamente en la API de Kushki.

Cuando isSubscription: true, el token resultante debe usarse con la API de cargos recurrentes de Kushki para crear una suscripción — no se puede usar para un cargo único.

Para la referencia completa, revisa la definición del método initApplePayButton.

Otros métodos

requestBankList()

Obtén la lista de bancos disponibles y sus IDs. Debes enviar el ID del banco seleccionado al solicitar un token de transferencia.

Envía un objeto IKushki válido al llamar al método requestBankList() para obtener la lista completa de bancos disponibles.

Propiedad	Tipo	Requerido	Descripción
kushkiInstance	IKushki	Sí	Objeto con el id público del comercio y el ambiente de trabajo.

Errores

Esta es la lista de errores que el método requestBankList() puede devolver como un objeto KushkiError:

Código	Mensaje	Ejemplo	Descripción
E014	Error en solicitud de lista de bancos	`{ code: "E014", message: "Error en solicitud de lista de bancos" }`	Error obtaining the bank list. Please try again; if the error persists, contact Kushki support.

Más información en la definición del método requestBankList.

requestBrandsByMerchant()

Obtén la lista de marcas de tarjeta disponibles en tu comercio llamando al método requestBrandsByMerchant(). Esta información puede ser útil para mostrar las opciones de pago disponibles en tu tienda.

Propiedad	Tipo	Requerido	Descripción
kushkiInstance	IKushki	Sí	Objeto con el id público del comercio y el ambiente de trabajo.

Errores

Esta es la lista de errores que el método requestBrandsByMerchant() puede devolver como un objeto KushkiError:

Código	Mensaje	Ejemplo	Descripción
E021	Error en solicitud de marcas de tarjetas del comercio	`{ code: "E021", message: "Error en solicitud de marcas de tarjetas del comercio" }`	Please check the information sent and try again.

Más información en la definición del método requestBrandsByMerchant.

requestCommissionConfiguration()

Este método solo funciona cuando el modo Split Payment está habilitado. El modo de recaudo Split Payment permite dividir el pago de una transacción entre dos comercios receptores: el comercio principal y el Comercio Receptor de Comisión.

Usa este método para calcular el monto que se le pagaría al Comercio Receptor de Comisión en una transacción determinada.

Nota

El modo Split Payment solo está disponible bajo demanda en Ecuador.

Propiedad	Tipo	Requerido	Descripción
kushkiInstance	IKushki	Sí	Objeto con el id público del comercio y el ambiente de trabajo.
body	`CommissionConfigurationRequest`	Sí	Objeto con la moneda y el monto para calcular las comisiones.

Errores

Esta es la lista de errores que el método requestCommissionConfiguration() puede devolver como un objeto KushkiError:

Código	Mensaje	Ejemplo	Descripción
E015	Error en solicitud de configuración de comisión	`{ code: "E015", message: "Error en solicitud de configuración de comisión" }`	Error getting commission settings. Please try again with the correct information.

Más información en la definición del método requestCommissionConfiguration.

requestInitCardBrandingAnimation()

La animación Card Branding le da al usuario una confirmación clara de su pago. Aplica esta animación solo cuando el usuario haya seleccionado una tarjeta Mastercard o Visa, y reprodúcela después de completar la transacción.

Define un contenedor donde aparecerá la animación:

Usa uno de los siguientes IDs válidos:

visa-sensory-branding — para transacciones con tarjeta Visa

mastercard-sensory-branding — para transacciones con tarjeta Mastercard

Propiedad	Tipo	Requerido	Descripción
opts	CardBrandingRequest (Visa, Mastercard)	Sí	Objeto con la configuración de la animación (Visa o Mastercard).

Errores

Esta es la lista de errores que el método requestInitCardBrandingAnimation() puede devolver como un objeto KushkiError:

Código	Mensaje	Ejemplo	Descripción
E022	Error al generar animación	`{ code: "E022", message: "Error al generar animación" }`	Verifica que los parámetros de configuración de la animación sean correctos.

Más información en la definición del método requestInitCardBrandingAnimation.

Estilos (opcional)

Si quieres generar estilos personalizados para los hosted fields, la biblioteca ofrece dos enfoques a través de la interfaz Styles:

Clases CSS — La interfaz CssProperties te permite pasar un string para configurar una clase CSS de tu sitio.

Objeto JSS — La interfaz CssProperties te permite pasar un objeto para configurar estilos CSS personalizados en línea.

Nota

Puedes combinar las dos opciones: algunos atributos de estilo pueden ser clases CSS y otros, objetos.

Clases CSS

Puedes usar la clase CSS desde:

Un archivo CSS local

Un framework CSS

El siguiente ejemplo muestra la declaración de estilos CSS desde un archivo local:

Objetos de estilo

Otros artículos relacionados

Definición de scopes para los atributos de Styles

Ejemplo: estilos personalizados desde una clase CSS

Ejemplo: estilos personalizados con JSS

Ejemplo: pseudoelementos con JSS

Documentación de JSS

Pseudoelementos de CSS

Eventos (opcional)

Manejo del evento focus en el campo

Este evento se dispara cuando el campo recibe el foco. Para más información, revisa el método onFieldFocus dentro de la interfaz ICard.

Manejo del evento blur en el campo

Este evento se ejecuta cuando el campo pierde el foco. Para más información, revisa el método onFieldBlur dentro de la interfaz ICard.

Manejo del evento submit en el campo

Este evento se ejecuta cuando el campo se ha enviado. Para más información, revisa el método onFieldSubmit dentro de la interfaz ICard.

Manejo de la validación en el campo

Este evento se ejecuta cuando cambia la validación del campo. Para más información, revisa el método onFieldValidity dentro de la interfaz ICard.

Manejo de la validación del formulario para todos los hosted fields

Este evento se ejecuta cuando cambia la validación de cualquier campo. Para más información, revisa el método getFormValidity dentro de la interfaz ICard.

Enfocar un hosted field

Este método enfoca de forma asíncrona un campo del formulario del tipo indicado; de lo contrario, se genera una excepción. Para más información, revisa el método focus dentro de la interfaz ICard.

Restablecer un hosted field

Este método restablece de forma asíncrona un campo del formulario del tipo indicado a su estado por defecto; de lo contrario, se genera una excepción. Para más información, revisa el método reset dentro de la interfaz ICard.

Siguientes pasos

Una vez que hayas integrado los métodos descritos arriba para obtener un token desde el frontend, consume uno de los siguientes endpoints desde tu backend para continuar con el flujo de pago:

Hacer un cargo único si initCardToken() no se inicializó como suscripción.

Crear una suscripción si initCardToken() se inicializó como suscripción.

Hacer un pago One-click si initCardToken() se inicializó como suscripción y se generó un token con el método requestDeviceToken().

Cuando termines el proceso de desarrollo, realiza una certificación para obtener tus credenciales del ambiente de producción. Revisa la sección de certificación para conocer los requisitos de tu implementación de Kushki.js Hosted Fields.

¿Tienes alguna sugerencia sobre esta documentación? Escríbenos.

Importing Kushki.js Hosted Fields#

Inicializar Kushki.js Hosted Fields#

Parámetros de configuración#

Inicialización del formulario#

Paso 1. Define los contenedores para los hosted fields#

Paso 2. Crea una instancia de CardOptions#

Parámetros de CardOptions#

Paso 3. Renderiza los hosted fields con el método initCardToken()#

Errores#

Tokenización#

requestToken()#

Pagos diferidos#

México y Ecuador#

Chile, Colombia y Perú#

Chile: Cuotas Comercio (Merchant Installments)#

Respuesta#

Errores#

Ejemplos#

Seguridad#

OTP#

onOTPValidation()#

3D Secure#

Opcional: autenticación 3D Secure manual#

requestSecureInit()#

requestValidate3DS()#

Sift#

requestInitAntiFraud()#

Suscripciones#

Omitir el CVV#

Cargo recurrente#

Pagos One-click#

requestDeviceToken()#

Secure DeviceToken#

Card Payouts#

Inicialización del formulario#

Estilos#

Eventos#

Obtener un token de Card Payout#

Integración con Apple Pay#

Obtener un token de tarjeta desde Apple Pay#

Requisitos previos#

Pago único#

Suscripción#

Notas importantes#

Otros métodos#

requestBankList()#

requestBrandsByMerchant()#

requestCommissionConfiguration()#

requestInitCardBrandingAnimation()#

Estilos (opcional)#

Clases CSS#

Objetos de estilo#

Otros artículos relacionados#

Eventos (opcional)#

Manejo del evento focus en el campo#

Manejo del evento blur en el campo#

Manejo del evento submit en el campo#

Manejo de la validación en el campo#

Manejo de la validación del formulario para todos los hosted fields#

Enfocar un hosted field#

Restablecer un hosted field#

Siguientes pasos#

Importing Kushki.js Hosted Fields

Inicializar Kushki.js Hosted Fields

Parámetros de configuración

Inicialización del formulario

Paso 1. Define los contenedores para los hosted fields

Paso 2. Crea una instancia de CardOptions

Parámetros de CardOptions

Paso 3. Renderiza los hosted fields con el método initCardToken()

Errores

Tokenización

requestToken()

Pagos diferidos

México y Ecuador

Chile, Colombia y Perú

Chile: Cuotas Comercio (Merchant Installments)

Respuesta

Errores

Ejemplos

Seguridad

OTP

onOTPValidation()

3D Secure

Opcional: autenticación 3D Secure manual

requestSecureInit()

requestValidate3DS()

Sift

requestInitAntiFraud()

Suscripciones

Omitir el CVV

Cargo recurrente

Pagos One-click

requestDeviceToken()

Secure DeviceToken

Card Payouts

Inicialización del formulario

Estilos

Eventos

Obtener un token de Card Payout

Integración con Apple Pay

Obtener un token de tarjeta desde Apple Pay

Requisitos previos

Pago único

Suscripción

Notas importantes

Otros métodos

requestBankList()

requestBrandsByMerchant()

requestCommissionConfiguration()

requestInitCardBrandingAnimation()

Estilos (opcional)

Clases CSS

Objetos de estilo

Otros artículos relacionados

Eventos (opcional)

Manejo del evento focus en el campo

Manejo del evento blur en el campo

Manejo del evento submit en el campo

Manejo de la validación en el campo

Manejo de la validación del formulario para todos los hosted fields

Enfocar un hosted field

Restablecer un hosted field

Siguientes pasos