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
- Bank: Statements or feeds from banks
- ERP: SAP, Oracle, NetSuite exports
- Ledger: Internal ledger systems (including Midaz)
- Payment processor: Stripe, Adyen, PayPal settlements
- Card network: Visa, Mastercard, Elo files
Source setup
Each source has:
- Name: Label it (e.g., “Chase Checking”)
- Type: Category (bank, ERP, etc.)
- Field map: How its fields map to Matcher’s 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 | Type | Description |
|---|
transaction_id | String | Source-system transaction identifier |
amount | Decimal | Transaction amount (positive or negative) |
currency | String | ISO 4217 currency code |
date | DateTime | Transaction date |
reference | String | External reference or description |
metadata | Object | Source-specific attributes |
Example mapping
A bank statement exposing TXN_ID, VALUE, CCY, and POST_DATE would be mapped as:
{
"transaction_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)
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 | fields: list of fields to compare |
| TOLERANCE | percent: percentage variance, absolute: fixed variance amount |
| DATE_LAG | days_before, days_after: allowed offset from transaction date |
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 |
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 |
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 |
| Rule match | 10% | Deterministic rule application |
Confidence tiers
| Tier | Score range | System behavior |
|---|
| Auto-approved | ≥ 90 | Confirmed automatically |
| Needs review | 60–89 | Flagged for manual review |
| No match | < 60 | Treated as an exception |
Confidence thresholds can be customized per tenant to reflect different risk tolerances.
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 |
|---|
timestamp | Action timestamp (UTC) |
user_id | Actor responsible for the action |
action | Action performed |
resource_type | Affected resource type |
resource_id | Identifier of the affected resource |
before_state | State before the action |
after_state | State after the action |
notes | Justification, when applicable |
Audit logs are append-only. Entries cannot be modified or removed.
Next steps
