1. Pagos en un paso
Kushki Docs
Español
  • Español
  • English
  • Inicio
  • Inicio rápido
    • Preguntas frecuentes
    • Paso a producción
    • Política de cambios importantes del API
    • Códigos de error
    • Datos de prueba
    • Últimas novedades
  • Glosario de pagos
    • Glosario de pagos
  • Pagos únicos con tarjeta (Online)
    • Network Tokens
    • Funcionalidades por modelo de negocio
    • Marcas de tarjeta soportadas
    • Pagos en un paso
      • Cargo directo (sin token)
      • Códigos de error autenticación OTP
      • ¿Cómo funcionan los pagos con tarjeta?
      • Acepta un pago con tarjeta
      • Acepta pagos únicos con OTP
      • Códigos de error pagos únicos con tarjeta
    • Pagos en dos pasos
      • Recibe pagos con autorización y captura
      • ¿Cómo funcionan los pagos únicos con autorización y captura?
    • Pagos con Webpay Plus
      • Reserva fondos con Webpay Plus
    • Pagos con Apple Pay
      • Pruebas en Sandbox Apple Pay
      • Configuración de Apple Pay
    • Devoluciones
      • Devoluciones, anulaciones y reembolsos
    • Autenticación 3DS
      • Introducción a 3DS
      • Integración 3DS API + librería kushki.js
      • Integración 3DS con librería kushki.js
      • Integración 100% API de 3DS
      • Códigos de error autenticación 3DS
  • Pagos recurrentes con tarjeta (Online)
    • Autentica tus suscripciones con 3DS
    • Apple Pay en Suscripciones
    • Suscripciones externas a Kushki
    • Acepta pagos one click con 3DS
    • Funcionalidades por modelo de negocio
    • Códigos de error en cargos recurrentes
    • Pagos calendarizados
      • Maneja tus cargos calendarizados
      • Crea un cargo recurrente
      • ¿Cómo funcionan los cargos recurrentes con tarjeta?
    • Pagos calendarizados con Webpay OneClick
      • Reserva fondos en recurrencias con Webpay OneClick
      • Recurrencias con Webpay OneClick
    • Pagos OneClick con Webpay OneClick
      • Pagos one click con Webpay OneClick
      • Reserva fondos en pagos one click con Webpay OneClick
    • Pagos OneClick
      • ¿Cómo funcionan los pagos OneClick con autorización y captura?
      • Recibe pagos OneClick con autorización y captura
      • Genera pagos one click
  • Pagos con tarjeta presente
    • Acepta pagos con tarjeta presente
    • Datos de prueba
    • Webhooks para tarjeta presente
    • Raw card-present API
      • Script de ejemplo para cifrar información
      • Acepta pagos
      • Intercambio de claves criptográficas
      • Preguntas frecuentes
      • Códigos de error para transacciones con tarjeta presente
    • Transacciones
      • Anula un pago
      • Transacciones
    • Kushki One
      • Autenticación y Cifrado de Requests
      • Realiza cobros con Kushki One
      • Formato de montos en Kushki ONE
      • Impresión en terminal SmartPOS
      • Catálogo Unificado de Errores — Kushki ONE Connect
      • Servicios asíncronos y webhooks
    • Kushki One App de Pagos
      • Procesa un cobro
      • Devoluciones y PreAuth & Capture
      • Pago Dividido en la terminal
      • Configuración del terminal
      • Consulta tus transacciones
  • Pagos con transferencias
    • Recibe transferencias bancarias
    • Consulta el estado de una transacción
    • Bancos y detalles de operación para pagos con transferencia bancaria
  • Pagos en efectivo
    • Acepta un pago en efectivo
    • Puntos de recaudo
    • Códigos de error para transacciones declinadas en efectivo
  • Dispersión de dinero
    • Transferencia bancaria
      • ¿Cómo funciona la dispersión por transferencia bancaria?
      • Códigos de error para dispersiones por transferencia
      • Dispersa a cuentas bancarias
  • Plugins
    • Shopify
      • Shopify
      • Operación del Plugin
    • Vtex
      • Guía de integración VTEX
  • Links de pago
    • Smartlinks
  • Formularios y botones de pago
    • Introducción
    • Kajita
      • Kajitas de pago
      • ¿Cómo funciona?
    • Botón de pago
      • Genera un botón de pago
      • ¿Cómo funciona el botón de pago?
  • Administración de sucursales
    • ¿Cómo realizar el onboarding de subcomercios vía API?
  • Notificaciones
    • Buenas prácticas
    • Consulta tus webhooks
    • Webhooks para pagos únicos
      • Webhook para pagos únicos con tarjeta
      • Webhook para pagos únicos con transferencia bancaria
      • Webhook para pagos únicos con efectivo
      • Webhook para pagos con Webpay Plus
    • Webhooks para pagos recurrentes
      • Webhook para pagos recurrentes con tarjeta
      • Webhook para pagos recurrentes con Webpay OneClick
    • Webhooks para dispersiones
      • Webhook para dispersión de dinero con transferencia
    • Webhooks para botón de pagos
      • Webhooks con Botón de pago
    • Webhooks para smartlinks
      • Webhooks con Smartlinks
    • Webhooks para devoluciones
      • Webhook para devoluciones
      • Webhook para contracargos
HomeMexico 🇲🇽Ecuador 🇪🇨Chile 🇨🇱
Colombia 🇨🇴Peru 🇵🇪
HomeMexico 🇲🇽Ecuador 🇪🇨Chile 🇨🇱
Colombia 🇨🇴Peru 🇵🇪
Status
Soporte / Support
Español
  • Español
  • English
  1. Pagos en un paso

Acepta un pago con tarjeta

Acepta pagos con tarjeta online de manera segura
Web
iOS
Android
Esta funcionalidad se encuentra disponible para los siguientes modelos:
☑ Adquirente

☑ Agregador
Para conocer los tipos de tarjeta habilitados en cada uno de los modelos de afiliación, por favor consulta nuestra guía de marcas de tarjeta soportados.
Puedes crear tu cuenta de prueba con Kushki en minutos con la opción de Afiliación Inmediata.
¿Estas buscando un plugin?
Revisa nuestra documentación de plugins e instálalos en pocos clics en tu sitio E-commerce.
Recibir pagos con tarjetas de crédito y débito en tu sito consiste en capturar la información de la tarjeta, crear un token y enviar el pago a Kushki para ser procesado.
Importante
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.
Un ejemplo de un formulario de pago con tarjeta sería el siguiente:
El flujo de pago que integrarás es el siguiente:
Flujo pago con tarjeta

1. 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 luego enviarla al back-end para iniciar el proceso de pago.
Tienes tres opciones para integrar: Kajita, Kushki.js y Kushki.js Hosted Fields.

Kajita#

Kushki cuenta con formularios de pago listos para recopilar información de tarjeta de forma segura. Podrás usar cualquiera de nuestras versiones:
Cajita: la primera versión del formulario de pagos. No es personalizable.
Kajita: la segunda versión. Te permite personalizar tus formularios de pago desde tu Consola de administración e incluso tener varias versiones de Kajita.
La cajita incluirá las validaciones del BIN de la tarjeta ingresado por tu cliente de forma tal que se muestren las diferentes opciones de pago diferido disponibles.

Crea y personaliza tus Kajitas#

Con Kushki puedes crear tus Kajitas desde la Consola de administración. Haz clic aquí para aprender cómo hacerlo.

Configura Kajita#

Incluye el script de kushki-checkout.js en tu página de pago añadiéndolo al <head> de tu archivo HTML. Siempre carga kushki-checkout directamente desde cdn.kushkipagos.com. No incluyas el script en un bundle o paquete ni hostees una copia de él.

Añade Kajita a tu sitio#

Kajita necesita un espacio dentro de tu página. Ingresa el siguiente código en el <body> de tu sitio donde quieras que se despliegue el formulario de pago.
Para Kajita (v.2):
Para Cajita (v.1)
Recuerda configurar la acción del formulario action de acuerdo con el endpoint correspondiente en tu back-end, para obtener el token.
Luego, agrega el tag script.
Para la Kajita (v.2) Podrás obtener dicho script desde tu Consola de administración según lo explicado aquí.
Para la v.1 (Cajita), añade el siguiente script y asegúrate de que el formulario se haya cargado:
Esto creará un formulario predefinido en tu página para aceptar pagos.
Puedes utilizar Kajita para ofrecer no solo pagos con tarjetas, sino también en efectivo y mediante transferencias bancarias.

Kushki.js#

Usa Kushki.js si necesitas un mayor control sobre el "look & feel" o apariencia de tu formulario de pago.

Configura Kushki.js#

Opción 1 - CDN#
Usa el siguiente tag script al final del <body> en tu página de pagos.
Option 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ón

Recoge la información del usuario y envíala a tu back-end#

Primero, añade el formulario a tu página de pagos con los campos requeridos. Puedes diseñarlo de la forma que mejor te parezca.
Por ejemplo:

Muestra las opciones de diferidos de acuerdo al BIN de la tarjeta de tu cliente#

Tan pronto el número de tarjeta de tu cliente es ingresado, deberás consultar el método de request deferred options 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 tipo type, los meses disponibles y los meses de gracia (skip payments), tal como se muestra en el siguiente ejemplo de respuesta.
  {
      type: "all",
      months: ["2", "3", "4", "5", "6", "7"],
      monthsOfGrace: []
    }
