Invoice Payment Session

Overview

An invoice payment session is the bounded checkout context that connects an invoice with its current payment instructions, payer interaction, quote, and lifecycle state. In an operational payment system, this field or policy should have one authoritative meaning across the API, checkout, webhook, ledger, and support tools.

The session may contain a payment URL, selected asset and network, requested crypto amount, address, expiry, redirects, and a provider-generated identifier. A replacement session can be created without changing the underlying commercial order. In practice, the system should preserve the original request, the observed blockchain or checkout evidence, and every status change that affects this value. This makes support investigations and financial reconciliation possible without reconstructing the payment from screenshots or mutable client data.

Sessions should be unique, time-limited when rates or addresses are temporary, protected against unauthorized modification, and linked to webhook events and payment attempts. Reopening a session should not duplicate fulfillment. The implementation should use exact asset precision, authenticated server-side updates, and idempotent processing wherever repeated API calls, blockchain observations, or webhook deliveries can occur.

It differs from the invoice itself, which represents the obligation, and from a payment attempt, which represents one effort or transaction within the session. It should be interpreted alongside Invoice Session ID, Invoice Payment Attempt, Invoice Payment Window. These concepts belong to the same workflow, but each answers a different operational question and should not be collapsed into one ambiguous field.

An invoice for an order can have an initial session that expires after 30 minutes and a second session with a refreshed exchange rate while retaining the same order ID. The practical test is whether a merchant can explain how the value was produced, verify it independently, and apply the same rule consistently when the payment is delayed, duplicated, partially paid, refunded, or reviewed manually.