# POST /api/hostedpaymentpages Create hosted payment page Creates a new hosted payment page for customer checkout. **Operation ID:** `hostedPaymentPagesCreate` ## Authorization Requires: HostedPaymentPage.HostedPaymentPages, HostedPaymentPage.HostedPaymentPages.Create, merchant scope. Required permissions: - `HostedPaymentPage.HostedPaymentPages` - `HostedPaymentPage.HostedPaymentPages.Create` ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | suppressNulls | query | no | boolean | If true, omit properties with null values. | ## Request Body **Content type:** `application/json` Schema: `HostedPaymentPageCreateDto` Properties: - `name` (string) - `merchantId` (string(uuid)) required - `isActive` (boolean) - `title` (string): Conditional: When Title is not empty. Min length: 5. - `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`. - `hideBanner` (boolean) - `supportRetail` (boolean) - `usePostOnSubmit` (boolean) - `useCaptcha` (boolean) - `supportTokenization` (boolean) - `pageActions` (HostedPaymentPageActionUrls): Represents the set of action URLs for the hosted payment page, including submit, edit, continue, and cancel (Back) actions. - `donations` (HostedPageDonations): Represents donation configuration for the hosted payment page, including enablement and predefined amounts. - `theme` (HostedPageTheme): Represents theme settings for the hosted payment page, including colors, fonts, and header styles. - `fieldsAndPanels` (HostedPageFieldsAndPanels): Represents the configuration of fields and panels for the hosted payment page, including display options and custom labels. - `receiptAndNotifications` (HostedPageReceipts): Represents receipt and notification settings for the hosted payment page, including callback URLs, email options, and notification recipients. - `disclosures` (HostedPageDisclosures): Represents disclosure information for a hosted payment page, including display and acceptance requirements. - `customText` (HostedPageCustomText): Represents custom text and links for a hosted payment page, including terms, promo, support, and privacy policy. - `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. - `templateName` (string): Deprecated. The template's name when `isTemplate` is `true`; the page's own name is used when this is empty. - `templateDescription` (string): Deprecated. The template's description when `isTemplate` is `true`. - `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`. - `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. - `pageMode` (object) - `collectBusinessName` (boolean) - `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. - `allowPromoCodes` (boolean) - `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. - `savePaymentDetails` (boolean) - `declineRetryMode` (object): 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. - `requireTermsAcceptance` (boolean) - `termsUrl` (string): Conditional: When TermsUrl is not empty. Max length: 500. - `callToActionText` (string) - `productName` (string) - `productDescription` (string) - `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`. - `fixedAmount` (number(double)): Conditional: When FixedAmount is not null. Must be >= 0. Conditional: Conditional (see validator source). Conditional: When IsCardCapture(PagePurpose) is true. - `allowCustomAmount` (boolean): Conditional: Conditional (see validator source). Conditional: When IsCardCapture(PagePurpose) is true. - `successRedirectUrl` (string): Conditional: When SuccessRedirectUrl is not empty. Max length: 500. - `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. - `paymentMethods` (array) - `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. - `allowedEmbeddingDomains` (array) - `checkoutLayout` (object): Conditional: When CheckoutLayout is not null. - `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. - `pagePurpose` (object): 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. - `recurringPlan` (object): 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). - `captureMode` (object): 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. - `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. - `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). - `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. - `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. - `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. - `products` (array): 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. _Example: Classic Mode (full configuration)_ The original full-control hosted payment page builder with accordion-style configuration sections. Use this when you need fine-grained control over which fields are shown, theme/branding, donations, custom text, and disclosures. ```json { "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "useCaptcha": true, "supportTokenization": true, "pageActions": { "submit": { "url": "https://acme.example.com/checkout/submit", "enabled": true, "label": "Pay Now" }, "edit": { "url": "https://acme.example.com/cart", "enabled": true, "label": "Edit Cart" }, "continue": { "url": "https://acme.example.com/thank-you", "enabled": true, "label": "Continue" } }, "theme": { "panelBackColor": "#ffffff", "panelBorderColor": "#e0e0e0", "buttonColor": "#0066cc", "buttonBorderColor": "#0066cc", "inputFieldBorderColor": "#cccccc", "inputFieldBackgroundColor": "#ffffff", "inputFieldFontColor": "#333333", "inputFieldBackgroundFocusColor": "#f0f8ff", "backColor": "#fafafa", "fontColor": "#333333", "font": "Inter, sans-serif", "headerFont": "Inter, sans-serif", "headerFontColor": "#111111", "headerBackColor": "#ffffff", "headerBorderColor": "#e0e0e0", "customCSS": "" }, "fieldsAndPanels": { "fieldInvoice": "Required", "fieldTax": "Required", "fieldConvenienceFee": "Hidden", "fieldShipping": "Required", "fieldTotal": true, "fieldBillingAddr": "Required", "fieldShipAddr": "Required", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Summary", "customizeOrderPanelText": true, "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result", "fieldTip": "Optional" }, "receiptAndNotifications": { "callbackUrl": "https://acme.example.com/webhooks/hpp", "enableWebhookNotification": true, "enableCustomerEmail": true, "useHostedConfirm": true }, "disclosures": { "disclosureText": "By clicking Place Order you agree to Acme's Terms of Service.", "showDisclosures": true, "requireDisclosureAccept": true }, "customText": { "termsAndConditionsLink": "https://acme.example.com/terms", "processButtonText": "Place Order", "headerText": "Secure Checkout", "supportLink": "https://acme.example.com/support", "poweredByText": "Powered by Acme", "copyrightText": "© 2026 Acme Corp", "privacyPolicyLink": "https://acme.example.com/privacy" }, "pageMode": "Classic" } ``` _Example: Streamlined Mode (Stripe-style)_ Simplified Stripe-inspired checkout with a clean two-column layout, fixed product, and minimum chrome. Designed to be embedded in an iframe on the merchant's site - configure AllowedEmbeddingDomains. ```json { "name": "Annual Membership Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Annual Membership", "supportTokenization": true, "receiptAndNotifications": { "enableCustomerEmail": true }, "pageMode": "Streamlined", "collectPhone": false, "allowPromoCodes": true, "savePaymentDetails": true, "requireTermsAcceptance": true, "termsUrl": "https://acme.example.com/terms", "callToActionText": "Subscribe", "productName": "Annual Membership", "productDescription": "12 months of full access to all member benefits.", "fixedAmount": 99, "allowCustomAmount": false, "successRedirectUrl": "https://acme.example.com/welcome", "paymentMethods": [ "card" ], "allowedEmbeddingDomains": [ "acme.example.com", "*.acme.example.com" ], "checkoutLayout": "Standard" } ``` _Example: Save Card page (store a card, no charge)_ A dedicated card-capture page: the customer's card is validated with a zero-dollar account verification (authorize $0 with AVS/CVV, immediate void), vaulted as a reusable payment token, and stored-credential consent is captured. No charge is taken, so amount-bearing configuration (tax, tip, shipping, convenience fee, invoice amounts, donations) must stay hidden/off. Requires the merchant's processor to support zero-dollar verification. ```json { "name": "Add Payment Method", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Save Your Card", "supportTokenization": true, "fieldsAndPanels": { "fieldInvoice": "Hidden", "fieldTax": "Hidden", "fieldConvenienceFee": "Hidden", "fieldShipping": "Hidden", "fieldTotal": true, "fieldBillingAddr": "Hidden", "fieldShipAddr": "Hidden", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Details", "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result" }, "receiptAndNotifications": { "enableCustomerEmail": true }, "pageMode": "Streamlined", "savePaymentDetails": true, "callToActionText": "Save Card", "productName": "Card on File", "productDescription": "Securely save a card for future purchases. You will not be charged today.", "paymentMethods": [ "card" ], "checkoutLayout": "Compact", "pagePurpose": "SaveCard" } ``` _Example: Save Card with Initial Charge (subscription enrollment)_ A card-capture page that also charges the first payment of an inlined recurring plan as a real sale, vaults the card with Recurring stored-credential consent, and creates a contract for the remaining payments. The charged amount comes entirely from the recurring plan, so the page's amount-bearing fields stay hidden. The plan needs complete economics: a positive recurring amount, an interval of at least 1, and at least two total payments; initialChargeAmount optionally overrides payment one (for example a bundled setup fee). The page must accept card only. ```json { "name": "Gold Plan Enrollment", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Join the Gold Plan", "supportTokenization": true, "fieldsAndPanels": { "fieldInvoice": "Hidden", "fieldTax": "Hidden", "fieldConvenienceFee": "Hidden", "fieldShipping": "Hidden", "fieldTotal": true, "fieldBillingAddr": "Hidden", "fieldShipAddr": "Hidden", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Details", "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result" }, "receiptAndNotifications": { "enableCustomerEmail": true }, "pageMode": "Streamlined", "savePaymentDetails": true, "callToActionText": "Enroll", "productName": "Gold Plan", "productDescription": "$49.99 today, then $29.99 per month for 11 more payments.", "paymentMethods": [ "card" ], "checkoutLayout": "Standard", "pagePurpose": "SaveCardWithInitialCharge", "recurringPlan": { "recurringAmount": 29.99, "frequency": "Monthly", "interval": 1, "numberOfPayments": 12, "initialChargeAmount": 49.99 } } ``` _Example: Embedded page with no heading chrome_ A Streamlined page embedded inside the merchant's own checkout, where the surrounding site already shows the branding. HideTitle suppresses the page heading and HideMerchantName suppresses the business-name line in the page header, so the payment form sits flush against the host page. Both default to false, so omitting them keeps the existing look. HideLoadingIndicator suppresses the gateway's own loading chrome as well, for an embedding page that paints its own loading state and reveals the frame when the ready event arrives; it too defaults to false. Title is optional and may be sent empty; when you do supply it, it must be 5-100 characters. Hiding these display slots never changes the merchant named on the Apple Pay or Paze payment sheet, or in the bank-account authorization text. ```json { "name": "Embedded Checkout (chrome-free)", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "", "supportTokenization": true, "receiptAndNotifications": { "enableCustomerEmail": true }, "pageMode": "Streamlined", "callToActionText": "Pay", "productName": "Order Total", "paymentMethods": [ "card" ], "allowedEmbeddingDomains": [ "acme.example.com", "*.acme.example.com" ], "checkoutLayout": "Embedded", "allowTransparentEmbedding": true, "hideTitle": true, "hideMerchantName": true, "hideLoadingIndicator": true } ``` _Example: Streamlined page selling catalog products_ A page priced from the merchant's invoicing product catalog rather than a single amount. Each entry names a catalog product the merchant owns (active, and priced in the merchant's currency) with the page's own presentation rules: display order, whether the customer may leave it out (isOptional), whether they may change the quantity (allowQuantityChange), the quantity the page starts at, and optional page-level quantity limits that only narrow the catalog's own. The customer picks quantities on the page; the total is computed on the server at the catalog prices in force when each payment link is created, and the customer cannot edit it. A page that sells products carries no fixedAmount, no allowCustomAmount and no donation amounts. ```json { "name": "Field Guide Shop", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Field Guide Shop", "fieldsAndPanels": { "fieldInvoice": "Hidden", "fieldTax": "Hidden", "fieldConvenienceFee": "Hidden", "fieldShipping": "Hidden", "fieldTotal": true, "fieldBillingAddr": "Hidden", "fieldShipAddr": "Hidden", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Details", "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result" }, "receiptAndNotifications": { "enableCustomerEmail": true }, "pageMode": "Streamlined", "callToActionText": "Buy", "paymentMethods": [ "card" ], "products": [ { "productId": "00000000-0000-0000-0000-00000000000c", "allowQuantityChange": true, "defaultQuantity": 1, "maximumQuantity": 10 }, { "productId": "00000000-0000-0000-0000-00000000000d", "displayOrder": 1, "isOptional": true, "defaultQuantity": 1 } ] } ``` **Content type:** `text/json` Schema: `HostedPaymentPageCreateDto` Properties: - `name` (string) - `merchantId` (string(uuid)) required - `isActive` (boolean) - `title` (string): Conditional: When Title is not empty. Min length: 5. - `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`. - `hideBanner` (boolean) - `supportRetail` (boolean) - `usePostOnSubmit` (boolean) - `useCaptcha` (boolean) - `supportTokenization` (boolean) - `pageActions` (HostedPaymentPageActionUrls): Represents the set of action URLs for the hosted payment page, including submit, edit, continue, and cancel (Back) actions. - `donations` (HostedPageDonations): Represents donation configuration for the hosted payment page, including enablement and predefined amounts. - `theme` (HostedPageTheme): Represents theme settings for the hosted payment page, including colors, fonts, and header styles. - `fieldsAndPanels` (HostedPageFieldsAndPanels): Represents the configuration of fields and panels for the hosted payment page, including display options and custom labels. - `receiptAndNotifications` (HostedPageReceipts): Represents receipt and notification settings for the hosted payment page, including callback URLs, email options, and notification recipients. - `disclosures` (HostedPageDisclosures): Represents disclosure information for a hosted payment page, including display and acceptance requirements. - `customText` (HostedPageCustomText): Represents custom text and links for a hosted payment page, including terms, promo, support, and privacy policy. - `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. - `templateName` (string): Deprecated. The template's name when `isTemplate` is `true`; the page's own name is used when this is empty. - `templateDescription` (string): Deprecated. The template's description when `isTemplate` is `true`. - `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`. - `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. - `pageMode` (object) - `collectBusinessName` (boolean) - `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. - `allowPromoCodes` (boolean) - `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. - `savePaymentDetails` (boolean) - `declineRetryMode` (object): 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. - `requireTermsAcceptance` (boolean) - `termsUrl` (string): Conditional: When TermsUrl is not empty. Max length: 500. - `callToActionText` (string) - `productName` (string) - `productDescription` (string) - `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`. - `fixedAmount` (number(double)): Conditional: When FixedAmount is not null. Must be >= 0. Conditional: Conditional (see validator source). Conditional: When IsCardCapture(PagePurpose) is true. - `allowCustomAmount` (boolean): Conditional: Conditional (see validator source). Conditional: When IsCardCapture(PagePurpose) is true. - `successRedirectUrl` (string): Conditional: When SuccessRedirectUrl is not empty. Max length: 500. - `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. - `paymentMethods` (array) - `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. - `allowedEmbeddingDomains` (array) - `checkoutLayout` (object): Conditional: When CheckoutLayout is not null. - `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. - `pagePurpose` (object): 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. - `recurringPlan` (object): 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). - `captureMode` (object): 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. - `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. - `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). - `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. - `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. - `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. - `products` (array): 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. _Example: Classic Mode (full configuration)_ The original full-control hosted payment page builder with accordion-style configuration sections. Use this when you need fine-grained control over which fields are shown, theme/branding, donations, custom text, and disclosures. ```json { "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "useCaptcha": true, "supportTokenization": true, "pageActions": { "submit": { "url": "https://acme.example.com/checkout/submit", "enabled": true, "label": "Pay Now" }, "edit": { "url": "https://acme.example.com/cart", "enabled": true, "label": "Edit Cart" }, "continue": { "url": "https://acme.example.com/thank-you", "enabled": true, "label": "Continue" } }, "theme": { "panelBackColor": "#ffffff", "panelBorderColor": "#e0e0e0", "buttonColor": "#0066cc", "buttonBorderColor": "#0066cc", "inputFieldBorderColor": "#cccccc", "inputFieldBackgroundColor": "#ffffff", "inputFieldFontColor": "#333333", "inputFieldBackgroundFocusColor": "#f0f8ff", "backColor": "#fafafa", "fontColor": "#333333", "font": "Inter, sans-serif", "headerFont": "Inter, sans-serif", "headerFontColor": "#111111", "headerBackColor": "#ffffff", "headerBorderColor": "#e0e0e0", "customCSS": "" }, "fieldsAndPanels": { "fieldInvoice": "Required", "fieldTax": "Required", "fieldConvenienceFee": "Hidden", "fieldShipping": "Required", "fieldTotal": true, "fieldBillingAddr": "Required", "fieldShipAddr": "Required", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Summary", "customizeOrderPanelText": true, "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result", "fieldTip": "Optional" }, "receiptAndNotifications": { "callbackUrl": "https://acme.example.com/webhooks/hpp", "enableWebhookNotification": true, "enableCustomerEmail": true, "useHostedConfirm": true }, "disclosures": { "disclosureText": "By clicking Place Order you agree to Acme's Terms of Service.", "showDisclosures": true, "requireDisclosureAccept": true }, "customText": { "termsAndConditionsLink": "https://acme.example.com/terms", "processButtonText": "Place Order", "headerText": "Secure Checkout", "supportLink": "https://acme.example.com/support", "poweredByText": "Powered by Acme", "copyrightText": "© 2026 Acme Corp", "privacyPolicyLink": "https://acme.example.com/privacy" }, "pageMode": "Classic" } ``` _Example: Streamlined Mode (Stripe-style)_ Simplified Stripe-inspired checkout with a clean two-column layout, fixed product, and minimum chrome. Designed to be embedded in an iframe on the merchant's site - configure AllowedEmbeddingDomains. ```json { "name": "Annual Membership Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Annual Membership", "supportTokenization": true, "receiptAndNotifications": { "enableCustomerEmail": true }, "pageMode": "Streamlined", "collectPhone": false, "allowPromoCodes": true, "savePaymentDetails": true, "requireTermsAcceptance": true, "termsUrl": "https://acme.example.com/terms", "callToActionText": "Subscribe", "productName": "Annual Membership", "productDescription": "12 months of full access to all member benefits.", "fixedAmount": 99, "allowCustomAmount": false, "successRedirectUrl": "https://acme.example.com/welcome", "paymentMethods": [ "card" ], "allowedEmbeddingDomains": [ "acme.example.com", "*.acme.example.com" ], "checkoutLayout": "Standard" } ``` _Example: Save Card page (store a card, no charge)_ A dedicated card-capture page: the customer's card is validated with a zero-dollar account verification (authorize $0 with AVS/CVV, immediate void), vaulted as a reusable payment token, and stored-credential consent is captured. No charge is taken, so amount-bearing configuration (tax, tip, shipping, convenience fee, invoice amounts, donations) must stay hidden/off. Requires the merchant's processor to support zero-dollar verification. ```json { "name": "Add Payment Method", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Save Your Card", "supportTokenization": true, "fieldsAndPanels": { "fieldInvoice": "Hidden", "fieldTax": "Hidden", "fieldConvenienceFee": "Hidden", "fieldShipping": "Hidden", "fieldTotal": true, "fieldBillingAddr": "Hidden", "fieldShipAddr": "Hidden", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Details", "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result" }, "receiptAndNotifications": { "enableCustomerEmail": true }, "pageMode": "Streamlined", "savePaymentDetails": true, "callToActionText": "Save Card", "productName": "Card on File", "productDescription": "Securely save a card for future purchases. You will not be charged today.", "paymentMethods": [ "card" ], "checkoutLayout": "Compact", "pagePurpose": "SaveCard" } ``` _Example: Save Card with Initial Charge (subscription enrollment)_ A card-capture page that also charges the first payment of an inlined recurring plan as a real sale, vaults the card with Recurring stored-credential consent, and creates a contract for the remaining payments. The charged amount comes entirely from the recurring plan, so the page's amount-bearing fields stay hidden. The plan needs complete economics: a positive recurring amount, an interval of at least 1, and at least two total payments; initialChargeAmount optionally overrides payment one (for example a bundled setup fee). The page must accept card only. ```json { "name": "Gold Plan Enrollment", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Join the Gold Plan", "supportTokenization": true, "fieldsAndPanels": { "fieldInvoice": "Hidden", "fieldTax": "Hidden", "fieldConvenienceFee": "Hidden", "fieldShipping": "Hidden", "fieldTotal": true, "fieldBillingAddr": "Hidden", "fieldShipAddr": "Hidden", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Details", "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result" }, "receiptAndNotifications": { "enableCustomerEmail": true }, "pageMode": "Streamlined", "savePaymentDetails": true, "callToActionText": "Enroll", "productName": "Gold Plan", "productDescription": "$49.99 today, then $29.99 per month for 11 more payments.", "paymentMethods": [ "card" ], "checkoutLayout": "Standard", "pagePurpose": "SaveCardWithInitialCharge", "recurringPlan": { "recurringAmount": 29.99, "frequency": "Monthly", "interval": 1, "numberOfPayments": 12, "initialChargeAmount": 49.99 } } ``` _Example: Embedded page with no heading chrome_ A Streamlined page embedded inside the merchant's own checkout, where the surrounding site already shows the branding. HideTitle suppresses the page heading and HideMerchantName suppresses the business-name line in the page header, so the payment form sits flush against the host page. Both default to false, so omitting them keeps the existing look. HideLoadingIndicator suppresses the gateway's own loading chrome as well, for an embedding page that paints its own loading state and reveals the frame when the ready event arrives; it too defaults to false. Title is optional and may be sent empty; when you do supply it, it must be 5-100 characters. Hiding these display slots never changes the merchant named on the Apple Pay or Paze payment sheet, or in the bank-account authorization text. ```json { "name": "Embedded Checkout (chrome-free)", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "", "supportTokenization": true, "receiptAndNotifications": { "enableCustomerEmail": true }, "pageMode": "Streamlined", "callToActionText": "Pay", "productName": "Order Total", "paymentMethods": [ "card" ], "allowedEmbeddingDomains": [ "acme.example.com", "*.acme.example.com" ], "checkoutLayout": "Embedded", "allowTransparentEmbedding": true, "hideTitle": true, "hideMerchantName": true, "hideLoadingIndicator": true } ``` _Example: Streamlined page selling catalog products_ A page priced from the merchant's invoicing product catalog rather than a single amount. Each entry names a catalog product the merchant owns (active, and priced in the merchant's currency) with the page's own presentation rules: display order, whether the customer may leave it out (isOptional), whether they may change the quantity (allowQuantityChange), the quantity the page starts at, and optional page-level quantity limits that only narrow the catalog's own. The customer picks quantities on the page; the total is computed on the server at the catalog prices in force when each payment link is created, and the customer cannot edit it. A page that sells products carries no fixedAmount, no allowCustomAmount and no donation amounts. ```json { "name": "Field Guide Shop", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Field Guide Shop", "fieldsAndPanels": { "fieldInvoice": "Hidden", "fieldTax": "Hidden", "fieldConvenienceFee": "Hidden", "fieldShipping": "Hidden", "fieldTotal": true, "fieldBillingAddr": "Hidden", "fieldShipAddr": "Hidden", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Details", "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result" }, "receiptAndNotifications": { "enableCustomerEmail": true }, "pageMode": "Streamlined", "callToActionText": "Buy", "paymentMethods": [ "card" ], "products": [ { "productId": "00000000-0000-0000-0000-00000000000c", "allowQuantityChange": true, "defaultQuantity": 1, "maximumQuantity": 10 }, { "productId": "00000000-0000-0000-0000-00000000000d", "displayOrder": 1, "isOptional": true, "defaultQuantity": 1 } ] } ``` **Content type:** `application/*+json` Schema: `HostedPaymentPageCreateDto` Properties: - `name` (string) - `merchantId` (string(uuid)) required - `isActive` (boolean) - `title` (string): Conditional: When Title is not empty. Min length: 5. - `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`. - `hideBanner` (boolean) - `supportRetail` (boolean) - `usePostOnSubmit` (boolean) - `useCaptcha` (boolean) - `supportTokenization` (boolean) - `pageActions` (HostedPaymentPageActionUrls): Represents the set of action URLs for the hosted payment page, including submit, edit, continue, and cancel (Back) actions. - `donations` (HostedPageDonations): Represents donation configuration for the hosted payment page, including enablement and predefined amounts. - `theme` (HostedPageTheme): Represents theme settings for the hosted payment page, including colors, fonts, and header styles. - `fieldsAndPanels` (HostedPageFieldsAndPanels): Represents the configuration of fields and panels for the hosted payment page, including display options and custom labels. - `receiptAndNotifications` (HostedPageReceipts): Represents receipt and notification settings for the hosted payment page, including callback URLs, email options, and notification recipients. - `disclosures` (HostedPageDisclosures): Represents disclosure information for a hosted payment page, including display and acceptance requirements. - `customText` (HostedPageCustomText): Represents custom text and links for a hosted payment page, including terms, promo, support, and privacy policy. - `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. - `templateName` (string): Deprecated. The template's name when `isTemplate` is `true`; the page's own name is used when this is empty. - `templateDescription` (string): Deprecated. The template's description when `isTemplate` is `true`. - `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`. - `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. - `pageMode` (object) - `collectBusinessName` (boolean) - `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. - `allowPromoCodes` (boolean) - `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. - `savePaymentDetails` (boolean) - `declineRetryMode` (object): 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. - `requireTermsAcceptance` (boolean) - `termsUrl` (string): Conditional: When TermsUrl is not empty. Max length: 500. - `callToActionText` (string) - `productName` (string) - `productDescription` (string) - `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`. - `fixedAmount` (number(double)): Conditional: When FixedAmount is not null. Must be >= 0. Conditional: Conditional (see validator source). Conditional: When IsCardCapture(PagePurpose) is true. - `allowCustomAmount` (boolean): Conditional: Conditional (see validator source). Conditional: When IsCardCapture(PagePurpose) is true. - `successRedirectUrl` (string): Conditional: When SuccessRedirectUrl is not empty. Max length: 500. - `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. - `paymentMethods` (array) - `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. - `allowedEmbeddingDomains` (array) - `checkoutLayout` (object): Conditional: When CheckoutLayout is not null. - `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. - `pagePurpose` (object): 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. - `recurringPlan` (object): 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). - `captureMode` (object): 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. - `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. - `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). - `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. - `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. - `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. - `products` (array): 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. _Example: Classic Mode (full configuration)_ The original full-control hosted payment page builder with accordion-style configuration sections. Use this when you need fine-grained control over which fields are shown, theme/branding, donations, custom text, and disclosures. ```json { "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "useCaptcha": true, "supportTokenization": true, "pageActions": { "submit": { "url": "https://acme.example.com/checkout/submit", "enabled": true, "label": "Pay Now" }, "edit": { "url": "https://acme.example.com/cart", "enabled": true, "label": "Edit Cart" }, "continue": { "url": "https://acme.example.com/thank-you", "enabled": true, "label": "Continue" } }, "theme": { "panelBackColor": "#ffffff", "panelBorderColor": "#e0e0e0", "buttonColor": "#0066cc", "buttonBorderColor": "#0066cc", "inputFieldBorderColor": "#cccccc", "inputFieldBackgroundColor": "#ffffff", "inputFieldFontColor": "#333333", "inputFieldBackgroundFocusColor": "#f0f8ff", "backColor": "#fafafa", "fontColor": "#333333", "font": "Inter, sans-serif", "headerFont": "Inter, sans-serif", "headerFontColor": "#111111", "headerBackColor": "#ffffff", "headerBorderColor": "#e0e0e0", "customCSS": "" }, "fieldsAndPanels": { "fieldInvoice": "Required", "fieldTax": "Required", "fieldConvenienceFee": "Hidden", "fieldShipping": "Required", "fieldTotal": true, "fieldBillingAddr": "Required", "fieldShipAddr": "Required", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Summary", "customizeOrderPanelText": true, "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result", "fieldTip": "Optional" }, "receiptAndNotifications": { "callbackUrl": "https://acme.example.com/webhooks/hpp", "enableWebhookNotification": true, "enableCustomerEmail": true, "useHostedConfirm": true }, "disclosures": { "disclosureText": "By clicking Place Order you agree to Acme's Terms of Service.", "showDisclosures": true, "requireDisclosureAccept": true }, "customText": { "termsAndConditionsLink": "https://acme.example.com/terms", "processButtonText": "Place Order", "headerText": "Secure Checkout", "supportLink": "https://acme.example.com/support", "poweredByText": "Powered by Acme", "copyrightText": "© 2026 Acme Corp", "privacyPolicyLink": "https://acme.example.com/privacy" }, "pageMode": "Classic" } ``` _Example: Streamlined Mode (Stripe-style)_ Simplified Stripe-inspired checkout with a clean two-column layout, fixed product, and minimum chrome. Designed to be embedded in an iframe on the merchant's site - configure AllowedEmbeddingDomains. ```json { "name": "Annual Membership Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Annual Membership", "supportTokenization": true, "receiptAndNotifications": { "enableCustomerEmail": true }, "pageMode": "Streamlined", "collectPhone": false, "allowPromoCodes": true, "savePaymentDetails": true, "requireTermsAcceptance": true, "termsUrl": "https://acme.example.com/terms", "callToActionText": "Subscribe", "productName": "Annual Membership", "productDescription": "12 months of full access to all member benefits.", "fixedAmount": 99, "allowCustomAmount": false, "successRedirectUrl": "https://acme.example.com/welcome", "paymentMethods": [ "card" ], "allowedEmbeddingDomains": [ "acme.example.com", "*.acme.example.com" ], "checkoutLayout": "Standard" } ``` _Example: Save Card page (store a card, no charge)_ A dedicated card-capture page: the customer's card is validated with a zero-dollar account verification (authorize $0 with AVS/CVV, immediate void), vaulted as a reusable payment token, and stored-credential consent is captured. No charge is taken, so amount-bearing configuration (tax, tip, shipping, convenience fee, invoice amounts, donations) must stay hidden/off. Requires the merchant's processor to support zero-dollar verification. ```json { "name": "Add Payment Method", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Save Your Card", "supportTokenization": true, "fieldsAndPanels": { "fieldInvoice": "Hidden", "fieldTax": "Hidden", "fieldConvenienceFee": "Hidden", "fieldShipping": "Hidden", "fieldTotal": true, "fieldBillingAddr": "Hidden", "fieldShipAddr": "Hidden", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Details", "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result" }, "receiptAndNotifications": { "enableCustomerEmail": true }, "pageMode": "Streamlined", "savePaymentDetails": true, "callToActionText": "Save Card", "productName": "Card on File", "productDescription": "Securely save a card for future purchases. You will not be charged today.", "paymentMethods": [ "card" ], "checkoutLayout": "Compact", "pagePurpose": "SaveCard" } ``` _Example: Save Card with Initial Charge (subscription enrollment)_ A card-capture page that also charges the first payment of an inlined recurring plan as a real sale, vaults the card with Recurring stored-credential consent, and creates a contract for the remaining payments. The charged amount comes entirely from the recurring plan, so the page's amount-bearing fields stay hidden. The plan needs complete economics: a positive recurring amount, an interval of at least 1, and at least two total payments; initialChargeAmount optionally overrides payment one (for example a bundled setup fee). The page must accept card only. ```json { "name": "Gold Plan Enrollment", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Join the Gold Plan", "supportTokenization": true, "fieldsAndPanels": { "fieldInvoice": "Hidden", "fieldTax": "Hidden", "fieldConvenienceFee": "Hidden", "fieldShipping": "Hidden", "fieldTotal": true, "fieldBillingAddr": "Hidden", "fieldShipAddr": "Hidden", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Details", "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result" }, "receiptAndNotifications": { "enableCustomerEmail": true }, "pageMode": "Streamlined", "savePaymentDetails": true, "callToActionText": "Enroll", "productName": "Gold Plan", "productDescription": "$49.99 today, then $29.99 per month for 11 more payments.", "paymentMethods": [ "card" ], "checkoutLayout": "Standard", "pagePurpose": "SaveCardWithInitialCharge", "recurringPlan": { "recurringAmount": 29.99, "frequency": "Monthly", "interval": 1, "numberOfPayments": 12, "initialChargeAmount": 49.99 } } ``` _Example: Embedded page with no heading chrome_ A Streamlined page embedded inside the merchant's own checkout, where the surrounding site already shows the branding. HideTitle suppresses the page heading and HideMerchantName suppresses the business-name line in the page header, so the payment form sits flush against the host page. Both default to false, so omitting them keeps the existing look. HideLoadingIndicator suppresses the gateway's own loading chrome as well, for an embedding page that paints its own loading state and reveals the frame when the ready event arrives; it too defaults to false. Title is optional and may be sent empty; when you do supply it, it must be 5-100 characters. Hiding these display slots never changes the merchant named on the Apple Pay or Paze payment sheet, or in the bank-account authorization text. ```json { "name": "Embedded Checkout (chrome-free)", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "", "supportTokenization": true, "receiptAndNotifications": { "enableCustomerEmail": true }, "pageMode": "Streamlined", "callToActionText": "Pay", "productName": "Order Total", "paymentMethods": [ "card" ], "allowedEmbeddingDomains": [ "acme.example.com", "*.acme.example.com" ], "checkoutLayout": "Embedded", "allowTransparentEmbedding": true, "hideTitle": true, "hideMerchantName": true, "hideLoadingIndicator": true } ``` _Example: Streamlined page selling catalog products_ A page priced from the merchant's invoicing product catalog rather than a single amount. Each entry names a catalog product the merchant owns (active, and priced in the merchant's currency) with the page's own presentation rules: display order, whether the customer may leave it out (isOptional), whether they may change the quantity (allowQuantityChange), the quantity the page starts at, and optional page-level quantity limits that only narrow the catalog's own. The customer picks quantities on the page; the total is computed on the server at the catalog prices in force when each payment link is created, and the customer cannot edit it. A page that sells products carries no fixedAmount, no allowCustomAmount and no donation amounts. ```json { "name": "Field Guide Shop", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Field Guide Shop", "fieldsAndPanels": { "fieldInvoice": "Hidden", "fieldTax": "Hidden", "fieldConvenienceFee": "Hidden", "fieldShipping": "Hidden", "fieldTotal": true, "fieldBillingAddr": "Hidden", "fieldShipAddr": "Hidden", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Details", "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result" }, "receiptAndNotifications": { "enableCustomerEmail": true }, "pageMode": "Streamlined", "callToActionText": "Buy", "paymentMethods": [ "card" ], "products": [ { "productId": "00000000-0000-0000-0000-00000000000c", "allowQuantityChange": true, "defaultQuantity": 1, "maximumQuantity": 10 }, { "productId": "00000000-0000-0000-0000-00000000000d", "displayOrder": 1, "isOptional": true, "defaultQuantity": 1 } ] } ``` ## Responses ### 200 OK **Content type:** `application/json` Schema: `HostedPaymentPageDto` Properties: - `extraProperties` (object) - `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. - `lastModificationTime` (string(date-time)): The date and time when this entity was last modified. - `lastModifierId` (string(uuid)): The ID of the user who last modified this entity. - `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. - `deletionTime` (string(date-time)): The date and time when this entity was deleted, if it is deleted. - `name` (string) - `concurrencyStamp` (string) - `tenantId` (string(uuid)) - `merchantId` (string(uuid)) - `isActive` (boolean) - `title` (string) - `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. - `hideBanner` (boolean) - `supportRetail` (boolean) - `usePostOnSubmit` (boolean) - `useCaptcha` (boolean) - `supportTokenization` (boolean) - `pageActions` (HostedPaymentPageActionUrls): Represents the set of action URLs for the hosted payment page, including submit, edit, continue, and cancel (Back) actions. - `donations` (HostedPageDonations): Represents donation configuration for the hosted payment page, including enablement and predefined amounts. - `theme` (HostedPageTheme): Represents theme settings for the hosted payment page, including colors, fonts, and header styles. - `fieldsAndPanels` (HostedPageFieldsAndPanels): Represents the configuration of fields and panels for the hosted payment page, including display options and custom labels. - `receiptAndNotifications` (HostedPageReceipts): Represents receipt and notification settings for the hosted payment page, including callback URLs, email options, and notification recipients. - `disclosures` (HostedPageDisclosures): Represents disclosure information for a hosted payment page, including display and acceptance requirements. - `customText` (HostedPageCustomText): Represents custom text and links for a hosted payment page, including terms, promo, support, and privacy policy. - `entityVersion` (integer(int32)) - `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). - `templateName` (string): Deprecated. The name of the template saved from this page, echoed from the shared template store; `null` when `isTemplate` is `false`. - `templateDescription` (string): Deprecated. The description of the template saved from this page, echoed from the shared template store; `null` when `isTemplate` is `false`. - `shareTemplate` (boolean): Deprecated. Whether the template saved from this page is shared beyond its merchant, echoed from the shared template store's published state. - `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. - `pageMode` (object) - `collectBusinessName` (boolean) - `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. - `allowPromoCodes` (boolean) - `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. - `savePaymentDetails` (boolean) - `declineRetryMode` (object): 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. - `requireTermsAcceptance` (boolean) - `termsUrl` (string) - `callToActionText` (string) - `productName` (string) - `productDescription` (string) - `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. - `fixedAmount` (number(double)) - `allowCustomAmount` (boolean) - `successRedirectUrl` (string) - `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. - `paymentMethods` (array) - `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. - `resolvedCustomFields` (array): 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`. - `allowedEmbeddingDomains` (array) - `checkoutLayout` (object) - `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. - `pagePurpose` (object): 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. - `recurringPlan` (object): The inlined recurring-schedule definition whose first payment a `SaveCardWithInitialCharge` page charges. `null` for every other purpose. - `captureMode` (object): Capture timing for the chargeable Payment flow. `null` resolves to `Sale`. `Authorize` produces an Authorization with capture deferred. - `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. - `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). - `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. - `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. - `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. - `products` (array): 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. - `isLocked` (boolean) - `lockedAt` (string(date-time)) - `lockedByUserId` (string(uuid)) - `lockedByUserName` (string) - `lockReason` (string) ### 403 Forbidden **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 401 Unauthorized **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 400 Bad Request **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 404 Not Found **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 501 Not Implemented **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 500 Internal Server Error **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 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. See the error-code reference in this document's description for the values `error.code` can take. **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 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` 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. - `title` (string) required: A short, human-readable summary of the problem type. - `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. - `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` Properties: - `error` (RemoteServiceErrorInfo) ## 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 HostedPaymentPageCreateDto. See the Request body section below for its fields. ### cURL ```bash curl -X POST "{{BASE_URL}}/api/hostedpaymentpages" \ -H "api-key: {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "useCaptcha": true, "supportTokenization": true, "pageActions": { "submit": { "url": "https://acme.example.com/checkout/submit", "enabled": true, "label": "Pay Now" }, "edit": { "url": "https://acme.example.com/cart", "enabled": true, "label": "Edit Cart" }, "continue": { "url": "https://acme.example.com/thank-you", "enabled": true, "label": "Continue" } }, "theme": { "panelBackColor": "#ffffff", "panelBorderColor": "#e0e0e0", "buttonColor": "#0066cc", "buttonBorderColor": "#0066cc", "inputFieldBorderColor": "#cccccc", "inputFieldBackgroundColor": "#ffffff", "inputFieldFontColor": "#333333", "inputFieldBackgroundFocusColor": "#f0f8ff", "backColor": "#fafafa", "fontColor": "#333333", "font": "Inter, sans-serif", "headerFont": "Inter, sans-serif", "headerFontColor": "#111111", "headerBackColor": "#ffffff", "headerBorderColor": "#e0e0e0", "customCSS": "" }, "fieldsAndPanels": { "fieldInvoice": "Required", "fieldTax": "Required", "fieldConvenienceFee": "Hidden", "fieldShipping": "Required", "fieldTotal": true, "fieldBillingAddr": "Required", "fieldShipAddr": "Required", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Summary", "customizeOrderPanelText": true, "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result", "fieldTip": "Optional" }, "receiptAndNotifications": { "callbackUrl": "https://acme.example.com/webhooks/hpp", "enableWebhookNotification": true, "enableCustomerEmail": true, "useHostedConfirm": true }, "disclosures": { "disclosureText": "By clicking Place Order you agree to Acme\u0027s Terms of Service.", "showDisclosures": true, "requireDisclosureAccept": true }, "customText": { "termsAndConditionsLink": "https://acme.example.com/terms", "processButtonText": "Place Order", "headerText": "Secure Checkout", "supportLink": "https://acme.example.com/support", "poweredByText": "Powered by Acme", "copyrightText": "\u00A9 2026 Acme Corp", "privacyPolicyLink": "https://acme.example.com/privacy" }, "pageMode": "Classic" }' ``` ### PowerShell ```powershell $headers = @{ 'api-key' = '{{API_KEY}}' } $body = @' { "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "useCaptcha": true, "supportTokenization": true, "pageActions": { "submit": { "url": "https://acme.example.com/checkout/submit", "enabled": true, "label": "Pay Now" }, "edit": { "url": "https://acme.example.com/cart", "enabled": true, "label": "Edit Cart" }, "continue": { "url": "https://acme.example.com/thank-you", "enabled": true, "label": "Continue" } }, "theme": { "panelBackColor": "#ffffff", "panelBorderColor": "#e0e0e0", "buttonColor": "#0066cc", "buttonBorderColor": "#0066cc", "inputFieldBorderColor": "#cccccc", "inputFieldBackgroundColor": "#ffffff", "inputFieldFontColor": "#333333", "inputFieldBackgroundFocusColor": "#f0f8ff", "backColor": "#fafafa", "fontColor": "#333333", "font": "Inter, sans-serif", "headerFont": "Inter, sans-serif", "headerFontColor": "#111111", "headerBackColor": "#ffffff", "headerBorderColor": "#e0e0e0", "customCSS": "" }, "fieldsAndPanels": { "fieldInvoice": "Required", "fieldTax": "Required", "fieldConvenienceFee": "Hidden", "fieldShipping": "Required", "fieldTotal": true, "fieldBillingAddr": "Required", "fieldShipAddr": "Required", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Summary", "customizeOrderPanelText": true, "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result", "fieldTip": "Optional" }, "receiptAndNotifications": { "callbackUrl": "https://acme.example.com/webhooks/hpp", "enableWebhookNotification": true, "enableCustomerEmail": true, "useHostedConfirm": true }, "disclosures": { "disclosureText": "By clicking Place Order you agree to Acme\u0027s Terms of Service.", "showDisclosures": true, "requireDisclosureAccept": true }, "customText": { "termsAndConditionsLink": "https://acme.example.com/terms", "processButtonText": "Place Order", "headerText": "Secure Checkout", "supportLink": "https://acme.example.com/support", "poweredByText": "Powered by Acme", "copyrightText": "\u00A9 2026 Acme Corp", "privacyPolicyLink": "https://acme.example.com/privacy" }, "pageMode": "Classic" } '@ $response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/hostedpaymentpages' ` -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.hostedPaymentPagesCreate({ "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "useCaptcha": true, "supportTokenization": true, "pageActions": { "submit": { "url": "https://acme.example.com/checkout/submit", "enabled": true, "label": "Pay Now" }, "edit": { "url": "https://acme.example.com/cart", "enabled": true, "label": "Edit Cart" }, "continue": { "url": "https://acme.example.com/thank-you", "enabled": true, "label": "Continue" } }, "theme": { "panelBackColor": "#ffffff", "panelBorderColor": "#e0e0e0", "buttonColor": "#0066cc", "buttonBorderColor": "#0066cc", "inputFieldBorderColor": "#cccccc", "inputFieldBackgroundColor": "#ffffff", "inputFieldFontColor": "#333333", "inputFieldBackgroundFocusColor": "#f0f8ff", "backColor": "#fafafa", "fontColor": "#333333", "font": "Inter, sans-serif", "headerFont": "Inter, sans-serif", "headerFontColor": "#111111", "headerBackColor": "#ffffff", "headerBorderColor": "#e0e0e0", "customCSS": "" }, "fieldsAndPanels": { "fieldInvoice": "Required", "fieldTax": "Required", "fieldConvenienceFee": "Hidden", "fieldShipping": "Required", "fieldTotal": true, "fieldBillingAddr": "Required", "fieldShipAddr": "Required", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Summary", "customizeOrderPanelText": true, "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result", "fieldTip": "Optional" }, "receiptAndNotifications": { "callbackUrl": "https://acme.example.com/webhooks/hpp", "enableWebhookNotification": true, "enableCustomerEmail": true, "useHostedConfirm": true }, "disclosures": { "disclosureText": "By clicking Place Order you agree to Acme\u0027s Terms of Service.", "showDisclosures": true, "requireDisclosureAccept": true }, "customText": { "termsAndConditionsLink": "https://acme.example.com/terms", "processButtonText": "Place Order", "headerText": "Secure Checkout", "supportLink": "https://acme.example.com/support", "poweredByText": "Powered by Acme", "copyrightText": "\u00A9 2026 Acme Corp", "privacyPolicyLink": "https://acme.example.com/privacy" }, "pageMode": "Classic" }); ``` ### TypeScript (raw HTTP) ```typescript const response = await fetch('{{BASE_URL}}/api/hostedpaymentpages', { method: 'POST', headers: { "api-key": "{{API_KEY}}", "Content-Type": "application/json", }, body: JSON.stringify({ "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "useCaptcha": true, "supportTokenization": true, "pageActions": { "submit": { "url": "https://acme.example.com/checkout/submit", "enabled": true, "label": "Pay Now" }, "edit": { "url": "https://acme.example.com/cart", "enabled": true, "label": "Edit Cart" }, "continue": { "url": "https://acme.example.com/thank-you", "enabled": true, "label": "Continue" } }, "theme": { "panelBackColor": "#ffffff", "panelBorderColor": "#e0e0e0", "buttonColor": "#0066cc", "buttonBorderColor": "#0066cc", "inputFieldBorderColor": "#cccccc", "inputFieldBackgroundColor": "#ffffff", "inputFieldFontColor": "#333333", "inputFieldBackgroundFocusColor": "#f0f8ff", "backColor": "#fafafa", "fontColor": "#333333", "font": "Inter, sans-serif", "headerFont": "Inter, sans-serif", "headerFontColor": "#111111", "headerBackColor": "#ffffff", "headerBorderColor": "#e0e0e0", "customCSS": "" }, "fieldsAndPanels": { "fieldInvoice": "Required", "fieldTax": "Required", "fieldConvenienceFee": "Hidden", "fieldShipping": "Required", "fieldTotal": true, "fieldBillingAddr": "Required", "fieldShipAddr": "Required", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Summary", "customizeOrderPanelText": true, "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result", "fieldTip": "Optional" }, "receiptAndNotifications": { "callbackUrl": "https://acme.example.com/webhooks/hpp", "enableWebhookNotification": true, "enableCustomerEmail": true, "useHostedConfirm": true }, "disclosures": { "disclosureText": "By clicking Place Order you agree to Acme\u0027s Terms of Service.", "showDisclosures": true, "requireDisclosureAccept": true }, "customText": { "termsAndConditionsLink": "https://acme.example.com/terms", "processButtonText": "Place Order", "headerText": "Secure Checkout", "supportLink": "https://acme.example.com/support", "poweredByText": "Powered by Acme", "copyrightText": "\u00A9 2026 Acme Corp", "privacyPolicyLink": "https://acme.example.com/privacy" }, "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(""" { "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "useCaptcha": true, "supportTokenization": true, "pageActions": { "submit": { "url": "https://acme.example.com/checkout/submit", "enabled": true, "label": "Pay Now" }, "edit": { "url": "https://acme.example.com/cart", "enabled": true, "label": "Edit Cart" }, "continue": { "url": "https://acme.example.com/thank-you", "enabled": true, "label": "Continue" } }, "theme": { "panelBackColor": "#ffffff", "panelBorderColor": "#e0e0e0", "buttonColor": "#0066cc", "buttonBorderColor": "#0066cc", "inputFieldBorderColor": "#cccccc", "inputFieldBackgroundColor": "#ffffff", "inputFieldFontColor": "#333333", "inputFieldBackgroundFocusColor": "#f0f8ff", "backColor": "#fafafa", "fontColor": "#333333", "font": "Inter, sans-serif", "headerFont": "Inter, sans-serif", "headerFontColor": "#111111", "headerBackColor": "#ffffff", "headerBorderColor": "#e0e0e0", "customCSS": "" }, "fieldsAndPanels": { "fieldInvoice": "Required", "fieldTax": "Required", "fieldConvenienceFee": "Hidden", "fieldShipping": "Required", "fieldTotal": true, "fieldBillingAddr": "Required", "fieldShipAddr": "Required", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Summary", "customizeOrderPanelText": true, "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result", "fieldTip": "Optional" }, "receiptAndNotifications": { "callbackUrl": "https://acme.example.com/webhooks/hpp", "enableWebhookNotification": true, "enableCustomerEmail": true, "useHostedConfirm": true }, "disclosures": { "disclosureText": "By clicking Place Order you agree to Acme\u0027s Terms of Service.", "showDisclosures": true, "requireDisclosureAccept": true }, "customText": { "termsAndConditionsLink": "https://acme.example.com/terms", "processButtonText": "Place Order", "headerText": "Secure Checkout", "supportLink": "https://acme.example.com/support", "poweredByText": "Powered by Acme", "copyrightText": "\u00A9 2026 Acme Corp", "privacyPolicyLink": "https://acme.example.com/privacy" }, "pageMode": "Classic" } """); var result = await api.HostedPaymentPagesCreateAsync(body); ``` ### C# (raw HTTP) ```csharp using System.Text; using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") }; var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/hostedpaymentpages"); request.Headers.Add("api-key", "{{API_KEY}}"); request.Content = new StringContent(""" { "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": true, "title": "Pay Acme Corp", "useCaptcha": true, "supportTokenization": true, "pageActions": { "submit": { "url": "https://acme.example.com/checkout/submit", "enabled": true, "label": "Pay Now" }, "edit": { "url": "https://acme.example.com/cart", "enabled": true, "label": "Edit Cart" }, "continue": { "url": "https://acme.example.com/thank-you", "enabled": true, "label": "Continue" } }, "theme": { "panelBackColor": "#ffffff", "panelBorderColor": "#e0e0e0", "buttonColor": "#0066cc", "buttonBorderColor": "#0066cc", "inputFieldBorderColor": "#cccccc", "inputFieldBackgroundColor": "#ffffff", "inputFieldFontColor": "#333333", "inputFieldBackgroundFocusColor": "#f0f8ff", "backColor": "#fafafa", "fontColor": "#333333", "font": "Inter, sans-serif", "headerFont": "Inter, sans-serif", "headerFontColor": "#111111", "headerBackColor": "#ffffff", "headerBorderColor": "#e0e0e0", "customCSS": "" }, "fieldsAndPanels": { "fieldInvoice": "Required", "fieldTax": "Required", "fieldConvenienceFee": "Hidden", "fieldShipping": "Required", "fieldTotal": true, "fieldBillingAddr": "Required", "fieldShipAddr": "Required", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Summary", "customizeOrderPanelText": true, "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result", "fieldTip": "Optional" }, "receiptAndNotifications": { "callbackUrl": "https://acme.example.com/webhooks/hpp", "enableWebhookNotification": true, "enableCustomerEmail": true, "useHostedConfirm": true }, "disclosures": { "disclosureText": "By clicking Place Order you agree to Acme\u0027s Terms of Service.", "showDisclosures": true, "requireDisclosureAccept": true }, "customText": { "termsAndConditionsLink": "https://acme.example.com/terms", "processButtonText": "Place Order", "headerText": "Secure Checkout", "supportLink": "https://acme.example.com/support", "poweredByText": "Powered by Acme", "copyrightText": "\u00A9 2026 Acme Corp", "privacyPolicyLink": "https://acme.example.com/privacy" }, "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.HostedPaymentPageCreateDto.from_dict({ "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": True, "title": "Pay Acme Corp", "useCaptcha": True, "supportTokenization": True, "pageActions": { "submit": { "url": "https://acme.example.com/checkout/submit", "enabled": True, "label": "Pay Now" }, "edit": { "url": "https://acme.example.com/cart", "enabled": True, "label": "Edit Cart" }, "continue": { "url": "https://acme.example.com/thank-you", "enabled": True, "label": "Continue" } }, "theme": { "panelBackColor": "#ffffff", "panelBorderColor": "#e0e0e0", "buttonColor": "#0066cc", "buttonBorderColor": "#0066cc", "inputFieldBorderColor": "#cccccc", "inputFieldBackgroundColor": "#ffffff", "inputFieldFontColor": "#333333", "inputFieldBackgroundFocusColor": "#f0f8ff", "backColor": "#fafafa", "fontColor": "#333333", "font": "Inter, sans-serif", "headerFont": "Inter, sans-serif", "headerFontColor": "#111111", "headerBackColor": "#ffffff", "headerBorderColor": "#e0e0e0", "customCSS": "" }, "fieldsAndPanels": { "fieldInvoice": "Required", "fieldTax": "Required", "fieldConvenienceFee": "Hidden", "fieldShipping": "Required", "fieldTotal": True, "fieldBillingAddr": "Required", "fieldShipAddr": "Required", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Summary", "customizeOrderPanelText": True, "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result", "fieldTip": "Optional" }, "receiptAndNotifications": { "callbackUrl": "https://acme.example.com/webhooks/hpp", "enableWebhookNotification": True, "enableCustomerEmail": True, "useHostedConfirm": True }, "disclosures": { "disclosureText": "By clicking Place Order you agree to Acme\u0027s Terms of Service.", "showDisclosures": True, "requireDisclosureAccept": True }, "customText": { "termsAndConditionsLink": "https://acme.example.com/terms", "processButtonText": "Place Order", "headerText": "Secure Checkout", "supportLink": "https://acme.example.com/support", "poweredByText": "Powered by Acme", "copyrightText": "\u00A9 2026 Acme Corp", "privacyPolicyLink": "https://acme.example.com/privacy" }, "pageMode": "Classic" }) result = api.hosted_payment_pages_create(body) ``` ### Python (raw HTTP) ```bash pip install requests ``` ```python import requests headers = { "api-key": "{{API_KEY}}", "Content-Type": "application/json", } body = { "name": "Acme Online Checkout", "merchantId": "00000000-0000-0000-0000-000000000001", "isActive": True, "title": "Pay Acme Corp", "useCaptcha": True, "supportTokenization": True, "pageActions": { "submit": { "url": "https://acme.example.com/checkout/submit", "enabled": True, "label": "Pay Now" }, "edit": { "url": "https://acme.example.com/cart", "enabled": True, "label": "Edit Cart" }, "continue": { "url": "https://acme.example.com/thank-you", "enabled": True, "label": "Continue" } }, "theme": { "panelBackColor": "#ffffff", "panelBorderColor": "#e0e0e0", "buttonColor": "#0066cc", "buttonBorderColor": "#0066cc", "inputFieldBorderColor": "#cccccc", "inputFieldBackgroundColor": "#ffffff", "inputFieldFontColor": "#333333", "inputFieldBackgroundFocusColor": "#f0f8ff", "backColor": "#fafafa", "fontColor": "#333333", "font": "Inter, sans-serif", "headerFont": "Inter, sans-serif", "headerFontColor": "#111111", "headerBackColor": "#ffffff", "headerBorderColor": "#e0e0e0", "customCSS": "" }, "fieldsAndPanels": { "fieldInvoice": "Required", "fieldTax": "Required", "fieldConvenienceFee": "Hidden", "fieldShipping": "Required", "fieldTotal": True, "fieldBillingAddr": "Required", "fieldShipAddr": "Required", "fieldCustomerEmail": "Required", "fieldCustomerNameOnCard": "Hidden", "orderPanelCustomText": "Order Summary", "customizeOrderPanelText": True, "customFieldPanelCustomText": "Custom Fields", "addressPanelCustomText": "Address", "cardPanelCustomText": "Card Data", "resultPanelCustomText": "Result", "fieldTip": "Optional" }, "receiptAndNotifications": { "callbackUrl": "https://acme.example.com/webhooks/hpp", "enableWebhookNotification": True, "enableCustomerEmail": True, "useHostedConfirm": True }, "disclosures": { "disclosureText": "By clicking Place Order you agree to Acme\u0027s Terms of Service.", "showDisclosures": True, "requireDisclosureAccept": True }, "customText": { "termsAndConditionsLink": "https://acme.example.com/terms", "processButtonText": "Place Order", "headerText": "Secure Checkout", "supportLink": "https://acme.example.com/support", "poweredByText": "Powered by Acme", "copyrightText": "\u00A9 2026 Acme Corp", "privacyPolicyLink": "https://acme.example.com/privacy" }, "pageMode": "Classic" } response = requests.request( "POST", "{{BASE_URL}}/api/hostedpaymentpages", headers=headers, json=body, ) response.raise_for_status() data = response.json() ``` ## See also - [All documentation](https://devportal-simpay-sbx.winkpg.io/llms.txt): the machine-readable index of every public page on this site.