Matches

What is a match

A match is a proposed link between an incoming transaction (actual payment received) and an expected transaction (payment you anticipated). LedgerMatch finds candidate expected transactions, scores them by confidence (0–1), and returns them ranked. Each match stays PENDING until you accept or reject it—or until it expires.

How matches are created

Matches are created when LedgerMatch is invoked:

• Auto-match — When autoMatchEnabled is true and a new incoming transaction is created
• Manual trigger — POST /matches/match with an incomingTransactionId
• Scheduled job — A batch matching job processes PENDING incoming transactions

See LedgerMatch Integration for REST vs gRPC and when each path is used.

Confidence and auto-accept

Each match has a confidence score (0–1). When confidence meets your tenant's matchingConfidenceThreshold, the system can auto-accept:

• Single candidate above threshold — Auto-accepted (if autoMatchEnabled)
• Multiple candidates above threshold — Behavior depends on tenant settings:
  • autoAcceptOnlyWhenSingleMatch: true — No auto-accept; requires manual review
  • autoAcceptTopRanked: true — Auto-accept only the top-ranked match

Configure these in Tenant Settings.

Match lifecycle

Accepting a match updates the incoming and expected transaction statuses to MATCHED. Rejecting leaves the incoming PENDING or UNMATCHED so you can try another candidate or create a new expected transaction.

Resolving matches

• Accept — Use when the match is correct. Links the incoming to the expected transaction and updates both to MATCHED.
• Reject — Use when the match is wrong. Optionally provide a reason. The incoming remains available for other matches.

For the full flow (Expected → Incoming → Match → Resolve), see Match Flow.

API Reference

For endpoints, parameters, and request/response samples, see Matches in the API Reference.