Payment intent

A payment intent is a merchant's request to be paid for an order. It is the entry point of every payment, and it is not a payment. An intent records what the merchant expects — the order it corresponds to, the base amount, the expected window — and binds that expectation to a single on-chain address. Whether a payment ever arrives, and what becomes of it, is determined later by on-chain truth, not by the intent.

The intent is a request, not a payment

An intent carries the merchant's expectation. It does not assert that funds have moved, that a customer has acted, or that anything has settled. A payment outcome is never read from the intent itself — it is derived from canonical on-chain truth and surfaced as a status projection. The intent fixes what should happen; the blockchain decides what did.

A deterministic deposit address

At creation, each intent is bound to exactly one deposit address, computed and fixed at that moment. The address is deterministic: it depends only on the intent's identity, never on the amount, the chain, the token, or any data the customer later supplies. Because of this, the address is known before any contract code exists at it — it can be presented immediately, and it carries no code until the moment of settlement or refund.

One intent has exactly one deposit address, identified by its payment_intent_id. Every attempt to pay the same intent resolves to that same address, regardless of which chain and token the customer selects. See Payment attempt.

Identity and correlation

An intent carries an order_reference — the merchant's own correlation value for the order being paid. It is recorded on the intent and travels with the payment through every surface that reports on it, so a payment can always be tied back to the order it belongs to.

An optional idempotency_key may accompany the creation request. Its handling on the create surface is described in Idempotency.

Expiry is a policy boundary

An intent has an expires_at. It is a policy boundary — the window during which the expected flow is considered active. It is not a truth boundary. A deposit that is confirmed on-chain after expires_at is still processed, and a late, confirmed, approved payment can still settle: on-chain truth has priority over the expected window.

expires_at therefore does not finalize an intent, make it immutable, or forbid a settlement. A status of EXPIRED is a statement about the expected window, not a guarantee that no payment will arrive. See Late payments and Statuses and projections.

One intent, many attempts, one settlement

An intent may accumulate several payment attempts as the customer changes chain, token, or wallet, and all of them share the one deposit address. Across all of them, 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, selected deterministically; every other finalized match is recorded as duplicate_payment and is not an additional settlement. Winner selection and the duplicate caveat are described in Statuses and projections.