View as Markdown

llms.txt

The API reference isn't available right now

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

Back to the API reference

No such operation

This instance documents no operation under that identifier. It may have been renamed, or it may belong to a feature this installation hasn't enabled.

Back to the API reference

This reference may be out of date

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

API reference Hosted Payment Pages

Creates a ready-to-use Save Card page for storing a card on file.

POST /api/hostedpaymentpages/create-save-card-capture-async deprecated

Requires: HostedPaymentPage.HostedPaymentPages, HostedPaymentPage.HostedPaymentPages.Create, merchant scope.

The page is created under `merchantId` and captures the card with a zero-dollar verification rather than a charge, so its amount configuration is neutralized for you. The merchant's processor must support zero-dollar verification; when it does not, the request is refused with a validation error. Everything else on the returned page can be changed afterwards through the ordinary update call.

Signed in, you can send this request to your own sandbox merchant from the console and read the answer. Sign in to try it.

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 . See the Request body section below for its fields.

Code sample language

cURL

curl -X POST "{{BASE_URL}}/api/hostedpaymentpages/create-save-card-capture-async" \
  -H "api-key: {{API_KEY}}"

PowerShell

$headers = @{
    'api-key' = '{{API_KEY}}'
}

$response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/hostedpaymentpages/create-save-card-capture-async' `
    -Headers $headers

npm install @winkpg/winkpg-api

TypeScript (SDK)

import { Configuration, HostedPaymentPagesApi } from '@winkpg/winkpg-api';

const api = new HostedPaymentPagesApi(new Configuration({
  basePath: '{{BASE_URL}}',
  apiKey: '{{API_KEY}}',
}));

const { data } = await api.hostedPaymentPagesCreateSaveCardCapture();

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/hostedpaymentpages/create-save-card-capture-async', {
  method: 'POST',
  headers: {
    "api-key": "{{API_KEY}}",
  },
});

const data = await response.json();

dotnet add package WinkPg.Api.Client

C# (SDK)

using WinkPg.Api.Client.Api;
using WinkPg.Api.Client.Client;

var config = new Configuration { BasePath = "{{BASE_URL}}" };
config.AddApiKey("api-key", "{{API_KEY}}");

var api = new HostedPaymentPagesApi(config);
var result = await api.HostedPaymentPagesCreateSaveCardCaptureAsync();

C# (raw HTTP)

using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") };

var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/hostedpaymentpages/create-save-card-capture-async");
request.Headers.Add("api-key", "{{API_KEY}}");

var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();

pip install winkpg-api

Python (SDK)

import winkpg_api

configuration = winkpg_api.Configuration(host="{{BASE_URL}}")
configuration.api_key["ApiKey"] = "{{API_KEY}}"

with winkpg_api.ApiClient(configuration) as client:
    api = winkpg_api.HostedPaymentPagesApi(client)
    result = api.hosted_payment_pages_create_save_card_capture()

pip install requests

Python (raw HTTP)

import requests

headers = {
    "api-key": "{{API_KEY}}",
}

response = requests.request(
    "POST",
    "{{BASE_URL}}/api/hostedpaymentpages/create-save-card-capture-async",
    headers=headers,
)
response.raise_for_status()
data = response.json()

Parameters

Name In Type Description
merchantId required query string (uuid) The owning merchant.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
name required query string Optional internal name; a default unique name is generated when null.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
suppressNulls required query boolean If true, omit properties with null values.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Request body

application/json , required

Field Type Description

This request body has no documented fields.

Responses

200 OK

Body: HostedPaymentPageDto HostedPaymentPageDto Each item has these fields.

Field Type Description
extraProperties required object nullableread only
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
id required string (uuid)
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
creationTime required string (date-time) The date and time when this entity was created.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
creatorId required string (uuid) The ID of the user who created this entity. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
lastModificationTime required string (date-time) The date and time when this entity was last modified. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
lastModifierId required string (uuid) The ID of the user who last modified this entity. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isDeleted required boolean Indicates whether this entity has been deleted.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
deleterId required string (uuid) The ID of the user who deleted this entity, if it is deleted. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
deletionTime required string (date-time) The date and time when this entity was deleted, if it is deleted. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
name required string nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
concurrencyStamp required string nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
tenantId required string (uuid) nullableread only
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
merchantId required string (uuid)
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isActive required boolean
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
title required string nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
bannerImage required string Filename of the header banner image, as produced by the portal image uploader. This is not a URL: the public page resolves the filename against the hosted-page image CDN container. See `bannerImage` for the write contract. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
hideBanner required boolean
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
supportRetail required boolean
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
usePostOnSubmit required boolean
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
useCaptcha required boolean
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
supportTokenization required boolean
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
pageActions required HostedPaymentPageActionUrls HostedPaymentPageActionUrls Represents the set of action URLs for the hosted payment page, including submit, edit, continue, and cancel (Back) actions.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of HostedPaymentPageActionUrls:

