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

HppSessionCreatedDto

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 returned after successfully creating an HPP session.

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
sessionId required string (uuid) The unique session identifier.
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 The short URL token for this session (12-character Base62). 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.
hppUrl required string The absolute HPP payment-link URL using the short token, resolved against the platform's configured public base URL (`HostedPaymentPage:PublicBaseUrl`, falling back to `App:SelfUrl`). Example: `https://pay.example.com/pay/s/aB3kX9mZqR`. Callers can use it directly without resolving it against the host they requested from. 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.
expiresAt required string (date-time) UTC timestamp when the session will expire, or `null` when the session was created with the `Permanent` lifetime and never expires on its own. Only a request that explicitly asked for that lifetime can receive `null` here. 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 The correlation ID echoed back from the request, if provided. 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.
idempotencyStatus required HppSessionCreateIdempotencyStatus HppSessionCreateIdempotencyStatus What the `idempotencyKey` on the request actually did. `Replayed` means this response is a session that already existed and nothing new was created; `KeyIgnored` means the key was accepted but bought nothing, because create idempotency is not enabled for this merchant. Always populated.
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.
NotRequested The request carried no idempotencyKey, so there was nothing to deduplicate. A repeat send opens a second session.
KeyIgnored The request carried an idempotencyKey, but deduplication is not enabled for this merchant, so the key had no effect and a repeat send opens a second session. Ask your provider to enable create idempotency for the merchant.
KeyAccepted The request carried an idempotencyKey, deduplication is enabled, and this request claimed the key. This is the original create; a repeat send of the same request inside the deduplication window replays this session instead of opening another.
Replayed The idempotencyKey matched a create that had already completed for this merchant and credential, so no new session was opened. The response body is that original session exactly as it stands, with its original identifiers, short token, link and expiry.
label required string The label echoed back from the request, if provided. 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 Back link address stored on the created session, if one was supplied. 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.
effective required HppSessionEffectiveShapeDto HppSessionEffectiveShapeDto The shape the server actually resolved this session into, read off the created session rather than off the request. Several inputs are legitimately accepted and then overridden (a card-capture purpose forces required consent, a page can veto tokenization, a fixed-amount page derives an amount mode, a credential-storage scope is defaulted or widened), and the call still returns 2xx either way. Read this block to confirm the session is shaped the way you intended, instead of loading the hosted page and inspecting it.
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 HppSessionEffectiveShapeDto:

