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.

​
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.
  • 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 return FX_RATE_UNAVAILABLE so your integration can retry, rather than treating the top-up as complete.
Same-currency top-ups are never affected, because they are credited 1:1 with no rate lookup.

​
Reconciling a converted top-up

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. This makes it straightforward to reconcile a converted top-up against the amount you paid.