Guarda los datos de tarjeta de tus clientes para recibir pagos one clickEsta funcionalidad se encuentra disponible para los siguientes modelos:
☐ Adquirente
☑ AgregadorSi buscas pagos recurrentes automáticos revisa nuestra guía. Ten en cuenta que, debido a nuestras políticas de riesgo, los medios de pago disponibles y el tipo de integración pueden variar al momento en que formalices la afiliación. Te indicaremos cómo proceder en caso de que este proceso aplique para tu comercio.
¿Cómo funciona?#
Guardar los datos de tarjetas de débito y crédito en tu sitio consiste en capturar la información de la tarjeta, crear un token y enviar la información a Kushki para ser guardada. Esta acción crea un identificador de suscripción para la tarjeta. Con ese identificador, desde tu back-end puedes realizar cobros one click.Al realizar la inscripción se realizará un cargo a la tarjeta del cliente por un monto pequeño que permite verificar que la tarjeta esté activa y con saldo. Este cobro se reversará automáticamente.
1. Inscripción#
Lo primero que debes hacer para generar cobros one click es inscribir la tarjeta de tu cliente. Para realizarlo, sigue los siguientes pasos:Configura tu front-end#
La responsabilidad del front-end es recoger la información de tarjeta del usuario de una manera segura, tokenizarla a través de los servidores de Kushki y enviarla a tu back-end e iniciar el proceso de inscripción de tarjeta para que luego puedas realizar cobros one click.Kushki.js#
Usa Kushki.js si necesitas un mayor control sobre el "look & feel" o apariencia de tu formulario de pago.Opción 1 - CDN#
Usa el siguiente tag script al final del <body> en tu página de pagos.Opción 2 - NPM#
Instala el paquete desde npm.Luego impórtalo en tu código utilizando el siguiente código.Configura el objeto Kushki#
Añade el siguiente código a tu aplicaciónPrimero, añade el formulario a tu página de pagos con los campos requeridos. Puedes diseñarlo de la forma que mejor te parezca.Muestra las opciones de diferidos de acuerdo al BIN de la tarjeta de tu cliente (Opcional)#
Tan pronto el número de tarjeta de tu cliente es ingresado, deberás consultar el método de solicitud de diferidos para verificar si hay opciones de pago diferido para el BIN de la tarjeta ingresada por el usuario.Como respuesta a esta llamada, recibirás el nombre del diferido , el tipo type (corresponde al creditType al ejecutar el cargo), los meses disponibles y los meses de gracia (skip payments), tal como se muestra en el siguiente ejemplo de respuesta. Esta es la información que deberás usar al ejecutar el cargo: {
name: "Diferido con intereses",
type: "002",
months: ["3", "6"],
monthsOfGrace: ["1", "2", "3"]
}
Los tipos de diferido disponibles para tu cliente dependerán del BIN de la tarjeta.
deferred cuando inicies el proceso de cobro con Kushki.Luego, cuando el usuario envía el formulario, deberás solicitar el token y enviarlo a tu back-end.Kushki.js Hosted Fields#
Con Hosted Fields, incluido en Kushki.js, podrás recolectar de forma segura la información del pago del cliente a través de campos almacenados en infraestructura de Kushki. Devuelve un token el cual permite continuar con el flujo de pago desde el back-end.Importa Kushki.js Hosted Fields en tu aplicación#
Opción 1 - CDN#
Importa la biblioteca de Kushki.js Hosted Fields en tu aplicación a través de una etiqueta <script> dentro de la etiqueta <body>. Una vez importada, podrás acceder a los recursos descritos a continuación para crear un flujo de pago con Kushki.Es necesario importar tanto la biblioteca kushki.min.js (la cuál trae el código necesario para almacenar las credenciales de tu comercio) como la biblioteca card.min.js (módulo el cuál trae las funcionalidades necesarias para el flujo de pagos con tarjeta).Opción 2 - NPM#
Instala la biblioteca Kushki.js Hosted Fields como un paquete npm dentro de tu aplicación con el siguiente código:Opción 3 - YARN#
Instala la biblioteca Kushki.js Hosted Fields como un paquete yarn dentro de tu aplicación con el siguiente código:Crea una instancia de KushkiOptions#
Para hacer uso de la biblioteca Kushki.js Hosted Fields, es necesario primero crear una instancia de tipo KushkiOptions la cuál te permite declarar la clave pública del comercio así como poder seleccionar el ambiente (prueba o producción) mediante el método init().Nota: Cuando estés listo para aceptar pagos reales, es necesario que reemplaces la clave de prueba con la clave de producción.
Paso 1. Definir los contenedores para los campos de lado del servidor.#
Antes de llamar al método initCardToken(), es requerido que coloques los elementos necesarios para poder renderizar cada campo de lado del servidor.Paso 2. Crear una instancia de CardOptions#
Crea una instancia de CardOptions con la información de la transacción tal como el monto, moneda, entre otros parámetros.Nota: Para crear una suscripción es necesario que envíes la propiedad isSubscription con el valor de true.
Paso 3. Renderizar campos de lado del servidor con el método initCardToken()#
Después de crear una instancia de CardOptions, es necesario mandar a llamar a la función initCardToken() para inicializar una instancia de ICard.Solicita un token para seguir con el flujo de pago#
Solicita un token de pago con tarjeta que podrás usar posteriormente para realizar un cobro One click.Para obtener un token de pago con tarjeta, es necesario llamar al método requestToken() en la instancia de card inicializada previamente. Este método realiza las validaciones de 3DS, OTP, Sift Science automáticamente. Te recomendamos validar que todos los campos sean correctos; de lo contrario, arrojará una excepción.Nota: Si la opción de diferidos está disponible para tu comercio, el objeto deferred será devuelto junto al token. Los campos disponibles dentro de deferred varían dependiendo el país. Consulta la referencia para más información sobre diferidos. Configura tu back-end#
La responsabilidad del back-end es recibir el token obtenido desde tu front-end e iniciar el proceso de inscripción de tarjeta con Kushki.Cuando el usuario envía el formulario, tu front-end transfiere un token a un endpoint que hayas especificado. Con este token, deberás realizar una llamada a nuestro endpoint de inscripción para inscribir la tarjeta.Es importante que definas la variable de periodicidad periodicity en custom ya que de otra manera cobrarás de manera recurrente a tu cliente. Para más información, consulta nuestras guías de cargos recurrentes. 2. Cobro#
Una vez que ya tengas inscrita la tarjeta de tu cliente, para realizar un cobro, es necesario realizar estos sencillos pasos, utilizando el subscriptionId.Configura tu front-end#
Kushki.js#
Aprovecharemos que nuestra librería Kushki.js ha sido importada y configurada anteriormente para utilizar un método que será de mucha ayuda para verificar la fiabilidad del cobro.Genera un token de cobro y envíalo a tu back-end#
Primero, es necesario obtener el id de suscripción de la tarjeta a la que se realizará el cobro.Luego, solicita el token de cobro y envíalo a tu back-end.Kushki.js Hosted Fields#
Para realizar un cargo one-click, y obtener el deviceToken tienes 2 opciones:1.
Sin validación del CVV en un campo hosteado: puedes obtener un token a través del método requestDeviceToken() enviando el subscriptionId generado previamente.
2.
Con validación de CVV: este método usa un campo hosteado para validar el CVV.
1. requestDeviceToken()#
Para realizar un cargo One-click sin validación CVV en un campo hosteado al realizar un cargo, debes llamar al método requestDeviceToken() enviando el ID de suscripción obtenido previamente.Nota: si la transacción se generó con una tarjeta que requiere autenticación 3DS o Sift Science, el método requestDeviceToken() realizará las validaciones y desplegará el modal en caso de que sea requerido.
2.Secure DeviceToken()#
Si necesitas validar el CVV al realizar un pago One-click, llama al método Secure DeviceToken. Este es el segundo método para obtener un deviceToken, pero utiliza un campo alojado (hosted field) para validar el CVV de la tarjeta.Se debe definir el contenedor donde se desplegará el campo para ingresar el valor del CVV.Desplegar el campo del CVV#
2.1. Llama al método initSecureDeviceToken().#
Llama al método initSecureDeviceToken(), que renderiza un campo alojado de CVV e inicializa una instancia de ICardSubscriptions.2.2. Llama al método requestDeviceToken().#
Para obtener un deviceToken seguro, debes llamar al método requestDeviceToken() en la instancia de suscripción de tarjeta que fue inicializada previamente.
Este método también valida si el campo de CVV es válido; de lo contrario, generará una excepción.Revisa aquí la referencia completa de la librería para más información. Configura tu back-end#
Una vez recibido el token de cobro, para realizar un cargo one click basta llamar a nuestro endpoint de cobros junto con el subscriptionIdbajo la lógica que definas.Si deseas recibir un pago en cuotas (diferidos), asegúrate de enviar el objeto deferred con los parámetros meses de gracia, meses y tipo de crédito, junto con la información del cobro, tal y como se muestra en el ejemplo a continuación.
Para obtener dichos parámetros primero deberás consultar el BIN, usando el método de consulta de información de la suscripción y posteriormente el método de consulta de diferidos. El objeto deferred solo debe enviarse en los casos en que la tarjeta tenga la posibilidad de hacer pagos diferidos, en todos los demás casos el objeto mencionado debe omitirse.
Cancela una inscripción (Opcional)#
Si tu cliente decide cancelar el servicio o una vez que dejes de prestarlo, para cancelar la inscripción de la tarjeta, simplemente debes llamar a nuestro endpoint de cancelación de inscripción desde tu backend.3. Prueba tu integración#
Para probar la recepción de pagos en cuotas (diferidos) es necesario una configuración adicional por parte del equipo de Kushki. Una vez se haga dicha configuración, podrás consultar las opciones de diferidos habilitadas para tu comercio desde tu Consola de administración en la opción Mi Comercio>Diferidos.
Transacción aprobada: 5451951574925480
Transacción declinada en solicitud de token (front-end): 4574441215190335
Transacción declinada en solicitud de cobro (back-end): 4349003000047015
4. Prepara tu certificación#
Toma en consideración las siguientes pautas para aprobar la certificación técnica (requerida para obtener credenciales productivas):Los cálculos de los impuestos están correctos.
No almacenar datos sensibles de tarjeta en tu base de datos (número completo de tarjeta, CVV, etc.).
Mensajes en pantalla de acuerdo con las respuestas de Kushki.
Guardar y registrar todas las respuestas de Kushki (requeridas en caso de necesitar soporte).
El logo de Kushki debe ser visible para el cliente. Puedes encontrar nuestro logo en varios formatos aquí. El nombre del titular de la tarjeta es requerido.
El campo de número de tarjeta es requerido.
El campo de número de tarjeta acepta solo números.
El campo de número de tarjeta acepta un máximo de 16 dígitos (pueden ser menos).
El campo de CVV es requerido.
El campo de CVV acepta solo números.
El campo de CVV permite un máximo de 4 dígitos y un mínimo de 3.
El campo de CVV debe ser tipo password.
La fecha de expiración es requerida.
La fecha de expiración debe aceptar solamente fechas futuras.
El botón de pago se deshabilita luego de hacer el primer clic.
El logo de Kushki debe ser visible para el cliente. Puedes encontrar nuestro logo en varios formatos aquí. Asegúrate de enviar los datos de contacto de tu cliente-pagador (contactDetails), junto con los datos de facturación ( orderDetails -> billingDetails) y envío (si tu modelo de negocio lo requiere: orderDetails -> shippingDetails), dentro del request para realizar el cargo. El ejemplo del Body del JSON para el charge, lo podrás encontrar en Referencia de la API.
Acepta webhooks
Maneja eventos pospago de la manera correcta. Modificado en 2026-10-21 19:52:42
