Realiza cobros con Kushki One

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

La Payment API te permite procesar cobros presenciales con tarjeta desde tu sistema de caja hacia una terminal Kushki ONE en modo semi-integrado. La terminal gestiona toda la interacción con el tarjetahabiente y el chip EMV: tu sistema envía el monto y recibe el resultado.

Requisitos

Antes de empezar

Una terminal Sunmi P3 o P2 SE vinculada a tu comercio y operando en modo semi-integrado.

Tu Business-Code, entregado por el equipo de integraciones.

El terminalSerial de cada dispositivo. Lo entrega el equipo de integraciones durante el onboarding.

La topología de conexión definida: Nube, Red Local o Localhost.

Cómo funciona

Los payloads y los headers son idénticos entre topologías. Las rutas no — cambian tres cosas, y están listadas debajo de los base URL.

Topología	Base URL
Red Local (LAN / Wi-Fi)	`http://{TERMINAL_IP}:6868/terminal/v1` o `https://{TERMINAL_IP}:6869/terminal/v1`
Nube (Internet) — UAT	`https://uat-cloudt.kushkipagos.com/terminal/v1/{terminalSerial}`
Nube (Internet) — Producción	`https://cloudt.kushkipagos.com/terminal/v1/{terminalSerial}`

Qué cambia entre Nube y red local, más allá del base URL:

Diferencia	Red Local	Nube
Método de `/abort`	GET, en ambos modos	POST, solo síncrono
Abort asíncrono	Disponible	No existe
Rutas de impresión	`/terminal/v1/print`	`/{terminalSerial}/sync/print`

¿No sabes qué topología usar?

Revisa Topologías de integración en Primeros pasos antes de continuar.

Modos síncrono y asíncrono

Cada operación que requiere interacción con la terminal existe en dos variantes, bajo prefijos de ruta distintos.

Modo	Prefijo	Comportamiento	Dónde llega el resultado
Síncrono	`/sync/`	Mantiene la conexión abierta hasta que el adquirente responde	En la respuesta HTTP
Asíncrono	`/async/`	Responde de inmediato con un acuse `TERMINAL_ACKNOWLEDGED`. No bloquea	Solo por webhook

Cuándo usar el modo asíncrono

Un cobro con tarjeta presente depende de la interacción de una persona y suele exceder los 15 segundos que tolera la mayoría de las arquitecturas de caja. Si tu sistema no puede mantener una conexión abierta ese tiempo, usa el modo asíncrono y consume los eventos por webhook.

Operaciones disponibles

Operación	Ruta	Síncrono	Asíncrono	Qué hace
Venta	`/charge`	✅	✅	Cobro inmediato: autoriza y captura en un solo paso
Autorización	`/authorization`	✅	✅	Reserva fondos sin capturarlos
Captura	`/capture`	✅	✅	Cobra los fondos de una autorización aprobada
Re-autorización	`/re_authorization`	✅	✅	Extiende el monto o la vigencia de una autorización activa
Post propina	`/pos_tip`	✅	✅	Agrega propina a una transacción ya autorizada
Reversa	`/void`	✅	✅	Reversa una transacción: anulación dentro del día calendario, devolución pasado el corte
Cancelar	`/abort`	✅	✅	Cancela una operación en curso en la terminal
Consulta en línea	`/transaction_search_online`	✅	—	Consulta el historial en el adquirente
Consulta local	`/transaction_search_local`	✅	—	Consulta el historial almacenado en la terminal

Diferencias de /abort entre topologías

En Red Local, /abort usa el método GET y está disponible en ambos modos. En Nube usa POST y solo existe en modo síncrono.

Conceptos clave

client_transaction_id

Identificador UUID v4 que genera tu sistema de caja. Funciona como clave de idempotencia: si la terminal ya procesó ese identificador, detecta el duplicado y evita el doble cobro.

Genera uno nuevo por cada venta. Reutilízalo solo cuando estés reintentando exactamente la misma operación tras un fallo de red.

transaction_reference

Identificador que genera Kushki y devuelve en la respuesta de cada transacción aprobada, dentro de rawResponse. Es el vínculo entre operaciones del mismo ciclo de vida.

Persiste este valor

