ColombiaEcuadorMexicoPeru
English (EN)
Inicia Sesión
ColombiaEcuadorMexicoPeru
English (EN)
Referencia de API Centro de Soporte Estado del servicio Inicia Sesión
Referencia de APICentro de SoporteEstado del servicio
s

Realiza cobros con Kushki One

clock 25 marzo 2026

Pagos 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 se comunican directamente con el terminal a través de la red local (LAN o Wi-Fi). Tu sistema de caja actúa como orquestador: decide qué operación ejecutar y el terminal hace el trabajo de hardware.

http://TERMINAL_IP:6868/terminal/v1/sync

Reemplaza TERMINAL_IP con la IP estática o reserva DHCP asignada a tu terminal.

Endpoints disponibles

EndpointMétodoDescripción
/chargePOSTCobro inmediato: autorización y captura en una sola operación
/authorizationPOSTPre-autorización: reserva fondos sin capturarlos
/capturePOSTCaptura los fondos de una pre-autorización aprobada
/re_authorizationPOSTExtiende el monto o la vigencia de una pre-autorización activa
/pos_tipPOSTAgrega propina a una transacción ya autorizada
/voidPOSTAnula una transacción el mismo día, antes del corte del procesador
/refundPOSTDevuelve fondos de una transacción ya liquidada
/abortGETCancela una transacción activa en el terminal de forma inmediata
/transaction_searchPOSTConsulta el historial de transacciones del terminal con filtros

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 tarjetaVigencia 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:

CampoTipoReq.Descripción
ivanumber✅Impuesto al valor agregado. Usa 0 si no aplica
subtotal_ivanumber✅Subtotal que incluye IVA
subtotal_iva0number✅Subtotal exento de IVA
tipnumber❌Propina
extra_taxesobject❌Impuestos adicionales: airport_tax, iac, ice, travel_agency

Autenticación

Incluye estos headers en cada request:

HeaderDescripción
AuthorizationFirma HMAC-SHA256 calculada sobre el cuerpo del request usando tu Private-Credential-Id
timestampUnix timestamp en milisegundos

Anulaciones y devoluciones

OperaciónCuándo usarla
VoidMismo día de la transacción, antes del horario de corte del procesador
RefundUna vez que la transacción ya fue liquidada, o si se superó el horario de corte

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_reference en tu base de datos inmediatamente al recibir la respuesta de autorización.
  • Verifica que los campos de amount sumen correctamente antes de enviar el request.
  • Registra el client_transaction_id enviado y el código HTTP recibido en cada operación para facilitar la conciliación y el soporte.
  • Usa abort solo mientras una transacción está activa en el terminal — llamarlo después de que completó retorna 409 Conflict.

Referencia de API

Charge

Cobro inmediato en un solo paso. Flujo estándar para la mayoría de los comercios de retail.

Authorization (Pre-auth)

Reserva de fondos sin captura inmediata. Para hoteles, gasolineras y cuentas abiertas.

Capture

Captura los fondos reservados por una pre-autorización aprobada.

Re-authorization

Extiende el monto o la vigencia de una pre-autorización activa antes de la captura.

Post-tip

Agrega propina a una transacción ya autorizada.

Refund

Devuelve fondos de una transacción ya liquidada.

Abort

Cancela una transacción activa en el terminal de forma inmediata.