Realiza cobros con Kushki One

09 septiembre 2026

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

Cómo funciona

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

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

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.

Operaciones disponibles

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.

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.

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.

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:

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.

Cómo leer el status HTTP

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.

Vigencia de la autorización

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

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.

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.

const payload = {
  amount: {
    iva: 0, subtotal_iva: 0, subtotal_iva0: 12000,
    extra_taxes: { airport_tax: 0, iac: 0, ice: 0, travel_agency: 0 },
  },
  client_transaction_id: crypto.randomUUID(),
};

const res = await fetch(`${BASE_URL}/sync/charge`, {
  method: "POST",
  headers: buildHeaders(payload),
  body: JSON.stringify(payload),
});
const data = await res.json();
console.log(data.approved, data.rawResponse.transaction_reference);

import uuid, requests

payload = {
    "amount": {
        "iva": 0, "subtotal_iva": 0, "subtotal_iva0": 12000,
        "extra_taxes": {"airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0},
    },
    "client_transaction_id": str(uuid.uuid4()),
}

res = requests.post(f"{BASE_URL}/sync/charge",
                    headers=build_headers(payload), json=payload)
data = res.json()
print(data["approved"], data["rawResponse"]["transaction_reference"])

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.