Skip to main content

​
Wallet top-up currency conversion

When you top up your wallet in a currency other than your wallet currency, Orbit converts the payment to your wallet currency at the moment the credit is applied. You do not need to convert the amount yourself before paying.

​
How conversion works

  • Different currencies are converted at credit time. Orbit applies an exchange rate for the pair — for example, EUR → USD — and credits the converted amount to your wallet.
  • Same-currency top-ups are credited 1:1. If you pay in your wallet currency, no conversion happens and the full amount is credited.
  • The applied rate is recorded. Every converted top-up stores the exchange rate that was used on the resulting wallet transaction, so each credit traces back to the rate in effect when it was applied.

​
Where the exchange rate comes from

Orbit resolves the rate for a converted top-up in priority order and uses the first source that returns a usable rate. Which of these sources are active depends on how your Orbit deployment is configured, so the source that actually applies can differ between deployments:
  1. A pinned rate for the pair. If an administrator has set an explicit rate for a currency pair — for example to lock a rate during a launch or in a test environment — that rate is used first.
  2. A commercial provider feed. If your deployment is connected to a commercial exchange-rate provider, Orbit uses that provider’s hourly-refreshed rate. This is the same rate pipeline Orbit uses to price your usage, so a converted top-up and your ongoing spend stay consistent. This source is off unless the provider has been configured; it is not enabled by default.
  3. A public live feed. If live fetching has been turned on, Orbit reads a current rate from a public exchange-rate feed. This source is also off unless an administrator enables it; it is not enabled by default.
  4. A maintained reference table. Orbit ships a built-in table of reference rates, based on published central-bank reference rates and updated by the Orbit team between releases. In a default deployment the two live sources above are off, so this table is the source used for every converted top-up — it is the default, not a rare fallback.
The reference table has a staleness ceiling of 60 days. Orbit will not credit a converted top-up at a table rate older than that, because a rate that far out of date may no longer reflect the market.

​
Tell which source applied

You never have to guess. Every converted top-up records the source that resolved its rate, written onto the transaction’s metadata as fx_rate_source: The stored fx_rate_source_ref value goes one level deeper and names the exact resolution — for example ecb_ref:2026-08-21 for the reference table, or the feed endpoint plus its update timestamp for a live source. To read these fields on a given top-up, open Billing → Transaction history in the dashboard and locate the top-up’s transaction row, or fetch the same ledger with GET /billing/transactions.

​
Operator controls (deployment side)

These toggles are owned by the team that operates the Orbit deployment; they are not set from the tenant dashboard. Tenants read the result; operators decide which sources can resolve it. Sources resolve in strict priority order — pinned → commercial provider → public live → reference table — an enabled source outranks everything below it. Two useful implications:

​
If a rate cannot be determined

If no active source returns a usable rate — for example the maintained reference table has passed its 60-day staleness ceiling and no live source is enabled — Orbit does not guess. Rather than credit the top-up at an unreliable rate, it fails the conversion with the FX_RATE_UNAVAILABLE error. An API-initiated top-up returns a structured error, for example:
What to do with it:
  • Card top-ups through the hosted checkout are retried automatically. Your wallet is not credited at a bad rate; the credit is applied on a later retry once a valid rate is available again.
  • API-initiated top-ups (POST /balance/top-up) get FX_RATE_UNAVAILABLE back so your integration can retry later, rather than treating the top-up as complete. Ask the deployment operator to enable one of the live sources (or, for a pinned pair, to set the override) to clear it permanently.
Same-currency top-ups are never affected, because they are credited 1:1 with no rate lookup.

​
Reconciling a converted top-up

Reconcile each converted top-up against the rate stored on its transaction row — one comparison, nothing else:
  1. In the dashboard, open Billing → Transaction history and find the top-up’s credit row. The row records the original currency and amount, the applied rate, and which source resolved it (fx_rate_source / fx_rate_source_ref).
  2. Check that credited amount equals original amount × stored rate. The API returns the same fields from GET /billing/transactions, so this check can be scripted for finance tooling.
Because the rate is captured per top-up, the amount credited to your wallet always matches the rate in effect at credit time — not the rate at any later moment. If the stored rate matches what the original payment converted at, the row reconciles; if not, it never will, because no later rate is ever applied to that row.