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
COP), que no usan 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 |
|---|---|
| 1.244 COP | 1244 |
| 12.000 COP | 12000 |
| 25.800 COP | 25800 |
| 1.000.000 COP | 1000000 |
Nunca rellenes un monto en pesos colombianos
00 al final de un monto en COP, cobrarás 100 veces más de lo debido. Los ceros de relleno aplican solo a monedas con dos decimales.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 | 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
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
Tu moneda no necesita conversión
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:40