Chile
Colombia
Ecuador
Peru
Realiza cobros con Kushki One
31 marzo 2026Pagos con terminal SmartPOS
La Payment API te permite procesar cobros presenciales con tarjeta desde tu sistema de caja hacia un terminal Kushki ONE (Sunmi P3, Sunmi P2 SE) en modo Semi-Integrado. El terminal gestiona toda la interacción con el cliente y el chip EMV — tu sistema solo envía el monto y recibe el resultado.
Cómo funciona
Todos los endpoints comparten la misma estructura de request y respuesta independientemente de cómo conectes tu POS con la terminal. Lo que varía entre topologías es únicamente el base URL:
| Topología | Base URL |
|---|---|
| Red Local (LAN / Wi-Fi) | http://{TERMINAL_IP}:6868/terminal/v1/sync |
| Nube (Internet) — UAT | https://uat-cloudt.kushkipagos.com/terminal/v1/{terminalSerial}/sync |
| Nube (Internet) — Producción | https://cloudt.kushkipagos.com/terminal/v1/{terminalSerial}/sync |
Endpoints disponibles
| Endpoint | Método | Descripción |
|---|---|---|
/charge | POST | Cobro inmediato: autorización y captura en una sola operación |
/authorization | POST | Pre-autorización: reserva fondos sin capturarlos |
/capture | POST | Captura los fondos de una pre-autorización aprobada |
/re_authorization | POST | Extiende el monto o la vigencia de una pre-autorización activa |
/pos_tip | POST | Agrega propina a una transacción ya autorizada |
/void | POST | Anula una transacción el mismo día, antes del corte del procesador |
/refund | POST | Devuelve fondos de una transacción ya liquidada |
/abort | GET | Cancela una transacción activa en el terminal de forma inmediata |
/transaction_search_online | POST | Consulta el historial de transacciones en el adquirente (Kushki) |
/transaction_search_local | POST | Consulta el historial almacenado localmente en el terminal, sin necesidad de internet |
Flujos de pago
Cobro directo
El flujo más común para comercios de retail. El terminal activa el lector de tarjeta y bloquea hasta que el cliente completa la interacción y el adquirente responde.
POST /charge → 200 OK (approved: true)
Pre-autorización y captura
Ideal para hoteles, gasolineras y restaurantes de cuenta abierta, donde el monto final no se conoce al momento de la interacción con el cliente.
POST /authorization → guarda transaction_reference↓ (días después)POST /capture → usando el transaction_reference guardado
Vigencia de pre-autorizaciones
| 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 ser hasta el 110% del monto total autorizado (autorización + re-autorizaciones). Solo se permite una captura por ciclo de autorización.
Conceptos clave
client_transaction_id
Identificador UUID v4 generado por tu sistema de caja. Actúa como clave de idempotencia: si el terminal ya procesó ese ID, detecta el duplicado y evita el doble cobro. Genera uno único por intento y reutilízalo solo si estás reintentando exactamente la misma operación.
transaction_reference
Identificador generado por Kushki y retornado en la respuesta de cada transacción aprobada. Es el vínculo entre operaciones del mismo ciclo de vida. Persiste este valor en tu sistema — sin él no puedes capturar, re-autorizar, anular ni devolver.
Estructura de monto
Todos los endpoints que involucran un monto usan el mismo objeto amount.
| Campo | Tipo | Req. | Endpoints | Descripción |
|---|---|---|---|---|
iva | number | ✅ | Todos | Impuesto al valor agregado. Usa 0 si no aplica |
subtotal_iva | number | ✅ | Todos | Subtotal que incluye IVA |
subtotal_iva0 | number | ✅ | Todos | Subtotal exento de IVA. Monto principal de la transacción |
tip | number | ❌ | Solo /pos_tip | Monto de propina. No enviar en /charge ni /authorization |
extra_taxes | object | ❌ | /charge, /authorization, /pos_tip | Impuestos adicionales: airport_tax, iac, ice, travel_agency |
Autenticación
Incluye estos headers en cada request:
| Header | Descripción |
|---|---|
Authorization | Firma HMAC-SHA256 calculada sobre el cuerpo del request usando tu Private-Credential-Id |
timestamp | Unix timestamp en milisegundos |
Anulaciones y devoluciones
| Operación | Cuándo usarla |
|---|---|
| Void | Mismo día de la transacción, antes del horario de corte del procesador |
| Refund | Una vez que la transacción ya fue liquidada, o si se superó el horario de corte |
Referencia de endpoints
Charge — Cobro directo
POST /terminal/v1/sync/charge
Autorización y captura en una sola operación. El terminal activa el lector de tarjeta al recibir el request y bloquea hasta que el cliente completa la interacción. Úsalo como flujo estándar para la mayoría de los comercios de retail.
Authorization — Pre-autorización
POST /terminal/v1/sync/authorization
Reserva fondos en la cuenta del tarjetahabiente sin capturarlos. Usa este flujo cuando el monto final no se conoce al momento de la interacción con el cliente: hoteles, gasolineras, restaurantes de cuenta abierta.
Capture — Captura
POST /terminal/v1/sync/capture
Cobra los fondos reservados por una autorización previa. Requiere el transaction_reference retornado en la respuesta de /authorization. El monto a capturar puede ser igual o menor al autorizado, hasta un máximo del 110% del total (autorización + re-autorizaciones).
Re-authorization — Re-autorización
POST /terminal/v1/sync/re_authorization
Extiende el monto reservado o la vigencia de una pre-autorización activa antes de la captura. Se puede ejecutar múltiples veces sobre la misma autorización base. Envía subtotal_iva0: 0 para extender solo la vigencia sin modificar el monto.
Post-tip — Propina posterior
POST /terminal/v1/sync/pos_tip
Agrega una propina a una transacción que ya fue autorizada. Úsalo en flujos donde el cliente decide el monto de propina después del cobro inicial. Envía el monto de propina en amount.tip.
Void — Anulación
POST /terminal/v1/sync/void
Cancela una transacción el mismo día antes del corte del procesador. El monto nunca se debita de la cuenta del cliente. Espera al menos 1 minuto después de la transacción original antes de ejecutar un void.
Refund — Devolución
POST /terminal/v1/sync/refund
Reembolsa una transacción ya capturada y liquidada. Puede ejecutarse días después del cobro original. Requiere el transaction_reference de la respuesta del cobro o captura original.
Abort — Cancelar transacción activa
GET /terminal/v1/sync/abort
Cancela de forma inmediata cualquier transacción en progreso en el terminal. No requiere cuerpo en el request. Llámalo solo mientras una transacción esté activa — después de que completó (aprobada o declinada) retorna 409 Conflict.
Transaction Search — Consulta de historial
Kushki ONE ofrece dos variantes de búsqueda según el origen de los datos:
POST /terminal/v1/sync/transaction_search_online
Consulta el historial de transacciones directamente en el adquirente (Kushki). Retorna los datos más completos y actualizados. Requiere conexión a internet. Los resultados son paginados y se pueden filtrar por tarjeta, rango de fechas o tipo de operación.
POST /terminal/v1/sync/transaction_search_local
Consulta el historial almacenado localmente en la terminal. Útil para
reconciliación offline o cuando el backend del adquirente no está disponible.
No incluye el campo transaction_type como filtro.
Buenas prácticas
- Genera un
client_transaction_idúnico por intento. Reutilízalo solo en reintentos de la misma operación lógica. - Persiste
transaction_referenceen tu base de datos inmediatamente al recibir la respuesta de autorización. - Verifica que los campos de
amountsumen correctamente antes de enviar el request. - Registra el
client_transaction_idenviado y el código HTTP recibido en cada operación para facilitar la conciliación y el soporte. - Usa
abortsolo mientras una transacción está activa en el terminal — llamarlo después de que completó retorna409 Conflict.
Catálogo de errores
Consulta los modelos de error, códigos y acciones correctivas recomendadas para todos los endpoints de la Payment API en el Catálogo de errores de Kushki ONE.