IDs and correlation

The identifiers you correlate against, on the API, on the webhook plane, and on-chain.

Tekmerion exposes a small set of identifiers. Each has one role; using the wrong one as a correlation key is the most common integration error. This page fixes what each identifier is, where it appears, and how to correlate against it.

Identifiers

Identifier	What it is	Stability	Correlate by it?
`payment_intent_id`	The canonical merchant-facing key for a payment.	One per intent; stable for the intent's lifetime.	Yes. This is the key to tie a payment to your own system, on the API and on every notification.
`order_reference`	Your own correlation value for the order being paid, recorded on the intent.	Set by you at intent creation; carried through every surface.	Yes — to tie a payment back to the order in your system.
`attempt_id`	A reference to one payment attempt under an intent.	One per attempt; an intent may have many.	Traceability only. MUST NOT be used as a notification's identity.
`deposit_address`	The deterministic on-chain address a payment resolves to.	One per intent; shared by every attempt; fixed at intent creation.	Yes — for on-chain correlation. See below.
`delivery_record_id`	The identity of one notification record.	One per `(endpoint, payment_intent_id, notification_class)`; shared across all retries and re-deliveries of that record.	Yes — as the deduplication anchor for notifications. Not a payment key.
`chain_id`	Numeric chain identifier (string-encoded on the notification wire).	Fixed per attempt.	As an identity component, with `deposit_address` and `token_id`.
`token_id`	Canonical token identifier (token contract address on EVM).	Fixed per attempt.	As an identity component, with `deposit_address` and `chain_id`.

Primary correlation key

payment_intent_id is the one key that is always present and always points at the same payment. Correlate every notification and every API record to your system by payment_intent_id — never by attempt_id, status, or delivery order.

Plane	What to correlate by	Notes
API	`payment_intent_id`	The intent is the stable entry point; statuses are projections of it.
Notifications	`payment_intent_id` for the payment; `delivery_record_id` for deduplication	A single `payment_intent_id` may produce several notification records, each a distinct `delivery_record_id`.
On-chain	`deposit_address` + `chain_id` + `token_id`	The matching anchor. See below.

On-chain correlation

deposit_address is the primary on-chain correlation anchor. The matching key is the triple deposit_address + chain_id + token_id.

Property	Statement
Known in advance	The `deposit_address` is computed and fixed at intent creation — before any contract code exists at that address. It can be presented immediately.
One per intent	One intent has exactly one `deposit_address`; every attempt under the intent resolves to the same address.
Not embedded in calldata	`payment_intent_id` and `attempt_id` are not injected into the on-chain transaction's calldata. Correlation is by `deposit_address`, whose uniqueness per intent guarantees deterministic intent-level correlation without any data embedded in the transfer.
Amount is not a key	A deposit is correlated by address, chain, and token — never by amount. The expected amount on an attempt is not a matching criterion. See Deposit.

`attempt_id` is not an identity key

attempt_id appears on the notification envelope as an upstream reference for traceability. It is nullable and MUST NOT be read as the identity of the notification record — that identity is delivery_record_id. See Payload envelope.

One intent, one settlement

A payment_intent_id is settled at most once. When more than one finalized, matched payment exists for the same intent, exactly one is the canonical winner; every other is recorded as duplicate_payment. Because of this, always reconcile at the level of payment_intent_id, not per attempt. See Statuses and projections.