Currency Lookup processor
The Currency Lookup processor automatically adds foreign exchange (FX) rates to your event data so that you can convert values from one currency to another during Mediation. It removes the need to manage complex currency conversion logic yourself in downstream processors or external systems.
The Currency Lookup processor:
- Looks up FX rates from an external FX service during meter processing.
- Uses exchange rate types provided by Oanda.
- Supports both fixed (static) currencies and currencies read dynamically from event fields.
- Caches recent FX lookups in memory to improve performance.
- Uses your tenant's timezone to resolve dates for historical rate lookups.
- Adds the retrieved exchange rate as a new field on each event.
How the Currency Lookup processor works
For each event that passes through the Currency Lookup processor:
- The processor reads the "from" currency, "to" currency, and a date from the event or from static configuration.
- It normalizes the date using the tenant's timezone so that the correct historical rate can be chosen.
- It checks an in‑memory cache to see if the FX rate for that currency pair and date is already available.
- If the rate is not cached, it queries the external FX service and stores the result in the cache.
- It writes the exchange rate into the event in the field that you configure as the rate field.
- If a required value is missing, invalid, or no rate is available, the event is sent to an error output with a descriptive error code instead of stopping the meter.
If there is no FX rate for a specific date, the processor marks the event with a “rate not available” error code and routes it to the error stream. You can decide whether to reprocess later, use a fallback rate, or ignore the event. The processor can look up future rates, only if the FX provider publishes future rates. Otherwise, the processor will treat them as not available and return an appropriate error code. The processor keeps FX rates only in an in‑memory cache to speed up processing. It does not persist rates beyond that cache.
Use cases
Multi‑currency billing: Convert customer usage data from local currency to a single billing currency. For example, convert usage from INR or EUR to USD before rating.
Financial reporting and analytics: Normalize transactions across currencies so that dashboards and reports can compare revenue or usage on a consistent basis.
Regulatory and audit compliance: Apply official daily rates when you must demonstrate which FX rates were used on a given date.
Usage‑based pricing: Convert usage into a consistent currency before applying tiered or volume‑based pricing models.
Best practices
-
Validate event data so that currency and date fields are always present and correctly formatted.
-
Choose rate types that match your business rules (for example, midpoint for analytics, bid/ask for trading‑like scenarios).
-
Use static currencies whenever possible when all events share the same "from" or "to" currencies.
-
Monitor error outputs to identify unexpected currencies or missing dates early.
-
Use the tenant timezone when interpreting dates, especially if events come from multiple regions.
-
The Currency Lookup processor includes a built‑in cache to reduce latency and external calls. Frequently used currency pairs for recent dates are stored in the memory. Cache size and expiration can be tuned so that you reuse rates for common lookups while still refreshing them regularly. A higher cache hit rate reduces the load on the FX service and speeds up meter runs.