# CreateHppSessionInput

A model the API reference uses in a request or a response. The operation pages link every field typed as this model here.

Input DTO for creating a new HPP session.

## Fields
- `hostedPageId` (string(uuid)) required: The HPP configuration ID this session targets. Required.
- `customerId` (string(uuid)): Optional trusted customer id the merchant binds to this session. When supplied, the  session relates to exactly this one customer: customer resolution at consent-capture  time uses this id exclusively and never falls back to the ambiguous cardholder-email  find-or-create, and the resulting transaction's `InvoiceData.CustomerId` is stamped  from it server-side. The id is validated at session-create time to exist, be active, and  belong to the session's merchant; a missing, inactive/soft-deleted, or cross-merchant id  is rejected. `null` (the default) preserves the historical anonymous behavior where  the customer is found-or-created from the cardholder email collected on the form. (nullable)
- `prefilledFields` (object): Pre-populated field key/value pairs used to pre-fill the payment form. Use one of the well-known  field keys listed below, or an enabled merchant custom field name. Keys reserved for sensitive card  data or internal identifiers are always rejected.     Handling of an unrecognized custom-field key depends on whether the target page scopes its custom  fields (see the hosted page's custom-field allow-list). When the page does NOT scope its custom  fields, an unrecognized key is accepted but ignored when the form is rendered (unchanged behavior).  When the page DOES scope its custom fields, a key that is not a well-known field and not one of the  page's allowed custom fields is rejected at session create with an error naming the offending key.       A custom field the merchant has configured to accept a value from this API without showing it to  the payer is also accepted here. Its value is applied to the resulting transaction server-side,  exactly as supplied, and the field is not rendered on the payment form. Because the payer never  sees it and nobody can correct it later, the value is validated against the field's own rules  (maximum length, regular expression, numeric range) at session create: a value that breaks one of  them is rejected here rather than being carried and dropped at payment time. Conditional: Conditional (see validator source). Conditional: When AmountMode == Suggested. Conditional: When RequiresPrefill(TaxAmountMode) is true. Conditional: When RequiresPrefill(ShippingAmountMode) is true. Conditional: When LockShippingAddress is true. Conditional: When PrefilledFields is not null.  Valid keys (in addition to enabled merchant custom field names):  - `allowed_payment_methods`: Comma-separated list of payment-method keys the session permits (e.g. `card,ach`). A directive, not a form field: it narrows the page's rendered payment methods for this session (intersection with the page's configured + capability-filtered methods). Empty or absent means no session-level restriction. Values must be recognized payment-method keys; session creation rejects unrecognized entries - `base_amount`: Base transaction amount - `billing_address1`: Billing address line 1 - `billing_address2`: Billing address line 2 - `billing_city`: Billing city - `billing_country`: Billing country - `billing_first_name`: Billing first name - `billing_last_name`: Billing last name - `billing_phone`: Billing phone number - `billing_state`: Billing state or province - `billing_zip`: Billing ZIP or postal code - `convenience_fee`: Convenience fee amount. Pins the fee on a session whose amount mode is Locked; on any other amount mode the page ignores it and applies the merchant's configured fee - `customer_email`: Customer email address - `invoice_number`: Invoice number - `order_summary`: JSON-serialized order summary containing line items and totals. Used to render a detailed summary panel on the payment page. Value must be a valid `HppOrderSummaryDto` JSON string - `po_number`: Customer code / purchase order number. Applied to `Level2Data.PoNumber` (max 25 characters, alphanumeric), the same slot the Virtual Terminal writes. Gated by the page's `FieldPurchaseOrder` visibility exactly as `InvoiceNumber` is gated by `FieldInvoice` - `promo_code`: A promotion code the link carries, so a merchant can send a payer a link that arrives with the discount already in the box. It is a <b>suggestion</b>, not a grant: the surfaces still evaluate it server-side against the promotion the merchant owns, and a code that no longer applies is refused exactly as a typed one is. Nothing about a prefilled code is trusted, which is why it can safely ride a URL a payer can edit - `shipping`: Shipping amount - `shipping_address1`: Shipping address line 1 - `shipping_address2`: Shipping address line 2 - `shipping_city`: Shipping city - `shipping_country`: Shipping country - `shipping_first_name`: Shipping first name - `shipping_last_name`: Shipping last name - `shipping_phone`: Shipping phone number - `shipping_state`: Shipping state or province - `shipping_zip`: Shipping ZIP or postal code - `suppress_convenience_fee`: Declares that this session authoritatively carries <b>no</b> convenience fee, so the public surfaces must neither seed one from the merchant's convenience-fee configuration nor recompute a percentage one, and must render no fee line and no disclosure block. A directive, not a form field: it states a producer's decision rather than a value the payer sees. Must be one of the `HppConvenienceFeeSuppressionPolicy` values (`true`, `false`); session creation rejects anything else. Absent means no declaration, which is the pre-directive behaviour: the surfaces resolve the fee themselves - `surcharge`: Surcharge amount - `tax`: Tax amount - `tip`: Tip amount - `vault_restriction`: Vault-restriction directive controlling how the payment instrument may be stored for this session. Must be one of the `VaultRestrictionValues` constants (`any`, `allow_new_and_saved`, `saved_only`). A directive, not a form field. Absent means no restriction (`any`) (nullable)
- `prefilledListFields` (object): Optional list-valued prefills for the merchant's multi-value custom fields, keyed by the  custom-field name. Each key must name a merchant custom field flagged multi-value; a key that  names a single-value field, a well-known field, a blocked key, or a key also present in  `prefilledFields` is rejected. The list is checked against the field's own rules  (value cap, maximum length per item, regular expression) at session create, and every item  must be non-empty. The payer sees the values read-only, one per line, and the resulting  transaction carries them as `customFields[].values`. A field configured to accept a  value from this API without showing it to the payer is accepted here too and stamped  server-side. Conditional: When PrefilledListFields is not null. (nullable)
- `expirySeconds` (integer(int32)): Requested session TTL in seconds. If `null`, the default for the resolved  `linkLifetime` is used. Must be within the bounds that lifetime allows, and must  be omitted entirely for `Permanent`, which has no expiry to set. Conditional: When ExpirySeconds is not null. (nullable)
- `linkLifetime` ([HppLinkLifetime](https://devportal.demo.winkpg.io/docs/api/models/HppLinkLifetime.md)): How long this payment link stays payable.  `Session` (the default) is the historical short single-use  checkout session: 60 to 900 seconds, defaulting to 600, still capped by the tenant's own TTL  settings. `Extended` widens the window to 1 hour through 90 days  for a link that is emailed or texted and paid later. `Permanent`  mints a link with no expiry at all, which stops being payable only when it is paid,  cancelled, or revoked.
  Values:
  - `Session`: The historical short single-use checkout session: 60 to 900 seconds, defaulting to 600, and still subject to the tenant's own min/max/default TTL settings. What every caller that does not name a lifetime gets.
  - `Extended`: A long-lived link, bounded by ExtendedMinTtlSeconds and ExtendedMaxTtlSeconds (1 hour to 90 days), for a link that is emailed or texted and paid later. The upper bound is capped by the tenant's HostedPaymentPageSettings.SessionMaxExtendedTtlSeconds setting.
  - `Permanent`: A link that never expires on its own. The session carries no expiry instant and no document time-to-live; it stops being payable only when it is paid, cancelled, or revoked. Requesting an expiry in seconds alongside this is rejected rather than ignored.
- `correlationId` (string): Optional merchant-supplied correlation ID for tracing/debugging. Conditional: When CorrelationId is not null. Max length: 200. (nullable, max length 200)
- `label` (string): Optional human-readable label for identifying this session (e.g., "Invoice #1234"). Conditional: When Label is not null. Max length: 100. (nullable)
- `cancelUrl` (string): Optional address the payer's Back link returns to from the payment form, before paying, such as  your cart page. Overrides the page's own `PageActions.Cancel` address for this session. Conditional: When CancelUrl is not empty. Max length: 200. (nullable)
- `inactiveMessage` (string): Optional plain-text message a payer sees instead of the generic out-of-service copy once this  link is paused, or once a reusable link has filled its completion cap. (nullable, max length 500)
- `idempotencyKey` (string): Optional caller-supplied key that makes this create safe to retry. Send the same key with the  same request body and the gateway returns the session it already opened instead of opening a  second one, so a timeout or a network retry cannot leave you with two payment links for one  order. Conditional: When IdempotencyKey is not empty. (nullable)
- `requestedCredentialStorage` ([StoredCredentialUsage](https://devportal.demo.winkpg.io/docs/api/models/StoredCredentialUsage.md)): Optional. Declares that the merchant intends to capture stored-credential consent on  this session. When set, the HPP checkout page renders the consent prompt; whether the  cardholder must tick it before submitting is governed by `requireConsent` (or  the tenant default when that is unset). `null` or  `None` leaves the prompt off. The flags describe the  permitted usage scopes the cardholder is being asked to consent to (`Recurring`,  `Installment`, `UnscheduledCOF`, `OneTimeFuture`) and are persisted on the  resulting `StoredCredentialConsent` record. 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. (nullable)
  Values:
  - `None`: No permitted uses. Consent record is effectively inactive.
  - `Recurring`: Scheduled recurring charges (subscriptions, membership dues). Maps to Recurring.
  - `Installment`: Fixed-schedule installment plans dividing a known total. Maps to Installment.
  - `UnscheduledCOF`: Merchant-triggered charges for pre-agreed events (balance top-ups, usage overages, no-show fees, delayed charges). Maps to several MIT reason codes including UnscheduledCOF, NoShow, DelayedCharge, and IncrementalAuth.
  - `OneTimeFuture`: A single known future cardholder-initiated purchase the credential was saved for (e.g. "save card for my next order"). Not used for MITs.
- `requireConsent` (boolean): Optional per-session override for whether ticking the stored-credential consent box is  mandatory before the payment can be submitted. `null` (the default) inherits the  tenant-level `StoredCredentialConsents.RequireConsent` setting, preserving historical  behavior. `true` forces consent to be required for this session (the cardholder must  tick the box to pay); `false` makes it optional (the box is still shown, but the  cardholder may submit a normal sale without ticking it: no token is vaulted and no consent  record is written when they decline). (nullable)
- `declineRetryMode` ([HppDeclineRetryMode](https://devportal.demo.winkpg.io/docs/api/models/HppDeclineRetryMode.md)): Optional per-session override of what this payment link does when the processor declines a  payment. `null` (the default) resolves the policy from the targeted hosted page and  then the tenant default, which is the historical single-use behavior. Conditional: When DeclineRetryMode is not null. (nullable)
  Values:
  - `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.
- `tokenizeOnPayment` (boolean): Optional: declares whether the cardholder's card should be vaulted as a reusable  `PaymentToken` when this session's payment succeeds. `null` (the default) defers  to the merchant's `MerchantFeatureSettings.HppTokenizeOnPaymentDefault` flag;  `true` forces tokenization on for this session; `false` forces it off regardless  of the merchant default. (nullable)
- `saveCardOnly` (boolean): Optional: when `true`, this session saves the cardholder's card <b>without</b>  charging it: the gateway runs a zero-dollar account verification (authorize $0 +  AVS/CVV, immediate void) instead of a payment, then vaults the card and captures  consent. Used for "save card now, charge later" onboarding / add-card-to-wallet.  Default `false` (a normal chargeable session). (nullable)
- `parentOrigin` (string): Optional HTTPS origin (scheme + host, e.g. `https://shop.example.com`) of the parent  page that will embed this HPP session in an iframe. When set, the HPP page emits  `postMessage` lifecycle events (`ready`, `session_loaded`,  `payment_succeeded`, etc.) using this value as the `targetOrigin`; never `'*'`.  The host portion must match an entry in the resolved page's `AllowedEmbeddingDomains`  (wildcard subdomains supported). When `null`, postMessage emission is disabled  (fail-closed) and the iframe still works for non-embedded use. Conditional: When ParentOrigin is not empty. Max length: 2048. Conditional: When HostChannel == NativeWebView. (nullable)
- `enableFieldEvents` (boolean): Optional opt-in to per-field `field_focused` / `field_blurred` postMessage  events. When `true`, the iframe attaches a single delegated  focus/blur listener on the form root and emits one envelope per focus boundary with the  element's `data-hpp-field` identifier. <strong>Field values are NEVER included.</strong>  When `false` (the default) no listener is registered, so there is no JS boundary at  which a value could leak. Requires `parentOrigin` to be set: otherwise the  emitter is fail-closed and emits nothing regardless of this flag.
- `presentationMode` ([HppPresentationMode](https://devportal.demo.winkpg.io/docs/api/models/HppPresentationMode.md)): How the public page presents itself for this session.  `Standalone` (the default) renders the full standalone page  exactly as today. `Embedded` renders a chrome-less compact  surface intended for mounting inside a merchant-site iframe: no standalone page background or  full-viewport height, tight paddings, and narrow-width behavior that stays readable at 320 px  without horizontal scrolling.
  Values:
  - `Standalone`: The default, historical behavior: a full standalone page with the surface background, full-viewport minimum height, and the standard outer page padding. null (legacy sessions) resolves here.
  - `Embedded`: A chrome-less compact presentation for mounting inside a merchant-site iframe: no standalone page surface or full-viewport height, tight paddings, and narrow-width behavior that stays readable down to a 320 px viewport without horizontal scrolling.
- `hostChannel` ([HppHostChannel](https://devportal.demo.winkpg.io/docs/api/models/HppHostChannel.md)): Where this session delivers its `postMessage` lifecycle envelopes, and where it accepts  commands from. `ParentWindow` (the default) is the historical  iframe integration: envelopes go to `window.parent` targeted at  `parentOrigin`. `NativeWebView` is for a native iOS,  Android or Flutter app that loads the page in a WebView, where envelopes go to the single  message handler the host app installed instead.
  Values:
  - `ParentWindow`: The default, historical behavior: envelopes are posted to window.parent with the session's parent origin as the target origin, and inbound commands arrive as window messages from that same origin. Emission fails closed when the session carries no parent origin. null (legacy sessions) resolves here.
  - `NativeWebView`: The page is a top-level document inside a native app's WebView, so it has no parent window and no parent origin. Envelopes are delivered to the single message handler the host app installed under the protocol's handler name, and commands arrive through the protocol's entry-point function the host app calls. The host app is the trust boundary: there is no origin to validate, and the embedding-domain allow-list does not apply.
- `purpose` ([HppSessionPurpose](https://devportal.demo.winkpg.io/docs/api/models/HppSessionPurpose.md)): Classifies the calling context that produced this session, which selects the allowed  TTL bounds and any other purpose-specific policy. Defaults to  `CheckoutLink`: the historical merchant-facing pay-link  behavior with a 15-minute TTL ceiling.
  Values:
  - `CheckoutLink`: Standard merchant-facing pay-link session. Short TTL (60s to 900s).
  - `Invoice`: Session created by the invoicing module's send flow to back an invoice's pay-link. Long TTL (1h to 90d) so the link survives net-30 invoice terms with margin for late payment.
  - `PaymentMethodCapture`: Session created by the Merchant Billing module to back a stored-payment-method capture link emailed to a merchant. Long TTL (1h to 90d) so a link sent now can be completed days later, on the merchant's own time, rather than synchronously by an operator.
- `level3Data` ([Level3Data](https://devportal.demo.winkpg.io/docs/api/models/Level3Data.md)): Optional Level 3 commercial-card data: header fields (PO/invoice numbers, ship-from /  destination ZIPs, freight/duty/discount) plus a list of line items. When supplied, the  data is persisted on the session, surfaced read-only on the HPP for the cardholder, and  forwarded onto the resulting `Transaction.Level3Data` so the existing TSYS L3  interchange-qualification mapping consumes it unchanged. `null` (the default)  preserves the historical L2-only flow. Conditional: When Level3Data is not null.
  Fields:
  - `shipFromZip` (string): The ZIP code from where the item is shipped. Conditional: When ShipFromZip is not null. Max length: 10. (nullable, max length 10)
  - `destinationZip` (string): The destination ZIP code for the shipment. Conditional: When DestinationZip is not null. Max length: 10. (nullable, max length 10)
  - `destinationCountryCode` (string): The destination country code for the shipment (ISO 3166-1 alpha-3 format). Conditional: When DestinationCountryCode is not empty. Pattern: ^[A-Z]{3}$. (nullable, max length 3)
  - `invoiceNumber` (string): The invoice number associated with the transaction. Conditional: When InvoiceNumber is not null. Max length: 25. (nullable, max length 25)
  - `orderNumber` (string): The order number for the transaction. Conditional: When OrderNumber is not null. Max length: 25. (nullable, max length 25)
  - `dutyAmount` (number(double)): The total duty amount for the transaction. Must be non-negative. Conditional: When DutyAmount is not null. Must be >= 0. (nullable)
  - `freightAmount` (number(double)): The total freight/shipping amount for the transaction. Must be non-negative. Conditional: When FreightAmount is not null. Must be >= 0. (nullable)
  - `discountAmount` (number(double)): The total discount amount applied at the header level. Must be non-negative. Conditional: When DiscountAmount is not null. Must be >= 0. (nullable)
  - `lineItems` (array<[Level3LineItem](https://devportal.demo.winkpg.io/docs/api/models/Level3LineItem.md)>) required: The list of line items associated with the transaction. (nullable, max items 250)
- `pagePurpose` ([HppPagePurpose](https://devportal.demo.winkpg.io/docs/api/models/HppPagePurpose.md)): Optional per-session override for the targeted page's purpose. `null` (the default) uses  the page's own purpose, so existing integrations are unaffected. A non-null value takes  precedence, letting one page back Payment, SaveCard, and SaveCardWithInitialCharge sessions  without maintaining parallel page instances. Conditional: When PagePurpose is not null. (nullable)
  Values:
  - `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` ([HppRecurringPlan](https://devportal.demo.winkpg.io/docs/api/models/HppRecurringPlan.md)): Optional per-session recurring definition, used only when the resolved `pagePurpose`  is `SaveCardWithInitialCharge`; it then overrides the page's inlined  plan. Required (from this override or the page) for that purpose and validated for complete  economics. Supplying it for any other resolved purpose is rejected. Conditional: Conditional (see validator source).
  Fields:
  - `recurringAmount` (number(double)): The amount charged on each recurring payment after the initial charge. (greater than 0)
  - `frequency` ([Frequency](https://devportal.demo.winkpg.io/docs/api/models/Frequency.md)): The frequency unit of the recurring schedule (e.g. Monthly, Weekly).
    Values:
    - `Secondly`
    - `Minutely`
    - `Hourly`
    - `Daily`
    - `Weekly`
    - `Monthly`
    - `Yearly`
  - `interval` (integer(int32)): The interval multiplier for `frequency` (e.g. `Frequency = Monthly` with  `Interval = 3` is every three months). Defaults to 1. (min 1)
  - `numberOfPayments` (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)
  - `initialChargeAmount` (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)
- `captureMode` ([HppCaptureMode](https://devportal.demo.winkpg.io/docs/api/models/HppCaptureMode.md)): Optional per-session capture-mode override for the chargeable Payment flow.  `Sale` authorizes and captures now (the default; `null` uses the  page value); `Authorize` authorizes now and defers capture. Only valid  on the Payment purpose; an explicit Authorize override against a card-capture purpose is rejected. Conditional: When CaptureMode is not null. Conditional: When IsCardCapture(PagePurpose) is true. (nullable)
  Values:
  - `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).
- `amountMode` ([HppSessionAmountMode](https://devportal.demo.winkpg.io/docs/api/models/HppSessionAmountMode.md)): How this session treats the payment amount, overriding whether the targeted page would let the  cardholder set it. `CustomerEntered` (the default) leaves the  page's own amount behavior in charge; `Suggested` pre-fills an  editable amount (e.g. a suggested donation); `Locked` pre-fills  a read-only amount the cardholder cannot change (e.g. paying an invoice) that the server verifies  on submit. The amount value is supplied via the `base_amount` prefilled field. Conditional: Conditional (see validator source). Must equal CustomerEntered.
  Values:
  - `CustomerEntered`: The default, historical behavior: the session specifies no amount and the cardholder types it on the page. null (legacy sessions) resolves here.
  - `Suggested`: The session specifies an amount (via the prefilled base_amount) that pre-fills the page, but the cardholder may edit it (e.g. a suggested donation).
  - `Locked`: The session specifies an amount (via the prefilled base_amount) that the cardholder cannot change (e.g. paying an invoice). The amount renders read-only but visible, and the server verifies on submit that the charged base amount matches the session's specified amount.
- `taxAmountMode` ([HppSessionAmountMode](https://devportal.demo.winkpg.io/docs/api/models/HppSessionAmountMode.md)): Optional. How this session treats the tax amount, independently of `amountMode`.  Omit it (`null`) and the tax follows `amountMode`, which is the behavior every  integration had before this property existed: a `tax` prefill on a Locked amount is  locked, and on any other amount mode it is a starting value the payer may change.  `Suggested` pre-fills an editable tax from the `tax`  prefilled field; `Locked` pre-fills a read-only tax that the  server charges whatever the payer submits; `CustomerEntered`  leaves the tax to the payer, even on a Locked amount. Conditional: When TaxAmountMode is not null. Conditional: Conditional (see validator source). (nullable)
  Values:
  - `CustomerEntered`: The default, historical behavior: the session specifies no amount and the cardholder types it on the page. null (legacy sessions) resolves here.
  - `Suggested`: The session specifies an amount (via the prefilled base_amount) that pre-fills the page, but the cardholder may edit it (e.g. a suggested donation).
  - `Locked`: The session specifies an amount (via the prefilled base_amount) that the cardholder cannot change (e.g. paying an invoice). The amount renders read-only but visible, and the server verifies on submit that the charged base amount matches the session's specified amount.
- `shippingAmountMode` ([HppSessionAmountMode](https://devportal.demo.winkpg.io/docs/api/models/HppSessionAmountMode.md)): Optional. How this session treats the shipping amount, independently of  `amountMode`. Omit it (`null`) and the shipping amount follows  `amountMode`, exactly as before this property existed.  `Suggested` pre-fills an editable amount from the  `shipping` prefilled field; `Locked` pre-fills a read-only  amount that the server charges whatever the payer submits;  `CustomerEntered` leaves the shipping amount to the payer,  even on a Locked amount. Conditional: When ShippingAmountMode is not null. Conditional: Conditional (see validator source). (nullable)
  Values:
  - `CustomerEntered`: The default, historical behavior: the session specifies no amount and the cardholder types it on the page. null (legacy sessions) resolves here.
  - `Suggested`: The session specifies an amount (via the prefilled base_amount) that pre-fills the page, but the cardholder may edit it (e.g. a suggested donation).
  - `Locked`: The session specifies an amount (via the prefilled base_amount) that the cardholder cannot change (e.g. paying an invoice). The amount renders read-only but visible, and the server verifies on submit that the charged base amount matches the session's specified amount.
- `lockShippingAddress` (boolean): Optional. When `true`, the shipping address supplied through the `shipping_*`  prefilled fields is shown to the payer display-only: they cannot edit it on the hosted page,  and the transaction records that address whatever the submit carried. `false` (the  default) keeps the historical behavior, where a prefilled shipping address is a starting value  the payer may change.
- `customerEmailVisibility` ([HppFieldVisibility](https://devportal.demo.winkpg.io/docs/api/models/HppFieldVisibility.md)): Optional per-session override for whether the payer-facing customer-email field is collected.  `null` (the default) inherits the targeted page's own `FieldCustomerEmail`  configuration, which is what every existing integration gets.  `Hidden` drops the field on a page that shows it,  `Optional` shows it without demanding a value, and  `Required` shows it and blocks submit until it is filled, even  on a page that hides it. One page can therefore serve both a known-customer flow and an  anonymous email-matched flow without a second page configuration. Conditional: When CustomerEmailVisibility is not null. (nullable)
  Values:
  - `Hidden`
  - `Optional`
  - `Required`
- `campaignId` (string(uuid)): Optional campaign this payment link belongs to. Omit it and the session inherits the targeted  page's own campaign, so a merchant can attach a page to a campaign once instead of naming the  campaign on every link it issues. Supply a value and it wins over the page's. (nullable)
- `reusable` (boolean): Whether this link accepts many payers rather than one. Defaults to `false`, which is  the single-use link every caller written before this field existed asks for.
- `maxCompletions` (integer(int32)): How many payments a reusable link accepts before it closes, or `null` for a link that  keeps accepting payers until it is revoked or expires. (nullable)
- `currency` (string): Optional ISO 4217 currency code this link is denominated in, for example `USD`. Omit it  and the session takes the merchant's own configured currency, which is what every link got  before this field existed. Either way the created session reports the currency it settled on,  so an integrator can read it back rather than infer it. Conditional: When Currency is not null. (nullable, max length 3)
- `campaignSource` (string): Optional per-channel source tag for this link: `email`, `sms`, `qr`,  `social`, or whatever short label names the channel you are issuing it through. Mint one  link per channel with a different tag and the campaign report compares them side by side. Conditional: When CampaignSource is not null. (nullable, max length 32)
- `products` (array<[HppSessionProductInput](https://devportal.demo.winkpg.io/docs/api/models/HppSessionProductInput.md)>): Optional cart for a page that sells catalog products: the products to start the order at and  their quantities. Each entry must name a product on the page. A quantity of zero leaves an  optional product out; a required product cannot be left out. Products the cart does not  mention start at the page's default quantity. Rejected on a page that sells no products. Conditional: When Products is not null. (nullable, max items 50)
  Fields of each item:
  - `productId` (string(uuid)) required: The catalog product, which must be one the page sells.
  - `quantity` (number(double)): The quantity to start the order at. Zero leaves an optional product out of the order (the  payer can add it back); a required product needs a quantity inside its limits. (min 0, max 9999)

## See also

- [All documentation](https://devportal.demo.winkpg.io/llms.txt): the machine-readable index of every public page on this site.