# HppSessionDto

A model the API reference uses in a request or a response. The operation pages link every field typed as this model here.

Output DTO representing an HPP session for management display.
Pre-filled field values are redacted: only the field key names are exposed
to prevent accidental PII/sensitive data leakage via management APIs.

## Fields
- `id` (string(uuid))
- `hostedPageId` (string(uuid)): The HPP configuration ID this session targets.
- `merchantId` (string(uuid)): The merchant that owns the HPP configuration.
- `status` ([HppSessionStatus](https://devportal.demo.winkpg.io/docs/api/models/HppSessionStatus.md)): Current lifecycle status of the session.
  Values:
  - `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` (array<string>): The names of the pre-filled fields (values are redacted for security). (nullable)
- `prefilledFieldCount` (integer(int32)): Number of pre-filled fields in the session.
- `timeToLive` (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)
- `createdAt` (string(date-time)): UTC timestamp when the session was created.
- `expiresAt` (string(date-time)): UTC timestamp when the session expires, or `null` for a permanent link that never  expires on its own. (nullable)
- `linkLifetime` ([HppLinkLifetime](https://devportal.demo.winkpg.io/docs/api/models/HppLinkLifetime.md)): 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:
  - `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` (string(uuid)): The transaction ID that consumed this session, if any. (nullable)
- `consumedAt` (string(date-time)): UTC timestamp when the session was consumed. (nullable)
- `declineRetryMode` ([HppDeclineRetryMode](https://devportal.demo.winkpg.io/docs/api/models/HppDeclineRetryMode.md)): What this session does with its payment link when a payment is declined. (nullable)
  Values:
  - `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` (integer(int32)): How many times this link has already been reopened after a declined payment. (nullable)
- `lastDeclinedTransactionId` (string(uuid)): The transaction that most recently declined against this session and reopened its link. (nullable)
- `lastDeclineReleasedAt` (string(date-time)): When this link was most recently reopened after a declined payment. (nullable)
- `correlationId` (string): Optional merchant-supplied correlation ID for tracing/debugging. (nullable)
- `label` (string): Optional human-readable label for identifying this session. (nullable)
- `cancelUrl` (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)
- `campaignSource` (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)
- `consumedPromotionCode` (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)
- `catalogOrder` ([HppCatalogOrder](https://devportal.demo.winkpg.io/docs/api/models/HppCatalogOrder.md)): 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`.
  Fields:
  - `lines` (array<[HppCatalogOrderLine](https://devportal.demo.winkpg.io/docs/api/models/HppCatalogOrderLine.md)>): The products on the order, in display order. (nullable)
  - `currency` (string): The ISO 4217 code every line is priced in, or `null` when it was not known at snapshot  time (read as the merchant's currency). (nullable)
  - `subtotalAmount` (number(double)): The sum of the selected lines' totals, rounded to cents. Stored alongside the lines so a  reader does not have to recompute it; `HppCatalogOrderPolicy` keeps it in step. (nullable)
- `consumedOrder` ([HppCatalogOrder](https://devportal.demo.winkpg.io/docs/api/models/HppCatalogOrder.md)): 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.
  Fields:
  - `lines` (array<[HppCatalogOrderLine](https://devportal.demo.winkpg.io/docs/api/models/HppCatalogOrderLine.md)>): The products on the order, in display order. (nullable)
  - `currency` (string): The ISO 4217 code every line is priced in, or `null` when it was not known at snapshot  time (read as the merchant's currency). (nullable)
  - `subtotalAmount` (number(double)): The sum of the selected lines' totals, rounded to cents. Stored alongside the lines so a  reader does not have to recompute it; `HppCatalogOrderPolicy` keeps it in step. (nullable)
- `currency` (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)
- `shortToken` (string): Short URL token for friendly payment links. (nullable)
- `lastSentTo` (string): The address this session's payment link was most recently sent to, masked. `null` when  the link has never been sent. (nullable)
- `lastSentAtUtc` (string(date-time)): When this session's payment link was most recently sent, in UTC, or `null` when it has  never been sent. (nullable)
- `boundCustomerId` (string(uuid)): The customer this session is bound to, or `null` when it is bound to none. (nullable)
- `amountMode` ([HppSessionAmountMode](https://devportal.demo.winkpg.io/docs/api/models/HppSessionAmountMode.md)): 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:
  - `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` ([HppSessionAmountMode](https://devportal.demo.winkpg.io/docs/api/models/HppSessionAmountMode.md)): The mode the tax line runs under, resolved: the session's own tax amount mode when it declared  one, otherwise `amountMode`.
  Values:
  - `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` ([HppSessionAmountMode](https://devportal.demo.winkpg.io/docs/api/models/HppSessionAmountMode.md)): The mode the shipping amount runs under, resolved: the session's own shipping amount mode when  it declared one, otherwise `amountMode`.
  Values:
  - `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` (boolean): Whether this session shows its prefilled shipping address display-only and records that  address on the transaction whatever the payer submits.
- `baseAmount` (number(double)): The base amount this session was minted with, when it carries one, in the session's  `currency`. (nullable)
- `derivedState` ([HppSessionDerivedState](https://devportal.demo.winkpg.io/docs/api/models/HppSessionDerivedState.md)): The state a reader should see for this session, with a terminal status winning over the  clock: usable, expired, consumed, revoked or cancelled.
  Values:
  - `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` ([StoredCredentialUsage](https://devportal.demo.winkpg.io/docs/api/models/StoredCredentialUsage.md)): 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:
  - `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` (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`.  .
- `saveCardOnly` (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.
- `purpose` ([HppSessionPurpose](https://devportal.demo.winkpg.io/docs/api/models/HppSessionPurpose.md)): 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:
  - `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` (boolean): Whether this link accepts many payers rather than one.
- `maxCompletions` (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)
- `completionCount` (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.
- `isExpired` (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)
- `isUsable` (boolean): Returns `true` if the session is still pending and has not expired. (read only)
- `isPaused` (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.
- `pausedAt` (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)
- `inactiveMessage` (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)

## See also

- [All documentation](https://devportal.demo.winkpg.io/llms.txt): the machine-readable index of every public page on this site.