# PUT /api/hostedpaymentpages/{id} Update hosted payment page Updates an existing hosted payment page configuration. **Operation ID:** `hostedPaymentPagesUpdate` ## Authorization Requires: HostedPaymentPage.HostedPaymentPages, HostedPaymentPage.HostedPaymentPages.Update, merchant scope. Requires API key scope: `transactions:write` Required permissions: - `HostedPaymentPage.HostedPaymentPages` - `HostedPaymentPage.HostedPaymentPages.Update` ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | id | path | yes | string(uuid) | | | suppressNulls | query | no | boolean | If true, omit properties with null values. | ## Request Body **Content type:** `application/json` Schema: [`HostedPaymentPageUpdateDto`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HostedPaymentPageUpdateDto.md) Properties: - `name` (string): (nullable, min length 5, max length 100) - `merchantId` (string(uuid)) required - `isActive` (boolean) - `title` (string): Conditional: When Title is not empty. Min length: 5. (nullable, max length 100) - `bannerImage` (string): Filename of the header banner image to display on the page, as returned by the portal image uploader (for example `3f2a5b90-7c41-4d2e-9f0a-1b8c6d5e4f21.png`). This is not a URL: the public page resolves the filename against the hosted-page image CDN container. Upload the image in the page builder's appearance section, then send the filename it returns. Leave empty for no banner, or set `hideBanner` to suppress an image without discarding it. Validated by `HppImageBlobName`. (nullable) - `hideBanner` (boolean) - `supportRetail` (boolean) - `usePostOnSubmit` (boolean) - `useCaptcha` (boolean) - `supportTokenization` (boolean) - `pageActions` ([HostedPaymentPageActionUrls](https://devportal.signapay-sbx.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.signapay-sbx.winkpg.io/docs/api/models/URLConfig.md)): Gets or sets the URL to use when the payment is submitted. - `edit` ([URLConfig](https://devportal.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.winkpg.io/docs/api/models/HostedPageDonationAmount.md)>): Gets or sets the list of predefined donation amount options. (nullable) - `theme` ([HostedPageTheme](https://devportal.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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. A Classic page reads this flag on its own. A Streamlined page reads it together with `fixedAmount` and `allowCustomAmount`: when `allowCustomAmount` is true the customer can change the amount whatever this flag says, and this flag applies only while the page has no positive `fixedAmount`. The Streamlined builder saves this flag from its Amount and Allow Custom Amount settings: true when the amount is empty or a custom amount is allowed, and false on a card capture page or a page that sells catalog products. A create or update through the API stores the value you send. - `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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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` - `tipPresetPercentages` (array): Gets or sets the tip percentages the payer can choose with one tap, in display order: one to four distinct whole percentages, each 1 to 100. `null` or empty means the single free-entry tip field with no buttons. (nullable) - `defaultTipSelection` ([HppTipPresetDefault](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HppTipPresetDefault.md)): Gets or sets what a page with tip presets selects before the payer chooses. `null` is treated as `NoTip`. (nullable) Values: - `NoTip`: Nothing is preselected: the tip is empty and the custom amount input stays closed until the payer chooses Custom. - `Preset`: One of the presets is preselected, named by defaultTipPercentage, and the tip opens at that percentage of the amount. - `Custom`: Custom is preselected: the custom amount input is open and empty. - `defaultTipPercentage` (integer(int32)): Gets or sets the preset selected by default, as a whole percent (20 means 20%). Required when `defaultTipSelection` is `Preset`, where it must be one of `tipPresetPercentages`, and refused at save otherwise. (nullable) - `fieldPurchaseOrder` ([HppFieldVisibility](https://devportal.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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) - `cardConsentMerchantTerms` (string): Optional per-page merchant terms shown under the card stored-credential consent text when the page saves a card. Plain text: it is HTML-encoded at render, never interpreted as markup. The terms add to the platform consent text and never replace it. A consent captured on the page records a version hash of the terms shown beside the consent text version. (nullable, max length 2000) - `customText` ([HostedPageCustomText](https://devportal.signapay-sbx.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 for the button that submits the payment. Defaults to `Process`. (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) - `isTemplate` (boolean): Deprecated. Templates live in the shared template store, not on the page. During the deprecation window this still drives that store: `true` saves a template from this page (creating the store row, or refreshing the existing one with the page's current values, name and description); `false`, or leaving the field out, removes the template saved from this page, which is what the field always meant on a full-replace update. The page itself is not changed either way. (deprecated) - `templateName` (string): Deprecated. The template's name when `isTemplate` is `true`; the page's own name is used when this is empty. (nullable, deprecated) - `templateDescription` (string): Deprecated. The template's description when `isTemplate` is `true`. (nullable, deprecated) - `shareTemplate` (boolean): Deprecated. Whether the template saved from this page is shared beyond its merchant; written to the store row's published state when `isTemplate` is `true`. (deprecated) - `createdFromTemplateId` (string(uuid)): The template this page is being created from, or `null` for a page started blank. The designers stamp it when Load Template is applied and the create-from-template path sets it server-side; it is recorded on the page and never copied into a template. (nullable) - `pageMode` ([HostedPaymentPageMode](https://devportal.signapay-sbx.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 overwritten from it on every save, so a write here alongside a set visibility is discarded. Write `fieldsAndPanels.fieldContactPhone` instead. (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.signapay-sbx.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. Conditional: When DeclineRetryMode is not null. (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. - `maxFailedAttempts` (integer(int32)): How many declined or refused payments a payment link created against this page accepts before it pauses itself, from 1 to 20. `null` inherits the tenant default, which is no limit unless an administrator set one. (nullable, min 1, max 20) - `requireTermsAcceptance` (boolean): (nullable) - `termsUrl` (string): Conditional: When TermsUrl is not empty. Max length: 500. (nullable) - `callToActionText` (string): Optional wording for the pay button on a Streamlined page, shown followed by the total the payer is charged, for example `Donate $23.45`. On a Streamlined page it takes precedence over `customText.processButtonText`; leave it empty to use that value instead. A Classic page shows `customText.processButtonText`. (nullable, max length 50) - `productName` (string): (nullable, max length 100) - `productDescription` (string): (nullable, max length 500) - `productImageBlobName` (string): Filename of the product image shown in the Streamlined checkout order summary, as returned by the portal image uploader (for example `3f2a5b90-7c41-4d2e-9f0a-1b8c6d5e4f21.png`). Same contract as `bannerImage`: this is not a URL, and the public page resolves the filename against the hosted-page image CDN container. Upload the image in the Streamlined page builder, then send the filename it returns. Leave empty for no product image. Validated by `HppImageBlobName`. (nullable) - `fixedAmount` (number(double)): Conditional: When FixedAmount is not null. Must be >= 0. Conditional: Conditional (see validator source). Conditional: When IsCardCapture(PagePurpose) is true. (nullable) - `allowCustomAmount` (boolean): Conditional: Conditional (see validator source). Conditional: When IsCardCapture(PagePurpose) is true. (nullable) - `successRedirectUrl` (string): Conditional: When SuccessRedirectUrl is not empty. Max length: 500. (nullable) - `successRedirectDelaySeconds` (integer(int32)): How long the hosted confirmation panel is shown, in seconds, before the payer is sent to the configured post-payment address. Accepts 0 to 30; `0` redirects as soon as the panel has rendered. Omit it (or send `null`) to inherit the platform-configured delay, which defaults to 5 seconds. The payer always gets a `Continue now` button that skips the wait. Ignored when no post-payment address is configured, and on an embedded session, which never redirects. (nullable, min 0, max 30) - `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" (the default; existing pages that never set this stay unchanged). An explicit empty list means "no merchant custom fields on this page". A populated list intersects with the enabled / HPP-visible / save-card-purpose gates. This property is full-replace on update: because the update DTO carries the operator's complete selection, sending `null` on a round-trip clears a previously configured list back to the all-fields default, and sending `[]` scopes the page to no custom fields. A client that omits the property on update therefore resets it. The editors always send the operator's actual selection. Conditional: When CustomFieldNames is not null. (nullable, max items 100) - `allowedEmbeddingDomains` (array): (nullable, max items 20) - `checkoutLayout` ([CheckoutLayout](https://devportal.signapay-sbx.winkpg.io/docs/api/models/CheckoutLayout.md)): Conditional: When CheckoutLayout is not null. (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 overwritten from it on every save, so a write here alongside a set visibility is discarded. Write `fieldsAndPanels.fieldLevel3Amount` instead. (nullable) - `pagePurpose` ([HppPagePurpose](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HppPagePurpose.md)): Instance-level page purpose. `null` resolves to `Payment`. `SaveCard` dedicates the page to card capture (zero-dollar verification, no charge). A card-capture page cannot enable amount-bearing settings such as donation amounts or the tax, shipping and convenience fee fields; a request that does is rejected with a validation error. Conditional: Conditional (see validator source). Conditional: When PagePurpose is not null. (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.signapay-sbx.winkpg.io/docs/api/models/HppRecurringPlan.md)): The inlined recurring-schedule definition whose first payment a `SaveCardWithInitialCharge` page charges. Required (validated) when `pagePurpose` is `SaveCardWithInitialCharge`; `null` otherwise. Required: When RequiresRecurringPlan(PagePurpose) is true. Conditional: Conditional (see validator source). Fields: - `recurringAmount` (number(double)): The amount charged on each recurring payment after the initial charge. (greater than 0) - `frequency` ([Frequency](https://devportal.signapay-sbx.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) - `managementUrl` (string): The HTTPS address of a page where the payer can update or cancel this recurring payment. Apple Pay shows it on the recurring payment sheet and requires it on a recurring request, so a plan without one never asks Apple Pay for a merchant token, and Apple Pay is not offered on its sessions. Optional, 200 characters or fewer. Snapshotted onto the session with the rest of the plan, so a payer enrolls under the address that was in effect when their link was created. (nullable, max length 200) - `captureMode` ([HppCaptureMode](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HppCaptureMode.md)): Capture timing for the chargeable Payment flow: `Sale` (default; `null` resolves here) authorizes and captures now; `Authorize` authorizes now and defers capture. Composes with the save-card option to produce the "save card + delayed capture" combination. `Authorize` is rejected on the card-capture page purposes (`SaveCard` and `SaveCardWithInitialCharge`). Conditional: When CaptureMode is not null. Conditional: When IsCardCapture(PagePurpose) is true. (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 this page is rendered inside a merchant iframe, so the merchant's own page shows through behind the payment form. `null`/`false` is the default and keeps the page fully opaque. The transparent render additionally requires that the request is genuinely framed (resolved server-side from the browser-set `Sec-Fetch-Dest` header) and that `allowedEmbeddingDomains` is configured, so it applies only inside the parents the merchant allowlisted. A page opened directly as a standalone payment link always paints its own background. Only the backdrop clears: the payment form keeps its own paint. (nullable) - `allowDeveloperPortalEmbedding` (boolean): Allow the developer portal to embed this page, so a developer can try it in the portal's embed SDK playground without adding the portal's host to `allowedEmbeddingDomains`. `null`/`false` is the default and leaves embedding exactly as the allowlist defines it. When `true`, the developer portal's public origin, as configured for this environment, is accepted as a session's `parentOrigin`, and is added to the page's iframe allowlist when `allowedEmbeddingDomains` is configured. It admits that one origin and no other. A page with no allowed embedding domains can still be framed by any site, as before. Has no effect when the environment has no developer portal address configured. (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) - `requireSession` (boolean): Close the sessionless route for this page. When `true`, opening the page's own address shows the payer a notice asking for a payment link instead of the payment form, and only a payment session (its short link or its session id) renders the form. `null` or `false` is the default and keeps the page payable on both routes. For a page priced only through payment sessions. Sessions are still created through the API or the back office, and a session against this page resolves and renders as it does for any other page. The flag decides which address renders the form; a locked session amount, not this flag, is what stops a payer changing the price. (nullable) - `billLookupEnabled` (boolean): Offer a bill lookup on the page's own address. When `true` on a page whose purpose is Payment, opening the page's own address asks the payer for a bill number and the `billLookupSecondFactor`, shows the balance due, and sends the payer to that bill's payment link. `null` or `false` is the default and renders the page as before. Available only when bill lookup is enabled for your account; until then the page renders as if the flag were off. A payment link for the page renders the payment form whatever this flag says, because the link already names its bill. (nullable) - `billLookupSecondFactor` ([HppBillLookupSecondFactor](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HppBillLookupSecondFactor.md)): What the payer types beside the bill number when `billLookupEnabled` is `true`: `PostalCode` (the billing postal code on the bill) or `Email` (the address the bill was sent to). Required when `billLookupEnabled` is `true`, because a bill number alone is not enough to show a payer's balance. Required: When BillLookupEnabled is true. (nullable) Values: - `PostalCode`: The billing postal code on the bill. Compared on letters and digits only, ignoring case. - `Email`: The email address the bill was sent to. Compared ignoring case. - `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.signapay-sbx.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. Conditional: When Products is not null. (nullable, max items 50) 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) - `concurrencyStamp` (string): (nullable) _Example: Reset custom fields to all merchant fields_ Sending customFieldNames as null clears any previously configured scope, so the saved page shows every one of the merchant's hosted-page-visible custom fields. Send the concurrencyStamp from your latest read of the page. ```json { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic" } ``` _Example: Scope the page to no custom fields_ Sending customFieldNames as an empty list scopes the saved page to no merchant custom fields at all, so none are rendered or accepted. Send the concurrencyStamp from your latest read of the page. ```json { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [ ] } ``` _Example: Scope the page to selected custom fields_ Sending a populated customFieldNames list replaces any previously configured scope outright, so the saved page shows only the named fields that are still enabled and hosted-page-visible for the merchant. Send the concurrencyStamp from your latest read of the page. ```json { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [ "Purchase Order", "Department" ] } ``` **Content type:** `text/json` Schema: [`HostedPaymentPageUpdateDto`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HostedPaymentPageUpdateDto.md) Properties: - `name` (string): (nullable, min length 5, max length 100) - `merchantId` (string(uuid)) required - `isActive` (boolean) - `title` (string): Conditional: When Title is not empty. Min length: 5. (nullable, max length 100) - `bannerImage` (string): Filename of the header banner image to display on the page, as returned by the portal image uploader (for example `3f2a5b90-7c41-4d2e-9f0a-1b8c6d5e4f21.png`). This is not a URL: the public page resolves the filename against the hosted-page image CDN container. Upload the image in the page builder's appearance section, then send the filename it returns. Leave empty for no banner, or set `hideBanner` to suppress an image without discarding it. Validated by `HppImageBlobName`. (nullable) - `hideBanner` (boolean) - `supportRetail` (boolean) - `usePostOnSubmit` (boolean) - `useCaptcha` (boolean) - `supportTokenization` (boolean) - `pageActions` ([HostedPaymentPageActionUrls](https://devportal.signapay-sbx.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.signapay-sbx.winkpg.io/docs/api/models/URLConfig.md)): Gets or sets the URL to use when the payment is submitted. - `edit` ([URLConfig](https://devportal.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.winkpg.io/docs/api/models/HostedPageDonationAmount.md)>): Gets or sets the list of predefined donation amount options. (nullable) - `theme` ([HostedPageTheme](https://devportal.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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. A Classic page reads this flag on its own. A Streamlined page reads it together with `fixedAmount` and `allowCustomAmount`: when `allowCustomAmount` is true the customer can change the amount whatever this flag says, and this flag applies only while the page has no positive `fixedAmount`. The Streamlined builder saves this flag from its Amount and Allow Custom Amount settings: true when the amount is empty or a custom amount is allowed, and false on a card capture page or a page that sells catalog products. A create or update through the API stores the value you send. - `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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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` - `tipPresetPercentages` (array): Gets or sets the tip percentages the payer can choose with one tap, in display order: one to four distinct whole percentages, each 1 to 100. `null` or empty means the single free-entry tip field with no buttons. (nullable) - `defaultTipSelection` ([HppTipPresetDefault](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HppTipPresetDefault.md)): Gets or sets what a page with tip presets selects before the payer chooses. `null` is treated as `NoTip`. (nullable) Values: - `NoTip`: Nothing is preselected: the tip is empty and the custom amount input stays closed until the payer chooses Custom. - `Preset`: One of the presets is preselected, named by defaultTipPercentage, and the tip opens at that percentage of the amount. - `Custom`: Custom is preselected: the custom amount input is open and empty. - `defaultTipPercentage` (integer(int32)): Gets or sets the preset selected by default, as a whole percent (20 means 20%). Required when `defaultTipSelection` is `Preset`, where it must be one of `tipPresetPercentages`, and refused at save otherwise. (nullable) - `fieldPurchaseOrder` ([HppFieldVisibility](https://devportal.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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) - `cardConsentMerchantTerms` (string): Optional per-page merchant terms shown under the card stored-credential consent text when the page saves a card. Plain text: it is HTML-encoded at render, never interpreted as markup. The terms add to the platform consent text and never replace it. A consent captured on the page records a version hash of the terms shown beside the consent text version. (nullable, max length 2000) - `customText` ([HostedPageCustomText](https://devportal.signapay-sbx.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 for the button that submits the payment. Defaults to `Process`. (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) - `isTemplate` (boolean): Deprecated. Templates live in the shared template store, not on the page. During the deprecation window this still drives that store: `true` saves a template from this page (creating the store row, or refreshing the existing one with the page's current values, name and description); `false`, or leaving the field out, removes the template saved from this page, which is what the field always meant on a full-replace update. The page itself is not changed either way. (deprecated) - `templateName` (string): Deprecated. The template's name when `isTemplate` is `true`; the page's own name is used when this is empty. (nullable, deprecated) - `templateDescription` (string): Deprecated. The template's description when `isTemplate` is `true`. (nullable, deprecated) - `shareTemplate` (boolean): Deprecated. Whether the template saved from this page is shared beyond its merchant; written to the store row's published state when `isTemplate` is `true`. (deprecated) - `createdFromTemplateId` (string(uuid)): The template this page is being created from, or `null` for a page started blank. The designers stamp it when Load Template is applied and the create-from-template path sets it server-side; it is recorded on the page and never copied into a template. (nullable) - `pageMode` ([HostedPaymentPageMode](https://devportal.signapay-sbx.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 overwritten from it on every save, so a write here alongside a set visibility is discarded. Write `fieldsAndPanels.fieldContactPhone` instead. (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.signapay-sbx.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. Conditional: When DeclineRetryMode is not null. (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. - `maxFailedAttempts` (integer(int32)): How many declined or refused payments a payment link created against this page accepts before it pauses itself, from 1 to 20. `null` inherits the tenant default, which is no limit unless an administrator set one. (nullable, min 1, max 20) - `requireTermsAcceptance` (boolean): (nullable) - `termsUrl` (string): Conditional: When TermsUrl is not empty. Max length: 500. (nullable) - `callToActionText` (string): Optional wording for the pay button on a Streamlined page, shown followed by the total the payer is charged, for example `Donate $23.45`. On a Streamlined page it takes precedence over `customText.processButtonText`; leave it empty to use that value instead. A Classic page shows `customText.processButtonText`. (nullable, max length 50) - `productName` (string): (nullable, max length 100) - `productDescription` (string): (nullable, max length 500) - `productImageBlobName` (string): Filename of the product image shown in the Streamlined checkout order summary, as returned by the portal image uploader (for example `3f2a5b90-7c41-4d2e-9f0a-1b8c6d5e4f21.png`). Same contract as `bannerImage`: this is not a URL, and the public page resolves the filename against the hosted-page image CDN container. Upload the image in the Streamlined page builder, then send the filename it returns. Leave empty for no product image. Validated by `HppImageBlobName`. (nullable) - `fixedAmount` (number(double)): Conditional: When FixedAmount is not null. Must be >= 0. Conditional: Conditional (see validator source). Conditional: When IsCardCapture(PagePurpose) is true. (nullable) - `allowCustomAmount` (boolean): Conditional: Conditional (see validator source). Conditional: When IsCardCapture(PagePurpose) is true. (nullable) - `successRedirectUrl` (string): Conditional: When SuccessRedirectUrl is not empty. Max length: 500. (nullable) - `successRedirectDelaySeconds` (integer(int32)): How long the hosted confirmation panel is shown, in seconds, before the payer is sent to the configured post-payment address. Accepts 0 to 30; `0` redirects as soon as the panel has rendered. Omit it (or send `null`) to inherit the platform-configured delay, which defaults to 5 seconds. The payer always gets a `Continue now` button that skips the wait. Ignored when no post-payment address is configured, and on an embedded session, which never redirects. (nullable, min 0, max 30) - `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" (the default; existing pages that never set this stay unchanged). An explicit empty list means "no merchant custom fields on this page". A populated list intersects with the enabled / HPP-visible / save-card-purpose gates. This property is full-replace on update: because the update DTO carries the operator's complete selection, sending `null` on a round-trip clears a previously configured list back to the all-fields default, and sending `[]` scopes the page to no custom fields. A client that omits the property on update therefore resets it. The editors always send the operator's actual selection. Conditional: When CustomFieldNames is not null. (nullable, max items 100) - `allowedEmbeddingDomains` (array): (nullable, max items 20) - `checkoutLayout` ([CheckoutLayout](https://devportal.signapay-sbx.winkpg.io/docs/api/models/CheckoutLayout.md)): Conditional: When CheckoutLayout is not null. (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 overwritten from it on every save, so a write here alongside a set visibility is discarded. Write `fieldsAndPanels.fieldLevel3Amount` instead. (nullable) - `pagePurpose` ([HppPagePurpose](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HppPagePurpose.md)): Instance-level page purpose. `null` resolves to `Payment`. `SaveCard` dedicates the page to card capture (zero-dollar verification, no charge). A card-capture page cannot enable amount-bearing settings such as donation amounts or the tax, shipping and convenience fee fields; a request that does is rejected with a validation error. Conditional: Conditional (see validator source). Conditional: When PagePurpose is not null. (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.signapay-sbx.winkpg.io/docs/api/models/HppRecurringPlan.md)): The inlined recurring-schedule definition whose first payment a `SaveCardWithInitialCharge` page charges. Required (validated) when `pagePurpose` is `SaveCardWithInitialCharge`; `null` otherwise. Required: When RequiresRecurringPlan(PagePurpose) is true. Conditional: Conditional (see validator source). Fields: - `recurringAmount` (number(double)): The amount charged on each recurring payment after the initial charge. (greater than 0) - `frequency` ([Frequency](https://devportal.signapay-sbx.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) - `managementUrl` (string): The HTTPS address of a page where the payer can update or cancel this recurring payment. Apple Pay shows it on the recurring payment sheet and requires it on a recurring request, so a plan without one never asks Apple Pay for a merchant token, and Apple Pay is not offered on its sessions. Optional, 200 characters or fewer. Snapshotted onto the session with the rest of the plan, so a payer enrolls under the address that was in effect when their link was created. (nullable, max length 200) - `captureMode` ([HppCaptureMode](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HppCaptureMode.md)): Capture timing for the chargeable Payment flow: `Sale` (default; `null` resolves here) authorizes and captures now; `Authorize` authorizes now and defers capture. Composes with the save-card option to produce the "save card + delayed capture" combination. `Authorize` is rejected on the card-capture page purposes (`SaveCard` and `SaveCardWithInitialCharge`). Conditional: When CaptureMode is not null. Conditional: When IsCardCapture(PagePurpose) is true. (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 this page is rendered inside a merchant iframe, so the merchant's own page shows through behind the payment form. `null`/`false` is the default and keeps the page fully opaque. The transparent render additionally requires that the request is genuinely framed (resolved server-side from the browser-set `Sec-Fetch-Dest` header) and that `allowedEmbeddingDomains` is configured, so it applies only inside the parents the merchant allowlisted. A page opened directly as a standalone payment link always paints its own background. Only the backdrop clears: the payment form keeps its own paint. (nullable) - `allowDeveloperPortalEmbedding` (boolean): Allow the developer portal to embed this page, so a developer can try it in the portal's embed SDK playground without adding the portal's host to `allowedEmbeddingDomains`. `null`/`false` is the default and leaves embedding exactly as the allowlist defines it. When `true`, the developer portal's public origin, as configured for this environment, is accepted as a session's `parentOrigin`, and is added to the page's iframe allowlist when `allowedEmbeddingDomains` is configured. It admits that one origin and no other. A page with no allowed embedding domains can still be framed by any site, as before. Has no effect when the environment has no developer portal address configured. (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) - `requireSession` (boolean): Close the sessionless route for this page. When `true`, opening the page's own address shows the payer a notice asking for a payment link instead of the payment form, and only a payment session (its short link or its session id) renders the form. `null` or `false` is the default and keeps the page payable on both routes. For a page priced only through payment sessions. Sessions are still created through the API or the back office, and a session against this page resolves and renders as it does for any other page. The flag decides which address renders the form; a locked session amount, not this flag, is what stops a payer changing the price. (nullable) - `billLookupEnabled` (boolean): Offer a bill lookup on the page's own address. When `true` on a page whose purpose is Payment, opening the page's own address asks the payer for a bill number and the `billLookupSecondFactor`, shows the balance due, and sends the payer to that bill's payment link. `null` or `false` is the default and renders the page as before. Available only when bill lookup is enabled for your account; until then the page renders as if the flag were off. A payment link for the page renders the payment form whatever this flag says, because the link already names its bill. (nullable) - `billLookupSecondFactor` ([HppBillLookupSecondFactor](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HppBillLookupSecondFactor.md)): What the payer types beside the bill number when `billLookupEnabled` is `true`: `PostalCode` (the billing postal code on the bill) or `Email` (the address the bill was sent to). Required when `billLookupEnabled` is `true`, because a bill number alone is not enough to show a payer's balance. Required: When BillLookupEnabled is true. (nullable) Values: - `PostalCode`: The billing postal code on the bill. Compared on letters and digits only, ignoring case. - `Email`: The email address the bill was sent to. Compared ignoring case. - `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.signapay-sbx.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. Conditional: When Products is not null. (nullable, max items 50) 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) - `concurrencyStamp` (string): (nullable) _Example: Reset custom fields to all merchant fields_ Sending customFieldNames as null clears any previously configured scope, so the saved page shows every one of the merchant's hosted-page-visible custom fields. Send the concurrencyStamp from your latest read of the page. ```json { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic" } ``` _Example: Scope the page to no custom fields_ Sending customFieldNames as an empty list scopes the saved page to no merchant custom fields at all, so none are rendered or accepted. Send the concurrencyStamp from your latest read of the page. ```json { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [ ] } ``` _Example: Scope the page to selected custom fields_ Sending a populated customFieldNames list replaces any previously configured scope outright, so the saved page shows only the named fields that are still enabled and hosted-page-visible for the merchant. Send the concurrencyStamp from your latest read of the page. ```json { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [ "Purchase Order", "Department" ] } ``` **Content type:** `application/*+json` Schema: [`HostedPaymentPageUpdateDto`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HostedPaymentPageUpdateDto.md) Properties: - `name` (string): (nullable, min length 5, max length 100) - `merchantId` (string(uuid)) required - `isActive` (boolean) - `title` (string): Conditional: When Title is not empty. Min length: 5. (nullable, max length 100) - `bannerImage` (string): Filename of the header banner image to display on the page, as returned by the portal image uploader (for example `3f2a5b90-7c41-4d2e-9f0a-1b8c6d5e4f21.png`). This is not a URL: the public page resolves the filename against the hosted-page image CDN container. Upload the image in the page builder's appearance section, then send the filename it returns. Leave empty for no banner, or set `hideBanner` to suppress an image without discarding it. Validated by `HppImageBlobName`. (nullable) - `hideBanner` (boolean) - `supportRetail` (boolean) - `usePostOnSubmit` (boolean) - `useCaptcha` (boolean) - `supportTokenization` (boolean) - `pageActions` ([HostedPaymentPageActionUrls](https://devportal.signapay-sbx.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.signapay-sbx.winkpg.io/docs/api/models/URLConfig.md)): Gets or sets the URL to use when the payment is submitted. - `edit` ([URLConfig](https://devportal.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.winkpg.io/docs/api/models/HostedPageDonationAmount.md)>): Gets or sets the list of predefined donation amount options. (nullable) - `theme` ([HostedPageTheme](https://devportal.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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. A Classic page reads this flag on its own. A Streamlined page reads it together with `fixedAmount` and `allowCustomAmount`: when `allowCustomAmount` is true the customer can change the amount whatever this flag says, and this flag applies only while the page has no positive `fixedAmount`. The Streamlined builder saves this flag from its Amount and Allow Custom Amount settings: true when the amount is empty or a custom amount is allowed, and false on a card capture page or a page that sells catalog products. A create or update through the API stores the value you send. - `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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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` - `tipPresetPercentages` (array): Gets or sets the tip percentages the payer can choose with one tap, in display order: one to four distinct whole percentages, each 1 to 100. `null` or empty means the single free-entry tip field with no buttons. (nullable) - `defaultTipSelection` ([HppTipPresetDefault](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HppTipPresetDefault.md)): Gets or sets what a page with tip presets selects before the payer chooses. `null` is treated as `NoTip`. (nullable) Values: - `NoTip`: Nothing is preselected: the tip is empty and the custom amount input stays closed until the payer chooses Custom. - `Preset`: One of the presets is preselected, named by defaultTipPercentage, and the tip opens at that percentage of the amount. - `Custom`: Custom is preselected: the custom amount input is open and empty. - `defaultTipPercentage` (integer(int32)): Gets or sets the preset selected by default, as a whole percent (20 means 20%). Required when `defaultTipSelection` is `Preset`, where it must be one of `tipPresetPercentages`, and refused at save otherwise. (nullable) - `fieldPurchaseOrder` ([HppFieldVisibility](https://devportal.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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) - `cardConsentMerchantTerms` (string): Optional per-page merchant terms shown under the card stored-credential consent text when the page saves a card. Plain text: it is HTML-encoded at render, never interpreted as markup. The terms add to the platform consent text and never replace it. A consent captured on the page records a version hash of the terms shown beside the consent text version. (nullable, max length 2000) - `customText` ([HostedPageCustomText](https://devportal.signapay-sbx.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 for the button that submits the payment. Defaults to `Process`. (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) - `isTemplate` (boolean): Deprecated. Templates live in the shared template store, not on the page. During the deprecation window this still drives that store: `true` saves a template from this page (creating the store row, or refreshing the existing one with the page's current values, name and description); `false`, or leaving the field out, removes the template saved from this page, which is what the field always meant on a full-replace update. The page itself is not changed either way. (deprecated) - `templateName` (string): Deprecated. The template's name when `isTemplate` is `true`; the page's own name is used when this is empty. (nullable, deprecated) - `templateDescription` (string): Deprecated. The template's description when `isTemplate` is `true`. (nullable, deprecated) - `shareTemplate` (boolean): Deprecated. Whether the template saved from this page is shared beyond its merchant; written to the store row's published state when `isTemplate` is `true`. (deprecated) - `createdFromTemplateId` (string(uuid)): The template this page is being created from, or `null` for a page started blank. The designers stamp it when Load Template is applied and the create-from-template path sets it server-side; it is recorded on the page and never copied into a template. (nullable) - `pageMode` ([HostedPaymentPageMode](https://devportal.signapay-sbx.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 overwritten from it on every save, so a write here alongside a set visibility is discarded. Write `fieldsAndPanels.fieldContactPhone` instead. (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.signapay-sbx.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. Conditional: When DeclineRetryMode is not null. (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. - `maxFailedAttempts` (integer(int32)): How many declined or refused payments a payment link created against this page accepts before it pauses itself, from 1 to 20. `null` inherits the tenant default, which is no limit unless an administrator set one. (nullable, min 1, max 20) - `requireTermsAcceptance` (boolean): (nullable) - `termsUrl` (string): Conditional: When TermsUrl is not empty. Max length: 500. (nullable) - `callToActionText` (string): Optional wording for the pay button on a Streamlined page, shown followed by the total the payer is charged, for example `Donate $23.45`. On a Streamlined page it takes precedence over `customText.processButtonText`; leave it empty to use that value instead. A Classic page shows `customText.processButtonText`. (nullable, max length 50) - `productName` (string): (nullable, max length 100) - `productDescription` (string): (nullable, max length 500) - `productImageBlobName` (string): Filename of the product image shown in the Streamlined checkout order summary, as returned by the portal image uploader (for example `3f2a5b90-7c41-4d2e-9f0a-1b8c6d5e4f21.png`). Same contract as `bannerImage`: this is not a URL, and the public page resolves the filename against the hosted-page image CDN container. Upload the image in the Streamlined page builder, then send the filename it returns. Leave empty for no product image. Validated by `HppImageBlobName`. (nullable) - `fixedAmount` (number(double)): Conditional: When FixedAmount is not null. Must be >= 0. Conditional: Conditional (see validator source). Conditional: When IsCardCapture(PagePurpose) is true. (nullable) - `allowCustomAmount` (boolean): Conditional: Conditional (see validator source). Conditional: When IsCardCapture(PagePurpose) is true. (nullable) - `successRedirectUrl` (string): Conditional: When SuccessRedirectUrl is not empty. Max length: 500. (nullable) - `successRedirectDelaySeconds` (integer(int32)): How long the hosted confirmation panel is shown, in seconds, before the payer is sent to the configured post-payment address. Accepts 0 to 30; `0` redirects as soon as the panel has rendered. Omit it (or send `null`) to inherit the platform-configured delay, which defaults to 5 seconds. The payer always gets a `Continue now` button that skips the wait. Ignored when no post-payment address is configured, and on an embedded session, which never redirects. (nullable, min 0, max 30) - `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" (the default; existing pages that never set this stay unchanged). An explicit empty list means "no merchant custom fields on this page". A populated list intersects with the enabled / HPP-visible / save-card-purpose gates. This property is full-replace on update: because the update DTO carries the operator's complete selection, sending `null` on a round-trip clears a previously configured list back to the all-fields default, and sending `[]` scopes the page to no custom fields. A client that omits the property on update therefore resets it. The editors always send the operator's actual selection. Conditional: When CustomFieldNames is not null. (nullable, max items 100) - `allowedEmbeddingDomains` (array): (nullable, max items 20) - `checkoutLayout` ([CheckoutLayout](https://devportal.signapay-sbx.winkpg.io/docs/api/models/CheckoutLayout.md)): Conditional: When CheckoutLayout is not null. (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 overwritten from it on every save, so a write here alongside a set visibility is discarded. Write `fieldsAndPanels.fieldLevel3Amount` instead. (nullable) - `pagePurpose` ([HppPagePurpose](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HppPagePurpose.md)): Instance-level page purpose. `null` resolves to `Payment`. `SaveCard` dedicates the page to card capture (zero-dollar verification, no charge). A card-capture page cannot enable amount-bearing settings such as donation amounts or the tax, shipping and convenience fee fields; a request that does is rejected with a validation error. Conditional: Conditional (see validator source). Conditional: When PagePurpose is not null. (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.signapay-sbx.winkpg.io/docs/api/models/HppRecurringPlan.md)): The inlined recurring-schedule definition whose first payment a `SaveCardWithInitialCharge` page charges. Required (validated) when `pagePurpose` is `SaveCardWithInitialCharge`; `null` otherwise. Required: When RequiresRecurringPlan(PagePurpose) is true. Conditional: Conditional (see validator source). Fields: - `recurringAmount` (number(double)): The amount charged on each recurring payment after the initial charge. (greater than 0) - `frequency` ([Frequency](https://devportal.signapay-sbx.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) - `managementUrl` (string): The HTTPS address of a page where the payer can update or cancel this recurring payment. Apple Pay shows it on the recurring payment sheet and requires it on a recurring request, so a plan without one never asks Apple Pay for a merchant token, and Apple Pay is not offered on its sessions. Optional, 200 characters or fewer. Snapshotted onto the session with the rest of the plan, so a payer enrolls under the address that was in effect when their link was created. (nullable, max length 200) - `captureMode` ([HppCaptureMode](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HppCaptureMode.md)): Capture timing for the chargeable Payment flow: `Sale` (default; `null` resolves here) authorizes and captures now; `Authorize` authorizes now and defers capture. Composes with the save-card option to produce the "save card + delayed capture" combination. `Authorize` is rejected on the card-capture page purposes (`SaveCard` and `SaveCardWithInitialCharge`). Conditional: When CaptureMode is not null. Conditional: When IsCardCapture(PagePurpose) is true. (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 this page is rendered inside a merchant iframe, so the merchant's own page shows through behind the payment form. `null`/`false` is the default and keeps the page fully opaque. The transparent render additionally requires that the request is genuinely framed (resolved server-side from the browser-set `Sec-Fetch-Dest` header) and that `allowedEmbeddingDomains` is configured, so it applies only inside the parents the merchant allowlisted. A page opened directly as a standalone payment link always paints its own background. Only the backdrop clears: the payment form keeps its own paint. (nullable) - `allowDeveloperPortalEmbedding` (boolean): Allow the developer portal to embed this page, so a developer can try it in the portal's embed SDK playground without adding the portal's host to `allowedEmbeddingDomains`. `null`/`false` is the default and leaves embedding exactly as the allowlist defines it. When `true`, the developer portal's public origin, as configured for this environment, is accepted as a session's `parentOrigin`, and is added to the page's iframe allowlist when `allowedEmbeddingDomains` is configured. It admits that one origin and no other. A page with no allowed embedding domains can still be framed by any site, as before. Has no effect when the environment has no developer portal address configured. (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) - `requireSession` (boolean): Close the sessionless route for this page. When `true`, opening the page's own address shows the payer a notice asking for a payment link instead of the payment form, and only a payment session (its short link or its session id) renders the form. `null` or `false` is the default and keeps the page payable on both routes. For a page priced only through payment sessions. Sessions are still created through the API or the back office, and a session against this page resolves and renders as it does for any other page. The flag decides which address renders the form; a locked session amount, not this flag, is what stops a payer changing the price. (nullable) - `billLookupEnabled` (boolean): Offer a bill lookup on the page's own address. When `true` on a page whose purpose is Payment, opening the page's own address asks the payer for a bill number and the `billLookupSecondFactor`, shows the balance due, and sends the payer to that bill's payment link. `null` or `false` is the default and renders the page as before. Available only when bill lookup is enabled for your account; until then the page renders as if the flag were off. A payment link for the page renders the payment form whatever this flag says, because the link already names its bill. (nullable) - `billLookupSecondFactor` ([HppBillLookupSecondFactor](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HppBillLookupSecondFactor.md)): What the payer types beside the bill number when `billLookupEnabled` is `true`: `PostalCode` (the billing postal code on the bill) or `Email` (the address the bill was sent to). Required when `billLookupEnabled` is `true`, because a bill number alone is not enough to show a payer's balance. Required: When BillLookupEnabled is true. (nullable) Values: - `PostalCode`: The billing postal code on the bill. Compared on letters and digits only, ignoring case. - `Email`: The email address the bill was sent to. Compared ignoring case. - `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.signapay-sbx.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. Conditional: When Products is not null. (nullable, max items 50) 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) - `concurrencyStamp` (string): (nullable) _Example: Reset custom fields to all merchant fields_ Sending customFieldNames as null clears any previously configured scope, so the saved page shows every one of the merchant's hosted-page-visible custom fields. Send the concurrencyStamp from your latest read of the page. ```json { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic" } ``` _Example: Scope the page to no custom fields_ Sending customFieldNames as an empty list scopes the saved page to no merchant custom fields at all, so none are rendered or accepted. Send the concurrencyStamp from your latest read of the page. ```json { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [ ] } ``` _Example: Scope the page to selected custom fields_ Sending a populated customFieldNames list replaces any previously configured scope outright, so the saved page shows only the named fields that are still enabled and hosted-page-visible for the merchant. Send the concurrencyStamp from your latest read of the page. ```json { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [ "Purchase Order", "Department" ] } ``` ## Responses ### 200 OK **Content type:** `application/json` Schema: [`HostedPaymentPageDto`](https://devportal.signapay-sbx.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.signapay-sbx.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.signapay-sbx.winkpg.io/docs/api/models/URLConfig.md)): Gets or sets the URL to use when the payment is submitted. - `edit` ([URLConfig](https://devportal.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.winkpg.io/docs/api/models/HostedPageDonationAmount.md)>): Gets or sets the list of predefined donation amount options. (nullable) - `theme` ([HostedPageTheme](https://devportal.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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. A Classic page reads this flag on its own. A Streamlined page reads it together with `fixedAmount` and `allowCustomAmount`: when `allowCustomAmount` is true the customer can change the amount whatever this flag says, and this flag applies only while the page has no positive `fixedAmount`. The Streamlined builder saves this flag from its Amount and Allow Custom Amount settings: true when the amount is empty or a custom amount is allowed, and false on a card capture page or a page that sells catalog products. A create or update through the API stores the value you send. - `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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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` - `tipPresetPercentages` (array): Gets or sets the tip percentages the payer can choose with one tap, in display order: one to four distinct whole percentages, each 1 to 100. `null` or empty means the single free-entry tip field with no buttons. (nullable) - `defaultTipSelection` ([HppTipPresetDefault](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HppTipPresetDefault.md)): Gets or sets what a page with tip presets selects before the payer chooses. `null` is treated as `NoTip`. (nullable) Values: - `NoTip`: Nothing is preselected: the tip is empty and the custom amount input stays closed until the payer chooses Custom. - `Preset`: One of the presets is preselected, named by defaultTipPercentage, and the tip opens at that percentage of the amount. - `Custom`: Custom is preselected: the custom amount input is open and empty. - `defaultTipPercentage` (integer(int32)): Gets or sets the preset selected by default, as a whole percent (20 means 20%). Required when `defaultTipSelection` is `Preset`, where it must be one of `tipPresetPercentages`, and refused at save otherwise. (nullable) - `fieldPurchaseOrder` ([HppFieldVisibility](https://devportal.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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) - `cardConsentMerchantTerms` (string): Optional per-page merchant terms shown under the card stored-credential consent text when the page saves a card. Plain text: it is HTML-encoded at render, never interpreted as markup. The terms add to the platform consent text and never replace it. A consent captured on the page records a version hash of the terms shown beside the consent text version. (nullable, max length 2000) - `customText` ([HostedPageCustomText](https://devportal.signapay-sbx.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 for the button that submits the payment. Defaults to `Process`. (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.signapay-sbx.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.signapay-sbx.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. - `maxFailedAttempts` (integer(int32)): How many declined or refused payments a payment link created against this page accepts before it pauses itself, from 1 to 20. `null` inherits the tenant default, which is no limit unless an administrator set one. (nullable) - `requireTermsAcceptance` (boolean): (nullable) - `termsUrl` (string): (nullable) - `callToActionText` (string): Wording for the pay button on a Streamlined page, shown followed by the total the payer is charged. On a Streamlined page it takes precedence over `customText.processButtonText`. (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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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) - `managementUrl` (string): The HTTPS address of a page where the payer can update or cancel this recurring payment. Apple Pay shows it on the recurring payment sheet and requires it on a recurring request, so a plan without one never asks Apple Pay for a merchant token, and Apple Pay is not offered on its sessions. Optional, 200 characters or fewer. Snapshotted onto the session with the rest of the plan, so a payer enrolls under the address that was in effect when their link was created. (nullable, max length 200) - `captureMode` ([HppCaptureMode](https://devportal.signapay-sbx.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) - `requireSession` (boolean): Close the sessionless route for this page. When `true`, opening the page's own address shows the payer a notice asking for a payment link instead of the payment form, and only a payment session (its short link or its session id) renders the form. `null` or `false` is the default and keeps the page payable on both routes. For a page priced only through payment sessions. Sessions are still created through the API or the back office, and a session against this page resolves and renders as it does for any other page. The flag decides which address renders the form; a locked session amount, not this flag, is what stops a payer changing the price. (nullable) - `billLookupEnabled` (boolean): Offer a bill lookup on the page's own address. When `true` on a page whose purpose is Payment, opening the page's own address asks the payer for a bill number and the `billLookupSecondFactor`, shows the balance due, and sends the payer to that bill's payment link. `null` or `false` is the default and renders the page as before. Available only when bill lookup is enabled for your account; until then the page renders as if the flag were off. A payment link for the page renders the payment form whatever this flag says, because the link already names its bill. (nullable) - `billLookupSecondFactor` ([HppBillLookupSecondFactor](https://devportal.signapay-sbx.winkpg.io/docs/api/models/HppBillLookupSecondFactor.md)): What the payer types beside the bill number when `billLookupEnabled` is `true`: `PostalCode` (the billing postal code on the bill) or `Email` (the address the bill was sent to). Required when `billLookupEnabled` is `true`, because a bill number alone is not enough to show a payer's balance. (nullable) Values: - `PostalCode`: The billing postal code on the bill. Compared on letters and digits only, ignoring case. - `Email`: The email address the bill was sent to. Compared ignoring case. - `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.signapay-sbx.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) ### 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.signapay-sbx.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.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 400 Bad request. The request was malformed or failed validation. When validation rejected it, `error.validationErrors` names each member at fault and why. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.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" ] } ] } } ``` ### 401 Unauthorized. The request carried no API key or signed-in session, or the key it carried is invalid, revoked or expired. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 403 Forbidden. The API key lacks the scope this operation needs, the signed-in user lacks the permission, or a business rule refused the request. The error code in the body names the reason. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 404 Not found. The resource the request names does not exist or is not visible to the caller: a resource that belongs to a merchant or tenant outside the caller's scope is reported as not found. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.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 } } ``` ### 409 Conflict. The `concurrencyStamp` sent is not the resource's current one: the resource changed after it was read. Read the resource again and retry with the `concurrencyStamp` it returns. The body carries the standard error envelope. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 500 Internal server error. The platform failed unexpectedly while handling the request. If it keeps failing, contact support and quote the correlation id, which the response carries in the `X-Correlation-Id` header and as `error.data.correlationId`. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 501 Not implemented. The operation is declared but has no implementation on this deployment, so no request to it can succeed. Retrying does not help. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.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.signapay-sbx.winkpg.io/docs/errors.md) lists the values `error.code` can take. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.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 } } ``` ### Errors These statuses answer with the error envelope outlined below. - `400`: Bad request. The request was malformed or failed validation. When validation rejected it, `error.validationErrors` names each member at fault and why. - `401`: Unauthorized. The request carried no API key or signed-in session, or the key it carried is invalid, revoked or expired. - `403`: Forbidden. The API key lacks the scope this operation needs, the signed-in user lacks the permission, or a business rule refused the request. The error code in the body names the reason. - `404`: Not found. The resource the request names does not exist or is not visible to the caller: a resource that belongs to a merchant or tenant outside the caller's scope is reported as not found. - `409`: Conflict. The `concurrencyStamp` sent is not the resource's current one: the resource changed after it was read. Read the resource again and retry with the `concurrencyStamp` it returns. The body carries the standard error envelope. - `500`: Internal server error. The platform failed unexpectedly while handling the request. If it keeps failing, contact support and quote the correlation id, which the response carries in the `X-Correlation-Id` header and as `error.data.correlationId`. - `501`: Not implemented. The operation is declared but has no implementation on this deployment, so no request to it can succeed. Retrying does not help. - `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.signapay-sbx.winkpg.io/docs/errors.md) lists the values `error.code` can take. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) Fields: - `code` (string): (nullable) - `message` (string): (nullable) - `details` (string): (nullable) - `data` (object): (nullable) - `validationErrors` (array<[RemoteServiceValidationErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceValidationErrorInfo.md)>): (nullable) _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" ] } ] } } ``` ## Authentication - `ApiKey` ## 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. The request body is a HostedPaymentPageUpdateDto. See the Request body section below for its fields. These blocks send the Reset custom fields to all merchant fields example. The other examples follow under Other request examples. Sending customFieldNames as null clears any previously configured scope, so the saved page shows every one of the merchant's hosted-page-visible custom fields. Send the concurrencyStamp from your latest read of the page. ### cURL ```bash curl -X PUT "{{BASE_URL}}/api/hostedpaymentpages/{id}" \ -H "api-key: {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic" }' ``` ### PowerShell ```powershell $headers = @{ 'api-key' = '{{API_KEY}}' } $body = @' { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic" } '@ $response = Invoke-RestMethod -Method PUT -Uri '{{BASE_URL}}/api/hostedpaymentpages/{id}' ` -Headers $headers -ContentType 'application/json' -Body $body ``` ### 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.hostedPaymentPagesUpdate("3fa85f64-5717-4562-b3fc-2c963f66afa6", { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic" }); ``` ### TypeScript (raw HTTP) ```typescript const response = await fetch('{{BASE_URL}}/api/hostedpaymentpages/{id}', { method: 'PUT', headers: { "api-key": "{{API_KEY}}", "Content-Type": "application/json", }, body: JSON.stringify({ "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic" }), }); 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; using System.Text.Json; var config = new Configuration { BasePath = "{{BASE_URL}}" }; config.AddApiKey("api-key", "{{API_KEY}}"); var api = new HostedPaymentPagesApi(config); var body = JsonSerializer.Deserialize(""" { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic" } """); var result = await api.HostedPaymentPagesUpdateAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"), body); ``` ### C# (raw HTTP) ```csharp using System.Text; using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") }; var request = new HttpRequestMessage(new HttpMethod("PUT"), "/api/hostedpaymentpages/{id}"); request.Headers.Add("api-key", "{{API_KEY}}"); request.Content = new StringContent(""" { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic" } """, Encoding.UTF8, "application/json"); 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) body = winkpg_api.HostedPaymentPageUpdateDto.from_dict({ "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": True, "title": "Pay Acme Corp", "supportTokenization": True, "pageMode": "Classic" }) result = api.hosted_payment_pages_update("3fa85f64-5717-4562-b3fc-2c963f66afa6", body) ``` ### Python (raw HTTP) ```bash pip install requests ``` ```python import requests headers = { "api-key": "{{API_KEY}}", "Content-Type": "application/json", } body = { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": True, "title": "Pay Acme Corp", "supportTokenization": True, "pageMode": "Classic" } response = requests.request( "PUT", "{{BASE_URL}}/api/hostedpaymentpages/{id}", headers=headers, json=body, ) response.raise_for_status() data = response.json() ``` ## Other request examples Each example below is one request, shown in every language with the same placeholders. ### Scope the page to no custom fields Sending customFieldNames as an empty list scopes the saved page to no merchant custom fields at all, so none are rendered or accepted. Send the concurrencyStamp from your latest read of the page. #### cURL ```bash curl -X PUT "{{BASE_URL}}/api/hostedpaymentpages/{id}" \ -H "api-key: {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [] }' ``` #### PowerShell ```powershell $headers = @{ 'api-key' = '{{API_KEY}}' } $body = @' { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [] } '@ $response = Invoke-RestMethod -Method PUT -Uri '{{BASE_URL}}/api/hostedpaymentpages/{id}' ` -Headers $headers -ContentType 'application/json' -Body $body ``` #### 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.hostedPaymentPagesUpdate("3fa85f64-5717-4562-b3fc-2c963f66afa6", { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [] }); ``` #### TypeScript (raw HTTP) ```typescript const response = await fetch('{{BASE_URL}}/api/hostedpaymentpages/{id}', { method: 'PUT', headers: { "api-key": "{{API_KEY}}", "Content-Type": "application/json", }, body: JSON.stringify({ "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [] }), }); 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; using System.Text.Json; var config = new Configuration { BasePath = "{{BASE_URL}}" }; config.AddApiKey("api-key", "{{API_KEY}}"); var api = new HostedPaymentPagesApi(config); var body = JsonSerializer.Deserialize(""" { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [] } """); var result = await api.HostedPaymentPagesUpdateAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"), body); ``` #### C# (raw HTTP) ```csharp using System.Text; using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") }; var request = new HttpRequestMessage(new HttpMethod("PUT"), "/api/hostedpaymentpages/{id}"); request.Headers.Add("api-key", "{{API_KEY}}"); request.Content = new StringContent(""" { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [] } """, Encoding.UTF8, "application/json"); 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) body = winkpg_api.HostedPaymentPageUpdateDto.from_dict({ "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": True, "title": "Pay Acme Corp", "supportTokenization": True, "pageMode": "Classic", "customFieldNames": [] }) result = api.hosted_payment_pages_update("3fa85f64-5717-4562-b3fc-2c963f66afa6", body) ``` #### Python (raw HTTP) ```bash pip install requests ``` ```python import requests headers = { "api-key": "{{API_KEY}}", "Content-Type": "application/json", } body = { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": True, "title": "Pay Acme Corp", "supportTokenization": True, "pageMode": "Classic", "customFieldNames": [] } response = requests.request( "PUT", "{{BASE_URL}}/api/hostedpaymentpages/{id}", headers=headers, json=body, ) response.raise_for_status() data = response.json() ``` ### Scope the page to selected custom fields Sending a populated customFieldNames list replaces any previously configured scope outright, so the saved page shows only the named fields that are still enabled and hosted-page-visible for the merchant. Send the concurrencyStamp from your latest read of the page. #### cURL ```bash curl -X PUT "{{BASE_URL}}/api/hostedpaymentpages/{id}" \ -H "api-key: {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [ "Purchase Order", "Department" ] }' ``` #### PowerShell ```powershell $headers = @{ 'api-key' = '{{API_KEY}}' } $body = @' { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [ "Purchase Order", "Department" ] } '@ $response = Invoke-RestMethod -Method PUT -Uri '{{BASE_URL}}/api/hostedpaymentpages/{id}' ` -Headers $headers -ContentType 'application/json' -Body $body ``` #### 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.hostedPaymentPagesUpdate("3fa85f64-5717-4562-b3fc-2c963f66afa6", { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [ "Purchase Order", "Department" ] }); ``` #### TypeScript (raw HTTP) ```typescript const response = await fetch('{{BASE_URL}}/api/hostedpaymentpages/{id}', { method: 'PUT', headers: { "api-key": "{{API_KEY}}", "Content-Type": "application/json", }, body: JSON.stringify({ "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [ "Purchase Order", "Department" ] }), }); 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; using System.Text.Json; var config = new Configuration { BasePath = "{{BASE_URL}}" }; config.AddApiKey("api-key", "{{API_KEY}}"); var api = new HostedPaymentPagesApi(config); var body = JsonSerializer.Deserialize(""" { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [ "Purchase Order", "Department" ] } """); var result = await api.HostedPaymentPagesUpdateAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"), body); ``` #### C# (raw HTTP) ```csharp using System.Text; using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") }; var request = new HttpRequestMessage(new HttpMethod("PUT"), "/api/hostedpaymentpages/{id}"); request.Headers.Add("api-key", "{{API_KEY}}"); request.Content = new StringContent(""" { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "supportTokenization": true, "pageMode": "Classic", "customFieldNames": [ "Purchase Order", "Department" ] } """, Encoding.UTF8, "application/json"); 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) body = winkpg_api.HostedPaymentPageUpdateDto.from_dict({ "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": True, "title": "Pay Acme Corp", "supportTokenization": True, "pageMode": "Classic", "customFieldNames": [ "Purchase Order", "Department" ] }) result = api.hosted_payment_pages_update("3fa85f64-5717-4562-b3fc-2c963f66afa6", body) ``` #### Python (raw HTTP) ```bash pip install requests ``` ```python import requests headers = { "api-key": "{{API_KEY}}", "Content-Type": "application/json", } body = { "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f", "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": True, "title": "Pay Acme Corp", "supportTokenization": True, "pageMode": "Classic", "customFieldNames": [ "Purchase Order", "Department" ] } response = requests.request( "PUT", "{{BASE_URL}}/api/hostedpaymentpages/{id}", headers=headers, json=body, ) response.raise_for_status() data = response.json() ``` ## See also - [All documentation](https://devportal.signapay-sbx.winkpg.io/llms.txt): the machine-readable index of every public page on this site.