Conoce Kushki ONE, nuestra solución regional para pagos de venta presente (Card Present).
🚧 Early Release — Beta
Este producto está en acceso temprano. Los parámetros, estructuras de respuesta y comportamientos pueden cambiar sin previo aviso. No uses esta versión en producción sin coordinarlo previamente con el equipo de integraciones de Kushki.
Kushki ONE es la solución integral de pagos presenciales de Kushki. Está diseñada para que los comercios reciban pagos físicos a través de terminales SmartPOS, unificando toda la operación en un solo ecosistema.Recibe pagos usando directamente la aplicación de cobro instalada en la terminal, o conecta tu software de punto de venta a través de nuestra API. Opera desde una caja, tablet, computador u otro dispositivo con conexión a red, o desde una app instalada en la misma terminal.
La cantidad de decimales cambia cómo envías el monto
Los montos se envían como enteros en la unidad mínima de la moneda, y el resultado depende del país. Revisa Formato de montos en Kushki ONE antes de construir tu primer request.
Esta documentación se divide en dos rutas según tu rol.
Ruta 1: operadores y administradores
Para quienes operan el punto de venta o administran el negocio: hardware certificado, la Payment App, el catálogo de operaciones y los modos Standalone y Semi-Integrado.
Ruta 2: desarrolladores e integradores
Para quienes conectan el software de caja con la terminal: Kushki ONE Connect, topologías de integración, seguridad, requisitos de red y el flujo completo de la transacción.
Ruta 1: Para Operadores y Administradores de Comercio#
La arquitectura de Kushki ONE es agnóstica respecto al hardware y todos sus componentes son interoperables. Sin embargo, para garantizar el máximo rendimiento y estabilidad, la solución está certificada únicamente para estos dispositivos SmartPOS.
Modelo
Pantalla y diseño
Procesador y memoria
Sistema operativo
Sunmi P3 (estándar)
6.75" HD+ sin biseles (350 nits). Ultradelgado de 17 mm con recubrimiento antihuellas
Quad-Core A53 a 2.0 GHz, 2 GB RAM, 32 GB ROM
Sunmi OS (Android 11 Go)
Sunmi P2 SE
Pantalla compacta. Diseño ligero, resistente a polvo, salpicaduras y caídas. Motor de escaneo de QR y códigos de barras
Es la aplicación de cobro instalada directamente en la terminal física. Su interfaz permite al operador ejecutar y gestionar el ciclo de vida completo de un pago sin necesidad de un punto de venta externo.
Cobro en un solo paso. Admite propina, cuotas de comercio, cuotas de emisor y cashback
Autorización
✅
Reserva el cupo en la tarjeta para un cobro posterior
Captura
✅
Cobra un monto previamente autorizado
Re-autorización
✅
Modifica el monto autorizado o extiende el plazo para aplicar la captura
Devolución
✅
Retorna el dinero de una venta. Internamente ejecuta una anulación o un reembolso según el momento de la ejecución
Post propina
✅
Ingresa un monto de propina posterior a la autorización de una transacción
Divide la cuenta
❌
Divide un monto en varios pagos secuenciales. Solo Standalone — no tiene endpoint
Divide la cuenta no es Split Payment
Son pagos concatenados para simplificar la división de una cuenta, por ejemplo en un restaurante. No los confundas con las operaciones de Split Payment del comercio electrónico, que reparten un mismo pago entre varios comercios.
Kushki ONE Connect es nuestra capa de integración por API que permite a tu software de caja interactuar directamente con la terminal física cuando opera en modo Semi-Integrado. Tu sistema envía los comandos financieros a la aplicación de pago, y con eso eliminas la digitación manual y los errores humanos.La premisa es simple: es la misma API independientemente del canal que uses. Lo único que varía entre topologías es la vía de comunicación, no la estructura de los endpoints ni los payloads.
Punto de venta en la nube, comercios multisede, caja y terminal en redes distintas
Supermercados, retail y restaurantes bajo la misma red
App de caja propia instalada en la terminal
Requisito clave
Internet estable en la caja y en la terminal
IP estática o reserva DHCP en la terminal
No requiere red interna entre las apps
Internet siempre es necesario
La comunicación por localhost no requiere red entre las apps, pero el dispositivo siempre necesita salida a internet para procesar la transacción financiera con Kushki.
Tu caja envía una petición HTTP directamente a la IP local de la terminal, sin triangular con servidores externos. Eso reduce la latencia de forma notable.
Ventaja: menor latencia, porque la comunicación entre caja y terminal no depende de internet.
Consideración: la terminal necesita IP estática o reserva DHCP. Si la IP cambia, tu caja pierde la comunicación.
3. Integración en el Mismo Dispositivo (Localhost)#
Aplica cuando tienes tu propia app de caja instalada dentro de la misma terminal SmartPOS. Tu app y la Kushki ONE Payment App conviven en el mismo hardware y se comunican apuntando a localhost.
Ventaja principal: reemplaza los flujos de integración app a app tradicionales con llamadas HTTP estándar.
Sin red interna: la comunicación entre las dos apps no necesita Wi-Fi ni Ethernet.
Todas las comunicaciones hacia Kushki ONE Connect se autentican con una firma que calculas a partir de tu Business-Code.
Business-Code no es private_credential_id
La llave de firma es tu Business-Code. El private_credential_id es un campo de configuración de la terminal y nunca se usa para firmar requests.
La lógica de firma y cifrado no cambia entre topologías: es la misma en Nube, Red Local y Localhost. Hay un solo mecanismo — hash + cifrado:
Elemento
Valor
Authorization
Basic seguido del hash SHA-512
timestamp
Unix timestamp en segundos, dentro de ±5 minutos de la hora del servidor
Cuerpo
El sobre cifrado {"data": "<iv_hex>:<ciphertext_hex>"}
En Red Local y Localhost, envía el header encrypted_http_communication en true
Si integras por Red Local o Localhost, envía el header encrypted_http_communication: true en cada request, en UAT y en producción. Sin él, tus requests no se firman ni se cifran, y al pasar a producción fallan con AUTH-001 («Invalid or expired credentials»). La integración por Nube no requiere este header.
Escríbela una sola vez
La lógica de firma y cifrado de este apartado es la misma en las tres topologías. El flujo completo — derivación de claves, los siete pasos y el árbol de diagnóstico — está en Autenticación y cifrado de requests.
Aplica únicamente si usas la topología de Red Local.
IP estática o reserva DHCP: configura el router para que asigne siempre la misma IP a la terminal, asociada a su dirección MAC.
Puertos de comunicación: el firewall interno debe permitir tráfico bidireccional en los puertos TCP de la terminal — 6868 para HTTP y 6869 para HTTPS. Una red que solo abre el 6868 bloquea el acceso HTTPS a la terminal.
Seguridad Wi-Fi: las terminales certificadas soportan WPA2-PSK y WPA3.
Redes no recomendadas
No conectes las terminales a redes públicas abiertas ni a redes con portales cautivos, que exigen usuario y contraseña en un navegador para dar acceso.
La terminal siempre requiere salida a internet para procesar transacciones y recibir actualizaciones. Si tu red corporativa bloquea el tráfico saliente, tu equipo de TI debe habilitar estos hosts en el puerto 443. Abre solo la columna de tu ambiente — uat-cloudt es un host de pruebas y no corresponde en una red productiva:
Propósito
UAT
Producción
Quién lo necesita
Relay de Nube
uat-cloudt.kushkipagos.com
cloudt.kushkipagos.com
La terminal y la red del POS
Procesamiento de pagos
api-uat.kushkipagos.com
api.kushkipagos.com
Solo la terminal
Gestión de terminales
uat-tms.kushkipagos.com
tms.kushkipagos.com
Solo la terminal
Los tres son egress real de la terminal. La única fila que además hay que abrir desde la red del POS es el relay de Nube, y solo si integras por esa topología.
Puerto 6868 y puerto 443 no son lo mismo
Los puertos 6868 y 6869 son los puertos de escucha locales de la terminal y solo aplican a la comunicación entre tu caja y la terminal dentro de la misma red. El tráfico hacia los servidores de Kushki siempre usa el puerto 443. Si tu política de red exige una lista exhaustiva que incluya los servicios de telemetría del fabricante, solicítala al equipo de integraciones.
Generación de la solicitud: tu sistema de caja genera la solicitud y envía el monto a cobrar por API.
2.
Decisión y enrutamiento: Kushki ONE Connect recibe la solicitud y la enruta hacia el dispositivo físico según la configuración del comercio, por Nube o por Red Local.
3.
Recepción y captura de datos: la terminal recibe la petición, muestra el monto en pantalla y lee la tarjeta del cliente.
4.
Procesamiento: la terminal envía la información a Kushki, que procesa la transacción financiera.
Antes de tu primer cobro, comprueba que tu caja alcanza la terminal. Este endpoint no mueve dinero y es la forma más rápida de validar red, puerto y credenciales.
JavaScript
Python
La misma verificación existe en Nube, donde cambia el método — es un POST dirigido a la terminal por número de serie:
POST /terminal/v1/{terminalSerial}/sync/local/test
Hay un segundo endpoint de diagnóstico que conviene conocer, disponible en las dos topologías:
GET /terminal/v1/sync/config/terminal_info ← red local
POST /terminal/v1/{terminalSerial}/sync/config/terminal_info ← Nube
Devuelve {model, room, serialNumber}. El campo room es la versión de app de la terminal — el único dato con el que sabés contra qué build estás probando, algo que importa mientras el producto está en Beta.Si recibes un error TER-002, la terminal no responde: revisa la conectividad de red y que el puerto esté abierto. Si recibes un error de autenticación, revisa tu firma.
