Selling cash on delivery
Money and currencies
Amounts are decimal strings with exactly the currency's number of decimals. Never parse them into floating-point numbers.
The money object
Every amount the API returns looks like this:
{ "amount": "2500.00", "currency": "DZD" }currencyis the ISO 4217 code of the store's currency, fromGET /v1/store.amountis a string, in the currency's major unit, with exactly as many decimals as the currency has: two for the Algerian dinar and the Moroccan dirham, three for the Tunisian and Libyan dinars.
| Currency | Decimals | Example |
|---|---|---|
DZD Algerian dinar | 2 | "2500.00" |
MAD Moroccan dirham | 2 | "149.90" |
TND Tunisian dinar | 3 | "12.500" |
LYD Libyan dinar | 3 | "45.750" |
The store's currency and its number of decimals are in GET /v1/store (currency.code and currency.exponent).
Why a string
0.1 + 0.2 is not 0.3 in floating point, and a few millimes lost on every order add up. A string carries the exact value. Parse it with a decimal type, or into an integer number of minor units:
// "2500.00" with exponent 2 -> 250000 minor units, exactly.
function toMinor(amount, exponent) {
const [whole, frac = ''] = amount.split('.')
return BigInt(whole + frac.padEnd(exponent, '0'))
}from decimal import Decimal
total = Decimal(order["total"]["amount"]) # never float(...)// bcmath keeps every digit.
$total = bcadd($order['total']['amount'], '0', 3);Sending amounts
You rarely send money: orders are priced by the store. Where you do (a product's price), send a decimal string with no more decimals than the currency has: "3500.00" or "3500" for DZD. A value with more decimals ("3500.005") is refused with validation_failed.
Totals on an order
An order carries subtotal (the lines), shipping, discount and total. total is what the courier collects from the customer.
