Multi-currency matching

Matcher lets you reconciliation of 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.

Enabling multi-currency

Context configuration

Enable multi-currency matching at the context level when creating or updating a context:

{
  "name": "International Treasury Reconciliation",
  "type": "MULTI_CURRENCY",
  "settings": {
    "multi_currency": {
      "enabled": true,
      "base_currency": "USD",
      "fx_rate_source": "external_provider",
      "fx_tolerance_percent": 2.0,
      "fx_tolerance_absolute": 10.0
    }
  }
}

API Reference: Create context, Update context

Multi-currency settings

Setting	Type	Description
`enabled`	Boolean	Enable multi-currency matching
`base_currency`	String	ISO 4217 code for comparison currency
`fx_rate_source`	String	Source for FX rates
`fx_tolerance_percent`	Decimal	Percentage tolerance for FX variance
`fx_tolerance_absolute`	Decimal	Absolute tolerance in base currency
`rate_date_strategy`	String	How to determine which date’s rate to use
`fallback_behavior`	String	Action when FX rate unavailable

Base currency

The base currency is used as the common denominator for all comparisons.

Choosing a base currency

Scenario	Recommended Base	Rationale
US-based company	USD	Matches reporting currency
EU-based company	EUR	Matches reporting currency
Multi-region operations	USD	Most liquid, widely available rates
Brazil domestic + international	BRL	Matches local reporting

Changing base currency

Changing the base currency affects all pending matches. Complete or archive existing matches before changing.

FX rate sources

Matcher supports multiple sources for foreign exchange rates.

External provider

Connect to third-party FX rate APIs by configuring the FX rate source in your context settings:

{
  "type": "external_provider",
  "provider": "openexchangerates",
  "settings": {
    "api_key_id": "secret_fx_001",
    "base_url": "https://openexchangerates.org/api/",
    "cache_duration_minutes": 60,
    "fallback_to_previous_day": true
  }
}

Supported Providers:

Provider	Features	Update Frequency
Open Exchange Rates	170+ currencies	Hourly
Fixer.io	170+ currencies	Hourly
Currency Layer	168 currencies	Hourly
XE	185+ currencies	Real-time
European Central Bank	EUR crosses	Daily

Midaz asset rate engine (optional)

If you’re using Midaz Ledger, you can query FX rates directly from it:

{
  "type": "midaz",
  "settings": {
    "ledger_id": "ldg_001",
    "rate_type": "spot",
    "fallback_to_closing": true
  }
}

This option is only available if you have Midaz integrated. See Midaz Integration for setup instructions.

Manual entry

Upload rates manually for controlled environments by including them in the context configuration or using dedicated rate management.

Rate date strategy

Determine which date’s FX rate to use for conversion.

Strategy options

Strategy	Description	Use Case
`earlier_date`	Use rate from earlier transaction date	Default, conservative
`later_date`	Use rate from later transaction date	When settlement date matters
`source_date`	Use rate from internal source date	When internal is authoritative
`target_date`	Use rate from external source date	When external is authoritative
`average`	Average of both dates’ rates	Reduce single-day volatility

Configure rate date strategy

{
  "settings": {
    "multi_currency": {
      "rate_date_strategy": "earlier_date",
      "rate_time": "closing",
      "timezone": "America/New_York"
    }
  }
}

Rate time options

Option	Description
`opening`	Day’s opening rate
`closing`	Day’s closing rate (default)
`midday`	12:00 rate
`spot`	Real-time rate at transaction time

Tolerance configuration

Multi-currency matching uses combined tolerance to account for FX fluctuations.

Tolerance formula

converted_amount_a = amount_a * fx_rate_a_to_base
converted_amount_b = amount_b * fx_rate_b_to_base

diff = abs(converted_amount_a - converted_amount_b)
max_amount = max(abs(converted_amount_a), abs(converted_amount_b))

passes = diff <= max(tolerance_absolute, tolerance_percent * max_amount)

Tolerance examples

Example 1: Within Tolerance

Transaction	Original	FX Rate	Base (USD)
A (EUR)	1,000.00	1.0850	1,085.00
B (USD)	1,095.00	1.0000	1,095.00

