Amounts and currency conversion

This page explains how amounts are represented, how currency conversion is performed, and how exchange rates and rounding are applied.

Supported item currencies

Order items and modifiers may be priced in any of the following currencies:

Items within the same order may use different currencies.

Supported payment currencies

Each order is paid using a single payment currency, selected at creation time.

All item amounts are converted into this payment currency.

Amount representation

All monetary values in the API are represented as decimal strings.

{
  "unit_price": "19.99",
  "total_amount": "49.97",
  "remaining_amount": "10.00"
}

Floating-point numbers must not be used.

Decimal precision

Decimal precision is enforced per currency or asset:

Amounts are validated and normalized using these precisions.

Conversion process

When an order is created:

1. Each item (and modifier) amount is multiplied by its quantity.

2. If the item currency differs from the payment currency:

   • The amount is converted using the latest available exchange rate.

3. All converted amounts are summed to produce:

   • total_amount
   • remaining_amount

The final totals are always expressed in the payment currency.

Exchange rates

Exchange rates are sourced from trusted providers and refreshed every minute:

• Fiat currencies
  Rates are sourced from providers such as XE or equivalent institutional FX data sources.

• Crypto assets
  Rates are sourced from providers such as CoinMarketCap or CoinGecko.

The exact provider may vary by environment or availability.

Rates object

The rates object included in the Order records the exchange rates used during conversion.

{
  "rates": {
    "USD_USDT": "1.0000",
    "MXN_USDT": "0.0583"
  }
}

Each entry represents:

<BASE>_<QUOTE> = exchange rate used for conversion

This allows merchants to:

• Audit conversions
• Reproduce totals
• Reconcile accounting data

Rounding rules

All conversions follow bankers rounding (round half to even) at the precision of the target currency.

Rounding is applied:

• After each conversion
• Before final aggregation

This ensures:

• Deterministic totals
• Reduced cumulative rounding error
• Consistent reconciliation across systems