Matcher concepts

Learn Matcher’s five core concepts — contexts, sources, field maps, match rules, and matches — that shape every reconciliation you build.

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 reconcile. It is the configuration container for sources and rules. Matcher creates a new context in DRAFT, and its inline sources and rules are optional.

A context answers: what am I matching against what?

You can start with an empty draft. To activate it, configure at least one LEFT source and one RIGHT source, map every source (or declare valid camt053 options, which self-map), and add a match rule. If fee normalization is enabled, add a fee rule too.

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. A draft context can start without sources; an activatable context needs at least one source on each matching side.

Source types

• LEDGER: Ledger source category
• BANK: Bank source category
• GATEWAY: Payment-gateway source category
• CUSTOM: Custom source category
• FETCHER: A Fetcher source category

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 is optional. If you omit it, Matcher stores an empty config and uses parser defaults for absent policy keys.

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.

When a source config declares camt053 options, Matcher uses its built-in ISO 20022 mapping and ignores a field map; activation treats that source as mapped.

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 ascending priority; a transaction claimed by an earlier rule is unavailable to later rules, which still evaluate the remaining transactions.

Rule types

• EXACT: Compares configured fields exactly. Amount, currency, date (by day), and reference are enabled by default.
• TOLERANCE: Matches amounts inside the configured absolute and/or percentage tolerance. Omitted amount tolerances and dateWindowDays default to 0, so no drift or date window is allowed until you configure one.
• DATE_LAG: Matches within a configured day-difference band. minDays and maxDays both default to 0 (same day), not ±3. Like FUZZY, DATE_LAG matches never auto-confirm — they always go to manual review.
• FUZZY: Grades normalized transaction references. It uses Reference, populated from the transaction’s ExternalID; a field-map description is not a FUZZY input. FUZZY only proposes—it never auto-confirms, so a human reviews every fuzzy link.

Priority order

Lower numbers run first. A rule claims its matching transactions; later rules continue with the remaining transactions.

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%

These priorities and values are illustrative rules, not engine defaults. Configure the values for your reconciliation policy.

Rule parameters

Rule type	Parameters
EXACT	matchAmount, matchCurrency, matchDate, matchReference: which fields must match exactly
TOLERANCE	Top-level non-negative percentTolerance and/or absTolerance values (numbers or decimal strings); optionally set dateWindowDays (0 by default; maximum 3650). Do not wrap these values in a tolerance object.
DATE_LAG	minDays, maxDays: allowed day-difference band. Both default to 0, must be from 0 to 3650, and maxDays must be at least minDays; inclusive defaults to true and controls the upper bound.
FUZZY	minSimilarity: normalized-reference threshold from 0 to 1 (defaults to 0.80), plus optional amount, currency, and date axes.

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

N:M match

Multiple transactions on each side are reconciled together. N:M evaluation only executes EXACT and TOLERANCE rules; it considers up to four transactions per side in a group and caps each identity bucket at 40 candidates.

Bank: $100.00 + $200.00 → ERP: $150.00 + $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 records a transaction that needs review, including unmatched transactions and matched transactions with residual conditions such as FX-rate variance.

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	Absolute base amount ≥ 100,000, age ≥ 120 hours, or a configured regulatory source type
High	Absolute base amount ≥ 10,000 or age ≥ 72 hours
Medium	Absolute base amount ≥ 1,000 or age ≥ 24 hours
Low	All other cases

The classifier evaluates the criteria from top to bottom. When an exception meets the criteria of more than one severity, the highest matching severity applies.

Resolution workflows

• Resolve: Record a resolution label and optional reason to close an exception.
• Force match: Resolve an exception by forcing a match with an override reason after manual review.
• Adjust entry: Resolve an exception by creating an adjustment entry with a reason, notes, positive amount, currency, and effective time.

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	10%	Normalized reference 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	Does not create a match proposal

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

Audit log

---

An audit log is an immutable, append-only record created by an instrumented workflow. It provides traceability for the actions Matcher records.

Logged events

Only workflows instrumented to emit an audit event create entries. When audit publishing is configured, verified producers include:

• Context, source, field-map, and rule mutations
• Exception workflows, including force match and adjust entry

Audit entry contents

Field	Description
createdAt	Record creation timestamp (UTC), which can differ from the audited action time
actorId	Actor identifier, when supplied
action	Action performed
entityType	Affected entity type
entityId	Identifier of the affected entity
changes	Structured JSON event data; emitted events include occurred_at and any supplied changes
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.