Difference: $10.00 (0.92%)
Tolerance: max( $10.00, 2% ×$ 1,095) = max( $10.00,$ 21.90) = $21.90
Result: Match ( $10.00 <=$ 21.90)

Example 2: Outside Tolerance

Transaction	Original	FX Rate	Base (USD)
A (EUR)	1,000.00	1.0850	1,085.00
B (USD)	1,150.00	1.0000	1,150.00

Difference: $65.00 (5.99%)
Tolerance: max( $10.00, 2% ×$ 1,150) = max( $10.00,$ 23.00) = $23.00
Result: No Match ( $65.00 >$ 23.00)

Custom tolerance by currency pair

Set different tolerances for volatile currency pairs:

{
  "settings": {
    "multi_currency": {
      "fx_tolerance_percent": 2.0,
      "fx_tolerance_absolute": 10.0,
      "currency_pair_overrides": [
        {
          "pair": "BRL/USD",
          "tolerance_percent": 5.0,
          "tolerance_absolute": 50.0
        },
        {
          "pair": "ARS/USD",
          "tolerance_percent": 10.0,
          "tolerance_absolute": 100.0
        }
      ]
    }
  }
}

Handling missing FX rates

When an FX rate is unavailable, Matcher follows the configured fallback behavior.

Fallback options

Behavior	Description	Risk Level
`exception`	Create exception for manual handling	Lowest
`skip`	Skip match attempt, continue processing	Low
`previous_day`	Use previous available rate	Medium
`interpolate`	Estimate from surrounding dates	Medium
`fail`	Fail the entire job	Highest

Configure fallback

{
  "settings": {
    "multi_currency": {
      "fallback_behavior": "previous_day",
      "max_fallback_days": 3,
      "alert_on_fallback": true
    }
  }
}

Missing rate exception

When fallback is exception, the transaction becomes an exception with specific details:

{
  "exceptionId": "{exceptionId}",
  "type": "FX_RATE_UNAVAILABLE",
  "severity": "HIGH",
  "details": {
    "from_currency": "TRY",
    "to_currency": "USD",
    "required_date": "2024-01-20",
    "nearest_available": "2024-01-18",
    "gap_days": 2
  },
  "resolution_options": [
    "Provide manual rate",
    "Use fallback rate from 2024-01-18",
    "Mark as no match"
  ]
}

Confidence scoring impact

Multi-currency matching affects confidence scoring through the currency component.

Currency score calculation

Scenario	Currency Score
Same currency	30/30 (100%)
Different currency, exact FX match	28/30 (93%)
Different currency, within 1% FX variance	25/30 (83%)
Different currency, within 2% FX variance	22/30 (73%)
Different currency, >2% FX variance	15-20/30
FX rate unavailable (fallback used)	10/30 (33%)

Score example

Multi-currency match with slight FX variance:

{
  "confidence": 82,
  "confidence_breakdown": {
    "amount": {
      "score": 36,
      "weighted_score": 14.4,
      "details": {
        "source_amount": "EUR 1,000.00",
        "target_amount": "USD 1,095.00",
        "converted_source": "USD 1,085.00",
        "variance_percent": 0.91
      }
    },
    "currency": {
      "score": 22,
      "weighted_score": 6.6,
      "details": {
        "source_currency": "EUR",
        "target_currency": "USD",
        "fx_rate_used": 1.085,
        "fx_rate_date": "2024-01-15",
        "fx_variance_from_market": 0.8
      }
    },
    "date": {
      "score": 18,
      "weighted_score": 3.6
    },
    "rule": {
      "score": 10,
      "weighted_score": 1.0
    }
  }
}

Variable rates by transaction attributes

Advanced Feature: Variable rate matching allows rates to change based on transaction attributes like MCC, card type, transaction method, and merchant segment. This is commonly used in acquiring/card network reconciliation.

In some reconciliation scenarios, particularly in acquiring and card network processing, the applicable rate varies based on multiple transaction attributes rather than being fixed.

Common use cases

