# GET /api/hostedpaymentpages/{id} Get hosted payment page Retrieves detailed information about a specific hosted payment page. **Operation ID:** `hostedPaymentPagesGet` ## Authorization Requires: HostedPaymentPage.HostedPaymentPages, merchant scope. Requires API key scope: `transactions:read` Required permissions: - `HostedPaymentPage.HostedPaymentPages` ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | id | path | yes | string(uuid) | | | suppressNulls | query | no | boolean | If true, omit properties with null values. | ## Responses ### 200 OK **Content type:** `application/json` Schema: [`HostedPaymentPageDto`](https://devportal.demo.winkpg.io/docs/api/models/HostedPaymentPageDto.md) Properties: - `extraProperties` (object): (nullable, read only) - `id` (string(uuid)) - `creationTime` (string(date-time)): The date and time when this entity was created. - `creatorId` (string(uuid)): The ID of the user who created this entity. (nullable) - `lastModificationTime` (string(date-time)): The date and time when this entity was last modified. (nullable) - `lastModifierId` (string(uuid)): The ID of the user who last modified this entity. (nullable) - `isDeleted` (boolean): Indicates whether this entity has been deleted. - `deleterId` (string(uuid)): The ID of the user who deleted this entity, if it is deleted. (nullable) - `deletionTime` (string(date-time)): The date and time when this entity was deleted, if it is deleted. (nullable) - `name` (string): (nullable) - `concurrencyStamp` (string): (nullable) - `tenantId` (string(uuid)): (nullable, read only) - `merchantId` (string(uuid)) - `isActive` (boolean) - `title` (string): (nullable) - `bannerImage` (string): Filename of the header banner image, as produced by the portal image uploader. This is not a URL: the public page resolves the filename against the hosted-page image CDN container. See `bannerImage` for the write contract. (nullable) - `hideBanner` (boolean) - `supportRetail` (boolean) - `usePostOnSubmit` (boolean) - `useCaptcha` (boolean) - `supportTokenization` (boolean) - `pageActions` ([HostedPaymentPageActionUrls](https://devportal.demo.winkpg.io/docs/api/models/HostedPaymentPageActionUrls.md)): Represents the set of action URLs for the hosted payment page, including submit, edit, continue, and cancel (Back) actions. Fields: - `submit` ([URLConfig](https://devportal.demo.winkpg.io/docs/api/models/URLConfig.md)): Gets or sets the URL to use when the payment is submitted. - `edit` ([URLConfig](https://devportal.demo.winkpg.io/docs/api/models/URLConfig.md)): Gets or sets the URL to use on the hosted receipt page to return to the transaction page. - `continue` ([URLConfig](https://devportal.demo.winkpg.io/docs/api/models/URLConfig.md)): Gets or sets the URL to use on the hosted receipt page to navigate to a different page. - `cancel` ([URLConfig](https://devportal.demo.winkpg.io/docs/api/models/URLConfig.md)): Gets or sets the address the payer's Back link returns to from the payment form, before paying (typically the merchant's cart). A session-level `cancelUrl` overrides it. - `donations` ([HostedPageDonations](https://devportal.demo.winkpg.io/docs/api/models/HostedPageDonations.md)): Represents donation configuration for the hosted payment page, including enablement and predefined amounts. Fields: - `enableDonationAmounts` (boolean): Gets or sets a value indicating whether donation amounts are enabled. - `donationAmounts` (array<[HostedPageDonationAmount](https://devportal.demo.winkpg.io/docs/api/models/HostedPageDonationAmount.md)>): Gets or sets the list of predefined donation amount options. (nullable) - `theme` ([HostedPageTheme](https://devportal.demo.winkpg.io/docs/api/models/HostedPageTheme.md)): Represents theme settings for the hosted payment page, including colors, fonts, and header styles. Fields: - `panelBackColor` (string): Gets or sets the background color of the panels. (nullable, max length 20) - `panelBorderColor` (string): Gets or sets the border color of the panels. (nullable, max length 20) - `buttonColor` (string): Gets or sets the border color of the form buttons. (nullable, max length 20) - `buttonBorderColor` (string): Gets or sets the border color of the buttons. (nullable, max length 20) - `inputFieldBorderColor` (string): Gets or sets the border color of the form input fields. (nullable, max length 20) - `inputFieldBackgroundColor` (string): Gets or sets the color of the form input fields background. (nullable, max length 20) - `inputFieldFontSize` (integer(int32)): Gets or sets the size of the input fields font. (nullable) - `inputFieldFontColor` (string): Gets or sets the color of the form input fields font. (nullable, max length 20) - `inputFieldBackgroundFocusColor` (string): Gets or sets the color of the form input fields background when the field has focus. (nullable, max length 20) - `backColor` (string): Gets or sets the page background color. (nullable, max length 20) - `fontColor` (string): Gets or sets the font color. (nullable, max length 20) - `font` (string): Gets or sets the name of the font to use for the body. (nullable, max length 50) - `fontSize` (integer(int32)): Gets or sets the size of the font. (nullable) - `headerFont` (string): Gets or sets the name of the font to use for header text. (nullable, max length 50) - `headerFontColor` (string): Gets or sets the font color to use for the header text. (nullable, max length 20) - `headerFontSize` (integer(int32)): Gets or sets the font size to use for the header text. (nullable) - `headerBackColor` (string): Gets or sets the background color to use for the header text. (nullable, max length 20) - `headerBorderColor` (string): Gets or sets the background color to use for the header text. (nullable, max length 20) - `customCSS` (string): Gets or sets custom css for the HPP (nullable, max length 3000) - `fieldsAndPanels` ([HostedPageFieldsAndPanels](https://devportal.demo.winkpg.io/docs/api/models/HostedPageFieldsAndPanels.md)): Represents the configuration of fields and panels for the hosted payment page, including display options and custom labels. Fields: - `fieldInvoice` ([HppFieldVisibility](https://devportal.demo.winkpg.io/docs/api/models/HppFieldVisibility.md)): Gets or sets a value indicating whether to display the invoice number field. Values: - `Hidden` - `Optional` - `Required` - `fieldTax` ([HppFieldVisibility](https://devportal.demo.winkpg.io/docs/api/models/HppFieldVisibility.md)): Gets or sets the visibility of the tax amount field. Values: - `Hidden` - `Optional` - `Required` - `fieldConvenienceFee` ([HppFieldVisibility](https://devportal.demo.winkpg.io/docs/api/models/HppFieldVisibility.md)): Gets or sets the visibility of the convenience fee field. Values: - `Hidden` - `Optional` - `Required` - `fieldShipping` ([HppFieldVisibility](https://devportal.demo.winkpg.io/docs/api/models/HppFieldVisibility.md)): Gets or sets the visibility of the shipping amount field. Values: - `Hidden` - `Optional` - `Required` - `fieldTotal` (boolean): Gets or sets a value indicating whether to display the total amount field. - `fieldBillingAddr` ([HppFieldVisibility](https://devportal.demo.winkpg.io/docs/api/models/HppFieldVisibility.md)): Gets or sets a value indicating whether to display the billing address fields. Values: - `Hidden` - `Optional` - `Required` - `fieldShipAddr` ([HppFieldVisibility](https://devportal.demo.winkpg.io/docs/api/models/HppFieldVisibility.md)): Gets or sets a value indicating whether to display the shipping address fields. Values: - `Hidden` - `Optional` - `Required` - `panelWidthOrder` (integer(int32)): Gets or sets an optional width for the order detail panel. (nullable) - `panelWidthCustom` (integer(int32)): Gets or sets an optional width for the custom fields panel. (nullable) - `panelWidthAddress` (integer(int32)): Gets or sets an optional width for the address panels. (nullable) - `panelWidthCard` (integer(int32)): Gets or sets an optional width for the card detail panel. (nullable) - `amountSetByCustomer` (boolean): Gets or sets a value indicating whether the total amount can be set by the customer. - `panelWidthResult` (integer(int32)): Gets or sets an optional width for the result panel. (nullable) - `customerSetsInvoiceNumber` (boolean): Gets or sets a value indicating whether the customer can set the invoice number. - `fieldCustomerEmail` ([HppFieldVisibility](https://devportal.demo.winkpg.io/docs/api/models/HppFieldVisibility.md)): Gets or sets a value indicating whether to display the customer email field. Values: - `Hidden` - `Optional` - `Required` - `fieldCustomerNameOnCard` ([HppFieldVisibility](https://devportal.demo.winkpg.io/docs/api/models/HppFieldVisibility.md)): Gets or sets a value indicating whether to display the customer Name on card. Values: - `Hidden` - `Optional` - `Required` - `hideHeaderMenu` (boolean): Gets or sets a value indicating whether to hide the header menu/panel. - `orderPanelCustomText` (string): Gets or sets an optional custom label for the order panel. (nullable, max length 125) - `customizeOrderPanelText` (boolean): Gets or sets a value indicating whether to replace the default order panel label with a custom label. - `customFieldPanelCustomText` (string): Gets or sets an optional custom label for the custom field panel. (nullable, max length 125) - `customizeCustomFieldPanelText` (boolean): Gets or sets a value indicating whether to replace the default custom field panel label with a custom label. - `addressPanelCustomText` (string): Gets or sets an optional custom label for the address panel. (nullable, max length 125) - `customizeAddressPanelText` (boolean): Gets or sets a value indicating whether to replace the default address panel label with a custom label. - `cardPanelCustomText` (string): Gets or sets an optional custom label for the card detail panel. (nullable, max length 125) - `customizeCardPanelText` (boolean): Gets or sets a value indicating whether to replace the default card panel label with a custom label. - `resultPanelCustomText` (string): Gets or sets an optional custom label for the result panel. (nullable, max length 125) - `customizeResultPanelText` (boolean): Gets or sets a value indicating whether to replace the default result panel label with a custom label. - `showOrderPanelText` (boolean): Gets or sets a value indicating whether to display header label for the order panel. - `showCustomFieldsText` (boolean): Gets or sets a value indicating whether to display the header label for the custom fields panel. - `showAddressPanelText` (boolean): Gets or sets a value indicating whether to display the header label for the address panel. - `showCardPanelText` (boolean): Gets or sets a value indicating whether to display the header label for the card detail panel. - `showResultPanelText` (boolean): Gets or sets a value indicating whether to display the header label for the result panel. - `hideAddressAndPhone` (boolean): Gets or sets a value indicating whether to hide the address and phone number fields. - `fieldTip` ([HppFieldVisibility](https://devportal.demo.winkpg.io/docs/api/models/HppFieldVisibility.md)): Gets or sets the visibility of the tip amount field. `null` is treated as `Hidden`. (nullable) Values: - `Hidden` - `Optional` - `Required` - `fieldPurchaseOrder` ([HppFieldVisibility](https://devportal.demo.winkpg.io/docs/api/models/HppFieldVisibility.md)): Gets or sets the visibility of the customer code / purchase order field. `null` is treated as `Hidden`. (nullable) Values: - `Hidden` - `Optional` - `Required` - `fieldContactPhone` ([HppFieldVisibility](https://devportal.demo.winkpg.io/docs/api/models/HppFieldVisibility.md)): Gets or sets the visibility of the contact phone field. `null` means the page has never configured it and the older control decides: the Streamlined `CollectPhone` toggle, or on a Classic page the always-rendered phone input behind `hideAddressAndPhone`. (nullable) Values: - `Hidden` - `Optional` - `Required` - `fieldLevel3Amount` ([HppFieldVisibility](https://devportal.demo.winkpg.io/docs/api/models/HppFieldVisibility.md)): Gets or sets the visibility of the read-only Level 3 summary a session can carry. `null` means the page has never configured it and the older `AllowLevel3LineItems` toggle decides. (nullable) Values: - `Hidden` - `Optional` - `Required` - `shippingAmountMode` ([HppShippingAmountMode](https://devportal.demo.winkpg.io/docs/api/models/HppShippingAmountMode.md)): Gets or sets where this page's shipping amount comes from. `null` is treated as `CardholderEntered`. (nullable) Values: - `CardholderEntered`: The cardholder types the shipping amount into the shipping field (today's behaviour, and what a persisted null mode coalesces to). - `Flat`: The merchant fixed a single shipping amount for this page. The field renders visible, seeded with that amount, and non-editable, and the create path stamps the configured value server-side. An amount of zero is free shipping, which is a configured value like any other. - `ProviderCalculated`: The shipping amount comes from a carrier rate quote the cardholder selects. The page quotes the shipping address once it is complete, re-quotes whenever it changes, and preselects an option so a cardholder who ignores the selector still has a valid total. The submit carries only the quote and option identifiers; the create path re-reads the stored quote and charges its amount. What happens when no rate can be quoted is the page's shippingQuoteFailureBehavior. A session that locks a shipping amount wins over this mode, and the selector does not render for it at all. - `flatShippingAmount` (number(double)): Gets or sets the fixed shipping amount this page charges. Meaningful only in `Flat` mode; the save-time validator refuses a non-null value in any other mode so a stale amount cannot sit in the document waiting to be reactivated by a later mode change. (nullable) - `shippingQuoteFailureBehavior` ([HppShippingQuoteFailureBehavior](https://devportal.demo.winkpg.io/docs/api/models/HppShippingQuoteFailureBehavior.md)): Gets or sets what a `ProviderCalculated` page does when no carrier rate can be quoted. `null` is treated as `BlockPayment`. (nullable) Values: - `BlockPayment`: The payment cannot be taken until a rate is quoted. The default, and what a persisted null coalesces to: the safest reading of a page that never chose. - `ChargeFallbackAmount`: The page charges its configured fallback shipping amount (shippingFallbackAmount), which may be zero. - `ChargeNoShipping`: The payment proceeds with no shipping charged. - `shippingFallbackAmount` (number(double)): Gets or sets the shipping amount, in the transaction currency, that a `ProviderCalculated` page charges when no carrier rate can be quoted and the page is set to `ChargeFallbackAmount`. Zero is a valid configured value. (nullable) - `taxAmountMode` ([HppTaxAmountMode](https://devportal.demo.winkpg.io/docs/api/models/HppTaxAmountMode.md)): Gets or sets where this page's tax amount comes from. `null` is treated as `CardholderEntered`. (nullable) Values: - `CardholderEntered`: The cardholder types the tax amount into the tax field, or the merchant's own auto-calculated tax rate fills it. The default, and what a persisted null mode coalesces to. - `FlatRate`: The merchant picked one of its invoicing tax rates for this page. The tax field renders read-only, filled with that rate applied to the taxable amount, and the server computes and charges the same figure whatever the browser submitted. - `ProviderCalculated`: The rate comes from the merchant's tax provider, looked up for the customer's address. The tax field renders read-only, is quoted when the address is complete and re-quoted when it changes, and the server re-derives the rate for the submitted address and refuses a submit whose tax disagrees with it. A provider that cannot answer blocks the payment rather than charging no tax. - `flatTaxRateId` (string(uuid)): Gets or sets the identifier of the merchant's invoicing tax rate this page charges. Meaningful only in `FlatRate` mode; the save-time validator refuses a non-null value in any other mode so a stale rate cannot be reactivated by a later mode change. (nullable) - `taxQuoteAddress` ([HppTaxQuoteAddress](https://devportal.demo.winkpg.io/docs/api/models/HppTaxQuoteAddress.md)): Gets or sets which of the customer's addresses a `ProviderCalculated` page looks the tax rate up for. `null` is treated as `Billing`. The save-time validator refuses a non-null value in any other mode. (nullable) Values: - `Billing`: The billing address. What a persisted null coalesces to. - `Shipping`: The shipping address, for a merchant that ships goods and owes tax where they are delivered. A page in this setting must show the shipping address panel. - `panelLayout` (array<[HppPanelDefinition](https://devportal.demo.winkpg.io/docs/api/models/HppPanelDefinition.md)>): Optional explicit panel ordering and sizing for the public form. When `null`, the page uses the default panel layout. (nullable) - `receiptAndNotifications` ([HostedPageReceipts](https://devportal.demo.winkpg.io/docs/api/models/HostedPageReceipts.md)): Represents receipt and notification settings for the hosted payment page, including callback URLs, email options, and notification recipients. Fields: - `callbackUrl` (string): Gets or sets an optional URL to receive a webhook notification when a hosted page transaction is processed. Conditional: Conditional (see validator source). Max length: 200. Conditional: When CallbackUrl is not empty. (nullable) - `enableWebhookNotification` (boolean): (nullable) - `enableCustomerEmail` (boolean): (nullable) - `customerEmailLogo` (string): Gets or sets a logo to include on email receipts sent to the customer. (nullable) - `customerEmailFooter` (string): Gets or sets optional footer text to include in customer email receipts. (nullable, max length 1000) - `customerEmailBody` (string): Gets or sets optional body text for customer email receipts. (nullable, max length 3000) - `useHostedConfirm` (boolean): Gets or sets a value indicating whether to use the hosted confirmation/receipt page. - `receiptAdditionalText` (string): Gets or sets optional additional text to include on receipts. (nullable, max length 1000) - `customerEmailAsPdf` (boolean): Gets or sets a value indicating whether customer receipts are sent as PDF attachments. - `emailPurchaseNotifications` (boolean): Gets or sets a value indicating whether to notify email addresses of transactions completed via the hosted payment page. - `purchaseNotifyEmails` (array<[HostedPagePurchaseNotificationEmail](https://devportal.demo.winkpg.io/docs/api/models/HostedPagePurchaseNotificationEmail.md)>): Gets or sets the list of email addresses to notify of completed purchases. (nullable) - `disclosures` ([HostedPageDisclosures](https://devportal.demo.winkpg.io/docs/api/models/HostedPageDisclosures.md)): Represents disclosure information for a hosted payment page, including display and acceptance requirements. Fields: - `disclosureText` (string): Gets or sets the body text to display as a disclosure before processing a transaction. (nullable, max length 3000) - `showDisclosures` (boolean): Gets or sets a value indicating whether to show disclosure text. - `requireDisclosureAccept` (boolean): Gets or sets a value indicating whether the customer must accept the disclosure before completing a transaction. - `achWebAuthorizationText` (string): Optional per-page override for the NACHA WEB single-debit ACH authorization wording shown on the ACH consent checkbox. Blank/unset renders the platform default. Supports the `{MerchantName}` placeholder, substituted with the merchant's display name at render. When set it is captured verbatim (with a content version hash) on each resulting ACH WEB debit, so custom language a merchant's bank/ODFI approved becomes the recorded authorization. The save-time validator guarantees a configured override never renders blank, so the submit-time fail-closed gate is never reached with a blank override. Conditional: When AchWebAuthorizationText is not empty. Max length: 2000. (nullable) - `achRecurringWebAuthorizationText` (string): Optional per-page override for the NACHA WEB recurring ACH authorization wording shown on the ACH consent checkbox of a Save-Card-with-Initial-Charge page. Blank/unset renders the platform default recurring language. Supports the `{MerchantName}` placeholder and the `{RecurringSchedule}` placeholder (substituted with the plan's schedule summary at render). Used only when the ACH debit establishes a recurring arrangement; a one-off ACH debit uses `achWebAuthorizationText`. Captured verbatim (with a content version hash) on the resulting initial ACH WEB debit. Conditional: When AchRecurringWebAuthorizationText is not empty. Max length: 2000. (nullable) - `achSaveOnlyWebAuthorizationText` (string): Optional per-page override for the NACHA save-only (storage) ACH authorization wording shown on the ACH consent checkbox of a store-bank-account-no-charge page. Blank/unset renders the platform default save-only language. Supports the `{MerchantName}` placeholder, substituted with the merchant's display name at render. Used only when the account is stored without any debit being taken now; a one-off debit uses `achWebAuthorizationText` and an initial-charge recurring arrangement uses `achRecurringWebAuthorizationText`. Captured verbatim (with a content version hash) on the resulting save. Conditional: When AchSaveOnlyWebAuthorizationText is not empty. Max length: 2000. (nullable) - `customText` ([HostedPageCustomText](https://devportal.demo.winkpg.io/docs/api/models/HostedPageCustomText.md)): Represents custom text and links for a hosted payment page, including terms, promo, support, and privacy policy. Fields: - `termsAndConditionsLink` (string): Gets or sets an optional URL for a link to your terms and conditions. Conditional: Conditional (see validator source). Max length: 200. Conditional: When TermsAndConditionsLink is not empty. (nullable) - `aboutUsLink` (string): Gets or sets an optional URL for a link to your 'about us' page. Conditional: Conditional (see validator source). Max length: 200. Conditional: When AboutUsLink is not empty. (nullable) - `processButtonText` (string): Gets or sets optional custom text to display in place of 'Process' on the process button. (nullable, max length 50) - `headerText` (string): Gets or sets optional text to display at the top of the hosted page. (nullable, max length 100) - `promoText` (string): Gets or sets optional text to display as a highlighted announcement or promotion. (nullable, max length 200) - `promoLink` (string): Gets or sets an optional URL to make the promo text a link. Conditional: Conditional (see validator source). Max length: 200. Conditional: When PromoLink is not empty. (nullable) - `supportLink` (string): Gets or sets an optional URL for hosted page customers to access support in processing a transaction. Conditional: Conditional (see validator source). Max length: 200. Conditional: When SupportLink is not empty. (nullable) - `poweredByText` (string): Gets or sets optional text to use as a 'powered by' caption at the bottom of the page. (nullable, max length 100) - `copyrightText` (string): Gets or sets optional text to use as a copyright statement. (nullable, max length 100) - `shippingInfoLink` (string): Gets or sets an optional URL to more information about shipping policies and terms. Conditional: Conditional (see validator source). Max length: 200. Conditional: When ShippingInfoLink is not empty. (nullable) - `privacyPolicyLink` (string): Gets or sets an optional link to your privacy policy. Conditional: Conditional (see validator source). Max length: 200. Conditional: When PrivacyPolicyLink is not empty. (nullable) - `entityVersion` (integer(int32)): (read only) - `isTemplate` (boolean): Deprecated. `true` when a template has been saved from this page. Templates live in the shared template store; this echoes whether a store row exists for the page (or, for a page written under the former inline model that has not been migrated yet, its stored flag). (deprecated) - `templateName` (string): Deprecated. The name of the template saved from this page, echoed from the shared template store; `null` when `isTemplate` is `false`. (nullable, deprecated) - `templateDescription` (string): Deprecated. The description of the template saved from this page, echoed from the shared template store; `null` when `isTemplate` is `false`. (nullable, deprecated) - `shareTemplate` (boolean): Deprecated. Whether the template saved from this page is shared beyond its merchant, echoed from the shared template store's published state. (deprecated) - `createdFromTemplateId` (string(uuid)): The template this page was created from, or `null` for a page started blank. Set by the create-from-template paths and by the designers' Load Template action when the page is saved. (nullable) - `pageMode` ([HostedPaymentPageMode](https://devportal.demo.winkpg.io/docs/api/models/HostedPaymentPageMode.md)): (nullable) Values: - `Classic`: The original full-control builder with accordion sections and comprehensive configuration. - `Streamlined`: A simplified, Stripe-inspired builder with live preview and a clean two-column public form. - `collectBusinessName` (boolean): (nullable) - `collectPhone` (boolean): Older Streamlined control for the payer phone field. Honored only while `fieldsAndPanels.fieldContactPhone` is `null`; once that visibility is set it decides what the page renders, and this toggle is kept in step with it on every save. (nullable) - `allowPromoCodes` (boolean): (nullable) - `collectTaxId` (boolean): Deprecated and inert. No hosted payment page renders a tax ID field, so setting this collects nothing and no tax ID is stored. To capture a buyer tax ID, define a merchant custom field and make it visible on hosted payment pages. (nullable) - `savePaymentDetails` (boolean): (nullable) - `declineRetryMode` ([HppDeclineRetryMode](https://devportal.demo.winkpg.io/docs/api/models/HppDeclineRetryMode.md)): What a payment link created against this page does when a payment is declined. `null` inherits the tenant default, which is the historical single-use behavior: any declined payment spends the link permanently. (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. - `requireTermsAcceptance` (boolean): (nullable) - `termsUrl` (string): (nullable) - `callToActionText` (string): (nullable) - `productName` (string): (nullable) - `productDescription` (string): (nullable) - `productImageBlobName` (string): Filename of the Streamlined order-summary product image, as produced by the portal image uploader. This is not a URL: the public page resolves the filename against the hosted-page image CDN container. See `productImageBlobName` for the write contract. (nullable) - `fixedAmount` (number(double)): (nullable) - `allowCustomAmount` (boolean): (nullable) - `successRedirectUrl` (string): (nullable) - `successRedirectDelaySeconds` (integer(int32)): Seconds the hosted confirmation panel is shown before the payer is sent to the configured post-payment address. `null` means the page inherits the platform-configured delay. See `successRedirectDelaySeconds` for the write contract. (nullable) - `paymentMethods` (array): (nullable) - `customFieldNames` (array): Optional per-page allow-list of merchant custom-field names this page shows and accepts. `null` means "all of the merchant's HPP-visible custom fields"; an explicit empty list means "no merchant custom fields on this page". See `customFieldNames` for the full-replace semantics. (nullable) - `resolvedCustomFields` (array<[HppResolvedCustomFieldDto](https://devportal.demo.winkpg.io/docs/api/models/HppResolvedCustomFieldDto.md)>): The merchant custom fields this page actually shows and accepts, in the order it renders them. Read-only, and resolved on every page the hosted-payment-pages API returns: `customFieldNames` is only the page's selection, and its default (`null`) means "all of the merchant's hosted-page custom fields", so the selection on its own does not tell a caller what the page uses. This resolves it against the merchant's current definitions, applying the same enabled / hosted-page-visible / page-purpose gates the page itself applies, and reports each field's validation rules so a value can be checked before it is posted. The list also carries the fields the merchant keeps hidden from the payer but opted in to accepting a value for through the session API, flagged by `isRenderedToPayer`. Those are reported precisely because the API is the only way to use them. Empty means the page uses no merchant custom fields. Definitions are merchant-global and live, so this tracks the merchant's configuration: renaming or disabling a field changes what this returns for every page that had not scoped itself to a fixed list. Sending it back on a create or update has no effect; the write contract is `customFieldNames`. (nullable) Fields of each item: - `name` (string): The field's name. This is the key the value is carried under: in a session's prefilled fields, and in the transaction's `customFields` collection. (nullable) - `label` (string): The text the page labels the input with: the merchant's description of the field when one is configured, otherwise `name`. (nullable) - `position` (integer(int32)): The field's position in the page's rendering order, lowest first. The page breaks ties on `name`; the list is already returned in that order. - `isRequired` (boolean): The merchant's requiredness setting for the field, reported as configured. - `isReadOnly` (boolean): Whether the page displays the field without letting the customer edit it. A read-only field still submits the value the session prefilled it with. - `isNumeric` (boolean): Whether the field accepts only a number. - `isRenderedToPayer` (boolean): Whether the payer sees the field on the page. `false` marks a field the merchant keeps hidden but opted in to carrying a value supplied through the session API: pass it in the session's prefilled fields and the platform stamps it onto the resulting transaction. Those fields are reported here precisely because the API is the only way to use them. - `maxLength` (integer(int32)): The number of characters a value may carry: the narrower of the merchant's configured limit and the platform ceiling. A numeric field reports the platform ceiling, which is what its rules enforce. - `decimalPlaces` (integer(int32)): Decimal places a numeric value may carry. `null` when the field is not numeric. (nullable) - `numericMinValue` (number(double)): Lowest accepted value for a numeric field. `null` when the field is not numeric. (nullable) - `numericMaxValue` (number(double)): Highest accepted value for a numeric field. `null` when the field is not numeric. (nullable) - `regEx` (string): The merchant's optional regular expression the value has to match. `null` when the merchant configured none. A pattern that does not compile is ignored rather than failing the submit. (nullable) - `regExErrorMessage` (string): The message the page shows when `regEx` rejects the value, when the merchant wrote one. `null` falls back to a generic message. (nullable) - `isMultiValue` (boolean): Whether the field carries a list of values rather than a single value. A multi-value field is prefilled through the session's `prefilledListFields` and reaches the transaction as `customFields[].values`; the page renders the list read-only. A single value sent for it is still accepted and mirrored into the list. - `maxValues` (integer(int32)): The largest number of values a multi-value field accepts, after the platform default and ceiling are applied. `null` when the field is not multi-value. (nullable) - `allowedEmbeddingDomains` (array): (nullable) - `checkoutLayout` ([CheckoutLayout](https://devportal.demo.winkpg.io/docs/api/models/CheckoutLayout.md)): (nullable) Values: - `Standard`: Two-column layout: order summary on the left, payment form on the right. This is the default layout matching the original Streamlined mode design. - `Compact`: Single centered column with an inline summary at the top, form fields below, and a prominent CTA button. Minimal chrome, max-width ~480px. - `Split`: Full-width hero header with product image and summary information, then a centered narrower column (~560px) with the payment form below. - `Embedded`: Frameless minimal layout designed for iframe embedding. No order summary panel, just payment fields and CTA with minimal padding. - `allowLevel3LineItems` (boolean): Older control for the read-only Level 3 line-item summary. Honored only while `fieldsAndPanels.fieldLevel3Amount` is `null`; once that visibility is set it decides what the page renders, and this toggle is kept in step with it on every save. (nullable) - `pagePurpose` ([HppPagePurpose](https://devportal.demo.winkpg.io/docs/api/models/HppPagePurpose.md)): Instance-level page purpose. `null` resolves to `Payment`. `SaveCard` dedicates the page to capturing and storing the customer's card via a zero-dollar verification (no charge); amount-bearing configuration is hidden in the builder and rejected by the validator, and sessions created against the page inherit the save-card flow. (nullable) Values: - `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). - `recurringPlan` ([HppRecurringPlan](https://devportal.demo.winkpg.io/docs/api/models/HppRecurringPlan.md)): The inlined recurring-schedule definition whose first payment a `SaveCardWithInitialCharge` page charges. `null` for every other purpose. Fields: - `recurringAmount` (number(double)): The amount charged on each recurring payment after the initial charge. (greater than 0) - `frequency` ([Frequency](https://devportal.demo.winkpg.io/docs/api/models/Frequency.md)): The frequency unit of the recurring schedule (e.g. Monthly, Weekly). Values: - `Secondly` - `Minutely` - `Hourly` - `Daily` - `Weekly` - `Monthly` - `Yearly` - `interval` (integer(int32)): The interval multiplier for `frequency` (e.g. `Frequency = Monthly` with `Interval = 3` is every three months). Defaults to 1. (min 1) - `numberOfPayments` (integer(int32)): Total number of payments in the schedule, including the initial charge. A Contract instantiated from this definition covers the payments after the initial charge (`GetScheduledPaymentCount`). (min 2) - `initialChargeAmount` (number(double)): Optional override for the first (initial) charge amount. When `null`, the initial charge uses `recurringAmount`. Lets a merchant charge a different amount up front (e.g. a setup fee bundled into payment one) while the recurring schedule stays at `recurringAmount`. Conditional: When InitialChargeAmount is not null. Must be > 0. (nullable) - `captureMode` ([HppCaptureMode](https://devportal.demo.winkpg.io/docs/api/models/HppCaptureMode.md)): Capture timing for the chargeable Payment flow. `null` resolves to `Sale`. `Authorize` produces an Authorization with capture deferred. (nullable) Values: - `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). - `allowTransparentEmbedding` (boolean): Opt-in to a see-through backdrop when the page is rendered inside a merchant iframe. `null`/`false` keeps the page opaque (the default). Honoured only when the request is genuinely framed and `allowedEmbeddingDomains` is configured. (nullable) - `allowDeveloperPortalEmbedding` (boolean): Whether the developer portal's public origin is allowed to embed this page, in addition to `allowedEmbeddingDomains`. `null`/`false` is off (the default). (nullable) - `hideTitle` (boolean): Suppress the page `title` on the payer-facing page (both the Classic and the Streamlined renderer). `null`/`false` is the default and renders the title exactly as before. Display-only: the title is still stored, still returned, and still shown on the administrative surfaces (grid, quick view, favorites subtitle). (nullable) - `hideMerchantName` (boolean): Suppress the merchant business-name line in the Streamlined identity header on the payer-facing page. `null`/`false` is the default. The banner image in that same header stays governed by `hideBanner`. Display-only, and deliberately narrow: the merchant name still reaches the Apple Pay / Paze sheet total label and the NACHA ACH consent copy (and the consent evidence captured with an ACH authorization), which must name the real merchant regardless of this flag. (nullable) - `hideLoadingIndicator` (boolean): Suppress the gateway's own loading chrome on the payer-facing page: the loading card shown while the page resolves, and the connecting affordance drawn over the prerendered form before the circuit is live. `null`/`false` is the default and shows them exactly as before. For an integrator who embeds the page and paints a loading state of their own, revealing the frame on the `ready` event. Display-only: the session, the payment and the events the page emits are untouched. Honored on the initial document, which the embedding-restriction feature resolves the page for; a deployment with that feature off shows the chrome as before. (nullable) - `campaignId` (string(uuid)): Optional campaign this page belongs to. Sessions created from this page inherit it when the create request names no campaign of its own, so a merchant can attach a whole page to a campaign once instead of naming it on every link. (nullable) - `products` (array<[HppPageProduct](https://devportal.demo.winkpg.io/docs/api/models/HppPageProduct.md)>): The catalog products this page sells, in display order, or `null` for a page priced by a single `productName` with a `fixedAmount` or a payer-entered amount. Each entry references an invoicing catalog product owned by this page's merchant; the price, name and quantity limits are read from the catalog when a link is created and snapshotted onto that link, so editing the catalog never reprices a link already in a payer's hands. (nullable) Fields of each item: - `productId` (string(uuid)) required: The invoicing catalog product this entry sells. - `displayOrder` (integer(int32)): Zero-based position of the product in the payer-facing list. (min 0) - `isOptional` (boolean): `true` for an add-on the payer may leave out; `false` for a product every purchase on this page includes. - `allowQuantityChange` (boolean): Whether the payer may change the quantity from `defaultQuantity`. - `defaultQuantity` (number(double)): The quantity the page starts at. Must sit inside the effective quantity bounds, and is the only quantity a payer can buy when `allowQuantityChange` is `false`. Conditional: When MinimumQuantity is not null. Must be >= . Conditional: When MaximumQuantity is not null. Must be <= . (greater than 0, max 9999) - `minimumQuantity` (number(double)): Optional page-level floor on the quantity, applied on top of the product's own `MinimumQuantity`. The effective minimum is the larger of the two. Conditional: When MinimumQuantity is not null. Must be > 0. (nullable) - `maximumQuantity` (number(double)): Optional page-level ceiling on the quantity, applied on top of the product's own `MaximumQuantity`. The effective maximum is the smaller of the two. Conditional: When MaximumQuantity is not null. Must be > 0. Conditional: When MinimumQuantity is not null and MaximumQuantity is not null. Must be >= . (nullable) - `isLocked` (boolean): (nullable) - `lockedAt` (string(date-time)): (nullable) - `lockedByUserId` (string(uuid)): (nullable) - `lockedByUserName` (string): (nullable) - `lockReason` (string): (nullable) ### 403 Forbidden **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 401 Unauthorized **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 400 Bad Request **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) _Example: Request failed validation_ One or more fields were rejected before any rule ran. error.code is null on the envelope and the causes are in validationErrors, one entry per failure. An entry carries code when the validator declared a publishable one, and memberPaths when the full path says more than members does (an element inside a collection, for example). Both keys are omitted when they would add nothing. ```json { "error": { "code": "null", "message": "Your request is not valid!", "details": "The following errors were detected during validation.", "data": { "correlationId": "0123456789abcdef0123456789abcdef" }, "validationErrors": [ { "message": "'Amount' must be greater than 0.", "members": [ "amount" ] }, { "message": "The card has expired.", "members": [ "expirationDate" ], "code": "CardData:CardExpired" }, { "message": "'Value' must not be empty.", "members": [ "value" ], "memberPaths": [ "customFields[2].value" ] } ] } } ``` ### 404 Not Found **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) _Example: Resource not found_ The id in the path names no record the caller can see. Most resources answer with a null error.code and a message naming the resource type and the id; a resource that publishes a not-found code in the catalog above carries it in error.code instead, so check for one before matching on the message. ```json { "error": { "code": "null", "message": "There is no entity Transaction with id = 7d1f3a52-0c4e-4b8a-9e21-5a6b7c8d9e00!", "details": "null", "data": { "correlationId": "0123456789abcdef0123456789abcdef" }, "validationErrors": "null" } } ``` ### 501 Not Implemented **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 500 Internal Server Error **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### default The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The [error reference](https://devportal.demo.winkpg.io/docs/errors.md) lists the values `error.code` can take. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) _Example: Business rule refused the request_ The request was understood and rejected by a platform rule. This is the shape that carries a code from the catalog above, so branch on error.code rather than on the message text. The HTTP status is the one listed against the code. ```json { "error": { "code": "Transactions:OperationNotAllowed", "message": "The operation 'Void' is not allowed on a Sale transaction with result 'Approved' and settlement state 'Settled'.", "details": "null", "data": { "correlationId": "0123456789abcdef0123456789abcdef" }, "validationErrors": "null" } } ``` ### 429 The request was refused because a rate limit was exceeded, or because something a later retry can clear stopped it. A rate limit refusal carries an `application/problem+json` body: wait at least the interval `Retry-After` names before retrying, then back off. Limits are tuned per deployment, so read the allowance from the response headers rather than assuming a fixed ceiling. Any other refusal carries the standard error envelope as `application/json`, and its `error.code` names the cause. **Content type:** `application/problem+json` Schema: [`RateLimitProblemDetails`](https://devportal.demo.winkpg.io/docs/api/models/RateLimitProblemDetails.md) Properties: - `type` (string) required: The problem type identifier. Always the same value: the failure is the status code itself, so there is no sub-type for a caller to branch on. (nullable) - `title` (string) required: A short, human-readable summary of the problem type. (nullable) - `status` (integer(int32)) required: The HTTP status code, repeated in the body as the problem-details format defines. - `detail` (string) required: A human-readable explanation of this occurrence of the problem. (nullable) - `retryAfterSeconds` (integer(int32)) required: How long to wait before retrying, in whole seconds, carrying the same figure as the `Retry-After` header. Always at least one: a value of zero would invite an immediate retry that is certain to be rejected again. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ## Example request Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key. ### cURL ```bash curl -X GET "{{BASE_URL}}/api/hostedpaymentpages/{id}" \ -H "api-key: {{API_KEY}}" ``` ### PowerShell ```powershell $headers = @{ 'api-key' = '{{API_KEY}}' } $response = Invoke-RestMethod -Method GET -Uri '{{BASE_URL}}/api/hostedpaymentpages/{id}' ` -Headers $headers ``` ### TypeScript (SDK) ```bash npm install @winkpg/winkpg-api ``` ```typescript import { Configuration, HostedPaymentPagesApi } from '@winkpg/winkpg-api'; const api = new HostedPaymentPagesApi(new Configuration({ basePath: '{{BASE_URL}}', apiKey: '{{API_KEY}}', })); const { data } = await api.hostedPaymentPagesGet("3fa85f64-5717-4562-b3fc-2c963f66afa6"); ``` ### TypeScript (raw HTTP) ```typescript const response = await fetch('{{BASE_URL}}/api/hostedpaymentpages/{id}', { method: 'GET', headers: { "api-key": "{{API_KEY}}", }, }); const data = await response.json(); ``` ### C# (SDK) ```bash dotnet add package WinkPg.Api.Client ``` ```csharp using WinkPg.Api.Client.Api; using WinkPg.Api.Client.Client; var config = new Configuration { BasePath = "{{BASE_URL}}" }; config.AddApiKey("api-key", "{{API_KEY}}"); var api = new HostedPaymentPagesApi(config); var result = await api.HostedPaymentPagesGetAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6")); ``` ### C# (raw HTTP) ```csharp using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") }; var request = new HttpRequestMessage(new HttpMethod("GET"), "/api/hostedpaymentpages/{id}"); request.Headers.Add("api-key", "{{API_KEY}}"); var response = await http.SendAsync(request); response.EnsureSuccessStatusCode(); var json = await response.Content.ReadAsStringAsync(); ``` ### Python (SDK) ```bash pip install winkpg-api ``` ```python import winkpg_api configuration = winkpg_api.Configuration(host="{{BASE_URL}}") configuration.api_key["ApiKey"] = "{{API_KEY}}" with winkpg_api.ApiClient(configuration) as client: api = winkpg_api.HostedPaymentPagesApi(client) result = api.hosted_payment_pages_get("3fa85f64-5717-4562-b3fc-2c963f66afa6") ``` ### Python (raw HTTP) ```bash pip install requests ``` ```python import requests headers = { "api-key": "{{API_KEY}}", } response = requests.request( "GET", "{{BASE_URL}}/api/hostedpaymentpages/{id}", headers=headers, ) response.raise_for_status() data = response.json() ``` ## See also - [All documentation](https://devportal.demo.winkpg.io/llms.txt): the machine-readable index of every public page on this site.