Update hosted payment page

PUT /api/hostedpaymentpages/{id} deprecated

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

Updates an existing hosted payment page configuration.

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 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	Older Streamlined control for the payer phone field. Honored only while `fieldsAndPanels.fieldContactPhone` is `null`; once that visibility is set it decides what the page renders, and this toggle is overwritten from it on every save, so a write here alongside a set visibility is discarded. Write `fieldsAndPanels.fieldContactPhone` instead. nullable
`allowPromoCodes` 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	Older control for the read-only Level 3 line-item summary. Honored only while `fieldsAndPanels.fieldLevel3Amount` is `null`; once that visibility is set it decides what the page renders, and this toggle is overwritten from it on every save, so a write here alongside a set visibility is discarded. Write `fieldsAndPanels.fieldLevel3Amount` instead. nullable
`pagePurpose` 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.