Formato de montos en Kushki ONE
🚧 Early Release — Beta
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.Tu moneda y sus decimales
MXN), que usan dos decimales.La moneda no viaja en el request
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
| Para cobrar | Envías |
|---|---|
| 12.44 MXN | 1244 |
| 12.00 MXN | 1200 |
| 1,000.00 MXN | 100000 |
| 1,160.00 MXN | 116000 |
Cómo se compone el monto
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 |
Ejemplo completo
| Componente | Valor | Unidad mínima |
|---|---|---|
subtotal_iva | 1,000.00 MXN | 100000 |
iva | 160.00 MXN | 16000 |
| Total cobrado | 1,160.00 MXN | 116000 |
{
"amount": {
"iva": 16000,
"subtotal_iva": 100000,
"subtotal_iva0": 0,
"extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 }
},
"client_transaction_id": "3c4d5e6f-1111-4000-8000-aabbccddeeff"
}Venta sin desglose de impuestos
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
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.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
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
| 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.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.Modificado en 2026-10-13 20:10:29