Formato de montos en Kushki ONE

04 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 usan dos decimales.

La regla de conversión

Los últimos dos dígitos del entero son siempre la parte decimal. Cuando el monto no tiene fracción, agrega igualmente los dos ceros.

Cómo se compone el monto

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

Ejemplo completo

Cuenta de restaurante: 20,000.00 COP en alimentos, IVA del 19% y una propina de 2,000.00 COP.

{
  "amount": {
    "iva": 380000,
    "subtotal_iva": 2000000,
    "subtotal_iva0": 0,
    "tip": 200000,
    "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 sin perder centavos

Pasa el valor como cadena de texto, no como número decimal: Decimal(12.44) hereda el mismo error binario que intentas evitar.

const DECIMALES = { COP: 2, 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", "COP"); // 1244
aUnidadMinima("1244", "CLP");  // 1244

from decimal import Decimal

DECIMALES = {"COP": 2, "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", "COP")  # 1244
a_unidad_minima("1244", "CLP")   # 1244

Errores frecuentes

Si operas en varios mercados

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