# Currencies and countries

> Learn how Nexpay handles currencies and countries.

When working with the Nexpay API you soon will need to specify currencies and country codes. In this article we explain how Nexpay deals with currencies and countries across its API.

---

## Currencies

In any API call where a currency must be specified, the currency code must be a valid ISO 4217 currency code. To see the list of all currencies in the ISO 4217 standard, [check this page](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes).

### Currency unit

API requests require amounts to be specified in **major units** (decimal form). They are NOT in cents/minor units. For instance, 10 AUD is `10.00` (or `10`), and 5,125.50 USD is `5125.50` (or `5125.5`).

> **Warning — Decimal precision**
>
> Nexpay respects the standard decimal precision for each currency. Most currencies use 2 decimal places (e.g. USD, AUD, EUR), some use 3 (e.g. BHD, KWD, OMR), and others use 0 (e.g. JPY, KRW).

### Serialisation — JSON number vs decimal string

Nexpay uses **two different serialisations** for amounts on the wire, depending on the endpoint:

| Endpoint family | Format | Examples |
| --- | --- | --- |
| `/v2/quotes`, `/v2/fx-rate` | JSON **number** (decimal) | `10`, `10.00`, `5125.5`, `5125.50` — all accepted; the server normalises to the currency's precision. |
| `/v2/payment-intents` (recipient amounts) | Decimal **string** | `"10.00"`, `"5125.50"`, `"1000"` (JPY zero-decimal), `"5.250"` (BHD three-decimal) |

Strings on payment-intent recipients avoid IEEE-754 rounding for financial fidelity — when the amount round-trips through JSON across multiple systems, sending `"10.00"` as a string preserves the exact representation that hits ledgers. JSON numbers work fine on the `/v2/quotes` and `/v2/fx-rate` flows because the server normalises immediately.

In particular, on `/v2/payment-intents`:

```json
"recipients": [
  {
    "role": "education_provider",
    "amount": {
      "payerAmount": "10000.00",   // string, not number
      "currency": "AUD"
    }
  }
]
```

Sending `"payerAmount": 10000.00` (number) on a payment-intent recipient is rejected — the DTO enforces `IsString` on this field. The string carries the currency's full precision; do not strip trailing zeros.

---

## Countries

In any API call where a country must be specified, the country code must be a valid ISO 3166-1 alpha-2 code. To see the list of all country codes in the ISO 3166-1 alpha-2 standard, [check this page](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements).

We may support some countries that are not officially supported by the ISO 3166-1 alpha-2 standard. Countries such as Kosovo, Montenegro and others are examples of this exception to the rule.

---

## Percentages

In any API call where a percentage must be specified, use a value from 0 to 1. Example: a 10% percentage rate would be 0.1.