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", not "99.955 DKK". Trailing zeros are fine: "99.50 DKK" is "99.5 DKK". |
| Currency | Three capital letters, an 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 can't be read 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 item's total in a code that is
not in the table below fails with 500 invalid item total currency.
v1 reads more than these rules allow, but write amounts as they say:
- The space before the currency may be left out, as in
"99.95DKK", and so may digits before or after the point, as in".5 DKK"or"5. DKK". Leading zeros and white space are skipped. - An item's total with more decimals than its currency has is cut
down to them, not rounded:
"10.999 DKK"is taken as"10.99 DKK", with no error.
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 |
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"