Fee rules

Configure fee schedules and predicate rules used by NET or GROSS normalization when the matching side and currencies are compatible.

Fee handling in Matcher is split across two entities that work together:

• 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.

When fee normalization is enabled and the transaction and schedule currencies match, modeling expected fees this way lets Matcher account for predictable charges before comparing transactions.

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 the difference is expected and documented. Fee schedules describe the charge, and fee rules select when to use it during enabled fee normalization.

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.

1. A fee schedule is created once at the tenant level and can be reused by many rules across many contexts.
2. A fee rule is created inside a context. It sets a side, a feeScheduleId, a priority, and a list of predicates.
3. When Matcher processes a context with fee normalization enabled, 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 how a fee is computed by editing the schedule, and change when it applies by editing the rule — without touching the other.

A fee rule alone does not change comparison amounts. Fee-rule evaluation affects fee reconciliation only when the context sets feeNormalization to NET or GROSS, the relevant side has rules, and the transaction and schedule currencies match.

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:

• Create fee schedule
• List fee schedules
• Retrieve fee schedule
• Update fee schedule
• Delete fee schedule

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 the code MTCH-0108; the API problem does not list the 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:

• Create fee rule
• List fee rules
• Retrieve fee rule
• Update fee rule
• Delete fee rule

End-to-end flow

---

Putting it together, expected-fee handling follows three steps:

1. 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.

2. 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.

3. Apply during matching

   Set the context’s feeNormalization to NET or GROSS. 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). The conflict response does not list blocking contexts. Update or remove current rule references first; historical variance references continue to block deletion.

Next steps

---

Match rules

Configure how transactions are compared once expected fees are accounted for.

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.