# 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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.
- `minimumAmount` (number(double)): The smallest base amount, in the session currency, the payer may pay on a Suggested amount, or `null` for no minimum. (nullable)
- `maximumAmount` (number(double)): The largest base amount, in the session currency, the payer may pay on a Suggested amount, or `null` for no maximum. (nullable)
- `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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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)
- `pauseReason` (string): Why the platform paused this link: `FailedAttemptLimit` when it reached its failed-attempt limit. `null` when a user paused it, and whenever it is not paused. (nullable)
- `maxFailedAttempts` (integer(int32)): How many declined or refused payments this link accepts before it pauses itself, or `null` when it has no limit. (nullable)
- `failedAttemptCount` (integer(int32)): How many declined or refused payments this link has counted since it was created or last resumed. Always 0 on a link with no `maxFailedAttempts`, which does not count.
- `theme` ([HostedPageThemeOverrideDto](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HostedPageThemeOverrideDto.md)): The look this session lays over its hosted page's theme, as it was stored, or `null` when the session renders with the page's own theme. Only the members the session set are present.
  Fields:
  - `backColor` (string): The page background color, in hex. (nullable, pattern ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$)
  - `fontColor` (string): The body text color, in hex. (nullable, pattern ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$)
  - `font` (string): The body font family name, for example `Open Sans`. (nullable, max length 50, pattern ^[A-Za-z][A-Za-z0-9 \-]*$)
  - `fontSize` (integer(int32)): The body font size, in pixels. (nullable, min 8, max 48)
  - `headerBackColor` (string): The header background color, in hex. (nullable, pattern ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$)
  - `headerBorderColor` (string): The header border color, in hex. (nullable, pattern ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$)
  - `headerFont` (string): The header font family name. (nullable, max length 50, pattern ^[A-Za-z][A-Za-z0-9 \-]*$)
  - `headerFontColor` (string): The header text color, in hex. (nullable, pattern ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$)
  - `headerFontSize` (integer(int32)): The header font size, in pixels. (nullable, min 8, max 72)
  - `panelBackColor` (string): The panel background color, in hex. (nullable, pattern ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$)
  - `panelBorderColor` (string): The panel border color, in hex. (nullable, pattern ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$)
  - `inputFieldBackgroundColor` (string): The input field background color, in hex. (nullable, pattern ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$)
  - `inputFieldBackgroundFocusColor` (string): The input field background color while the field has focus, in hex. (nullable, pattern ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$)
  - `inputFieldBorderColor` (string): The input field border color, in hex. (nullable, pattern ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$)
  - `inputFieldFontColor` (string): The input field text color, in hex. (nullable, pattern ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$)
  - `inputFieldFontSize` (integer(int32)): The input field font size, in pixels. (nullable, min 8, max 48)
  - `buttonColor` (string): The button color, in hex. (nullable, pattern ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$)
  - `buttonBorderColor` (string): The button border color, in hex. (nullable, pattern ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$)

## See also

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