Primeros Pasos

25 marzo 2026

Conoce Kushki ONE, nuestra solución regional para pagos de venta presente (Card Present).

Marcas soportadas

¿Qué es Kushki ONE?

Kushki ONE es la solución integral de pagos de venta presente 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.

Permite recibir pagos usando directamente la aplicación de cobro instalada en la terminal, o conectando tu software de punto de venta (POS) a través de nuestra API. Puede operar desde una caja, tablet, computador u otro dispositivo con conexión a red, o desde una app instalada en la misma terminal.

¿Cómo utilizar esta guía?

Esta documentación se divide en dos rutas principales según tu rol:

• Hardware soportado (Sunmi P3, P2 SE)
• Kushki ONE Payment App
• Operaciones: Venta, Devolución, Post Propina, División de cuenta
• Modos: Standalone y Semi-Integrado

• ¿Qué es Kushki ONE Connect?
• Topologías: Nube, Red Local y Localhost
• Seguridad y autenticación (Hash / Private-Credential-Id)
• Requisitos de red e infraestructura
• Flujo completo de la transacción

Ruta 1: Para Operadores y Administradores de Comercio

Hardware Soportado

La arquitectura de Kushki ONE es agnóstica respecto al hardware; todos sus componentes son interoperables. Sin embargo, para garantizar el máximo rendimiento y estabilidad, la solución está certificada únicamente para los siguientes dispositivos SmartPOS:

Sunmi P3 — Características adicionales

• Impresora integrada: Impresora térmica de alta velocidad (70 mm/s).
• Batería: Litio extraíble (7.7 V / 2630 mAh). Hasta 13 días en standby.
• Diseño: Ultradelgado (17 mm) con recubrimiento antihuellas, pensado para entornos de alto tráfico.

Sunmi P2 SE — Características adicionales

• Movilidad: Diseño compacto y ligero, ideal para pagos a la mesa, retail o delivery.
• Lector de códigos: Motor de escaneo profesional para códigos de barras y QR, incluso deteriorados.
• Durabilidad: Resistente a polvo, salpicaduras y caídas. Batería optimizada para turnos largos.

Kushki ONE Payment App

Es la aplicación de cobro instalada directamente en la terminal física. Su interfaz intuitiva permite a los operadores ejecutar y gestionar el ciclo de vida completo de un pago sin necesidad de un POS externo (modo Standalone).

Catálogo de Operaciones

Modos de Operación de la Terminal

Existen dos modalidades:

Modo Standalone (Independiente)

• La terminal funciona 100% autónoma, sin integración con sistemas externos.
• El operador usa la pantalla táctil como calculadora. Todo el ciclo (cobro, devoluciones) se realiza en el dispositivo.
• Ideal para: comercios sin sistema POS externo.

Modo Semi-Integrado

• Requerido para conectar tu POS con la terminal vía Kushki ONE Connect (API).
• La interfaz se bloquea en estado “Esperando llamada”. Solo reacciona a comandos enviados desde tu software de caja.
• Ideal para: integración con POS propio (Ruta 2).

Ruta 2: Para Desarrolladores e Integradores (Kushki ONE Connect)

¿Qué es Kushki ONE Connect?

Kushki ONE Connect es nuestra capa de integración vía API que permite a tu software de caja interactuar directamente con la terminal física cuando está en modo Semi-Integrado. Tu sistema envía los comandos financieros (Venta, Devolución, etc.) a la aplicación de pago, eliminando la digitación manual y los errores humanos.

La premisa central es simple: es la misma API independientemente del canal que uses para conectar tu POS con la terminal. Lo único que varía entre las tres topologías es la vía de comunicación, no la estructura de los endpoints ni los payloads.

Topologías de Integración (Vías de Comunicación)

Kushki ONE Connect ofrece tres vías para enviar peticiones a la terminal. La siguiente tabla resume las diferencias antes de entrar al detalle:

*La comunicación interna (localhost) no requiere red entre las apps, pero el dispositivo sí necesita salida a internet para procesar la transacción financiera.

1. Integración vía Nube (Internet)

Tu POS envía la petición a los servidores de Kushki. Estos identifican a qué terminal va dirigida la orden y la envían a través de internet.

