Matcher concepts

The five core concepts in Matcher: contexts, sources, field maps, rules, and matches. Understand these and you’ll understand how the entire system works.

Context

A context defines what you’re reconciling. It’s the container that holds your sources, rules, and results.

A context answers: what am I matching against what?

Context types

Type	Description	Example
1:1	One-to-one reconciliation	Bank statement vs ERP records
1:N	One-to-many reconciliation	One payment covering multiple invoices
N:M	Many-to-many reconciliation	Netting or aggregation scenarios

Example

A context named “Chase Bank vs ERP System” would:

Define Chase Bank as one reconciliation source
Define your ERP system as another source
Specify the rules used to reconcile transactions between them

Source

A source is where transactions come from. Every context needs at least two sources—that’s what you’re reconciling.

Source types

LEDGER: Internal ledger systems (including Midaz)
BANK: Bank statement feeds
GATEWAY: Payment gateway settlements (Stripe, Adyen, PayPal)
CUSTOM: Bespoke, user-defined feeds
FETCHER: Sources pulled automatically by the discovery engine (aggregator connections)

Source setup

Each source requires:

Name: Label it (e.g., “Chase Checking”)
Type: Category (LEDGER, BANK, GATEWAY, CUSTOM, or FETCHER)
Side: Which matching side it feeds (LEFT or RIGHT)
Config: Source-specific connection and parsing settings

Field maps translate each source’s fields into Matcher’s standard schema.

Field map

A field map translates external field names into Matcher’s standard schema. Every system calls things differently—field maps normalize that.

Standard fields

Field	Required	Type	Description
`external_id`	Yes	String	Source-system transaction identifier
`amount`	Yes	Decimal	Transaction amount (positive or negative)
`currency`	Yes	String	ISO 4217 currency code
`date`	Yes	DateTime	Transaction date
`description`	No	String	External reference or description
`fee_amount`	No	Decimal	Optional fee amount column
`fee_currency`	No	String	Optional fee currency column

The canonical vocabulary is closed — a field map that declares any other key is rejected.

Example mapping

A bank statement exposing TXN_ID, VALUE, CCY, and POST_DATE would be mapped as:

{
  "external_id": "TXN_ID",
  "amount": "VALUE",
  "currency": "CCY",
  "date": "POST_DATE"
}

Match rule

A match rule tells Matcher how to compare transactions. Rules run in priority order—first match wins.

Rule types

EXACT: Fields must match exactly (amount, date, reference)
TOLERANCE: Allow small differences (0.5% variance, $10 absolute)
DATE_LAG: Match within a date window (±3 days). Like FUZZY, DATE_LAG matches never auto-confirm — they always go to manual review.
FUZZY: Graded similarity on references/descriptions (normalized, substring, or similarity-scored). FUZZY only proposes—it never auto-confirms, so a human reviews every fuzzy link.

Priority order

Lower numbers run first. Matcher stops at the first matching rule.

Priority	Rule	Description
1	Exact match	Amount, date, and reference must match
2	Same-day tolerance	Same date, amount within 0.5%
3	Week tolerance	Within 7 days, amount within 1%

Rule parameters

Rule type	Parameters
EXACT	`matchAmount`, `matchCurrency`, `matchDate`, `matchReference`: which fields must match exactly
TOLERANCE	`tolerance`: object with `percentTolerance` and/or `absTolerance` (decimal strings)
DATE_LAG	`minDays`, `maxDays`: allowed day-difference band, plus `inclusive` for the upper bound

Match

A match is when transactions from different sources are reconciled together. It’s the end goal.

Match status

Status	Description
`PROPOSED`	Matcher found it, waiting for confirmation
`CONFIRMED`	Auto-approved or manually approved
`REJECTED`	Manually rejected
`REVOKED`	A previously confirmed match was unmatched, returning its transactions to review

Match patterns

1:1 match

One transaction from each source is reconciled.

Bank: $100.00 on Jan 15 → ERP: $100.00 on Jan 15

1:N match

One transaction is reconciled against multiple transactions.