Field Type Description
submit required URLConfig URLConfig Gets or sets the URL to use when the payment is submitted.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
edit required URLConfig URLConfig Gets or sets the URL to use on the hosted receipt page to return to the transaction page.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
continue required URLConfig URLConfig Gets or sets the URL to use on the hosted receipt page to navigate to a different page.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
cancel required URLConfig URLConfig Gets or sets the address the payer's Back link returns to from the payment form, before paying (typically the merchant's cart). A session-level `cancelUrl` overrides it.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

donations required HostedPageDonations HostedPageDonations Represents donation configuration for the hosted payment page, including enablement and predefined amounts.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of HostedPageDonations:

Field Type Description
enableDonationAmounts required boolean Gets or sets a value indicating whether donation amounts are enabled.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
donationAmounts required array of HostedPageDonationAmount array of HostedPageDonationAmount Gets or sets the list of predefined donation amount options. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

theme required HostedPageTheme HostedPageTheme Represents theme settings for the hosted payment page, including colors, fonts, and header styles.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of HostedPageTheme:

Field Type Description
panelBackColor required string Gets or sets the background color of the panels. nullablemax length 20
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
panelBorderColor required string Gets or sets the border color of the panels. nullablemax length 20
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
buttonColor required string Gets or sets the border color of the form buttons. nullablemax length 20
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
buttonBorderColor required string Gets or sets the border color of the buttons. nullablemax length 20
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
inputFieldBorderColor required string Gets or sets the border color of the form input fields. nullablemax length 20
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
inputFieldBackgroundColor required string Gets or sets the color of the form input fields background. nullablemax length 20
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
inputFieldFontSize required integer (int32) Gets or sets the size of the input fields font. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
inputFieldFontColor required string Gets or sets the color of the form input fields font. nullablemax length 20
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
inputFieldBackgroundFocusColor required string Gets or sets the color of the form input fields background when the field has focus. nullablemax length 20
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
backColor required string Gets or sets the page background color. nullablemax length 20
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
fontColor required string Gets or sets the font color. nullablemax length 20
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
font required string Gets or sets the name of the font to use for the body. nullablemax length 50
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
fontSize required integer (int32) Gets or sets the size of the font. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
headerFont required string Gets or sets the name of the font to use for header text. nullablemax length 50
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
headerFontColor required string Gets or sets the font color to use for the header text. nullablemax length 20
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
headerFontSize required integer (int32) Gets or sets the font size to use for the header text. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
headerBackColor required string Gets or sets the background color to use for the header text. nullablemax length 20
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
headerBorderColor required string Gets or sets the background color to use for the header text. nullablemax length 20
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
customCSS required string Gets or sets custom css for the HPP nullablemax length 3000
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

fieldsAndPanels required HostedPageFieldsAndPanels HostedPageFieldsAndPanels Represents the configuration of fields and panels for the hosted payment page, including display options and custom labels.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of HostedPageFieldsAndPanels:

