Skip to main content
Real-world reconciliation often involves transactions that don’t match 1:1. A single payment may cover multiple invoices, or several deposits may consolidate into one bank entry. Matcher handles these complex scenarios through split and aggregate matching.

​
Overview

Matcher supports four matching patterns:
PatternDescriptionExample
1:1One source to one targetSingle invoice payment
1:NOne source to many targetsBulk payment covering invoices
N:1Many sources to one targetDeposits consolidated at bank
N:MMany sources to many targetsComplex netting

​
How it works

Split and aggregate behavior is controlled by two mechanisms:
  1. Context type — determines the matching cardinality (1:1, 1:N, or N:M).
  2. Rule allocation flags — control how amounts are distributed within a match group.
There is no separate “split” or “aggregate” setting on the context. The context type defines what patterns are allowed, and the rule config controls allocation behavior.

​
Context type mapping

Context typeAllowed patterns
1:1One source to one target only
1:NOne source to many targets (split), or many sources to one target (aggregate)
N:MAny combination of sources and targets

​
Rule allocation settings

All rule types accept allocation flags in their config:
FieldTypeDescription
allowPartialBooleanAllow partial allocation of transaction amounts
allocationDirectionStringAllocation order: LEFT_TO_RIGHT or RIGHT_TO_LEFT
allocationToleranceModeStringHow tolerance is measured: ABS (absolute) or PERCENT
allocationToleranceValueDecimalTolerance threshold for allocation residuals
allocationUseBaseAmountBooleanUse base (converted) amount for allocation

​
Example: tolerance rule with allocation

cURL
curl -X POST "https://api.matcher.example.com/v1/config/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "TOLERANCE",
   "priority": 2,
   "config": {
     "percentTolerance": 0.01,
     "absTolerance": 5.0,
     "matchCurrency": true,
     "allowPartial": true,
     "allocationDirection": "LEFT_TO_RIGHT",
     "allocationToleranceMode": "ABS",
     "allocationToleranceValue": 10.0,
     "matchScore": 85,
     "matchBaseScore": 80
   }
 }'

​
Creating a 1:N context

To enable split or aggregate matching, create a context with type 1:N:
cURL
curl -X POST "https://api.matcher.example.com/v1/config/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Payment Reconciliation",
   "type": "1:N",
   "interval": "daily"
 }'
API Reference: Create context

​
1:N split matching

One source transaction matches multiple target transactions.

​
Common use cases

  • Bulk payment: Single wire covering multiple invoices
  • Payroll: One bank debit for multiple salary payments
  • Settlement: One gateway payout for multiple orders

​
Example: bulk invoice payment

Source (Bank Statement):
IDAmountReference
bank_001$15,000.00BULK-PAY-2024-001
Targets (Ledger Entries):
IDAmountInvoice
inv_001$5,000.00INV-2024-001
inv_002$7,500.00INV-2024-002
inv_003$2,500.00INV-2024-003
Result: 1:3 match with full allocation

​
N:1 aggregate matching

Multiple source transactions match one target transaction.

​
Common use cases

  • Bank deposits: Multiple checks deposited as one credit
  • Card settlements: Daily batch of transactions as one deposit
  • Cash consolidation: Multiple register receipts to one deposit

​
Example: consolidated deposit

Sources (Point of Sale):
IDAmountRegister
pos_001$1,250.00REG-01
pos_002$980.00REG-02
pos_003$1,770.00REG-03
Target (Bank Statement):
IDAmountReference
bank_002$4,000.00DEPOSIT-20240120
Result: 3:1 match with full allocation

​
N:M many-to-many matching

Multiple source transactions match multiple target transactions. This is the most complex pattern.

​
Common use cases

  • Intercompany netting: Multiple invoices netted against multiple payments
  • Trade settlements: Complex clearing with partial fills
  • Revenue recognition: Multiple deliveries against multiple advances

​
Example: intercompany netting

Sources (Company A Payables):
IDAmountReference
pay_001$10,000.00IC-PAY-001
pay_002$8,000.00IC-PAY-002
Targets (Company A Receivables):
IDAmountReference
rec_001$12,000.00IC-REC-001
rec_002$6,000.00IC-REC-002
Result: 2:2 match, $18,000 total matched To enable N:M matching, create a context with type N:M:
cURL
curl -X POST "https://api.matcher.example.com/v1/config/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Intercompany Netting",
   "type": "N:M",
   "interval": "weekly"
 }'

​
Running and reviewing matches

After configuring the context and rules, trigger a matching run and review the resulting groups.

​
Run matching

cURL
curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mode": "DRY_RUN"
 }'

​
View match run history

cURL
curl -X GET "https://api.matcher.example.com/v1/matching/contexts/{contextId}/runs" \
 -H "Authorization: Bearer $TOKEN"

​
View match groups

cURL
curl -X GET "https://api.matcher.example.com/v1/matching/runs/{runId}/groups" \
 -H "Authorization: Bearer $TOKEN"

​
View group details

cURL
curl -X GET "https://api.matcher.example.com/v1/matching/groups/{groupId}" \
 -H "Authorization: Bearer $TOKEN"

​
Confirm a match group

cURL
curl -X POST "https://api.matcher.example.com/v1/matching/groups/{groupId}/confirm" \
 -H "Authorization: Bearer $TOKEN"

​
Reject a match group

cURL
curl -X POST "https://api.matcher.example.com/v1/matching/groups/{groupId}/reject" \
 -H "Authorization: Bearer $TOKEN"

​
Revoke a confirmed match group

cURL
curl -X POST "https://api.matcher.example.com/v1/matching/groups/{groupId}/revoke" \
 -H "Authorization: Bearer $TOKEN"

​
Matching algorithm

For N:M scenarios, Matcher uses deterministic sequential allocation to pair transactions.

​
How it works

  1. Sort: Transactions are sorted deterministically to ensure reproducible results across runs.
  2. Iterate: The engine walks through candidates in priority order.
  3. Allocate: Amounts are distributed according to the allocationDirection setting (LEFT_TO_RIGHT or RIGHT_TO_LEFT).
  4. Track residuals: Any remaining unallocated amounts are tracked. If allowPartial is true, partial matches are created; otherwise, unallocated transactions become exceptions.

​
Best practices

Many-to-many matching is complex. Start with simpler patterns and enable N:M only when necessary.
Small rounding differences are common in split payments. Set allocationToleranceValue to a few cents to avoid false exceptions.
Only set allowPartial to true when partial matches are expected. This prevents false matches from incomplete data.
Always test split and aggregate matching in DRY_RUN mode first to verify allocation results.
Track residual amounts over time. Growing residuals may indicate systematic matching issues.

​
Next steps

Match Rules

Configure rules and allocation settings.

Security

Security and access control.