# Amounts & currency

## You are always paid in TND

Paymee charges the buyer's card and settles you in **Tunisian Dinar (TND)**. Every
`amount` the API returns — on session detail, session list, the hosted checkout
and every webhook — is the amount in your account's currency, TND: **what the
card is charged and what your balance is credited with.**

You may *request* a payment in another currency (for example a store priced in
EUR). The gateway converts that request into TND at the exchange rate you
configured, and keeps what you requested alongside the result. See
[Foreign-currency requests](#foreign-currency-requests) below.

## Amounts are strings

Send `amount` as a **decimal string**, not a number. Floating-point math loses
precision on money, and a JSON number drops trailing zeros (`10.500` arrives as `10.5`
and is then refused for its precision); a string preserves exactly what you intend.

```json
{ "amount": "10.500" }
```

`amount` is the value in the currency's **main unit** — for `TND`, dinars, not
millimes. Send `"10.500"` for ten dinars and five hundred millimes; the gateway
converts to millimes internally before talking to the acquirer. Never send a
millimes integer like `10500`.

## Precision follows the requested currency

Format `amount` with exactly the ISO 4217 number of decimals of the currency you
send it in. TND is subdivided into **1000 millimes**, so a TND amount has
**three** decimals — unlike most currencies, which have two.

| Currency | Decimals | Example |
| --- | --- | --- |
| `TND` | 3 | `"10.500"` |
| `EUR`, `USD`, `GBP` | 2 | `"10.50"` |
| `JPY` | 0 | `"1000"` |

:::caution
The API **rejects** an amount whose decimal places don't match its currency: for
`TND`, `"10.50"` or `"10"` are refused with a `validation-error` whose
`errors[].code` is `invalid_precision` — they are not silently reinterpreted.
:::

## Currency field

`currency` is an ISO 4217 code, case-insensitive. If omitted, the request is in
your account's currency (`TND`). The maximum amount is `999999.999` TND, applied
both to what you request and to the converted TND amount.

## Foreign-currency requests

A request in a currency other than TND is accepted only when you have configured
an **exchange rate** for it in the merchant portal (Settings → Currencies). A
rate is the TND value of one unit of the currency — `1 EUR = 3.350000 TND` —
with up to six decimals. Live and test mode keep separate rate tables.

When a session is created in such a currency, the gateway:

1. validates the amount at the **requested** currency's precision (2 decimals for EUR);
2. multiplies it by your rate and rounds **half-up to millimes**;
3. stores the result as the session's `amount` in `TND`, and freezes what you
   requested and the rate applied in an `original` object.

```json
// POST /gateway/sessions/  { "amount": "100.00", "currency": "EUR", ... }

{
  "amount": "335.000",
  "currency": "TND",
  "original": { "amount": "100.00", "currency": "EUR", "rate": "3.350000" },
  ...
}
```

`original` is present on **every** session response and session event. For a TND
request it simply mirrors the charge, with `rate` = `"1.000000"`:

```json
{ "amount": "10.500", "currency": "TND", "original": { "amount": "10.500", "currency": "TND", "rate": "1.000000" } }
```

Three guarantees follow from the snapshot:

- **The rate is frozen at creation.** Changing or removing a rate in the portal
  never alters an existing session, and an [idempotent replay](/guides/idempotency/)
  of the same `merchant_reference` returns the original snapshot, never a
  re-conversion at today's rate.
- **The buyer sees both amounts.** The hosted checkout shows the quote in your
  currency, the TND amount the card will be charged, and the rate.
- **Refunds are in TND**, capped at the charged `amount`.

:::note
If you integrate a store priced in a foreign currency, read `amount`/`currency`
as *what you will receive* and `original` as *what you asked for*. They are only
equal for TND requests.
:::

### Unsupported currency

A request in a currency you have **not** configured a rate for is rejected with
`422` and a `validation-error` on the `currency` field:

```json
{
  "type": "https://api.paymee.online/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "One or more fields failed validation.",
  "errors": [
    { "field": "currency", "code": "currency_unsupported", "message": "No exchange rate is configured for GBP. ..." }
  ]
}
```

Configure a rate for the currency, or send the request in TND.

Source: https://docs.paymee.online/guides/amounts-and-currency/