Field Type Description
consentRequired required boolean Whether the cardholder <b>must</b> tick the stored-credential consent box before the payment can be submitted.
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.
consentPromptShown required boolean Whether the public page renders the stored-credential consent prompt for this session, i.e. whether the session declared any credential-storage intent. When `false`, consent plays no part in the flow and `consentRequired` is `false`.
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.
requestedCredentialStorage required StoredCredentialUsage StoredCredentialUsage The stored-credential usage scopes the cardholder is being asked to consent to, after server-side defaulting and purpose forcing: a tokenizing session that declared no scope resolves to `UnscheduledCOF`, and a Save Card with Initial Charge session always has `Recurring` unioned in on top of whatever the request asked for. `null` means no credential storage was requested. 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.
pagePurpose required HppPagePurpose HppPagePurpose The page purpose this session actually runs, after applying the request's optional `pagePurpose` override over the targeted page's own configured purpose. A page with no configured purpose resolves to `Payment`.
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.
Payment The default, historical behavior: a chargeable payment page. null resolves here, so every pre-existing HPP instance keeps behaving exactly as before.
SaveCard A card-capture page: the cardholder's card is validated via a zero-dollar account verification (authorize $0 + AVS/CVV, immediate void), then vaulted with stored-credential consent. No charge is taken. Amount-bearing configuration (tax, shipping, convenience fee, invoice amounts, donations, tip) is irrelevant and is hidden in the builder / rejected by the validator. Requires the merchant's processor to advertise SupportsZeroDollarVerification.
SaveCardWithInitialCharge A card-capture page that also charges the first of a recurring schedule. The cardholder's card is charged a real initial sale (the first payment of a referenced reusable recurring plan, framed as the customer-initiated transaction that establishes the credential-on-file agreement), vaulted with Recurring stored-credential consent, and a customer Contract is created for the remaining payments. Like SaveCard, the amount-bearing builder configuration (tax, shipping, convenience, invoice, donations, tip, customer-set amount) is hidden: the charged amount is driven entirely by the inlined recurring definition, not by per-page amount fields. Requires a complete inlined recurring definition (RecurringPlan).
tokenizeOnPayment required boolean Whether the cardholder's payment method will be vaulted as a reusable token. This is the effective decision after the merchant's tokenize-by-default setting is applied and after the targeted page's tokenization toggle (`SupportTokenization` / `SavePaymentDetails`) has had its say. A request that asked for `tokenizeOnPayment: true` against a page whose merchant disabled tokenization reports `false` here: that is the veto, which previously only appeared in a server-side log line. Always `true` for a card-capture purpose, which exists to store the credential.
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 Whether this session stores the payment method with no charge at all. `true` for a resolved `SaveCard` purpose or an explicit `saveCardOnly` request on a Payment page. Deliberately `false` for `SaveCardWithInitialCharge`, which takes a real initial charge, so a request that sent `saveCardOnly: true` against that purpose reports `false` here.
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.
captureMode required HppCaptureMode HppCaptureMode Capture timing for the chargeable Payment flow: `Sale` authorizes and captures in one step, `Authorize` authorizes now for a later capture. Resolved from the request's optional override over the page's configured value. Reported as `Sale` for a card-capture purpose, where capture timing is not an axis: those purposes set their own transaction shape.
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.
Sale Authorize and capture funds in a single step (the historical, default behavior). null resolves here, so every pre-existing chargeable page keeps doing an implicit Sale.
Authorize Authorize now, capture later (delayed capture). The resulting transaction is an Authorization in an Authorized state, eligible for capture and void per the action matrix; the capture is completed later against the resulting transaction id via the existing capture action path (including the Apple Pay single-use token case).
amountMode required HppSessionAmountMode HppSessionAmountMode How the cardholder may set the amount. `CustomerEntered` leaves the page's own amount behaviour in charge; `Suggested` pre-fills an editable amount; `Locked` pre-fills a read-only amount that the server verifies on submit.
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. This is the resolved value: a request that omitted `taxAmountMode` reports the effective `amountMode` here, because that is what the tax follows. `Locked` means the server charges the session's `tax` prefill 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.
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 same way as `taxAmountMode`. `Locked` means the server charges the session's `shipping` prefill, ahead of any flat shipping rate the page configures.
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.
customerEmailVisibility required HppFieldVisibility HppFieldVisibility The per-session visibility of the payer-facing customer-email field, as it was accepted and stored. `null` means the session did not override it and the page's own `FieldCustomerEmail` 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.
Hidden
Optional
Required
declineRetryMode required HppDeclineRetryMode HppDeclineRetryMode What this session does with its payment link when a payment is declined, as resolved from the per-session override, the hosted page and the tenant default 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.
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.
linkLifetime required HppLinkLifetime HppLinkLifetime The link lifetime the session was actually minted with, read off the created session rather than off the request. `Session` is what a request that named no lifetime resolves to.
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.
remainingDeclineReleases required integer (int32) How many further times this link may be reopened after a declined payment. Always zero when `declineRetryMode` is `ConsumeOnDecline`, and it counts down as a payer spends attempts.
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. A request that named one gets it back verbatim, having been checked against the merchant's configured currency; a request that named none gets the merchant's currency, which is the defaulting this block exists to report. `null` only when the merchant has no currency configured at all, which is the state every session predating this field is in. 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.
customerId required string (uuid) The customer this session is bound to, echoed from the request's `customerId` after it was validated to exist, be active, and belong to the page's merchant. `null` for an unbound session, where the cardholder's email is the only customer-resolution anchor. 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.
prefilledFieldKeys required array of string array of The prefilled field keys stored on the session, in no particular order. Values are never echoed. Compare against what was sent to confirm every key was accepted, and note that the server may add one: deriving a locked amount from a fixed-amount page stamps `base_amount` even when the request supplied 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.
ignoredPrefillKeys required array of string array of The subset of `prefilledFieldKeys` that the hosted page will silently ignore when it renders: keys that are neither a well-known field nor an enabled, page-visible merchant custom field. They are accepted and persisted rather than rejected, for backward compatibility, so this list is the only signal that a key will have no effect (usually a typo, or a custom field that is disabled or hidden for hosted pages). 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.

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.