Update hosted payment page

PUT /api/hostedpaymentpages/{id} deprecated

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

Updates an existing hosted payment page configuration.

Example request

Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key.

The request body is a HostedPaymentPageUpdateDto. See the Request body section below for its fields.

cURL PowerShell TypeScript C# Python

cURL

curl -X PUT "{{BASE_URL}}/api/hostedpaymentpages/{id}" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
  "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f",
  "name": "Acme Online Checkout",
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "isActive": true,
  "title": "Pay Acme Corp",
  "supportTokenization": true,
  "pageMode": "Classic"
}'

PowerShell

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

$body = @'
{
  "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f",
  "name": "Acme Online Checkout",
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "isActive": true,
  "title": "Pay Acme Corp",
  "supportTokenization": true,
  "pageMode": "Classic"
}
'@

$response = Invoke-RestMethod -Method PUT -Uri '{{BASE_URL}}/api/hostedpaymentpages/{id}' `
    -Headers $headers -ContentType 'application/json' -Body $body

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.hostedPaymentPagesUpdate("3fa85f64-5717-4562-b3fc-2c963f66afa6", {
  "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f",
  "name": "Acme Online Checkout",
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "isActive": true,
  "title": "Pay Acme Corp",
  "supportTokenization": true,
  "pageMode": "Classic"
});

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/hostedpaymentpages/{id}', {
  method: 'PUT',
  headers: {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f",
    "name": "Acme Online Checkout",
    "merchantId": "00000000-0000-0000-0000-000000000001",
    "isActive": true,
    "title": "Pay Acme Corp",
    "supportTokenization": true,
    "pageMode": "Classic"
  }),
});

const data = await response.json();

dotnet add package WinkPg.Api.Client

C# (SDK)

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<HostedPaymentPageUpdateDto>("""
    {
      "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f",
      "name": "Acme Online Checkout",
      "merchantId": "00000000-0000-0000-0000-000000000001",
      "isActive": true,
      "title": "Pay Acme Corp",
      "supportTokenization": true,
      "pageMode": "Classic"
    }
    """);

var result = await api.HostedPaymentPagesUpdateAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"), body);

C# (raw HTTP)

using System.Text;

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

var request = new HttpRequestMessage(new HttpMethod("PUT"), "/api/hostedpaymentpages/{id}");
request.Headers.Add("api-key", "{{API_KEY}}");

request.Content = new StringContent("""
    {
      "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f",
      "name": "Acme Online Checkout",
      "merchantId": "00000000-0000-0000-0000-000000000001",
      "isActive": true,
      "title": "Pay Acme Corp",
      "supportTokenization": true,
      "pageMode": "Classic"
    }
    """, Encoding.UTF8, "application/json");

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

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)
    body = winkpg_api.HostedPaymentPageUpdateDto.from_dict({
      "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f",
      "name": "Acme Online Checkout",
      "merchantId": "00000000-0000-0000-0000-000000000001",
      "isActive": True,
      "title": "Pay Acme Corp",
      "supportTokenization": True,
      "pageMode": "Classic"
    })
    result = api.hosted_payment_pages_update("3fa85f64-5717-4562-b3fc-2c963f66afa6", body)

pip install requests

Python (raw HTTP)

import requests

headers = {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
}

body = {
  "concurrencyStamp": "9f1c4d2e7b8a4f6c9d0e1a2b3c4d5e6f",
  "name": "Acme Online Checkout",
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "isActive": True,
  "title": "Pay Acme Corp",
  "supportTokenization": True,
  "pageMode": "Classic"
}

response = requests.request(
    "PUT",
    "{{BASE_URL}}/api/hostedpaymentpages/{id}",
    headers=headers,
    json=body,
)
response.raise_for_status()
data = response.json()

Parameters

Name	In	Type	Description
`id` required	path	string (uuid)
`suppressNulls` required	query	boolean	If true, omit properties with null values.

Request body

application/json , required

Field	Type	Description
`name` required	string	nullablemin length 5max length 100
`merchantId` required	string (uuid)
`isActive` required	boolean
`title` required	string	Conditional: When Title is not empty. Min length: 5. nullablemax length 100
`bannerImage` required	string	Filename of the header banner image to display on the page, as returned by the portal image uploader (for example `3f2a5b90-7c41-4d2e-9f0a-1b8c6d5e4f21.png`). This is not a URL: the public page resolves the filename against the hosted-page image CDN container. Upload the image in the page builder's appearance section, then send the filename it returns. Leave empty for no banner, or set `hideBanner` to suppress an image without discarding it. Validated by `HppImageBlobName`. nullable
`hideBanner` required	boolean
`supportRetail` required	boolean
`usePostOnSubmit` required	boolean
`useCaptcha` required	boolean
`supportTokenization` required	boolean
`pageActions` required	HostedPaymentPageActionUrls	Represents the set of action URLs for the hosted payment page, including submit, edit, continue, and cancel (Back) actions.
`donations` required	HostedPageDonations	Represents donation configuration for the hosted payment page, including enablement and predefined amounts.
`theme` required	HostedPageTheme	Represents theme settings for the hosted payment page, including colors, fonts, and header styles.
`fieldsAndPanels` required	HostedPageFieldsAndPanels	Represents the configuration of fields and panels for the hosted payment page, including display options and custom labels.
`receiptAndNotifications` required	HostedPageReceipts	Represents receipt and notification settings for the hosted payment page, including callback URLs, email options, and notification recipients.
`disclosures` required	HostedPageDisclosures	Represents disclosure information for a hosted payment page, including display and acceptance requirements.
`customText` required	HostedPageCustomText	Represents custom text and links for a hosted payment page, including terms, promo, support, and privacy policy.
`isTemplate` required	boolean	Deprecated. Templates live in the shared template store, not on the page. During the deprecation window this still drives that store: `true` saves a template from this page (creating the store row, or refreshing the existing one with the page's current values, name and description); `false`, or leaving the field out, removes the template saved from this page, which is what the field always meant on a full-replace update. The page itself is not changed either way. deprecated
`templateName` required	string	Deprecated. The template's name when `isTemplate` is `true`; the page's own name is used when this is empty. nullabledeprecated
`templateDescription` required	string	Deprecated. The template's description when `isTemplate` is `true`. nullabledeprecated
`shareTemplate` required	boolean	Deprecated. Whether the template saved from this page is shared beyond its merchant; written to the store row's published state when `isTemplate` is `true`. deprecated
`createdFromTemplateId` required	string (uuid)	The template this page is being created from, or `null` for a page started blank. The designers stamp it when Load Template is applied and the create-from-template path sets it server-side; it is recorded on the page and never copied into a template. nullable
`pageMode` required	all of HostedPaymentPageMode	nullable
`collectBusinessName` required	boolean	nullable
`collectPhone` required	boolean	nullable
`allowPromoCodes` required	boolean	nullable
`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
`savePaymentDetails` required	boolean	nullable
`declineRetryMode` required	all of 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. Conditional: When DeclineRetryMode is not null. nullable
`requireTermsAcceptance` required	boolean	nullable
`termsUrl` required	string	Conditional: When TermsUrl is not empty. Max length: 500. nullable
`callToActionText` required	string	nullablemax length 50
`productName` required	string	nullablemax length 100
`productDescription` required	string	nullablemax length 500
`productImageBlobName` required	string	Filename of the product image shown in the Streamlined checkout order summary, as returned by the portal image uploader (for example `3f2a5b90-7c41-4d2e-9f0a-1b8c6d5e4f21.png`). Same contract as `bannerImage`: this is not a URL, and the public page resolves the filename against the hosted-page image CDN container. Upload the image in the Streamlined page builder, then send the filename it returns. Leave empty for no product image. Validated by `HppImageBlobName`. nullable
`fixedAmount` required	number (double)	Conditional: When FixedAmount is not null. Must be >= 0. Conditional: Conditional (see validator source). Conditional: When IsCardCapture(PagePurpose) is true. nullable
`allowCustomAmount` required	boolean	Conditional: Conditional (see validator source). Conditional: When IsCardCapture(PagePurpose) is true. nullable
`successRedirectUrl` required	string	Conditional: When SuccessRedirectUrl is not empty. Max length: 500. nullable
`successRedirectDelaySeconds` required	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. nullablemin 0max 30
`paymentMethods` required	array of string	nullable
`customFieldNames` required	array of string	Optional per-page allow-list of merchant custom-field names this page shows and accepts. `null` means "all of the merchant's HPP-visible custom fields" (the default; existing pages that never set this stay unchanged). An explicit empty list means "no merchant custom fields on this page". A populated list intersects with the enabled / HPP-visible / save-card-purpose gates. This property is full-replace on update: because the update DTO carries the operator's complete selection, sending `null` on a round-trip clears a previously configured list back to the all-fields default, and sending `[]` scopes the page to no custom fields. A client that omits the property on update therefore resets it. The editors always send the operator's actual selection. Conditional: When CustomFieldNames is not null. nullable
`allowedEmbeddingDomains` required	array of string	nullable
`checkoutLayout` required	all of CheckoutLayout	Conditional: When CheckoutLayout is not null. nullable
`allowLevel3LineItems` required	boolean	nullable
`pagePurpose` required	all of HppPagePurpose	Instance-level page purpose. `null` resolves to `Payment`. `SaveCard` dedicates the page to card capture (zero-dollar verification, no charge). A card-capture page cannot enable amount-bearing settings such as donation amounts or the tax, shipping and convenience fee fields; a request that does is rejected with a validation error. Conditional: Conditional (see validator source). Conditional: When PagePurpose is not null. nullable
`recurringPlan` required	all of HppRecurringPlan	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` required	all of HppCaptureMode	Capture timing for the chargeable Payment flow: `Sale` (default; `null` resolves here) authorizes and captures now; `Authorize` authorizes now and defers capture. Composes with the save-card option to produce the "save card + delayed capture" combination. `Authorize` is rejected on the card-capture page purposes (`SaveCard` and `SaveCardWithInitialCharge`). Conditional: When CaptureMode is not null. Conditional: When IsCardCapture(PagePurpose) is true. nullable
`allowTransparentEmbedding` required	boolean	Opt-in to a see-through backdrop when this page is rendered inside a merchant iframe, so the merchant's own page shows through behind the payment form. `null`/`false` is the default and keeps the page fully opaque. The transparent render additionally requires that the request is genuinely framed (resolved server-side from the browser-set `Sec-Fetch-Dest` header) and that `allowedEmbeddingDomains` is configured, so it applies only inside the parents the merchant allowlisted. A page opened directly as a standalone payment link always paints its own background. Only the backdrop clears: the payment form keeps its own paint. nullable
`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
`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
`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
`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
`products` required	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. Conditional: When Products is not null. nullable
`concurrencyStamp` required	string	nullable

This request body has no documented fields.