Bank: $300.00 → ERP: $100.00 + $100.00 + $100.00

N:1 match

Multiple transactions are reconciled against a single transaction.

Bank: $50.00 + $50.00 + $50.00 → ERP: $150.00

Match items

Each match group contains match items, which record transaction participation and allocation. This enables partial reconciliation in split and aggregation scenarios.

Exception

An exception is a transaction that didn’t match. It needs manual review.

Exception status

Status	Description
`OPEN`	Waiting for assignment
`ASSIGNED`	Someone’s investigating
`PENDING_RESOLUTION`	A resolution is in progress, awaiting completion
`RESOLVED`	Handled

Severity

Matcher auto-classifies exceptions so you know what to prioritize.

Severity	Default criteria
Critical	Amount ≥ $100K, age ≥ 5 days, or regulatory flagged
High	Amount ≥ $10K or age ≥ 3 days
Medium	Amount ≥ 1,000 or age ≥ 1 day
Low	All other cases

Resolution types

Force match: Manually reconcile transactions
Adjustment: Record a compensating adjustment
Write-off: Close the exception with justification

Confidence score

A confidence score indicates the reliability of an automated match on a 0–100 scale. Higher scores represent stronger alignment between transactions.

Score calculation

Component	Weight	Description
Amount match	40%	Degree of amount alignment
Currency match	30%	Currency consistency
Date tolerance	20%	Proximity of transaction dates
Reference/description	10%	Reference/description alignment (graded 0–1 for FUZZY rules)

Confidence tiers

Tier	Score range	System behavior
Auto-approved	≥ 90	Confirmed automatically (EXACT and TOLERANCE rules only — FUZZY and DATE_LAG always go to review)
Needs review	60–89	Flagged for manual review
No match	< 60	Treated as an exception

Confidence weights and tier thresholds are fixed by the engine and are not configurable.

Audit log

An audit log is an immutable record of all system actions. It provides full traceability for operational review, audits, and regulatory compliance.

Logged events

Audit entries are created for:

Context, source, and rule changes
File ingestion and processing
Match confirmations and rejections
Exception resolution and overrides

Audit entry contents

Field	Description
`createdAt`	Action timestamp (UTC)
`actorId`	Actor responsible for the action
`action`	Action performed
`entityType`	Affected entity type
`entityId`	Identifier of the affected entity
`changes`	What changed, as a structured diff
`tenantSeq`	Per-tenant sequence number
`prevHash` / `recordHash`	Hash chain linking each entry to the previous one, making tampering detectable

Audit logs are append-only. Entries cannot be modified or removed.

Next steps

Architecture

See how these concepts are implemented across bounded contexts.

Quick start

Apply these concepts in a guided, hands-on flow.

Overview

Guides

Matcher UI

MCP Server

Operations

Matcher concepts

Context

Context types

Example

Source

Source types

Source setup

Field map

Standard fields

Example mapping

Match rule

Rule types

Priority order

Rule parameters

Match

Match status

Match patterns

1:1 match

1:N match

N:1 match

Match items

Exception

Exception status

Severity

Resolution types

Confidence score

Score calculation

Confidence tiers

Audit log

Logged events

Audit entry contents

Next steps

Architecture

Quick start

​Context

​Context types

​Example

​Source

​Source types

​Source setup

​Field map

​Standard fields

​Example mapping

​Match rule

​Rule types

​Priority order

​Rule parameters

​Match

​Match status

​Match patterns

​1:1 match

​1:N match

​N:1 match

​Match items

​Exception

​Exception status

​Severity

​Resolution types

​Confidence score

​Score calculation

​Confidence tiers

​Audit log

​Logged events

​Audit entry contents

​Next steps

Architecture

Quick start

Context

Context types

Example

Source

Source types

Source setup

Field map

Standard fields

Example mapping

Match rule

Rule types

Priority order

Rule parameters

Match

Match status

Match patterns

1:1 match

1:N match

N:1 match

Match items

Exception

Exception status

Severity

Resolution types

Confidence score

Score calculation

Confidence tiers

Audit log

Logged events

Audit entry contents

Next steps