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 Chile you operate in Chilean pesos (CLP), which use no 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 value is sent as it is, with no zeros added.

To charge	You send
1,244 CLP	`1244`
12,000 CLP	`12000`
15,990 CLP	`15990`

Never pad a Chilean peso amount

If you add 00 to the end of a CLP amount, you will charge a hundred times more than intended. Padding zeros apply only to two-decimal currencies.

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 retail sale: 15,990 CLP, of which 2,553 is 19% VAT.

Component	Value	Minor units
`subtotal_iva`	13,437 CLP	`13437`
`iva`	2,553 CLP	`2553`
Total charged	15,990 CLP	`15990`

{
  "amount": {
    "iva": 2553,
    "subtotal_iva": 13437,
    "subtotal_iva0": 0,
    "extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 }
  },
  "client_transaction_id": "9a8b7c6d-2222-4000-8000-ffeeddccbbaa"
}

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

Your currency needs no conversion

In a currency with no decimals, the integer you send is the amount: there is no multiplication and no padding. The helper below only matters if your POS system also serves a two-decimal market.

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