Field Type Description
fieldInvoice required HppFieldVisibility HppFieldVisibility Gets or sets a value indicating whether to display the invoice number field.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Hidden
Optional
Required
fieldTax required HppFieldVisibility HppFieldVisibility Gets or sets the visibility of the tax amount field.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Hidden
Optional
Required
fieldConvenienceFee required HppFieldVisibility HppFieldVisibility Gets or sets the visibility of the convenience fee field.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Hidden
Optional
Required
fieldShipping required HppFieldVisibility HppFieldVisibility Gets or sets the visibility of the shipping amount field.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Hidden
Optional
Required
fieldTotal required boolean Gets or sets a value indicating whether to display the total amount field.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
fieldBillingAddr required HppFieldVisibility HppFieldVisibility Gets or sets a value indicating whether to display the billing address fields.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Hidden
Optional
Required
fieldShipAddr required HppFieldVisibility HppFieldVisibility Gets or sets a value indicating whether to display the shipping address fields.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Hidden
Optional
Required
panelWidthOrder required integer (int32) Gets or sets an optional width for the order detail panel. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
panelWidthCustom required integer (int32) Gets or sets an optional width for the custom fields panel. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
panelWidthAddress required integer (int32) Gets or sets an optional width for the address panels. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
panelWidthCard required integer (int32) Gets or sets an optional width for the card detail panel. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
amountSetByCustomer required boolean Gets or sets a value indicating whether the total amount can be set by the customer.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
panelWidthResult required integer (int32) Gets or sets an optional width for the result panel. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
customerSetsInvoiceNumber required boolean Gets or sets a value indicating whether the customer can set the invoice number.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
fieldCustomerEmail required HppFieldVisibility HppFieldVisibility Gets or sets a value indicating whether to display the customer email field.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Hidden
Optional
Required
fieldCustomerNameOnCard required HppFieldVisibility HppFieldVisibility Gets or sets a value indicating whether to display the customer Name on card.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Hidden
Optional
Required
hideHeaderMenu required boolean Gets or sets a value indicating whether to hide the header menu/panel.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
orderPanelCustomText required string Gets or sets an optional custom label for the order panel. nullablemax length 125
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
customizeOrderPanelText required boolean Gets or sets a value indicating whether to replace the default order panel label with a custom label.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
customFieldPanelCustomText required string Gets or sets an optional custom label for the custom field panel. nullablemax length 125
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
customizeCustomFieldPanelText required boolean Gets or sets a value indicating whether to replace the default custom field panel label with a custom label.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
addressPanelCustomText required string Gets or sets an optional custom label for the address panel. nullablemax length 125
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
customizeAddressPanelText required boolean Gets or sets a value indicating whether to replace the default address panel label with a custom label.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
cardPanelCustomText required string Gets or sets an optional custom label for the card detail panel. nullablemax length 125
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
customizeCardPanelText required boolean Gets or sets a value indicating whether to replace the default card panel label with a custom label.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
resultPanelCustomText required string Gets or sets an optional custom label for the result panel. nullablemax length 125
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
customizeResultPanelText required boolean Gets or sets a value indicating whether to replace the default result panel label with a custom label.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
showOrderPanelText required boolean Gets or sets a value indicating whether to display header label for the order panel.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
showCustomFieldsText required boolean Gets or sets a value indicating whether to display the header label for the custom fields panel.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
showAddressPanelText required boolean Gets or sets a value indicating whether to display the header label for the address panel.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
showCardPanelText required boolean Gets or sets a value indicating whether to display the header label for the card detail panel.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
showResultPanelText required boolean Gets or sets a value indicating whether to display the header label for the result panel.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
hideAddressAndPhone required boolean Gets or sets a value indicating whether to hide the address and phone number fields.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
fieldTip required HppFieldVisibility HppFieldVisibility Gets or sets the visibility of the tip amount field. `null` is treated as `Hidden`. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Hidden
Optional
Required
fieldPurchaseOrder required HppFieldVisibility HppFieldVisibility Gets or sets the visibility of the customer code / purchase order field. `null` is treated as `Hidden`. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Hidden
Optional
Required
fieldContactPhone required HppFieldVisibility HppFieldVisibility Gets or sets the visibility of the contact phone field. `null` means the page has never configured it and the older control decides: the Streamlined `CollectPhone` toggle, or on a Classic page the always-rendered phone input behind `hideAddressAndPhone`. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Hidden
Optional
Required
fieldLevel3Amount required HppFieldVisibility HppFieldVisibility Gets or sets the visibility of the read-only Level 3 summary a session can carry. `null` means the page has never configured it and the older `AllowLevel3LineItems` toggle decides. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Hidden
Optional
Required
shippingAmountMode required HppShippingAmountMode HppShippingAmountMode Gets or sets where this page's shipping amount comes from. `null` is treated as `CardholderEntered`. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
CardholderEntered The cardholder types the shipping amount into the shipping field (today's behaviour, and what a persisted null mode coalesces to).
Flat The merchant fixed a single shipping amount for this page. The field renders visible, seeded with that amount, and non-editable, and the create path stamps the configured value server-side. An amount of zero is free shipping, which is a configured value like any other.
ProviderCalculated The shipping amount comes from a carrier rate quote the cardholder selects. The page quotes the shipping address once it is complete, re-quotes whenever it changes, and preselects an option so a cardholder who ignores the selector still has a valid total. The submit carries only the quote and option identifiers; the create path re-reads the stored quote and charges its amount. What happens when no rate can be quoted is the page's shippingQuoteFailureBehavior. A session that locks a shipping amount wins over this mode, and the selector does not render for it at all.
flatShippingAmount required number (double) Gets or sets the fixed shipping amount this page charges. Meaningful only in `Flat` mode; the save-time validator refuses a non-null value in any other mode so a stale amount cannot sit in the document waiting to be reactivated by a later mode change. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
shippingQuoteFailureBehavior required HppShippingQuoteFailureBehavior HppShippingQuoteFailureBehavior Gets or sets what a `ProviderCalculated` page does when no carrier rate can be quoted. `null` is treated as `BlockPayment`. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
BlockPayment The payment cannot be taken until a rate is quoted. The default, and what a persisted null coalesces to: the safest reading of a page that never chose.
ChargeFallbackAmount The page charges its configured fallback shipping amount (shippingFallbackAmount), which may be zero.
ChargeNoShipping The payment proceeds with no shipping charged.
shippingFallbackAmount required number (double) Gets or sets the shipping amount, in the transaction currency, that a `ProviderCalculated` page charges when no carrier rate can be quoted and the page is set to `ChargeFallbackAmount`. Zero is a valid configured value. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
taxAmountMode required HppTaxAmountMode HppTaxAmountMode Gets or sets where this page's tax amount comes from. `null` is treated as `CardholderEntered`. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
CardholderEntered The cardholder types the tax amount into the tax field, or the merchant's own auto-calculated tax rate fills it. The default, and what a persisted null mode coalesces to.
FlatRate The merchant picked one of its invoicing tax rates for this page. The tax field renders read-only, filled with that rate applied to the taxable amount, and the server computes and charges the same figure whatever the browser submitted.
ProviderCalculated The rate comes from the merchant's tax provider, looked up for the customer's address. The tax field renders read-only, is quoted when the address is complete and re-quoted when it changes, and the server re-derives the rate for the submitted address and refuses a submit whose tax disagrees with it. A provider that cannot answer blocks the payment rather than charging no tax.
flatTaxRateId required string (uuid) Gets or sets the identifier of the merchant's invoicing tax rate this page charges. Meaningful only in `FlatRate` mode; the save-time validator refuses a non-null value in any other mode so a stale rate cannot be reactivated by a later mode change. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
taxQuoteAddress required HppTaxQuoteAddress HppTaxQuoteAddress Gets or sets which of the customer's addresses a `ProviderCalculated` page looks the tax rate up for. `null` is treated as `Billing`. The save-time validator refuses a non-null value in any other mode. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Billing The billing address. What a persisted null coalesces to.
Shipping The shipping address, for a merchant that ships goods and owes tax where they are delivered. A page in this setting must show the shipping address panel.
panelLayout required array of HppPanelDefinition array of HppPanelDefinition Optional explicit panel ordering and sizing for the public form. When `null`, the page uses the default panel layout. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

receiptAndNotifications required HostedPageReceipts HostedPageReceipts Represents receipt and notification settings for the hosted payment page, including callback URLs, email options, and notification recipients.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of HostedPageReceipts:

Field Type Description
callbackUrl required string Gets or sets an optional URL to receive a webhook notification when a hosted page transaction is processed. Conditional: Conditional (see validator source). Max length: 200. Conditional: When CallbackUrl is not empty. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
enableWebhookNotification required boolean nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
enableCustomerEmail required boolean nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
customerEmailLogo required string Gets or sets a logo to include on email receipts sent to the customer. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
customerEmailFooter required string Gets or sets optional footer text to include in customer email receipts. nullablemax length 1000
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
customerEmailBody required string Gets or sets optional body text for customer email receipts. nullablemax length 3000
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
useHostedConfirm required boolean Gets or sets a value indicating whether to use the hosted confirmation/receipt page.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
receiptAdditionalText required string Gets or sets optional additional text to include on receipts. nullablemax length 1000
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
customerEmailAsPdf required boolean Gets or sets a value indicating whether customer receipts are sent as PDF attachments.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
emailPurchaseNotifications required boolean Gets or sets a value indicating whether to notify email addresses of transactions completed via the hosted payment page.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
purchaseNotifyEmails required array of HostedPagePurchaseNotificationEmail array of HostedPagePurchaseNotificationEmail Gets or sets the list of email addresses to notify of completed purchases. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

disclosures required HostedPageDisclosures HostedPageDisclosures Represents disclosure information for a hosted payment page, including display and acceptance requirements.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of HostedPageDisclosures:

Field Type Description
disclosureText required string Gets or sets the body text to display as a disclosure before processing a transaction. nullablemax length 3000
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
showDisclosures required boolean Gets or sets a value indicating whether to show disclosure text.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
requireDisclosureAccept required boolean Gets or sets a value indicating whether the customer must accept the disclosure before completing a transaction.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
achWebAuthorizationText required string Optional per-page override for the NACHA WEB single-debit ACH authorization wording shown on the ACH consent checkbox. Blank/unset renders the platform default. Supports the `{MerchantName}` placeholder, substituted with the merchant's display name at render. When set it is captured verbatim (with a content version hash) on each resulting ACH WEB debit, so custom language a merchant's bank/ODFI approved becomes the recorded authorization. The save-time validator guarantees a configured override never renders blank, so the submit-time fail-closed gate is never reached with a blank override. Conditional: When AchWebAuthorizationText is not empty. Max length: 2000. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
achRecurringWebAuthorizationText required string Optional per-page override for the NACHA WEB <b>recurring</b> ACH authorization wording shown on the ACH consent checkbox of a Save-Card-with-Initial-Charge page. Blank/unset renders the platform default recurring language. Supports the `{MerchantName}` placeholder and the `{RecurringSchedule}` placeholder (substituted with the plan's schedule summary at render). Used only when the ACH debit establishes a recurring arrangement; a one-off ACH debit uses `achWebAuthorizationText`. Captured verbatim (with a content version hash) on the resulting initial ACH WEB debit. Conditional: When AchRecurringWebAuthorizationText is not empty. Max length: 2000. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
achSaveOnlyWebAuthorizationText required string Optional per-page override for the NACHA <b>save-only</b> (storage) ACH authorization wording shown on the ACH consent checkbox of a store-bank-account-no-charge page. Blank/unset renders the platform default save-only language. Supports the `{MerchantName}` placeholder, substituted with the merchant's display name at render. Used only when the account is stored without any debit being taken now; a one-off debit uses `achWebAuthorizationText` and an initial-charge recurring arrangement uses `achRecurringWebAuthorizationText`. Captured verbatim (with a content version hash) on the resulting save. Conditional: When AchSaveOnlyWebAuthorizationText is not empty. Max length: 2000. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

customText required HostedPageCustomText HostedPageCustomText Represents custom text and links for a hosted payment page, including terms, promo, support, and privacy policy.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of HostedPageCustomText:

Field Type Description
termsAndConditionsLink required string Gets or sets an optional URL for a link to your terms and conditions. Conditional: Conditional (see validator source). Max length: 200. Conditional: When TermsAndConditionsLink is not empty. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
aboutUsLink required string Gets or sets an optional URL for a link to your 'about us' page. Conditional: Conditional (see validator source). Max length: 200. Conditional: When AboutUsLink is not empty. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
processButtonText required string Gets or sets optional custom text to display in place of 'Process' on the process button. nullablemax length 50
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
headerText required string Gets or sets optional text to display at the top of the hosted page. nullablemax length 100
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
promoText required string Gets or sets optional text to display as a highlighted announcement or promotion. nullablemax length 200
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
promoLink required string Gets or sets an optional URL to make the promo text a link. Conditional: Conditional (see validator source). Max length: 200. Conditional: When PromoLink is not empty. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
supportLink required string Gets or sets an optional URL for hosted page customers to access support in processing a transaction. Conditional: Conditional (see validator source). Max length: 200. Conditional: When SupportLink is not empty. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
poweredByText required string Gets or sets optional text to use as a 'powered by' caption at the bottom of the page. nullablemax length 100
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
copyrightText required string Gets or sets optional text to use as a copyright statement. nullablemax length 100
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
shippingInfoLink required string Gets or sets an optional URL to more information about shipping policies and terms. Conditional: Conditional (see validator source). Max length: 200. Conditional: When ShippingInfoLink is not empty. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
privacyPolicyLink required string Gets or sets an optional link to your privacy policy. Conditional: Conditional (see validator source). Max length: 200. Conditional: When PrivacyPolicyLink is not empty. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

entityVersion required integer (int32) read only
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isTemplate required boolean Deprecated. `true` when a template has been saved from this page. Templates live in the shared template store; this echoes whether a store row exists for the page (or, for a page written under the former inline model that has not been migrated yet, its stored flag). deprecated
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
templateName required string Deprecated. The name of the template saved from this page, echoed from the shared template store; `null` when `isTemplate` is `false`. nullabledeprecated
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
templateDescription required string Deprecated. The description of the template saved from this page, echoed from the shared template store; `null` when `isTemplate` is `false`. nullabledeprecated
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
shareTemplate required boolean Deprecated. Whether the template saved from this page is shared beyond its merchant, echoed from the shared template store's published state. deprecated
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
createdFromTemplateId required string (uuid) The template this page was created from, or `null` for a page started blank. Set by the create-from-template paths and by the designers' Load Template action when the page is saved. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
pageMode required HostedPaymentPageMode HostedPaymentPageMode nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Classic The original full-control builder with accordion sections and comprehensive configuration.
Streamlined A simplified, Stripe-inspired builder with live preview and a clean two-column public form.
collectBusinessName required boolean nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
collectPhone required boolean Older Streamlined control for the payer phone field. Honored only while `fieldsAndPanels.fieldContactPhone` is `null`; once that visibility is set it decides what the page renders, and this toggle is kept in step with it on every save. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
allowPromoCodes required boolean nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
collectTaxId required boolean Deprecated and inert. No hosted payment page renders a tax ID field, so setting this collects nothing and no tax ID is stored. To capture a buyer tax ID, define a merchant custom field and make it visible on hosted payment pages. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
savePaymentDetails required boolean nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
declineRetryMode required HppDeclineRetryMode HppDeclineRetryMode What a payment link created against this page does when a payment is declined. `null` inherits the tenant default, which is the historical single-use behavior: any declined payment spends the link permanently. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
ConsumeOnDecline The historical behavior, and the default at every level of the resolution chain. Any processor answer spends the link permanently: the session stays Consumed and a payer who reloads it is told the link has already been used.
ReleaseOnDecline A definite issuer decline hands the link back to Pending so the payer can correct their card and resubmit on the same URL, instead of having to ask the merchant for a new link.
requireTermsAcceptance required boolean nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
termsUrl required string nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
callToActionText required string nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
productName required string nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
productDescription required string nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
productImageBlobName required string Filename of the Streamlined order-summary product image, as produced by the portal image uploader. This is not a URL: the public page resolves the filename against the hosted-page image CDN container. See `productImageBlobName` for the write contract. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
fixedAmount required number (double) nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
allowCustomAmount required boolean nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
successRedirectUrl required string nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
successRedirectDelaySeconds required integer (int32) Seconds the hosted confirmation panel is shown before the payer is sent to the configured post-payment address. `null` means the page inherits the platform-configured delay. See `successRedirectDelaySeconds` for the write contract. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
paymentMethods required array of string array of nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
customFieldNames required array of string array of Optional per-page allow-list of merchant custom-field names this page shows and accepts. `null` means "all of the merchant's HPP-visible custom fields"; an explicit empty list means "no merchant custom fields on this page". See `customFieldNames` for the full-replace semantics. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
resolvedCustomFields required array of HppResolvedCustomFieldDto array of HppResolvedCustomFieldDto The merchant custom fields this page actually shows and accepts, in the order it renders them. Read-only, and resolved on every page the hosted-payment-pages API returns: `customFieldNames` is only the page's selection, and its default (`null`) means "all of the merchant's hosted-page custom fields", so the selection on its own does not tell a caller what the page uses. This resolves it against the merchant's current definitions, applying the same enabled / hosted-page-visible / page-purpose gates the page itself applies, and reports each field's validation rules so a value can be checked before it is posted. The list also carries the fields the merchant keeps hidden from the payer but opted in to accepting a value for through the session API, flagged by `isRenderedToPayer`. Those are reported precisely because the API is the only way to use them. Empty means the page uses no merchant custom fields. Definitions are merchant-global and live, so this tracks the merchant's configuration: renaming or disabling a field changes what this returns for every page that had not scoped itself to a fixed list. Sending it back on a create or update has no effect; the write contract is `customFieldNames`. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each HppResolvedCustomFieldDto:

Field Type Description
name required string The field's name. This is the key the value is carried under: in a session's prefilled fields, and in the transaction's `customFields` collection. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
label required string The text the page labels the input with: the merchant's description of the field when one is configured, otherwise `name`. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
position required integer (int32) The field's position in the page's rendering order, lowest first. The page breaks ties on `name`; the list is already returned in that order.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isRequired required boolean The merchant's requiredness setting for the field, reported as configured.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isReadOnly required boolean Whether the page displays the field without letting the customer edit it. A read-only field still submits the value the session prefilled it with.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isNumeric required boolean Whether the field accepts only a number.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isRenderedToPayer required boolean Whether the payer sees the field on the page. `false` marks a field the merchant keeps hidden but opted in to carrying a value supplied through the session API: pass it in the session's prefilled fields and the platform stamps it onto the resulting transaction. Those fields are reported here precisely because the API is the only way to use them.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
maxLength required integer (int32) The number of characters a value may carry: the narrower of the merchant's configured limit and the platform ceiling. A numeric field reports the platform ceiling, which is what its rules enforce.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
decimalPlaces required integer (int32) Decimal places a numeric value may carry. `null` when the field is not numeric. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
numericMinValue required number (double) Lowest accepted value for a numeric field. `null` when the field is not numeric. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
numericMaxValue required number (double) Highest accepted value for a numeric field. `null` when the field is not numeric. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
regEx required string The merchant's optional regular expression the value has to match. `null` when the merchant configured none. A pattern that does not compile is ignored rather than failing the submit. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
regExErrorMessage required string The message the page shows when `regEx` rejects the value, when the merchant wrote one. `null` falls back to a generic message. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isMultiValue required boolean Whether the field carries a list of values rather than a single value. A multi-value field is prefilled through the session's `prefilledListFields` and reaches the transaction as `customFields[].values`; the page renders the list read-only. A single value sent for it is still accepted and mirrored into the list.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
maxValues required integer (int32) The largest number of values a multi-value field accepts, after the platform default and ceiling are applied. `null` when the field is not multi-value. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

allowedEmbeddingDomains required array of string array of nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
checkoutLayout required CheckoutLayout CheckoutLayout nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Standard Two-column layout: order summary on the left, payment form on the right. This is the default layout matching the original Streamlined mode design.
Compact Single centered column with an inline summary at the top, form fields below, and a prominent CTA button. Minimal chrome, max-width ~480px.
Split Full-width hero header with product image and summary information, then a centered narrower column (~560px) with the payment form below.
Embedded Frameless minimal layout designed for iframe embedding. No order summary panel, just payment fields and CTA with minimal padding.
allowLevel3LineItems required boolean Older control for the read-only Level 3 line-item summary. Honored only while `fieldsAndPanels.fieldLevel3Amount` is `null`; once that visibility is set it decides what the page renders, and this toggle is kept in step with it on every save. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
pagePurpose required HppPagePurpose HppPagePurpose Instance-level page purpose. `null` resolves to `Payment`. `SaveCard` dedicates the page to capturing and storing the customer's card via a zero-dollar verification (no charge); amount-bearing configuration is hidden in the builder and rejected by the validator, and sessions created against the page inherit the save-card flow. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Payment The default, historical behavior: a chargeable payment page. null resolves here, so every pre-existing HPP instance keeps behaving exactly as before.
SaveCard A card-capture page: the cardholder's card is validated via a zero-dollar account verification (authorize $0 + AVS/CVV, immediate void), then vaulted with stored-credential consent. No charge is taken. Amount-bearing configuration (tax, shipping, convenience fee, invoice amounts, donations, tip) is irrelevant and is hidden in the builder / rejected by the validator. Requires the merchant's processor to advertise SupportsZeroDollarVerification.
SaveCardWithInitialCharge A card-capture page that also charges the first of a recurring schedule. The cardholder's card is charged a real initial sale (the first payment of a referenced reusable recurring plan, framed as the customer-initiated transaction that establishes the credential-on-file agreement), vaulted with Recurring stored-credential consent, and a customer Contract is created for the remaining payments. Like SaveCard, the amount-bearing builder configuration (tax, shipping, convenience, invoice, donations, tip, customer-set amount) is hidden: the charged amount is driven entirely by the inlined recurring definition, not by per-page amount fields. Requires a complete inlined recurring definition (RecurringPlan).
recurringPlan required HppRecurringPlan HppRecurringPlan The inlined recurring-schedule definition whose first payment a `SaveCardWithInitialCharge` page charges. `null` for every other purpose.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of HppRecurringPlan:

Field Type Description
recurringAmount required number (double) The amount charged on each recurring payment after the initial charge. greater than 0
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
frequency required Frequency Frequency The frequency unit of the recurring schedule (e.g. Monthly, Weekly).
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Secondly
Minutely
Hourly
Daily
Weekly
Monthly
Yearly
interval required integer (int32) The interval multiplier for `frequency` (e.g. `Frequency = Monthly` with `Interval = 3` is every three months). Defaults to 1. min 1
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
numberOfPayments required integer (int32) Total number of payments in the schedule, <b>including</b> the initial charge. A Contract instantiated from this definition covers the payments after the initial charge (`GetScheduledPaymentCount`). min 2
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
initialChargeAmount required number (double) Optional override for the first (initial) charge amount. When `null`, the initial charge uses `recurringAmount`. Lets a merchant charge a different amount up front (e.g. a setup fee bundled into payment one) while the recurring schedule stays at `recurringAmount`. Conditional: When InitialChargeAmount is not null. Must be > 0. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

captureMode required HppCaptureMode HppCaptureMode Capture timing for the chargeable Payment flow. `null` resolves to `Sale`. `Authorize` produces an Authorization with capture deferred. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Sale Authorize and capture funds in a single step (the historical, default behavior). null resolves here, so every pre-existing chargeable page keeps doing an implicit Sale.
Authorize Authorize now, capture later (delayed capture). The resulting transaction is an Authorization in an Authorized state, eligible for capture and void per the action matrix; the capture is completed later against the resulting transaction id via the existing capture action path (including the Apple Pay single-use token case).
allowTransparentEmbedding required boolean Opt-in to a see-through backdrop when the page is rendered inside a merchant iframe. `null`/`false` keeps the page opaque (the default). Honoured only when the request is genuinely framed and `allowedEmbeddingDomains` is configured. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
allowDeveloperPortalEmbedding required boolean Whether the developer portal's public origin is allowed to embed this page, in addition to `allowedEmbeddingDomains`. `null`/`false` is off (the default). nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
hideTitle required boolean Suppress the page `title` on the payer-facing page (both the Classic and the Streamlined renderer). `null`/`false` is the default and renders the title exactly as before. Display-only: the title is still stored, still returned, and still shown on the administrative surfaces (grid, quick view, favorites subtitle). nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
hideMerchantName required boolean Suppress the merchant business-name line in the Streamlined identity header on the payer-facing page. `null`/`false` is the default. The banner image in that same header stays governed by `hideBanner`. Display-only, and deliberately narrow: the merchant name still reaches the Apple Pay / Paze sheet total label and the NACHA ACH consent copy (and the consent evidence captured with an ACH authorization), which must name the real merchant regardless of this flag. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
hideLoadingIndicator required boolean Suppress the gateway's own loading chrome on the payer-facing page: the loading card shown while the page resolves, and the connecting affordance drawn over the prerendered form before the circuit is live. `null`/`false` is the default and shows them exactly as before. For an integrator who embeds the page and paints a loading state of their own, revealing the frame on the `ready` event. Display-only: the session, the payment and the events the page emits are untouched. Honored on the initial document, which the embedding-restriction feature resolves the page for; a deployment with that feature off shows the chrome as before. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
campaignId required string (uuid) Optional campaign this page belongs to. Sessions created from this page inherit it when the create request names no campaign of its own, so a merchant can attach a whole page to a campaign once instead of naming it on every link. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
products required array of HppPageProduct array of HppPageProduct The catalog products this page sells, in display order, or `null` for a page priced by a single `productName` with a `fixedAmount` or a payer-entered amount. Each entry references an invoicing catalog product owned by this page's merchant; the price, name and quantity limits are read from the catalog when a link is created and snapshotted onto that link, so editing the catalog never reprices a link already in a payer's hands. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each HppPageProduct:

Field Type Description
productId required string (uuid) The invoicing catalog product this entry sells.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
displayOrder required integer (int32) Zero-based position of the product in the payer-facing list. min 0
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isOptional required boolean `true` for an add-on the payer may leave out; `false` for a product every purchase on this page includes.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
allowQuantityChange required boolean Whether the payer may change the quantity from `defaultQuantity`.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
defaultQuantity required number (double) The quantity the page starts at. Must sit inside the effective quantity bounds, and is the only quantity a payer can buy when `allowQuantityChange` is `false`. Conditional: When MinimumQuantity is not null. Must be >= . Conditional: When MaximumQuantity is not null. Must be <= . greater than 0max 9999
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
minimumQuantity required number (double) Optional page-level floor on the quantity, applied on top of the product's own `MinimumQuantity`. The effective minimum is the larger of the two. Conditional: When MinimumQuantity is not null. Must be > 0. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
maximumQuantity required number (double) Optional page-level ceiling on the quantity, applied on top of the product's own `MaximumQuantity`. The effective maximum is the smaller of the two. Conditional: When MaximumQuantity is not null. Must be > 0. Conditional: When MinimumQuantity is not null and MaximumQuantity is not null. Must be >= . nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

isLocked required boolean nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
lockedAt required string (date-time) nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
lockedByUserId required string (uuid) nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
lockedByUserName required string nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
lockReason required string nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

403 Forbidden

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

401 Unauthorized

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

400 Bad Request

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

404 Not Found

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

501 Not Implemented

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

500 Internal Server Error

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

default The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The error reference lists the values `error.code` can take. The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The error reference lists the values `error.code` can take.

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

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.

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

Errors

A failed request returns the platform error envelope. The error reference lists every value error.code can carry and shows the four response shapes.

Codes declared by

Authentication

    Reconnecting to the server

    Could not reconnect

    This session has ended

    Attempt 1

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

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