Formato de montos en Kushki ONE

26 agosto 2026

Aprende a construir el campo amount en unidades mínimas según la moneda de tu país y evita cobros con el monto equivocado

Todos los endpoints de Kushki ONE Connect que involucran dinero comparten el mismo objeto amount. Antes de construir tu primer request, necesitas entender una sola regla: los montos se envían como números enteros, en la unidad mínima de la moneda.

Nunca envíes puntos, comas, espacios ni ningún otro separador.

Tu moneda y sus decimales

En Colombia operas en pesos colombianos (COP), que no usan decimales.

La regla de conversión

El valor se envía tal cual, sin agregar ceros.

Para cobrar	Envías
1.244 COP	`1244`
12.000 COP	`12000`
25.800 COP	`25800`
1.000.000 COP	`1000000`

Cómo se compone el monto

El monto cobrado es la suma de todos los campos del objeto amount.

Campo	Qué representa
`subtotal_iva`	Porción de la venta afecta a impuesto
`iva`	Monto del impuesto sobre esa porción
`subtotal_iva0`	Porción exenta. Usa solo este campo cuando la venta no tiene desglose
`extra_taxes`	Impuestos de giros específicos: `airport_tax`, `iac`, `ice`, `travel_agency`. Envía `0` cuando no aplican
`tip`	Propina. Requiere la funcionalidad habilitada en el DMS

Ejemplo completo

Cuenta de restaurante: 20.000 COP en alimentos, IVA del 19% y una propina de 2.000 COP.

Componente	Valor	Unidad mínima
`subtotal_iva`	20.000 COP	`20000`
`iva`	3.800 COP	`3800`
`tip`	2.000 COP	`2000`
Total cobrado	25.800 COP	`25800`

{
  "amount": {
    "iva": 3800,
    "subtotal_iva": 20000,
    "subtotal_iva0": 0,
    "tip": 2000,
    "extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 }
  },
  "client_transaction_id": "7f8e9d0c-1111-4000-8000-aabbccddeeff"
}

Venta sin desglose de impuestos

Cuando no detallas impuestos, coloca el monto completo en subtotal_iva0:

{
  "amount": {
    "iva": 0,
    "subtotal_iva": 0,
    "subtotal_iva0": 11800,
    "extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 }
  },
  "client_transaction_id": "1a2b3c4d-3333-4000-8000-112233445566"
}

Convierte a la unidad mínima

Javascript
Python

const DECIMALES = { COP: 0, MXN: 2, PEN: 2, CLP: 0 };

function aUnidadMinima(valor, moneda) {
  const [entero, frac = ""] = String(valor).split(".");
  const exp = DECIMALES[moneda];
  return Number(entero + frac.padEnd(exp, "0").slice(0, exp));
}

aUnidadMinima("12.44", "MXN"); // 1244
aUnidadMinima("1244", "COP");  // 1244

from decimal import Decimal

DECIMALES = {"COP": 0, "MXN": 2, "PEN": 2, "CLP": 0}

def a_unidad_minima(valor: str, moneda: str) -> int:
    exp = DECIMALES[moneda]
    return int(Decimal(valor).scaleb(exp).to_integral_value())

a_unidad_minima("12.44", "MXN")  # 1244
a_unidad_minima("1244", "COP")   # 1244

Errores frecuentes

Error	Qué pasa	Cómo lo evitas
Enviar el monto con decimales	El cobro sale con el monto equivocado o el request se rechaza	Convierte a unidad mínima antes de enviar
Rellenar con `00` una moneda sin decimales	Cobras 100 veces más de lo debido	En `COP` y `CLP` el monto se envía tal cual
Reutilizar un helper de conversión de otro mercado	Cobras 100 veces más o de menos	Deriva los decimales por terminal, no por código
Enviar el monto como texto con separadores	Error de validación	Elimina todos los separadores y envía un entero
Convertir con punto flotante	Diferencia de un centavo en algunos montos	Usa enteros o un tipo decimal
Reutilizar un monto devuelto por un webhook	Magnitud incorrecta	Los eventos devuelven decimales (`12000.0`); los requests llevan enteros

Si operas en varios mercados

Esta sección aplica solo si tu sistema de caja atiende comercios en más de un país.

Moneda	País	Decimales
`CLP`	Chile	0
`COP`	Colombia	0
`MXN`	México	2
`PEN`	Perú	2

Acepta cobros con Kushki ONE

Con el monto correctamente construido, revisa los flujos de cobro: venta directa, pre-autorización, captura, propina posterior y anulación.

Catálogo de errores

Consulta los códigos de validación de monto y las acciones correctivas recomendadas.