Reference
Glossary
Canonical definitions for the public Tekmerion vocabulary.
The canonical meaning of every term Tekmerion exposes on a public surface. Definitions here match their use across the rest of these docs verbatim; where a term has a fixed wire token, the token is given exactly as it appears on the wire.
| Term | Definition |
|---|
| Payment intent | A merchant's request to be paid for an order. It is not a payment: it records what the merchant expects and binds that expectation to a single on-chain address. See Payment intent. |
payment_intent_id | The canonical merchant-facing correlation key. One per intent, stable across every attempt. Correlate a notification or an API record to a payment by this value. |
| Payment attempt | One concrete expectation of payment within an intent: a specific chain, token, and expected amount. An expectation, not an outcome. See Payment attempt. |
attempt_id | A per-attempt reference, carried for traceability only. It MUST NOT be interpreted as the identity of a notification record. |
order_reference | The merchant's own correlation value for the order being paid. Recorded on the intent and carried through every surface that reports on the payment. |
deposit_address | The deterministic, per-intent on-chain address a payment resolves to, computed and fixed at intent creation — known before any contract code exists at it. The primary on-chain matching anchor (deposit_address + chain_id + token_id). One intent has exactly one deposit_address; every attempt shares it. |
chain_id | Numeric chain identifier. On the notification wire it is encoded as a string. |
token_id | Canonical token identifier. On EVM chains, the token's contract address. |
delivery_record_id | Identifies one semantic notification record. The deduplication anchor: every retry and manual re-delivery of the same notification carries the same delivery_record_id. |
| Term | Definition |
|---|
| Quote snapshot | An immutable record fixing the conversion between a merchant's base amount and the amount a customer pays in a chosen token, valid for a bounded window. An expectation input; it has no bearing on payment outcome. See Quotes. |
expires_at | The end of a quote snapshot's validity window. Past it, a fresh quote is required to form a new attempt; an expired snapshot remains an immutable historical record. |
| Base units | The smallest indivisible unit of a token. On-chain token amounts are expressed in base units. See Amounts and decimals. |
| Term | Definition |
|---|
| Deposit | The on-chain transfer that pays an intent. It lands at the intent's deposit_address and from that moment is governed by on-chain truth. See Deposit. |
| Observed threshold | The confirmation depth at which a deposit is recognized as present and the post-deposit compliance pipeline begins. Per-chain — see Supported chains and tokens. |
| Finality threshold | The confirmation depth at which an outcome becomes canonical and a payment can be finalized. Per-chain. Before it, observations are reorg-sensitive. |
finality_outcome | The single canonical outcome a payment carries at finality. One of paid, refunded, failed, duplicate_payment. See Statuses and projections. |
paid | The deposit was swept to the merchant's approved destination; the protocol fee was collected on-chain. |
refunded | The merchant returned a reject decision with a refund destination; the deposit was refunded; the protocol fee was collected on-chain. |
failed | The payment reached a terminal failure state without settlement or merchant-directed refund. No funds moved. |
duplicate_payment | A finalized, matched payment for an intent that was already settled. The intent's settlement is unaffected. |
| Term | Definition |
|---|
| Sweep | The on-chain transfer of the deposited balance to the merchant's approved destination, on a merchant approve decision. Produces finality_outcome paid. See Sweep and refund. |
| Refund | The on-chain transfer of the deposited balance to a merchant-supplied destination, on a merchant reject decision. Produces finality_outcome refunded. |
| Protocol fee | The fee collected on-chain at settlement and at a merchant-reject refund. Zero on the sanctions-hold path. Rates: see Fees. |
| Destination whitelist | The set of merchant-controlled addresses the merchant has pre-authorized by signature as the only valid sweep and refund targets. A target outside it is rejected on-chain. |
| Signature-relay | Tekmerion relays a merchant-signed authorization and the blockchain executes the transfer. Tekmerion never holds keys that can move merchant or customer funds. |
| Term | Definition |
|---|
| Pre-deposit screening | A check at checkout session start (geoblock and bot detection) that gates whether a deposit address is presented. See Checkout session. |
| Sanctions screening | A post-deposit check of the deposit's source address against the sanctions list. A match holds the payment, moves no funds, and takes no fee. |
| Merchant decision | The merchant's transaction-level approve, reject, or hold decision, returned via the KYT webhook. Tekmerion screens but does not override it. See KYT webhook. |
| Term | Definition |
|---|
notification_class | The field that selects a notification's meaning. One of payment_observed, payment_finalized, payment_held, duplicate_payment_incident. See Event catalog. |
payment_observed | The payment was observed on-chain at the observed threshold. Progress, not settlement. |
payment_finalized | The payment reached finality and a terminal finality_outcome was published. |
payment_held | The payment is held; no funds moved and no outcome is finalized. |
duplicate_payment_incident | An additional finalized payment was detected for an already-settled intent. Its own record, alongside the canonical payment_finalized record. |
hold_reason | The reason a payment is held; present only on payment_held. One of sanctions, kyt_timeout. |
v1=<hex> | The value format of the X-Tekmerion-Signature header: the version token v1, the = delimiter, and a 64-character lowercase-hex HMAC-SHA256 digest. See Signature verification. |
| Term | Definition |
|---|
| Proof-of-Payment (PoP) | A blockchain-derived, signed JSON artifact proving a settled payment occurred. Produced for paid outcomes. See Proof-of-Payment. |
schema_version | The version that defines the layout and meaning of a PoP artifact's data payload. Authoritative for that artifact; immutable once published. See Schema versioning. |
| Status / projection | A status Tekmerion exposes for a payment is a projection of canonical on-chain truth. It is derived, it may lag, and it is never authoritative on its own. Reconcile through the API and the Proof-of-Payment, not a status read or a received notification. |
| Source of truth | The blockchain is canonical truth; the signed Proof-of-Payment derives from it. A notification is a side effect of a payment event, never the authoritative record of it. |