Memo-Based Payment Matching

Overview

Memo-Based Payment Matching uses a verified memo as the primary lookup key for a payment record. The system first extracts the on-chain field, validates its encoding and type, and searches for an active reference issued for the destination.

Shared-address systems benefit because they do not need a different address for every payer. However, the memo becomes operationally mandatory, and missing or incorrect values create unattributed deposits.

The method depends on accurate Memo Attribution. A memo can identify a customer, invoice, return transaction, or another purpose, so the namespace and issuance rule must be known before matching.

Matching should reject expired, already-consumed, duplicated, or cross-network memo values. An exact reference can still be unsafe if the amount or asset is wrong, so Amount-Based Matching and transaction validation remain necessary.

Audit records should preserve the issued reference, raw memo, decoded value, matched object, confidence, and any manual intervention. Random or nonsequential references reduce guessability and accidental collisions in public transaction data.

A memo should generally be single-use for invoice matching unless the product deliberately represents a reusable customer account. Single-use references should be marked consumed only after the payment transition commits successfully. If the database update fails, retries must not assign the same transaction to another active memo or credit the first record twice.

If a network has a maximum memo length or limited memo types, reference generation must respect those constraints before checkout creation. Truncating a reference after issuance can create collisions and make the original internal lookup impossible.

Collision tests should use the full active reference population and should treat different memo types as separate namespaces unless the application explicitly maps them together.