Formato de montos en Kushki ONE

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

🚧 Early Release — Beta

Este producto está en acceso temprano. Los parámetros, estructuras de respuesta y comportamientos pueden cambiar sin previo aviso. No uses esta versión en producción sin coordinarlo previamente con el equipo de integraciones de Kushki.

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 Perú operas en soles (PEN), que usan dos decimales.

La moneda no viaja en el request

El objeto amount no incluye un campo de moneda: la terminal resuelve la moneda desde su propia configuración. El equipo de integraciones confirma cuál usa tu terminal durante el onboarding.

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.

Para cobrar	Envías
12.44 PEN	`1244`
12.00 PEN	`1200`
100.00 PEN	`10000`
118.00 PEN	`11800`

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. Viaja en `/charge` y `/authorization`; en `/pos_tip` es el monto de la operación. Si la funcionalidad no está habilitada la terminal la ignora — solicítala en soporte@kushkipagos.com

El campo se llama iva aunque el impuesto sea el IGV

En Perú el impuesto general a las ventas es el IGV, pero el campo de la API conserva el nombre iva en todos los mercados. Envía el monto del IGV en ese campo.

Ejemplo completo

Venta de 100.00 PEN con IGV del 18%.

Componente	Valor	Unidad mínima
`subtotal_iva`	100.00 PEN	`10000`
`iva`	18.00 PEN	`1800`
Total cobrado	118.00 PEN	`11800`

{
  "amount": {
    "iva": 1800,
    "subtotal_iva": 10000,
    "subtotal_iva0": 0,
    "extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 }
  },
  "client_transaction_id": "5e6f7a8b-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

No uses aritmética de punto flotante

En la mayoría de los lenguajes, 12.44 * 100 da 1243.9999999999998, que al truncar queda en 1243. Subcobras un centavo y tu conciliación se rompe de forma intermitente. Usa enteros o un tipo decimal.

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

JavaScript

Python

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	El evento no copia tu request: `operation.amount` omite `iva` y `subtotal_iva` cuando van en cero y agrega `currency` y `tip`

Valida antes de enviar

Verifica que los campos de amount sumen el total que esperas cobrar antes de llamar a la API. Un monto mal armado es la causa más frecuente de diferencias en conciliación.

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

El mismo entero es distinto dinero

1244 representa 12.44 MXN en México y 1.244 COP en Colombia: una diferencia de 100 veces. Como el payload no lleva campo de moneda, resolver esto queda enteramente de tu lado.

Consulta el currency_code configurado en cada terminal y deriva la cantidad de decimales a partir de ahí, nunca a partir de la sucursal o del idioma del usuario.

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.

Formato de montos en Kushki ONE

Tu moneda y sus decimales#

La regla de conversión#

Cómo se compone el monto#

Ejemplo completo#

Venta sin desglose de impuestos#

Convierte a la unidad mínima#

Errores frecuentes#

Si operas en varios mercados#