Payment Match Key

Overview

What does Payment Match Key mean?

Payment Match Key is a field or composite identifier used to connect a blockchain transfer with the intended internal payment record.

How it works in practice

A payment match key is the deterministic identifier or composite of fields used to associate transfer evidence with a payment expectation. Depending on the model it may be an invoice-specific deposit address, an account-and-memo pair, or a tuple containing chain, token contract, transaction hash and event index. The design must define when the key is created, its uniqueness scope and how it behaves on retries. A durable mapping table lets multiple observers process the same event without crediting another order.

Limits and common misunderstandings

A transaction hash alone can be insufficient when one transaction contains multiple transfers or one transfer is allocated across separate obligations. A memo can be omitted or mistyped. Keys composed from rounded amounts or local timestamps are unstable and can collide.

Additional implementation considerations

Choosing the key depends on how the underlying chain represents transfers. Ethereum-style token payments can require an event index because one transaction may emit several Transfer events; Bitcoin-style UTXO systems may need output-level attribution. Store the original observation ID, match ID and merchant context in separate columns so a corrected invoice mapping never destroys the immutable chain evidence. Enforce uniqueness in the database, not only application code.

Related glossary terms

Payment Match Rule; Reference-Based Payment Matching; Order Attribution