LedgerMatch is the external service that powers matching. It takes an incoming transaction and expected candidates, returns ranked matches with confidence scores. Supports REST (single-transaction) and gRPC (bulk).

Role of LedgerMatch

LedgerMatch is the primary external dependency for reconciliation. Payment Reconciler sends it:

Input — One incoming transaction + expected transactions (candidates) for the same tenant and environment. Match requests include a non-negative amount and direction (DEBIT | CREDIT) so scoring aligns with accounting semantics.
Output — Ranked matches with confidence scores and per-field indicators

LedgerMatch does not store data; it performs the scoring and ranking. Payment Reconciler stores the resulting matches and lets you accept or reject them.

How LedgerMatch scores matches

Each match includes:

Score	Description
confidence	Combined score (0–1). Used for auto-accept threshold.
embeddingSimilarity	Semantic similarity of merchant/description (embeddings).
amountScore	How closely amounts align.
dateScore	Proximity of transaction dates.
referenceMatch	Whether reference IDs match (boolean).

LedgerMatch also returns matchedFields indicating which fields contributed (merchant, amount, date, description, reference). The explanation field provides a human-readable summary.

When LedgerMatch is called

Trigger	When	Protocol
Auto-match	New incoming transaction created and `autoMatchEnabled` is true	REST
Manual match	`POST /matches/match` with `incomingTransactionId`	REST
Scheduled matching job	Batch job processes PENDING incoming transactions	REST or gRPC

For scheduled jobs, the protocol depends on tenant settings and batch size. See REST vs gRPC below.

REST vs gRPC

Strategy	When used	Notes
rest	Default. Auto-match, manual trigger, single-transaction jobs.	One REST call per incoming transaction.
grpc	Tenant has `matchStrategy: 'grpc'` and job processes 2+ transactions.	Bulk gRPC stream; more efficient for large batches.

Configure via ledgerMatchPreferences.matchStrategy in Tenant Settings. When set to grpc, autoMatchEnabled is automatically disabled (auto-match uses REST only).

For gRPC bulk matching, autoAcceptForBulkMatch in LedgerMatch preferences controls whether top-ranked matches above threshold are auto-accepted during the batch run.

Retry and timeout

LedgerMatch calls can fail due to network or service issues. Configure in ledgerMatchPreferences:

retryAttempts — Number of retries (1–10)
retryDelaysMs — Comma-separated delays between retries (e.g. 1000,2000,4000)
timeoutMs — Request timeout (1000–60000 ms)

See LedgerMatch Preferences for details.

Health check

GET /health/ledger-match verifies LedgerMatch is reachable. Use this for monitoring and alerting. The response includes status and timestamp.

API Reference

For match endpoints and request/response structures, see Matches in the API Reference.