Payment Match Rule

Overview

What it means and why it matters

A payment match rule is a defined condition for linking an observed transfer to a business obligation. Good rules prevent both missed credits and accidental double attribution.

How it works in practice

Rules may require exact network, asset contract and destination, plus a unique memo or address assignment. They then check acceptable amount, time window, transfer status and whether the payment event has already been allocated. Strong identifiers are evaluated before weaker heuristics such as approximate amount and arrival time.

Technical detail without the jargon

Rules should be versioned and tested against duplicates, partial transfers, multi-output transactions and transfers after expiry. Use integer base units for token amounts to prevent floating-point rounding errors. Specify how tolerance, minimum confirmations and aggregation of several transfers work.

A deeper point to understand

The most important matching rule is often not a positive rule but an exclusion: a transfer on an unsupported chain must never satisfy an invoice. After applying such exclusions, the system can match more complex cases like split payments. This ordering helps prevent a plausible amount or timestamp from overriding a definitive network mismatch.

Common mistakes and limitations

A match based on similar payment amounts is unsafe when thousands of invoices share the same destination. Never equate an invoice reference supplied in an HTTP request with authenticated on-chain ownership.

What to check in a real payment system

Test rules with wrong-chain transfers, fake token contracts, duplicate transactions, partial payments and an invoice paid by multiple transactions. Document whether matching is exclusive, whether manual override is allowed and which evidence field has the highest priority.

Related concepts

Crypto Invoice, Transaction Hash, Crypto Payment Status.

Further reading

Bitcoin Developer Guide — Payment Processing.