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 below.

Amounts are strings

Send amount as a decimal string, not a float. Floating-point math loses precision on money; a string preserves exactly what you intend.

{ "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.

// 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 webhook payload. For a TND request it simply mirrors the charge, with rate = "1.000000":

{ "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 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 captured 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:

{
  "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.