id
required |
string (uuid)
|
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
hostedPageId
required |
string (uuid)
|
The HPP configuration ID this session targets.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
merchantId
required |
string (uuid)
|
The merchant that owns the HPP configuration.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
status
required |
HppSessionStatus
HppSessionStatus |
Current lifecycle status of the session.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Pending |
The session has been created and is awaiting use by a customer. Also the status a session returns to when a premature consume is released: a submission that was rejected by pure request-shape validation before the orchestrator was invoked leaves the link usable, so the payer can correct their input and resubmit on the same link (see Consumed). | Consumed |
The session has been consumed by a transaction submission. Terminal in practice: the only exit is the narrow release back to Pending performed by HppSession.ReleaseConsume, which requires that the session carries no OrchestratorDispatchedAt marker, that the consuming transaction id is still the one recorded, and that no vault token was minted. Once a submission reaches the orchestrator the marker is durable and the session stays Consumed regardless of the outcome, including a decline. Submit paths additionally validate the request BEFORE consuming, so a rejected request usually never spends the link in the first place; the release covers the rules that can only run inside the create. | Revoked |
The session has been manually revoked by an administrator. | Cancelled |
The session was cancelled by the parent page via the iframe two-way command channel Distinct from Revoked (admin-initiated) for clarity in audit + reporting: same terminal effect (session can no longer be consumed). | Completed |
A reusable link has taken every completion it was capped at, so it accepts no further payers. Terminal, and reachable only on a reusable session: a single-use link spends itself through Consumed instead, and a reusable one is never Consumed because its per-payer consume state lives on its HppSessionCompletion children rather than on the parent. A reusable link created with no cap never reaches this status; it stays payable until it is revoked, cancelled or expires. |
|
prefilledFieldKeys
required |
array of string
array of |
The names of the pre-filled fields (values are redacted for security).
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
prefilledFieldCount
required |
integer (int32)
|
Number of pre-filled fields in the session.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
timeToLive
required |
integer (int32)
|
The session's lifetime in seconds, as the caller asked for it; it decides when the session
expires. `null` for a permanent link, which has no lifetime.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
createdAt
required |
string (date-time)
|
UTC timestamp when the session was created.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
expiresAt
required |
string (date-time)
|
UTC timestamp when the session expires, or `null` for a permanent link that never
expires on its own.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
linkLifetime
required |
HppLinkLifetime
HppLinkLifetime |
How long this link was minted to stay payable.
`Session` on every session created before lifetimes existed and
on every one that named none.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Session |
The historical short single-use checkout session: 60 to 900 seconds, defaulting to 600, and still subject to the tenant's own min/max/default TTL settings. What every caller that does not name a lifetime gets. | Extended |
A long-lived link, bounded by ExtendedMinTtlSeconds and ExtendedMaxTtlSeconds (1 hour to 90 days), for a link that is emailed or texted and paid later. The upper bound is capped by the tenant's HostedPaymentPageSettings.SessionMaxExtendedTtlSeconds setting. | Permanent |
A link that never expires on its own. The session carries no expiry instant and no document time-to-live; it stops being payable only when it is paid, cancelled, or revoked. Requesting an expiry in seconds alongside this is rejected rather than ignored. |
|
consumedByTransactionId
required |
string (uuid)
|
The transaction ID that consumed this session, if any.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
consumedAt
required |
string (date-time)
|
UTC timestamp when the session was consumed.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
declineRetryMode
required |
HppDeclineRetryMode
HppDeclineRetryMode |
What this session does with its payment link when a payment is declined.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
ConsumeOnDecline |
The historical behavior, and the default at every level of the resolution chain. Any processor answer spends the link permanently: the session stays Consumed and a payer who reloads it is told the link has already been used. | ReleaseOnDecline |
A definite issuer decline hands the link back to Pending so the payer can correct their card and resubmit on the same URL, instead of having to ask the merchant for a new link. |
|
declineReleaseCount
required |
integer (int32)
|
How many times this link has already been reopened after a declined payment.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
lastDeclinedTransactionId
required |
string (uuid)
|
The transaction that most recently declined against this session and reopened its link.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
lastDeclineReleasedAt
required |
string (date-time)
|
When this link was most recently reopened after a declined payment.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
correlationId
required |
string
|
Optional merchant-supplied correlation ID for tracing/debugging.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
label
required |
string
|
Optional human-readable label for identifying this session.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
cancelUrl
required |
string
|
The address this session's Back link returns the payer to, when the session was created with
one. `null` means the page's own `PageActions.Cancel` slot, if enabled, applies.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
campaignSource
required |
string
|
The per-channel source tag this link carries (`email`, `sms`, `qr`,
`social`), normalized to lower case, or `null` when it carries none. Surfaced so an
operator picking a link to send or to render as a QR code can tell their per-channel links
apart.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
consumedPromotionCode
required |
string
|
The promotion code the payer applied to the submit that consumed this link, or `null`
when they applied none. `null` on every session written before promotions existed.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
catalogOrder
required |
HppCatalogOrder
HppCatalogOrder |
The catalog order this link sells, at the prices snapshotted when it was created and the
quantities it starts at, or `null` on a link off a page that sells no products (every
link created before products existed). The subtotal for those quantities is the link's locked
`base_amount`.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
consumedOrder
required |
HppCatalogOrder
HppCatalogOrder |
The order the payer actually bought, resolved and priced by the platform when they paid, or
`null` until then (and always on a link that sells no products). On a reusable link each
payer's own completion carries their order; the parent carries none.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
currency
required |
string
|
The ISO 4217 currency this session is denominated in, upper-cased, as resolved and frozen at
create time. `null` on a session created before the field existed, and on one whose
merchant had no currency configured; the payment page falls back to the merchant's current
currency at render in that case, exactly as it always has.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
shortToken
required |
string
|
Short URL token for friendly payment links.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
lastSentTo
required |
string
|
The address this session's payment link was most recently sent to, masked. `null` when
the link has never been sent.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
lastSentAtUtc
required |
string (date-time)
|
When this session's payment link was most recently sent, in UTC, or `null` when it has
never been sent.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
boundCustomerId
required |
string (uuid)
|
The customer this session is bound to, or `null` when it is bound to none.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
amountMode
required |
HppSessionAmountMode
HppSessionAmountMode |
How this session treats the payment amount: the cardholder types it, it is pre-filled but
editable, or it is pre-filled and read-only.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
CustomerEntered |
The default, historical behavior: the session specifies no amount and the cardholder types it on the page. null (legacy sessions) resolves here. | Suggested |
The session specifies an amount (via the prefilled base_amount) that pre-fills the page, but the cardholder may edit it (e.g. a suggested donation). | Locked |
The session specifies an amount (via the prefilled base_amount) that the cardholder cannot change (e.g. paying an invoice). The amount renders read-only but visible, and the server verifies on submit that the charged base amount matches the session's specified amount. |
|
taxAmountMode
required |
HppSessionAmountMode
HppSessionAmountMode |
The mode the tax line runs under, resolved: the session's own tax amount mode when it declared
one, otherwise `amountMode`.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
CustomerEntered |
The default, historical behavior: the session specifies no amount and the cardholder types it on the page. null (legacy sessions) resolves here. | Suggested |
The session specifies an amount (via the prefilled base_amount) that pre-fills the page, but the cardholder may edit it (e.g. a suggested donation). | Locked |
The session specifies an amount (via the prefilled base_amount) that the cardholder cannot change (e.g. paying an invoice). The amount renders read-only but visible, and the server verifies on submit that the charged base amount matches the session's specified amount. |
|
shippingAmountMode
required |
HppSessionAmountMode
HppSessionAmountMode |
The mode the shipping amount runs under, resolved: the session's own shipping amount mode when
it declared one, otherwise `amountMode`.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
CustomerEntered |
The default, historical behavior: the session specifies no amount and the cardholder types it on the page. null (legacy sessions) resolves here. | Suggested |
The session specifies an amount (via the prefilled base_amount) that pre-fills the page, but the cardholder may edit it (e.g. a suggested donation). | Locked |
The session specifies an amount (via the prefilled base_amount) that the cardholder cannot change (e.g. paying an invoice). The amount renders read-only but visible, and the server verifies on submit that the charged base amount matches the session's specified amount. |
|
lockShippingAddress
required |
boolean
|
Whether this session shows its prefilled shipping address display-only and records that
address on the transaction whatever the payer submits.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
baseAmount
required |
number (double)
|
The base amount this session was minted with, when it carries one, in the session's
`currency`.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
derivedState
required |
HppSessionDerivedState
HppSessionDerivedState |
The state a reader should see for this session, with a terminal status winning over the
clock: usable, expired, consumed, revoked or cancelled.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Usable |
Pending and not yet past its expiry instant: the link can still be presented and consumed. | Expired |
Pending, but the expiry instant has passed. The document may still be readable for the retention window configured by HostedPaymentPageSettings.SessionExpiredRetentionDays, which is what lets a payer see a distinct expired page and an administrator see the row on a grid. | Consumed |
Consumed by a transaction submission (Consumed). | Revoked |
Revoked by an administrator (Revoked). | Cancelled |
Cancelled by the parent page over the iframe command channel (Cancelled). | Completed |
A reusable link that has taken its last capped completion (Completed). The reusable analogue of Consumed: the link is spent, but by many payers rather than one. | Paused |
The merchant has paused the link. Unlike every other non-usable state this one is reversible: a resume puts the link straight back to Usable with its expiry, cap and prefill untouched. A payer who opens a paused link sees the merchant's own inactive message rather than the generic out-of-service copy. |
|
requestedCredentialStorage
required |
StoredCredentialUsage
StoredCredentialUsage |
When non-null, the session is configured to capture stored-credential consent on its
resulting transaction. Shown on admin screens so operators can see which sessions were
set up to require cardholder consent. Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
None |
No permitted uses. Consent record is effectively inactive. | Recurring |
Scheduled recurring charges (subscriptions, membership dues). Maps to Recurring. | Installment |
Fixed-schedule installment plans dividing a known total. Maps to Installment. | UnscheduledCOF |
Merchant-triggered charges for pre-agreed events (balance top-ups, usage overages, no-show fees, delayed charges). Maps to several MIT reason codes including UnscheduledCOF, NoShow, DelayedCharge, and IncrementalAuth. | OneTimeFuture |
A single known future cardholder-initiated purchase the credential was saved for (e.g. "save card for my next order"). Not used for MITs. |
|
tokenizeOnPayment
required |
boolean
|
`true` when the session is configured to vault the cardholder's card as a reusable
payment token on a successful payment (the effective value after the merchant default is
resolved). Shown on admin screens so operators can see which sessions tokenize. A
tokenizing session always also has a non-null `requestedCredentialStorage`.
.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
saveCardOnly
required |
boolean
|
`true` when the session saves the card via a zero-dollar verification instead of
charging it ("save card now, charge later"). <b>Currently always `false` in
practice</b>: save-card-only is fail-closed at session creation until the no-charge
verification routing is wired end to end, so no persisted session carries it set. Once
the path lands it will always also tokenize and capture consent. Shown on admin screens.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
purpose
required |
HppSessionPurpose
HppSessionPurpose |
Classifies the calling context that produced this session.
`CheckoutLink` is the historical merchant-facing
pay-link behavior; non-default values were created by system-initiated flows (e.g.
invoice send) and carry longer TTL windows. Read-only on admin screens.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
CheckoutLink |
Standard merchant-facing pay-link session. Short TTL (60s to 900s). | Invoice |
Session created by the invoicing module's send flow to back an invoice's pay-link. Long TTL (1h to 90d) so the link survives net-30 invoice terms with margin for late payment. | PaymentMethodCapture |
Session created by the Merchant Billing module to back a stored-payment-method capture link emailed to a merchant. Long TTL (1h to 90d) so a link sent now can be completed days later, on the merchant's own time, rather than synchronously by an operator. |
|
reusable
required |
boolean
|
Whether this link accepts many payers rather than one.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
maxCompletions
required |
integer (int32)
|
How many payments a reusable link accepts before it closes, or `null` for a link that
keeps accepting payers. Always `null` on a single-use link.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
completionCount
required |
integer (int32)
|
How many payments a reusable link has taken. Always `0` on a single-use link, which
records its one payment through `consumedByTransactionId` instead.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
isExpired
required |
boolean
|
Returns `true` if the session has passed its expiry time. Always `false` for a
permanent link, which has no expiry time to pass.
read only
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
isUsable
required |
boolean
|
Returns `true` if the session is still pending and has not expired.
read only
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
isPaused
required |
boolean
|
Whether the merchant has paused this link. A paused link accepts no payer until it is
resumed, and loses nothing in the meantime: its expiry, cap, prefill and completion history
are untouched.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
pausedAt
required |
string (date-time)
|
The UTC instant of the most recent pause, or `null` if this link has never been paused.
Left in place by a resume, so it still reads as the record of a pause that has ended.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
inactiveMessage
required |
string
|
The plain-text message a payer sees instead of the generic out-of-service copy when they open
this link while it is paused, or after a reusable link has filled its completion cap.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|