Acquiring Reconciliation (Interchange Plus)

Rate varies by MCC (Merchant Category Code)
Different rates for credit vs. debit cards
Segment-based pricing (retail, restaurant, fuel)
Transaction method (physical vs. link/online)

Telecommunications

Different rates per carrier
Rate varies by plan type and region
Promotional vs. standard pricing

Multi-Tier Pricing

Volume-based rate tiers
Customer segment pricing
Time-based rate variations

Rate lookup configuration

Configure rate lookup based on transaction metadata in your context settings:

{
  "name": "Interchange Plus Rate Lookup",
  "rate_type": "variable",
  "lookup_strategy": "multi_attribute",
  "attributes": [
    {
      "field": "metadata.mcc",
      "type": "string",
      "required": true
    },
    {
      "field": "metadata.card_type",
      "type": "string",
      "required": true,
      "values": [
        "credit",
        "debit"
      ]
    },
    {
      "field": "metadata.transaction_method",
      "type": "string",
      "required": true,
      "values": [
        "physical",
        "online",
        "link"
      ]
    }
  ],
  "rate_source": {
    "type": "api",
    "endpoint": "https://rates-api.example.com/interchange/v1/rate",
    "method": "POST",
    "auth_type": "bearer",
    "cache_ttl_seconds": 3600
  },
  "fallback": {
    "strategy": "default_rate",
    "default_rate": 2.5,
    "alert_on_fallback": true
  }
}

Best practices for variable rates

Cache rate lookups

Enable caching for rate API calls to reduce latency. Most rates don’t change within a day.

Version your rate tables

Use versioned rate tables (e.g., “2024Q1”) and track which version was used for each match.

Set appropriate tolerance

Network fees can vary slightly. Set tolerance to 1-2% to avoid false exceptions.

Monitor rate lookup failures

Alert when rate lookups fail frequently - may indicate missing MCC codes or API issues.

Best practices

Use reliable FX rate sources

Connect to established FX providers with historical data. Avoid sources with gaps or delayed updates.

Set appropriate tolerances by currency

Volatile currencies (emerging markets) need higher tolerances. Stable pairs (EUR/USD) can use tighter tolerances.

Monitor FX variance trends

Regularly review FX variance reports. Increasing variance may indicate timing issues or rate source problems.

Document rate source decisions

Record why specific rate sources and strategies were chosen. This helps during audits and troubleshooting.

Plan for rate unavailability

Configure sensible fallback behavior and alerts. Have a process for providing manual rates when needed.

Consider settlement timing

FX rates can shift between transaction and settlement dates. Choose rate date strategy based on your accounting requirements.

Introduction

Getting started

Configuration

Daily reconciliation

Integrations

Reference

​Overview

​Enabling multi-currency

​Context configuration

​Multi-currency settings

​Base currency

​Choosing a base currency

​Changing base currency

​FX rate sources

​External provider

​Midaz asset rate engine (optional)

​Manual entry

​Rate date strategy

​Strategy options

​Configure rate date strategy

​Rate time options

​Tolerance configuration

​Tolerance formula

​Tolerance examples

​Custom tolerance by currency pair

​Handling missing FX rates

​Fallback options

​Configure fallback

​Missing rate exception

​Confidence scoring impact

​Currency score calculation

​Score example

​Variable rates by transaction attributes

​Common use cases

​Rate lookup configuration

​Best practices for variable rates

​Best practices

​Next steps

Confidence Scoring

Split & Aggregate

Overview

Enabling multi-currency

Context configuration

Multi-currency settings

Base currency

Choosing a base currency

Changing base currency

FX rate sources

External provider

Midaz asset rate engine (optional)

Manual entry

Rate date strategy

Strategy options

Configure rate date strategy

Rate time options

Tolerance configuration

Tolerance formula

Tolerance examples

Custom tolerance by currency pair

Handling missing FX rates

Fallback options

Configure fallback

Missing rate exception

Confidence scoring impact

Currency score calculation

Score example

Variable rates by transaction attributes

Common use cases

Rate lookup configuration

Best practices for variable rates

Best practices

Next steps