# Amounts

Source: <https://docs.gjold.com/v2/amounts>

An amount is a string: a decimal number, a space, and an ISO 4217 currency code, as in `"99.95 DKK"`. It is never a JSON number, so that no amount is ever rounded by a float.

## In requests

```
"99.95 DKK"   "1000 DKK"   "0.50 EUR"   "12500 JPY"   "1.250 KWD"
```

| Part | Rule |
|---|---|
| Number | Digits, with a `.` before the decimals if there are any. No sign, no thousands separators, no comma for a decimal point, and no exponent. |
| Decimals | At most as many as the currency's minor unit has: 2 for DKK, so `"99.95 DKK"` but not `"99.955 DKK"`. Trailing zeros are fine: `"99.50 DKK"` is `"99.5 DKK"`. |
| Currency | Three capital letters, an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code from the table below, after one space. |
| Size | At most 61 digits before the point. Your acquirer's limit is far lower. |

An amount that breaks the rules fails the request with `400 invalid json in {field}: invalid amount`, or `missing currency` when it has none. A field that takes several amounts, such as the items of a payment link, takes them in one currency, or fails with `mismatching currencies DKK and EUR`.

An amount is never negative: a discount is taken off the items it is for, not given as an item of its own.

## In responses

We write amounts the same way, with as few decimals as the value needs:

- A whole amount has none: `"45 DKK"`, `"1000 JPY"`, `"0 DKK"`.
- Any other has the currency's full minor unit: `"45.50 DKK"`, never `"45.5 DKK"`, and `"1.500 KWD"`.
- There are no thousands separators: `"12998 DKK"`.

So parse amounts, don't compare them as strings: `"45 DKK"` and `"45.00 DKK"` are the same amount. Split at the space, and read the number as a decimal, or as an integer number of minor units, never as a float.

## Currencies

Every ISO 4217 currency is known, by the number of decimals in its minor unit. Which ones you can take payments in is up to your acquiring agreements, and a payment in a currency that your acquirer does not take is declined by it.

| Decimals | Currencies |
|---|---|
| 0 | BIF, CLP, DJF, GNF, ISK, JPY, KMF, KRW, PYG, RWF, UGX, UYI, VND, VUV, XAF, XOF, XPF |
| 2 | DKK, EUR, NOK, SEK, GBP, USD, CHF, PLN, and every other ISO 4217 currency but those in the other rows and below |
| 3 | BHD, IQD, JOD, KWD, LYD, OMR, TND |
| 4 | CLF, UYW |

Codes for metals, test codes, and funds without a minor unit, such as XAU, XTS, and XXX, can't be used.

## Arithmetic

The API adds amounts for you: a transaction's `"totals"` are sums of its items and its acts. When you add them yourself, as to check that a refund fits what was captured, use integers of minor units, or a decimal type:

```
"199.90 DKK" + "45 DKK" = 19990 + 4500 øre = 24490 øre = "244.90 DKK"
```