Amount Format

🚧 Early Release — Beta

This product is in early access. Parameters, response structures and behaviors may change without prior notice. Do not use this version in production without coordinating with the Kushki integrations team first.

Every Kushki ONE Connect endpoint that involves money shares the same amount object. Before you build your first request, you need one rule: amounts are sent as integers, in the currency's smallest unit.

Never send periods, commas, spaces or any other separator.

Your currency and its decimals

In Mexico you operate in Mexican pesos (MXN), which use two decimals.

Currency does not travel in the request

The amount object carries no currency field: the terminal resolves the currency from its own configuration. The integrations team confirms which one your terminal uses during onboarding.

The conversion rule

The last two digits of the integer are always the fractional part. When the amount has no fraction, add the two zeros anyway.

To charge	You send
12.44 MXN	`1244`
12.00 MXN	`1200`
1,000.00 MXN	`100000`
1,160.00 MXN	`116000`

How the amount adds up

The amount charged is the sum of every field in the amount object.

Field	What it represents
`subtotal_iva`	The portion of the sale subject to tax
`iva`	The tax amount on that portion
`subtotal_iva0`	The exempt portion. Use this field alone when the sale has no breakdown
`extra_taxes`	Industry-specific taxes: `airport_tax`, `iac`, `ice`, `travel_agency`. Send `0` when they do not apply
`tip`	Tip. Travels on `/charge` and `/authorization`; on `/pos_tip` it is the amount of the operation. If the capability is not enabled the terminal ignores it — request it at soporte@kushkipagos.com

Full example

A 1,000.00 MXN sale with 16% VAT.

Component	Value	Minor units
`subtotal_iva`	1,000.00 MXN	`100000`
`iva`	160.00 MXN	`16000`
Total charged	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"
}

Sale with no tax breakdown

When you do not itemize taxes, put the whole amount in 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"
}

Convert to the minor unit

Never use floating-point arithmetic

In most languages, 12.44 * 100 returns 1243.9999999999998, which truncates to 1243. You undercharge by one cent and your reconciliation breaks intermittently. Use integers or a decimal type.

Pass the value as a string, not as a decimal number: Decimal(12.44) inherits the same binary error you are trying to avoid.

JavaScript

Python

Common mistakes

Mistake	What happens	How to avoid it
Sending the amount with decimals	The charge goes out with the wrong amount, or the request is rejected	Convert to minor units before sending
Padding a no-decimal currency with `00`	You charge a hundred times more than intended	In `COP` and `CLP` the amount is sent as it is
Reusing a conversion helper from another market	You charge a hundred times more, or less	Derive the decimals per terminal, not per codebase
Sending the amount as text with separators	Validation error	Strip every separator and send an integer
Converting with floating point	One-cent difference on some amounts	Use integers or a decimal type
Reusing an amount returned by a webhook	Wrong magnitude	The event does not copy your request: `operation.amount` omits zero `iva` and `subtotal_iva` and adds `currency` and `tip`

Validate before you send

Check that the amount fields add up to the total you mean to charge before you call the API. A badly built amount is the most common cause of reconciliation gaps.

If you operate in several markets

This section applies only if your POS system serves merchants in more than one country.

Currency	Country	Decimals
`CLP`	Chile	0
`COP`	Colombia	0
`MXN`	Mexico	2
`PEN`	Peru	2

The same integer is different money

1244 means 12.44 MXN in Mexico and 1,244 COP in Colombia: a hundredfold difference. Since the payload carries no currency field, resolving this is entirely on your side.

Read the currency_code configured on each terminal and derive the decimal handling from there, never from the branch or the user's language.

Accept payments with Kushki ONE

With the amount correctly built, review the payment flows: direct sale, pre-authorization, capture, post-tip and void.

Error catalog

Look up the amount validation codes and their recommended corrective actions.

Your currency and its decimals#

The conversion rule#

How the amount adds up#

Full example#

Sale with no tax breakdown#

Convert to the minor unit#

Common mistakes#

If you operate in several markets#

Your currency and its decimals

The conversion rule

How the amount adds up

Full example

Sale with no tax breakdown

Convert to the minor unit

Common mistakes

If you operate in several markets