Primeros Pasos

10 septiembre 2026

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

¿Qué es Kushki ONE?

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.

Mercados y monedas

¿Cómo utilizar esta guía?

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

Ruta 1: Para Operadores y Administradores de Comercio

Hardware Soportado

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.

Sunmi P3

• Impresora integrada: térmica de alta velocidad, 70 mm/s.
• Batería: litio extraíble de 7.7 V y 2,630 mAh. Hasta 13 días en espera.
• Diseño: ultradelgado de 17 mm con recubrimiento antihuellas, pensado para entornos de alto tráfico.

Sunmi P2 SE

• Movilidad: diseño compacto y ligero, ideal para pagos en la mesa, retail o entrega a domicilio.
• 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 permite al operador ejecutar y gestionar el ciclo de vida completo de un pago sin necesidad de un punto de venta externo.

Catálogo de Operaciones

Modos de Operación de la Terminal

Modo Standalone

• La terminal funciona de forma autónoma, sin integración con sistemas externos.

• El operador usa la pantalla táctil como calculadora. Todo el ciclo se realiza en el dispositivo.

• Ideal para comercios sin un sistema de punto de venta externo. Modo Semi-Integrado

• Requerido para conectar tu punto de venta con la terminal mediante Kushki ONE Connect.

• La interfaz se bloquea en estado “Esperando llamada” y solo reacciona a los comandos que envía tu software de caja.

• Ideal para integraciones con un punto de venta propio.

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

¿Qué es Kushki ONE Connect?

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.

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

1. Integración vía Nube

Tu caja envía la petición a los servidores de Kushki, que identifican a qué terminal va dirigida la orden y la enrutan por internet.

• Ventaja: no requiere que la caja y la terminal compartan la misma red local.
• Consideración: requiere conexión a internet estable en ambos extremos. | Entorno | URL base | |---|---| | UAT | https://uat-cloudt.kushkipagos.com | | Producción | https://cloudt.kushkipagos.com |

Todos los endpoints incluyen el número de serie de la terminal en la ruta:

https://{host}/terminal/v1/{terminalSerial}/sync/{operación}

2. Integración vía Red Local

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.

¿Cómo saber la IP de tu terminal?

1. Entra a Ajustes y luego a Wi-Fi.
2. Pulsa el nombre de la red conectada.
3. Despliega Opciones avanzadas.
4. Desplázate hasta el campo Dirección IP.

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.

Seguridad en la Comunicación

Todas las comunicaciones hacia Kushki ONE Connect se autentican con una firma que calculas a partir de tu Business-Code.

El mecanismo no cambia entre topologías: tu lógica de autenticación es la misma en Nube, Red Local y Localhost. Hay un solo mecanismo — hash + cifrado:

Requisitos de Red e Infraestructura

1. Configuración de red local

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.

2. Dominios permitidos

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:

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.

Flujo Completo de una Transacción

1. 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.

Verifica tu conexión

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.

// Red Local
const res = await fetch("http://192.168.1.50:6868/terminal/v1/sync/local/test", {
  headers: buildHeaders({}),
});

console.log(res.status, await res.json());
// 200  { success: true, data: {} }

import requests

# Red Local
res = requests.get("http://192.168.1.50:6868/terminal/v1/sync/local/test",
                   headers=build_headers({}))

print(res.status_code, res.json())
# 200  {'success': True, 'data': {}}

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.

Próximos pasos