• Caso de uso ideal: Cloud POS, comercios multi-sede, o entornos donde la caja y la terminal están en redes distintas.
• Ventaja: No requiere que el POS y la terminal compartan la misma red local.
• Consideración: Requiere conexión a internet estable tanto en la caja como en la terminal.

2. Integración vía Red Local (Wi-Fi / LAN)

Tu POS envía una petición HTTP directamente a la IP local de la terminal, sin triangular con servidores externos. Esto reduce drásticamente la latencia.

• Caso de uso ideal: Supermercados, retail o restaurantes donde POS y terminales operan bajo la misma red Wi-Fi o LAN cerrada.
• Ventaja: Menor latencia al no depender de internet para la comunicación interna entre POS y terminal.
• Consideración clave: La terminal debe tener idealmente IP estática o con reserva DHCP. Si la IP cambia, el POS pierde la comunicación, por lo que será necesario tenerlo en consideración en el caso de IPs que cambien

¿Cómo saber la IP de tu terminal?

Si utilizas la Ruta 2 (Red Local), sigue estos pasos en el dispositivo:

• Entra a Ajustes > Wi-Fi.
• Toca el nombre de la red conectada.
• Despliega Opciones avanzadas.
• Desliza hacia abajo hasta encontrar el campo Dirección IP.

3. Integración en el Mismo Dispositivo (Localhost / App-to-App)

Aplica cuando cuentas con tu propia app POS 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 complejos flujos de integración App-to-App tradicionales. Usa llamadas HTTP estándar de forma instantánea.
• Sin red interna requerida: La comunicación entre las dos apps no necesita Wi-Fi ni Ethernet.
• Internet sigue siendo necesario: El dispositivo siempre requiere salida a internet para procesar la transacción con Kushki.

Flujo Completo de una Transacción

El siguiente flujo describe la interacción entre todos los componentes desde que se inicia una intención de cobro hasta recibir la respuesta:

1. Generación de la solicitud: El sistema de caja del comercio (POS) genera la solicitud enviando el monto a cobrar vía API hacia el ecosistema de pagos.
2. Decisión y Enrutamiento: Kushki ONE Connect recibe la solicitud y toma una decisión de enrutamiento basándose en la configuración que haya elegido el comercio; de esta manera, enruta la petición hacia el dispositivo físico, ya sea a través de la Nube o mediante la Red Local.
3. Recepción en la terminal y captura de datos: Kushki ONE Connect envía la petición de cobro a la Terminal SmartPOS. La terminal recibe la petición, muestra el monto a pagar en pantalla y lee la tarjeta del cliente.
4. Procesamiento de la transacción: Una vez leídos los datos, la terminal envía la información hacia Kushki, quien se encarga finalmente de procesar la transacción financiera.

Seguridad en la Comunicación

Independientemente de la topología elegida, todas las comunicaciones hacia Kushki ONE Connect deben autenticarse enviando un Hash de seguridad generado a partir de tu Private-Credential-Id.

Requisitos de Red e Infraestructura

Para garantizar que la comunicación entre tu POS y la terminal sea rápida, estable y segura:

1. Configuración de Red Local (LAN / Wi-Fi)

Aplica únicamente si utilizas 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 MAC). Si la IP cambia dinámicamente, el POS perderá la comunicación.
• Puerto de comunicación: El firewall interno debe permitir tráfico bidireccional en el puerto TCP de escucha de la terminal 6868.
• Seguridad Wi-Fi: Las terminales certificadas soportan redes con protocolos WPA2-PSK / WPA3.

2. Dominios Permitidos (Allowlisting)

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 los siguientes dominios en el puerto 6868 (HTTPS):

• Procesamiento de pagos: [DOMINIO_API_PRODUCCION — ej. api.kushkipagos.com]
• Gestión de terminales (DMS y Store): [DOMINIO_DMS_PRODUCCION — ej. tms.kushkipagos.com]
• Servicios de hardware y telemetría Sunmi: [DOMINIO_SUNMI — si aplica]

Próximos pasos

Una vez completada la configuración base, estás listo para integrar los servicios de interacción con la terminal: