Fee rules

Fee handling in Matcher is split across two entities:

A fee schedule defines how much fee to compute: the currency, rounding, and one or more fee items (flat, percentage, tiered, or expression-based).
A fee rule decides when a fee schedule applies. It belongs to a reconciliation context, targets a matching side, and carries predicates that a transaction’s metadata must satisfy. When the predicates match, the rule selects its fee schedule.

Modeling expected fees this way lets Matcher check matched transactions against the expected fee. With fee normalization enabled, Matcher also accounts for the fee before comparing transactions, when the transaction and schedule currencies match.

What fee handling solves

Reconciliation fails when one side of a transaction includes fees or charges that the other side doesn’t record. A payment gateway deducts a processing fee before settling. A bank charges a wire transfer fee. An acquirer nets fees against payouts. Without modeled fees, Matcher treats these differences as amount mismatches and generates exceptions, even when you expect and document the difference. Fee schedules describe the charge, and fee rules select when to use it.

How rules and schedules fit together

A fee rule does not contain the fee amount or calculation itself. It references a fee schedule by ID and applies it to the transactions its predicates select.

You create a fee schedule once at the tenant level. Many rules across many contexts can reuse it.
You create a fee rule inside a context. It sets a side, a feeScheduleId, a priority, and a list of predicates.
When Matcher processes a context, it evaluates the relevant side’s fee rules in priority order (lowest first). The first matching rule selects the referenced schedule.

This separation means you change when the fee applies by editing the rule, without touching the schedule. Editing a schedule changes only its name, application order, rounding scale, and rounding mode. To change its items or currency, create a new schedule and point the rule’s feeScheduleId at it.

A fee rule alone does not change comparison amounts. It changes them only when the context sets feeNormalization to NET or GROSS, the relevant side has rules, and the transaction and schedule currencies match. Once a context has fee rules, every COMMIT run also checks matched transactions against the expected fee and raises FEE_VARIANCE, FEE_DATA_MISSING, or FEE_CURRENCY_MISMATCH exceptions.

Fee rule structure

A fee rule belongs to a context and has the following fields.

Field	Type	Description
`side`	Enum	Which matching side the rule applies to: `LEFT`, `RIGHT`, or `ANY`. `ANY` matches transactions on either side.
`feeScheduleId`	UUID	The fee schedule this rule applies when its predicates match.
`name`	String	Human-readable name of the fee rule.
`priority`	Integer	Evaluation priority; lower numbers are evaluated first. Must be unique within the context. `LEFT`, `RIGHT`, and `ANY` rules share the same priority space.
`predicates`	Array	Predicates (ANDed together) that a transaction’s metadata must satisfy for this rule to apply.

Predicates

Each predicate tests one transaction metadata field with an operator.

Field	Description
`field`	The transaction metadata field the predicate tests (e.g. `institution`).
`operator`	The comparison operator (see below).
`value`	Single comparison value, used by `EQUALS`, `NEQ`, and the numeric comparators.
`values`	List of candidate values, used by `IN` and `BETWEEN`.

Available operators:

Operator	Meaning
`EQUALS`	Case-insensitive string equality with a single `value`.
`NEQ`	For a present field, numeric inequality when both values coerce to decimals; otherwise case-insensitive string inequality.
`IN`	Matches any entry in `values`.
`EXISTS`	Asserts the field is present (no value needed).
`GT` / `GTE` / `LT` / `LTE`	Numeric comparison of the field against a single decimal `value`.
`BETWEEN`	Inclusive numeric membership in `values` = `[lo, hi]` (with `lo <= hi`).

Missing fields evaluate to false for every operator except EXISTS.

Fee schedule structure

A fee schedule is a tenant-level entity that computes a fee from a gross amount.

Field	Type	Description
`name`	String	Human-readable name of the schedule.
`currency`	String	ISO 4217 currency the schedule’s amounts are denominated in.
`applicationOrder`	Enum	How items combine: `PARALLEL` applies every item to the same gross base; `CASCADING` applies each item to the net remaining after prior items.
`roundingScale`	Integer	Number of decimal places fee amounts are rounded to.
`roundingMode`	Enum	Rounding strategy: `HALF_UP`, `BANKERS`, `FLOOR`, `CEIL`, or `TRUNCATE`.
`items`	Array	One or more fee items that make up the schedule (at least one required).

Fee items

Each item declares a name, a priority (application order, relevant for CASCADING), a structureType, and a type-specific structure.

`structureType`	`structure` shape	Notes
`FLAT`	`{ "amount": "1.50" }`	Fixed amount.
`PERCENTAGE`	`{ "rate": "0.029" }`	`rate` is a `0..1` fraction of the base (`0.029` = 2.9%), not a percent value.
`TIERED`	`{ "tiers": [ { "rate": "0.01", "upTo": "1000" }, ... ] }`	Same `0..1` fraction semantics per tier rate.
`EXPRESSION`	`{ "expression": "gross - desconto + multa" }`	Formula over identifiers (`+ - * /`, parentheses, and the functions `days_late`, `days_between`, `max`, `min`, `abs`, `clamp`). `gross` is the engine-provided base amount and overrides any metadata key named `gross`; other identifiers resolve from metadata.

Managing fee schedules

Fee schedules are tenant-scoped and managed independently of any context.

Operation	Endpoint
Create a fee schedule	`POST /v1/fee-schedules`
List fee schedules	`GET /v1/fee-schedules`
Retrieve a fee schedule	`GET /v1/fee-schedules/{scheduleId}`
Update a fee schedule	`PATCH /v1/fee-schedules/{scheduleId}`
Delete a fee schedule	`DELETE /v1/fee-schedules/{scheduleId}`
Simulate a fee calculation	`POST /v1/fee-schedules/{scheduleId}/simulate`

Create a fee schedule

This schedule computes a 2.9% processing fee on the gross amount, denominated in BRL.

cURL

curl -X POST "https://api.matcher.example.com/v1/fee-schedules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Gateway Processing - 2.9%",
   "currency": "BRL",
   "applicationOrder": "PARALLEL",
   "roundingScale": 2,
   "roundingMode": "HALF_UP",
   "items": [
     {
       "name": "processing",
       "priority": 1,
       "structureType": "PERCENTAGE",
       "structure": { "rate": "0.029" }
     }
   ]
 }'

API Reference:

Simulate a fee schedule

Before wiring a schedule into a rule, simulate it against a gross amount to confirm the computed fee.

cURL

curl -X POST "https://api.matcher.example.com/v1/fee-schedules/{scheduleId}/simulate" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "grossAmount": "100.00",
   "currency": "BRL"
 }'

The response returns the netAmount, totalFee, and a per-item breakdown.

API Reference: Simulate fee calculation

A fee schedule cannot be deleted while a fee rule or fee-variance history references it. The delete request returns 409 Conflict with code MTCH-0108. When fee rules block the deletion, the response lists their contexts in the errors[] entry whose location is fee-schedule.delete.blocking-contexts. Remove or repoint current rule references first. Historical variance references continue to block deletion.

Managing fee rules

Fee rules are created inside a context and reference a fee schedule.

Operation	Endpoint
Create a fee rule	`POST /v1/contexts/{contextId}/fee-rules`
List fee rules for a context	`GET /v1/contexts/{contextId}/fee-rules`
Retrieve a fee rule	`GET /v1/fee-rules/{feeRuleId}`
Update a fee rule	`PATCH /v1/fee-rules/{feeRuleId}`
Delete a fee rule	`DELETE /v1/fee-rules/{feeRuleId}`

Create a fee rule

This rule applies the fee schedule created above to right-side transactions whose institution metadata equals Banco do Brasil.

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/fee-rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "side": "RIGHT",
   "feeScheduleId": "550e8400-e29b-41d4-a716-446655440000",
   "name": "BB Right-Side Processing Fee",
   "priority": 0,
   "predicates": [
     {
       "field": "institution",
       "operator": "EQUALS",
       "value": "Banco do Brasil"
     }
   ]
 }'

API Reference:

End-to-end flow

Expected-fee handling follows three steps:

Create the fee schedule

Define how the fee is computed once at the tenant level with POST /v1/fee-schedules. Optionally validate it with the simulate endpoint. Note the returned id.

Create the fee rule in the context

Inside the reconciliation context, create a fee rule with POST /v1/contexts/{contextId}/fee-rules. Set feeScheduleId to the schedule’s id, choose the side, set a unique priority, and add the predicates that select the transactions the fee applies to.

Apply during matching

Set the context’s feeNormalization to NET or GROSS. The context then needs at least one fee rule to activate. Until it has one, activation readiness reports context.activation.requirement.fee-rule. During matching, Matcher evaluates rules for each relevant side in priority order. A matching rule changes the comparison amount only when its schedule and the transaction use the same currency.

Best practices

Reuse schedules across contexts

A fee schedule is tenant-scoped and can be referenced by many rules. Define a schedule once (e.g. “Card Processing - Visa”) and point rules in different contexts at it. Editing the schedule updates every rule that uses it.

Keep priorities unique and intentional

Priorities are unique within a context and shared across LEFT, RIGHT, and ANY rules. Order them from most specific to most general so a narrow rule wins before a broad fallback.

Scope rules with precise predicates

Predicates are ANDed together and tested against transaction metadata. Combine operators (EQUALS, IN, BETWEEN, EXISTS) to target exactly the transactions a fee applies to and avoid unintended fee attribution.

Simulate before wiring a schedule into a rule

Use POST /v1/fee-schedules/{scheduleId}/simulate to confirm a schedule produces the expected fee for representative amounts before referencing it from a rule.

Repoint rules before deleting a schedule

A schedule referenced by a rule or fee-variance history cannot be deleted (409 MTCH-0108). When fee rules block it, the response lists their contexts in errors[]. Update or remove current rule references first; historical variance references continue to block deletion.

Next steps

Match rules

Configure how Matcher compares transactions once it accounts for expected fees.

Exception routing

Review explicit assignment, dispatch, and callback behavior for exceptions that fee handling doesn’t cover.

Fee schedules API

Full API reference for fee schedule endpoints.

Fee rules API

Full API reference for fee rule endpoints.

Overview

Guides

Console

MCP Server

Operations

What fee handling solves

How rules and schedules fit together

Fee rule structure

Predicates

Fee schedule structure

Fee items

Managing fee schedules

Create a fee schedule

Simulate a fee schedule

Managing fee rules

Create a fee rule

End-to-end flow

Best practices

Next steps

Match rules

Exception routing

Fee schedules API

Fee rules API

​What fee handling solves

​How rules and schedules fit together

​Fee rule structure

​Predicates

​Fee schedule structure

​Fee items

​Managing fee schedules

​Create a fee schedule

​Simulate a fee schedule

​Managing fee rules

​Create a fee rule

​End-to-end flow

​Best practices

​Next steps

Match rules

Exception routing

Fee schedules API

Fee rules API

What fee handling solves

How rules and schedules fit together

Fee rule structure

Predicates

Fee schedule structure

Fee items

Managing fee schedules

Create a fee schedule

Simulate a fee schedule

Managing fee rules

Create a fee rule

End-to-end flow

Best practices

Next steps