WinkPG Docs
View as Markdown

llms.txt

The API reference isn't available right now

This instance couldn't load its API specification. The reference returns as soon as the specification is readable again.

Back to the API reference

No such model

This instance publishes no model under that name. It may have been renamed, or no operation this installation serves uses it.

Back to the API reference

This reference may be out of date

This instance couldn't reach its API specification on the last attempt, so this page shows the copy fetched before that. Anything added or changed since then is missing here, and the reference updates itself as soon as the specification is readable again. Last fetched 2026-10-22 22:52 UTC.

API reference Models

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.

Values

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.

Fields

Field Type Description
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.

Fields of HppCatalogOrder:

Field Type Description
lines required array of HppCatalogOrderLine array of HppCatalogOrderLine The products on the order, in display order. 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.
currency required 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
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.
subtotalAmount required 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
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.

This body has no documented fields.

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.

Fields of HppCatalogOrder:

Field Type Description
lines required array of HppCatalogOrderLine array of HppCatalogOrderLine The products on the order, in display order. 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.
currency required 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
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.
subtotalAmount required 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
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.

This body has no documented fields.

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.

This model has no documented fields.

Reconnecting to the server

Could not reconnect

This session has ended

Attempt 1

Your work on this page is still here. Retrying keeps it; reloading starts the page again.

The server no longer holds this page's state, so it has to be loaded again.