# POST /api/hostedpaymentpages/create-save-card-capture-async Creates a ready-to-use Save Card page for storing a card on file. 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. **Operation ID:** `hostedPaymentPagesCreateSaveCardCapture` ## Authorization Requires: HostedPaymentPage.HostedPaymentPages, HostedPaymentPage.HostedPaymentPages.Create, merchant scope. Required permissions: - `HostedPaymentPage.HostedPaymentPages` - `HostedPaymentPage.HostedPaymentPages.Create` ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | merchantId | query | no | string(uuid) | The owning merchant. | | name | query | no | string | Optional internal name; a default unique name is generated when null. | | suppressNulls | query | no | boolean | If true, omit properties with null values. | ## Responses ### 200 OK **Content type:** `application/json` Schema: `HostedPaymentPageDto` Properties: - `extraProperties` (object) - `id` (string(uuid)) - `creationTime` (string(date-time)): The date and time when this entity was created. - `creatorId` (string(uuid)): The ID of the user who created this entity. - `lastModificationTime` (string(date-time)): The date and time when this entity was last modified. - `lastModifierId` (string(uuid)): The ID of the user who last modified this entity. - `isDeleted` (boolean): Indicates whether this entity has been deleted. - `deleterId` (string(uuid)): The ID of the user who deleted this entity, if it is deleted. - `deletionTime` (string(date-time)): The date and time when this entity was deleted, if it is deleted. - `name` (string) - `concurrencyStamp` (string) - `tenantId` (string(uuid)) - `merchantId` (string(uuid)) - `isActive` (boolean) - `title` (string) - `bannerImage` (string): Filename of the header banner image, as produced by the portal image uploader. This is not a URL: the public page resolves the filename against the hosted-page image CDN container. See `bannerImage` for the write contract. - `hideBanner` (boolean) - `supportRetail` (boolean) - `usePostOnSubmit` (boolean) - `useCaptcha` (boolean) - `supportTokenization` (boolean) - `pageActions` (HostedPaymentPageActionUrls): Represents the set of action URLs for the hosted payment page, including submit, edit, continue, and cancel (Back) actions. - `donations` (HostedPageDonations): Represents donation configuration for the hosted payment page, including enablement and predefined amounts. - `theme` (HostedPageTheme): Represents theme settings for the hosted payment page, including colors, fonts, and header styles. - `fieldsAndPanels` (HostedPageFieldsAndPanels): Represents the configuration of fields and panels for the hosted payment page, including display options and custom labels. - `receiptAndNotifications` (HostedPageReceipts): Represents receipt and notification settings for the hosted payment page, including callback URLs, email options, and notification recipients. - `disclosures` (HostedPageDisclosures): Represents disclosure information for a hosted payment page, including display and acceptance requirements. - `customText` (HostedPageCustomText): Represents custom text and links for a hosted payment page, including terms, promo, support, and privacy policy. - `entityVersion` (integer(int32)) - `isTemplate` (boolean): Deprecated. `true` when a template has been saved from this page. Templates live in the shared template store; this echoes whether a store row exists for the page (or, for a page written under the former inline model that has not been migrated yet, its stored flag). - `templateName` (string): Deprecated. The name of the template saved from this page, echoed from the shared template store; `null` when `isTemplate` is `false`. - `templateDescription` (string): Deprecated. The description of the template saved from this page, echoed from the shared template store; `null` when `isTemplate` is `false`. - `shareTemplate` (boolean): Deprecated. Whether the template saved from this page is shared beyond its merchant, echoed from the shared template store's published state. - `createdFromTemplateId` (string(uuid)): The template this page was created from, or `null` for a page started blank. Set by the create-from-template paths and by the designers' Load Template action when the page is saved. - `pageMode` (object) - `collectBusinessName` (boolean) - `collectPhone` (boolean): Older Streamlined control for the payer phone field. Honored only while `fieldsAndPanels.fieldContactPhone` is `null`; once that visibility is set it decides what the page renders, and this toggle is kept in step with it on every save. - `allowPromoCodes` (boolean) - `collectTaxId` (boolean): Deprecated and inert. No hosted payment page renders a tax ID field, so setting this collects nothing and no tax ID is stored. To capture a buyer tax ID, define a merchant custom field and make it visible on hosted payment pages. - `savePaymentDetails` (boolean) - `declineRetryMode` (object): What a payment link created against this page does when a payment is declined. `null` inherits the tenant default, which is the historical single-use behavior: any declined payment spends the link permanently. - `requireTermsAcceptance` (boolean) - `termsUrl` (string) - `callToActionText` (string) - `productName` (string) - `productDescription` (string) - `productImageBlobName` (string): Filename of the Streamlined order-summary product image, as produced by the portal image uploader. This is not a URL: the public page resolves the filename against the hosted-page image CDN container. See `productImageBlobName` for the write contract. - `fixedAmount` (number(double)) - `allowCustomAmount` (boolean) - `successRedirectUrl` (string) - `successRedirectDelaySeconds` (integer(int32)): Seconds the hosted confirmation panel is shown before the payer is sent to the configured post-payment address. `null` means the page inherits the platform-configured delay. See `successRedirectDelaySeconds` for the write contract. - `paymentMethods` (array) - `customFieldNames` (array): Optional per-page allow-list of merchant custom-field names this page shows and accepts. `null` means "all of the merchant's HPP-visible custom fields"; an explicit empty list means "no merchant custom fields on this page". See `customFieldNames` for the full-replace semantics. - `resolvedCustomFields` (array): The merchant custom fields this page actually shows and accepts, in the order it renders them. Read-only, and resolved on every page the hosted-payment-pages API returns: `customFieldNames` is only the page's selection, and its default (`null`) means "all of the merchant's hosted-page custom fields", so the selection on its own does not tell a caller what the page uses. This resolves it against the merchant's current definitions, applying the same enabled / hosted-page-visible / page-purpose gates the page itself applies, and reports each field's validation rules so a value can be checked before it is posted. The list also carries the fields the merchant keeps hidden from the payer but opted in to accepting a value for through the session API, flagged by `isRenderedToPayer`. Those are reported precisely because the API is the only way to use them. Empty means the page uses no merchant custom fields. Definitions are merchant-global and live, so this tracks the merchant's configuration: renaming or disabling a field changes what this returns for every page that had not scoped itself to a fixed list. Sending it back on a create or update has no effect; the write contract is `customFieldNames`. - `allowedEmbeddingDomains` (array) - `checkoutLayout` (object) - `allowLevel3LineItems` (boolean): Older control for the read-only Level 3 line-item summary. Honored only while `fieldsAndPanels.fieldLevel3Amount` is `null`; once that visibility is set it decides what the page renders, and this toggle is kept in step with it on every save. - `pagePurpose` (object): Instance-level page purpose. `null` resolves to `Payment`. `SaveCard` dedicates the page to capturing and storing the customer's card via a zero-dollar verification (no charge); amount-bearing configuration is hidden in the builder and rejected by the validator, and sessions created against the page inherit the save-card flow. - `recurringPlan` (object): The inlined recurring-schedule definition whose first payment a `SaveCardWithInitialCharge` page charges. `null` for every other purpose. - `captureMode` (object): Capture timing for the chargeable Payment flow. `null` resolves to `Sale`. `Authorize` produces an Authorization with capture deferred. - `allowTransparentEmbedding` (boolean): Opt-in to a see-through backdrop when the page is rendered inside a merchant iframe. `null`/`false` keeps the page opaque (the default). Honoured only when the request is genuinely framed and `allowedEmbeddingDomains` is configured. - `hideTitle` (boolean): Suppress the page `title` on the payer-facing page (both the Classic and the Streamlined renderer). `null`/`false` is the default and renders the title exactly as before. Display-only: the title is still stored, still returned, and still shown on the administrative surfaces (grid, quick view, favorites subtitle). - `hideMerchantName` (boolean): Suppress the merchant business-name line in the Streamlined identity header on the payer-facing page. `null`/`false` is the default. The banner image in that same header stays governed by `hideBanner`. Display-only, and deliberately narrow: the merchant name still reaches the Apple Pay / Paze sheet total label and the NACHA ACH consent copy (and the consent evidence captured with an ACH authorization), which must name the real merchant regardless of this flag. - `hideLoadingIndicator` (boolean): Suppress the gateway's own loading chrome on the payer-facing page: the loading card shown while the page resolves, and the connecting affordance drawn over the prerendered form before the circuit is live. `null`/`false` is the default and shows them exactly as before. For an integrator who embeds the page and paints a loading state of their own, revealing the frame on the `ready` event. Display-only: the session, the payment and the events the page emits are untouched. Honored on the initial document, which the embedding-restriction feature resolves the page for; a deployment with that feature off shows the chrome as before. - `campaignId` (string(uuid)): Optional campaign this page belongs to. Sessions created from this page inherit it when the create request names no campaign of its own, so a merchant can attach a whole page to a campaign once instead of naming it on every link. - `products` (array): The catalog products this page sells, in display order, or `null` for a page priced by a single `productName` with a `fixedAmount` or a payer-entered amount. Each entry references an invoicing catalog product owned by this page's merchant; the price, name and quantity limits are read from the catalog when a link is created and snapshotted onto that link, so editing the catalog never reprices a link already in a payer's hands. - `isLocked` (boolean) - `lockedAt` (string(date-time)) - `lockedByUserId` (string(uuid)) - `lockedByUserName` (string) - `lockReason` (string) ### 403 Forbidden **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 401 Unauthorized **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 400 Bad Request **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 404 Not Found **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 501 Not Implemented **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 500 Internal Server Error **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### default The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. See the error-code reference in this document's description for the values `error.code` can take. **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 429 The request was refused because a rate limit was exceeded, or because something a later retry can clear stopped it. A rate limit refusal carries an `application/problem+json` body: wait at least the interval `Retry-After` names before retrying, then back off. Limits are tuned per deployment, so read the allowance from the response headers rather than assuming a fixed ceiling. Any other refusal carries the standard error envelope as `application/json`, and its `error.code` names the cause. **Content type:** `application/problem+json` Schema: `RateLimitProblemDetails` Properties: - `type` (string) required: The problem type identifier. Always the same value: the failure is the status code itself, so there is no sub-type for a caller to branch on. - `title` (string) required: A short, human-readable summary of the problem type. - `status` (integer(int32)) required: The HTTP status code, repeated in the body as the problem-details format defines. - `detail` (string) required: A human-readable explanation of this occurrence of the problem. - `retryAfterSeconds` (integer(int32)) required: How long to wait before retrying, in whole seconds, carrying the same figure as the `Retry-After` header. Always at least one: a value of zero would invite an immediate retry that is certain to be rejected again. **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ## Example request Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key. ### cURL ```bash curl -X POST "{{BASE_URL}}/api/hostedpaymentpages/create-save-card-capture-async" \ -H "api-key: {{API_KEY}}" ``` ### PowerShell ```powershell $headers = @{ 'api-key' = '{{API_KEY}}' } $response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/hostedpaymentpages/create-save-card-capture-async' ` -Headers $headers ``` ### TypeScript (SDK) ```bash npm install @winkpg/winkpg-api ``` ```typescript import { Configuration, HostedPaymentPagesApi } from '@winkpg/winkpg-api'; const api = new HostedPaymentPagesApi(new Configuration({ basePath: '{{BASE_URL}}', apiKey: '{{API_KEY}}', })); const { data } = await api.hostedPaymentPagesCreateSaveCardCapture(); ``` ### TypeScript (raw HTTP) ```typescript 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(); ``` ### C# (SDK) ```bash dotnet add package WinkPg.Api.Client ``` ```csharp 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) ```csharp 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(); ``` ### Python (SDK) ```bash pip install winkpg-api ``` ```python import winkpg_api configuration = winkpg_api.Configuration(host="{{BASE_URL}}") configuration.api_key["ApiKey"] = "{{API_KEY}}" with winkpg_api.ApiClient(configuration) as client: api = winkpg_api.HostedPaymentPagesApi(client) result = api.hosted_payment_pages_create_save_card_capture() ``` ### Python (raw HTTP) ```bash pip install requests ``` ```python 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() ``` ## See also - [All documentation](https://devportal-simpay-sbx.winkpg.io/llms.txt): the machine-readable index of every public page on this site.