Skip to content
ABUNA
DocsAmounts, currencies and timestamps

Getting started

Amounts, currencies and timestamps

How the API writes money, currencies, and times.

View as Markdown

The API writes money as whole numbers with a currency code, and times as Unix seconds.

Amounts

An amount is an integer in the currency's smallest unit. XAF and XOF have no smaller unit, so 5000 means FCFA 5,000. USD amounts are in cents, so 1000 means $10.00.

A price's amount
{
  "amount": 5000,
  "currency": "XAF"
}

A price's amount must be greater than 0. An amount of 0 or less returns 422 with code invalid. A decimal like 5000.5 or a string like "5000" returns 400 with code invalid_json.

Each invoice keeps the amount and currency its price had when the invoice was issued. The amount a customer pays is on the invoice.

Currencies

Abuna supports three currencies: XAF (Central African CFA franc), XOF (West African CFA franc) and USD (US dollar). You can send the code in any case. The API stores and returns it in uppercase. Any other code returns 422 with code currency_unsupported.

Each app has a base_currency, which you choose when you create the app. Each price has its own currency. Both can be XAF, XOF or USD.

Paying in FCFA

Customers always pay by mobile money in FCFA, in their network's currency: XAF for networks in Central Africa, such as Cameroon, and XOF for networks in West Africa, such as Côte d'Ivoire or Senegal. When the invoice is in that currency, the customer pays the invoice amount. When it isn't, Abuna converts it:

  • Between XOF and XAF: 1 to 1, with no margin. An invoice for FCFA 5,000 in XOF is paid as FCFA 5,000 in XAF.
  • From USD: at the day's exchange rate plus 2%, rounded up to a whole franc. The 2% is part of the amount you receive. Abuna takes nothing from it.

The customer sees the exact FCFA amount before approving the payment on their phone. Hosted pages, like checkout and the pay page, show the price in its currency with the FCFA amount next to it, like $10.00 · FCFA 6,039. A retried request for the same payment keeps the amount of the first one.

Invoices stay in the price's currency. The rate is saved on each payment: amount and currency are what the customer was charged, original_amount and original_currency are the invoice's, and exchange_rate is the francs charged per unit of the invoice's currency, 2% included. See The payment object.

A $10.00 invoice paid in XAF
{
  "amount": 6039,
  "currency": "XAF",
  "original_amount": 1000,
  "original_currency": "USD",
  "exchange_rate": 603.8094,
  "exchange_margin_bps": 200,
  "exchange_rate_at": 1791100800
}

If no recent exchange rate is available, paying a USD invoice is refused with 503 and code exchange_rate_unavailable. Nothing is charged, and the pay page asks the customer to try again later. Rates are normally available every day.

Some payment providers take only XAF. Prices in XOF or USD still pay through them on Cameroon numbers, converted to XAF. See Choose a provider.

Timestamps

Every time in the API is an integer count of seconds since the Unix epoch, in UTC. A time that hasn't happened yet is null, such as activated_at before the first payment.

Times in a subscription
{
  "starts_at": 1727600000,
  "activated_at": null,
  "canceled_at": null,
  "created_at": 1727600000
}

Billing periods count from the subscription's start. A monthly subscription that starts on 31 January renews on the last day of February, then on 31 March. Periods keep the start's time of day.

Next steps