Guarda el transaction_reference en tu base de datos en el momento en que recibes la respuesta. Sin él no puedes capturar, re-autorizar, anular ni devolver esa transacción.

Estructura del monto

El objeto amount se envía en unidades mínimas de la moneda, como número entero. La cantidad de decimales depende del país.

Construye el monto correctamente

Un monto mal armado es la causa más frecuente de cobros incorrectos. Revisa Formato de montos en Kushki ONE antes de tu primera integración.

Campos opcionales, por operación

Estos son los únicos campos opcionales, y cada uno pertenece a operaciones específicas. Se comportan igual en síncrono y asíncrono.

Campo	Tipo	Aplica a	Qué hace
`amount.tip`	entero	`/charge` y `/authorization`	Agrega propina. Se puede fijar desde la preautorización, no solo al cobrar
`cashback_amount`	entero	`/charge`	Retiro de efectivo adicional a la compra. Envía `0` si no aplica
`deferred` / `query_deferred`	objeto / booleano	`/charge`	Cuotas. El campo y su forma cambian por país — ver abajo
`omit_card`	booleano	`/capture`, `/re_authorization` y `/void`	Con `true` la operación se ejecuta sin pedir la tarjeta
`metadata`	objeto	`/charge`, `/authorization` y `/pos_tip`	Trazabilidad libre: `reference`, `customer_email`, `device`

En /pos_tip, amount.tip no es un campo opcional — es el monto de la operación.

omit_card es lo que hace funcionar el caso de hotelería: extender o capturar una preautorización cuando el cliente ya no está en el mostrador.

Las cuotas cambian por país

Los dos campos son mutuamente excluyentes y nunca viajan juntos:

País	Campo	Forma	Máximo
México	`query_deferred`	Booleano. La terminal ofrece Meses Sin Intereses al tarjetahabiente después de leer la tarjeta; tu POS no elige los meses	—
Chile	`deferred`	`months`, más `credit_type: "03"` para cuotas comercio — string, no número	12 con `credit_type`, 48 sin él
Colombia	`deferred`	Solo `months`. `credit_type` no aplica	48
Perú	`deferred`	Solo `months`. `credit_type` no aplica	2–48, todas las redes

Si una capacidad no está habilitada para tu terminal, la terminal ignora el campo en vez de rechazar el request — así que un 200 no prueba que la propina se aplicó. Para habilitarla, escribe a soporte@kushkipagos.com.

Cobertura en Beta

Solo /charge se ejercitó de punta a punta con estos campos, en síncrono y asíncrono. amount.tip en /authorization y omit_card en sus seis combinaciones están definidos pero sin ejercitar — vas a ser el primero en pisarlos.

Cómo leer el status HTTP

En los endpoints de pago el status es siempre 200

Pase lo que pase, los endpoints de pago responden 200. El status confirma que la terminal procesó tu petición — no que la operación haya salido bien. Evalúa siempre el cuerpo de la respuesta. Un POS que decide por response.ok trata como éxito una terminal ocupada, un PIN vencido y una cancelación del tarjetahabiente.

Los endpoints de impresión son la excepción: devuelven códigos reales, 404 si el job no existe y 409 mientras la cola está ocupada.

Flujos de pago

Venta directa

El flujo más común en retail. La terminal activa el lector al recibir el request y espera a que el tarjetahabiente complete la interacción.

POST /sync/charge  →  200 OK (approved: true)

Pre-autorización y captura

Úsalo cuando el monto final no se conoce al momento de la interacción: hoteles, estaciones de servicio, restaurantes de cuenta abierta.

POST /sync/authorization  →  guarda transaction_reference
        ↓  (horas o días después)
POST /sync/capture  →  con el transaction_reference guardado

Puedes intercalar /re_authorization para ampliar el monto reservado o extender el plazo antes de capturar. Envía subtotal_iva0: 0 para extender solo la vigencia.

Una re-autorización se puede cancelar

Después de cancelar una re-autorización, la transacción no acepta re-autorizaciones adicionales.

Vigencia de la autorización

Tipo de tarjeta	Vigencia desde la autorización
Débito (Visa / Mastercard)	7 días
Crédito (Visa / Mastercard)	28 días

La captura puede llegar hasta el 110% del total autorizado, sumando la autorización y todas las re-autorizaciones no canceladas. Se permite una sola captura por ciclo.

Propina posterior

Agrega una propina a una transacción ya autorizada. Úsalo cuando el tarjetahabiente decide el monto después del cobro inicial. Envía el valor en amount.tip junto al transaction_reference original.

Reversa

Hay un solo endpoint de reversa, /void, y el sistema decide en qué se convierte la operación según cuándo la llamas. El corte es a las 23:59 hora local en los cuatro países: dentro del mismo día calendario la reversa es una anulación; a partir de la medianoche entra al ciclo de devolución y tarda días hábiles.

Espera al menos 1 minuto

Espera al menos 1 minuto después de la transacción original antes de reversarla, o falla sin motivo aparente.

El tipo que devuelve la búsqueda de transacciones dice qué terminó pasando:

Tipo	Qué significa
VOID	Llamaste `/void` el mismo día calendario. Anulación — el tarjetahabiente no ve el cargo
REFUND	Llamaste `/void` después del corte. Entró al ciclo de devolución y tarda días hábiles
REVERSE	No lo pediste. Lo genera la plataforma sola cuando falla la comunicación con la terminal

Un REVERSE que no pediste no es un error

Tu POS puede encontrar un REVERSE en la búsqueda sin haber llamado nada. Es cómo la plataforma resuelve un cobro cuya comunicación se cortó a mitad de camino — el escenario en que el POS cobra, se cae el enlace y nadie sabe si la transacción quedó.

Autenticación

Kushki ONE usa un solo mecanismo — hash + cifrado — y es el mismo en Nube, red local y localhost: Authorization: Basic <SHA512>, timestamp en segundos, y el cuerpo como el sobre cifrado {"data":"<iv_hex>:<cipher_hex>"}.

Todos los payloads de esta página son el texto plano que se cifra, no lo que viaja por la red. El flujo completo, la cadena de derivación de claves y el árbol de diagnóstico están en Autenticación y cifrado de requests.

Red Local y Localhost: envía el header encrypted_http_communication

En Red Local y Localhost, cada request lleva además el header encrypted_http_communication: true, en UAT y en producción. Nube no lo requiere. Detalle en Autenticación y cifrado de requests.

No confundas Business-Code con 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 no se usa para firmar requests.

Configura un timeout de cliente amplio

Un cobro presencial espera a una persona. Usa al menos 90 segundos en Nube, donde el relay agrega latencia sobre el tiempo de procesamiento de la propia terminal, y 15 segundos en red local. Un timeout de 30 segundos en Nube produce fallos fantasma sobre cobros que en realidad se aprobaron.

Ejemplo de venta directa

Cobro de 12000 unidades mínimas sin desglose de impuestos. Lo que representa depende de los decimales del país — revisa Formato de montos en Kushki ONE antes de tu primera integración.

JavaScript

Python

Buenas prácticas

Genera un client_transaction_id único por venta y reutilízalo solo en reintentos de la misma operación.

Persiste el transaction_reference en cuanto recibas la respuesta de autorización o cobro.

Verifica que los campos de amount sumen el total esperado antes de enviar el request.

Registra el client_transaction_id y el código HTTP de cada operación para facilitar la conciliación y el soporte.

Usa /abort solo mientras una transacción está activa en la terminal. Llamarlo después de que completó devuelve 409 Conflict.

Firma exactamente los mismos bytes que envías: serializa una vez, firma esa cadena y envía esa misma cadena.

Servicios asíncronos y webhooks

Integra el modo asíncrono: estados del ciclo de vida, estructura de los eventos y política de reintentos de entrega.

Catálogo de errores

Consulta los modelos de error, códigos por categoría y acciones correctivas para todos los endpoints.

Realiza cobros con Kushki One

Requisitos#

Cómo funciona#

Modos síncrono y asíncrono#

Operaciones disponibles#

Conceptos clave#

client_transaction_id#

transaction_reference#

Estructura del monto#

Campos opcionales, por operación#

Las cuotas cambian por país#

Cómo leer el status HTTP#

Flujos de pago#

Venta directa#

Pre-autorización y captura#

Vigencia de la autorización#

Propina posterior#

Reversa#

Autenticación#

Ejemplo de venta directa#

Buenas prácticas#