Currencies and amounts

Every amount sent to or returned by the API is an integer in the currency's minor unit. Never send a decimal or format an amount with floating-point arithmetic.

For example, AED 12.34 is 1234. Which of these you can use depends on your account: use the currencies enabled for your account (GET /account), which are the ones its card processing takes. Most accounts take AED only.

Enabled currencies

The API accepts only currencies enabled for the account and mode represented by the key. Retrieve the current list instead of hard-coding it:

curl https://utopia-payments.com/api/v1/account \
  -H "Authorization: Bearer $UTOPIA_API_KEY"

{
  "object": "account",
  "livemode": true,
  "payments_enabled": true,
  "subscriptions_enabled": true,
  "currencies": ["AED"]
}

When subscriptions_enabled is false, a checkout for a recurring product is paid once, as a one-time payment: its session's kind is payment and no subscription is created.

Creating a checkout in another currency returns CURRENCY_NOT_SUPPORTED. The response message includes the currently enabled currencies.

Prices in US dollars

Where your account lists USD beside AED, a price in US dollars is charged to the card in dirhams at the fixed rate of 1 USD = 3.6725 AED, the rate the dirham is pegged to the dollar at. A USD price of 1000 (USD 10.00) is charged AED 36.73; half a fils rounds up.

On some accounts the card is charged in dollars instead: the payment gateway converts the dirham amount back at its own rate, a few percent above 3.6725, and your customer sees that dollar amount before paying.

Everything you see stays in dollars: the payment's total_amount, its fee, refunds, events and your balance, which receives the dollar price either way. Your customer's checkout shows the dollar price and what their card is charged. A refund made in dirhams is recorded in dollars in proportion, so a full refund returns the whole dollar price.