La ejecución del cargo diferido dependerá del modelo de afiliación:
Agregador: deberás usar solo el parámetro months junto con la demás información del cobro.
"months": 3,
Adquiriencia: envía el objeto deferred que contiene los parámetros graceMonths, creditType y months. En el campo graceMonths se debe enviar 00 y en el campo creditType 01.
"deferred": {
    "graceMonths": "00",
    "creditType": "01",
    "months": 3
  }
Importante
Los tipos de diferido disponibles para tu cliente dependerán del BIN de la tarjeta.
De acuerdo a la respuesta, muestra en el formulario de pagos la información de opciones de diferidos que tu cliente tenga disponible. Asegúrate de capturar sus elecciones y enviarlas a su vez junto con los datos de pago en el objeto deferred o en el parámetro months 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.
Revisa la referencia completa en nuestra referencia de Kushki.js

Kushki.js Hosted Fields#

Con Hosted Fields, incluido en Kushki.js, podrás recolectar de forma segura la información de 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 más adelante 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 tu comercio esté listo para aceptar pagos reales, es necesario que reemplaces la clave de prueba con la clave de producción.
Añade el siguiente código a tu aplicación:
Revisa la referencia para más información sobre la instancia KushkiOptions.

Inicializa el formulario en el front-end#

Sigue los pasos a continuación para poder renderizar los campos de lado del servidor en tu sitio. De esta manera, tus clientes podrán ingresar los datos necesarios para realizar transacciones.
Paso 1. Definir los contenedores para los campos de lado del servidor.#
Antes de llamar al método initCardToken(), es requerido colocar 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, la moneda, entre otros parámetros.
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.
Revisa la referencia para más información sobre la inicialización del formulario
.

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 a un cliente con el endpoint para realizar un pago único o para crear un cargo recurrente.
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 y Sift Science automáticamente. También, valida 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. Para que el usuario pueda seleccionar los meses sin intereses a diferir la compra, se deberá colocar una etiqueta div con el id de deferred_id (<div id="deferred_id"></div>) y se deberá definir dentro de la instancia CardOptions en el objeto fields dicho id. Los campos disponibles dentro de deferred varían dependiendo el país. Consulta la referencia para más información sobre diferidos.
Una vez obtenido el token, envíalo a tu back-end para seguir con el flujo de pago.
Para realizar validaciones mediante OTP, revisa validación OTP.
Consulta la referencia para más información sobre la solicitud de token.

2. Configura tu back-end#

La responsabilidad del back-end es recibir el token obtenido desde tu front end e iniciar el proceso de pago 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 cobros para iniciar el cobro.
JavaScript
Python
PHP
Revisa nuestra Referencia de la API para mayor información.
De acuerdo con tu respuesta, redirecciona al usuario a una página de éxito o fracaso para informar al cliente si la transacción fue aprobada o declinada.
Envía notificaciones a tus clientes
Si deseas que tus clientes reciban notificación de sus transacciones, asegúrate de enviar a nuestro endpoint de cobros el email de tu cliente, como parte del objeto contactDetails. Adicional a esto, recuerda configurar habilitar la opción de notificaciones desde tu consola de administración.

3. Prueba tu integración#

Existen tarjetas de prueba que puedes utilizar en el ambiente UAT para asegurarte de que tu integración está lista. Úsalas con cualquier CVV, código postal y fecha de expiración futura.
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).
Asegúrate de enviar todos los datos requeridos que se especifican en la Referencia de la API, como por ejemplo los detalles del producto (productDetails), así como también los datos de contacto de tu cliente-pagador (contactDetails), junto con los datos de facturación ( "orderDetails"."billingDetails") y envío (si tú modelo de negocio lo requiere: "orderDetails"."shippingDetails"), dentro del request para realizar el cargo.
El logo de Kushki debe ser visible para el cliente. Puedes encontrar nuestro logo en varios formatos aquí.
Si estas utilizando Kushki.js, considera también lo siguiente:
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 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 debe ser tipo password.
El campo de CVV permite un máximo de 4 dígitos y un mínimo de 3.
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 click.
Si tienes habilitada la opción de notificación por correo electrónico a tus clientes del resultado de transacciones desde Kushki, el parámetro email, del objeto contactDetails es requerido.
El logo de Kushki debe ser visible para el cliente. Puedes encontrar nuestro logo en varios formatos aquí.

Acepta pagos con OTP
Sólo Web. OTP (One Time Password) es otro nivel de protección online en contra del fraude.
Acepta webhooks
Maneja eventos pospago de la manera correcta.
Modificado en 2026-10-21 19:52:54
Anterior
¿Cómo funcionan los pagos con tarjeta?
Siguiente
Acepta pagos únicos con OTP
Built with