Skip to main content
Matcher lets you reconcile transactions in different currencies by converting amounts to a common base currency before comparison. This enables matching across international transactions, treasury operations, and multi-entity reconciliations.

​
Overview

Multi-currency matching converts both transaction amounts to a base currency using the appropriate FX rate, then applies standard matching rules. If the converted amounts fall within tolerance, Matcher creates a match. Otherwise, it creates an exception for review.
Multi-currency matching flow.

Multi-currency matching flow.

​
How it works

Multi-currency support lives in the existing context types (1:1, 1:N, N:M) and match rules. There is no separate “multi-currency” context type. At match time, Matcher computes a base amount and a base currency for each transaction from FX hints in the transaction’s own metadata (see FX from transaction metadata below). Rules that set matchBaseAmount or matchBaseCurrency compare these base values. You cannot upload a base amount directly. There is no external FX provider or rate-lookup service: the rate always comes from the transaction row itself.

​
Key components

​
Configuring rules for multi-currency

Enable multi-currency comparison by setting matchBaseAmount and matchBaseCurrency to true in the rule config. The checks on the original values stay active. An EXACT rule compares amount while matchAmount is on, and EXACT and TOLERANCE rules compare currency while matchCurrency is on. Both are on by default, so a cross-currency rule turns them off.

​
Exact rule with base amount matching

cURL
matchBaseAmount compares the base amounts, and matchBaseCurrency compares the base currencies. A transaction without a base amount fails both checks.

​
Tolerance rule with base amount matching

cURL
With matchBaseAmount, a TOLERANCE rule compares base amounts in place of the original amounts, and absTolerance is in base-currency units.

​
Confidence scoring

Base-amount rules use the same fixed component weights as all other rules. For the full scoring model, see Confidence scoring.

​
FX from transaction metadata

When a transaction has no base amount yet, Matcher converts it at match time using FX hints carried in that transaction’s metadata. Matcher does not call any external rate provider. The rate travels with the row. Conversion only runs when fx_base_currency is present. Conversion never changes the original amount and currency, because it changes only the comparison. Matcher rounds the converted amount to the largest roundingScale among the context’s TOLERANCE rules, or to 2 decimal places when the context has none. Match simulation does not convert, so base-amount rules find no matches in a simulation.

​
Metadata fields

​
Example transaction with FX metadata

With the metadata above, Matcher derives a base amount of 1085.00 in USD, then compares it against the other side using the rule’s matchBaseAmount / matchBaseCurrency settings.
When the hints are absent or invalid (unparseable rate, failed expression), the transaction gets no base amount. It cannot match under a base-amount rule and stays unmatched. The run continues.

​
FX rate-variance band

Cross-currency amounts often disagree slightly, because each side converts at a different rate or on a different day. The fxVarianceBand key on TOLERANCE rules handles this: it defines a second threshold stacked above the match tolerance, expressed as a decimal fraction (0.0001 = 1 basis point). After the strict-tolerance pass, Matcher rescans unmatched cross-currency 1:1 pairs. A pair whose base-amount residual exceeds the match tolerance but stays within the band still matches. The pair becomes a proposed group with a fixed confidence of 75, below the auto-confirm threshold, so it always requires human review. Matcher flags both transactions with the FX_RATE_VARIANCE exception reason. The residual then becomes a typed exception instead of collapsing to UNMATCHED. The band applies only when:
  • both sides carry a base amount and the same base currency.
  • the original currencies differ (same-currency drift is a plain mismatch, not an FX case).
  • all of the rule’s other checks (date window, reference, composite fields) still pass. The rule must set matchCurrency to false, because the currency check rejects pairs whose original currencies differ.
A zero or absent fxVarianceBand disables the band.
cURL

​
Example: cross-currency reconciliation

Source (EUR account): Target (USD account): Both transactions carry fx_base_currency: "USD". txn_001 carries fx_rate: "1.085" and txn_002 carries fx_rate: "1". With a TOLERANCE rule (matchCurrency: false, matchBaseAmount: true, matchReference: false, percentTolerance: 0.02):
  • Base amounts: 1,085.00vs1,085.00 vs 1,095.00
  • Difference: $10.00
  • Threshold: 2% of the larger amount, $21.90
  • Result: Match (10.00<10.00 < 21.90)

​
Best practices

Attach fx_base_currency and fx_rate (or fx_notional_expr) to each transaction’s metadata at the source, using the rate that applied when the transaction settled. Because the rate travels with the row, results are reproducible across runs, with no runtime rate lookups.
FX conversions introduce small variances. Use TOLERANCE rules with matchBaseAmount to allow for rounding and rate timing differences.
Use a consistent base currency across all contexts. USD is common for international operations. Use your reporting currency for domestic + international.

​
Next steps

Confidence Scoring

How match scores work and what thresholds apply.

Match Rules

Full reference for rule types and config fields.