# POST /api/hostedpaymentpages/sessions

Creates a new HPP session with pre-populated field data.

Send an `idempotencyKey` to make the call safe to retry: the same key with the same request
body returns the session already opened rather than opening a second one, and the response's
`idempotencyStatus` says which happened. Reusing a key with a different body is refused.
The key is a request-body field; no `Idempotency-Key` header is read.

**Operation ID:** `hppSessionCreate`

## Authorization

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

Required permissions:
- `HostedPaymentPage.HppSessions`
- `HostedPaymentPage.HppSessions.Create`

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| suppressNulls | query | no | boolean | If true, omit properties with null values. |

## Request Body

The session creation parameters.

**Content type:** `application/json`

Schema: `CreateHppSessionInput`

Properties:
- `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.
- `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`)
- `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.
- `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.
- `linkLifetime` (object): 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.
- `correlationId` (string): Optional merchant-supplied correlation ID for tracing/debugging. Conditional: When CorrelationId is not null. 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.
- `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.
- `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.
- `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.
- `requestedCredentialStorage` (object): 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.
- `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).
- `declineRetryMode` (object): 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.
- `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.
- `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).
- `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.
- `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` (object): 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.
- `hostChannel` (object): 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.
- `purpose` (object): 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.
- `level3Data` (object): 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.
- `pagePurpose` (object): 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.
- `recurringPlan` (object): 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).
- `captureMode` (object): 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.
- `amountMode` (object): 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.
- `taxAmountMode` (object): 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).
- `shippingAmountMode` (object): 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).
- `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` (object): 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.
- `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.
- `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.
- `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.
- `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.
- `products` (array<HppSessionProductInput>): 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.

_Example: Basic checkout session_

The simplest session: a single-use pay link for the targeted hosted page. The page's own configuration decides everything else (amount fields, capture mode, card storage). The label and correlation id are optional merchant-side references for tracing.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "correlationId": "order-1042",
  "label": "Order #1042",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Prefilled checkout session_

Pre-fills form fields so the customer only enters card details. Use the well-known field keys (base_amount, invoice_number, customer_email, billing/shipping address fields) or an enabled merchant custom field name. A well-known key is rejected when its field is hidden on the targeted page's configuration (base_amount is always accepted); unrecognized keys are ignored when the form renders.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "125.00",
    "invoice_number": "INV-2071",
    "customer_email": "pat.smith@example.com",
    "billing_zip": "55401"
  },
  "linkLifetime": "Session",
  "label": "Invoice INV-2071",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Lock shipping address_

For a cart that already collected the shipping address and priced shipping from it. lockShippingAddress shows the prefilled shipping address display-only, with a note to return to the cart to change it, and the transaction records that address whatever the submit carried. It requires non-blank shipping_address1 and shipping_zip prefilled fields and a page that shows the shipping address. "Same as billing" is not offered, and a digital wallet is not asked for a delivery address. To change the address, create a new session.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "125.00",
    "shipping_address1": "100 Main St",
    "shipping_city": "Minneapolis",
    "shipping_state": "MN",
    "shipping_zip": "55401",
    "shipping_country": "US"
  },
  "linkLifetime": "Session",
  "label": "Order #1042",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered",
  "lockShippingAddress": true
}
```

_Example: Retry-safe session for an order_

Adds an idempotencyKey so the call is safe to resend. The same key with the same body returns the session already opened, with the same session id, link and expiry, instead of opening a second one; the response's idempotencyStatus reports Replayed when that happens, and KeyIgnored when create idempotency is not yet enabled for the merchant. Reusing the key for a different body is refused, so derive it from the thing you are collecting payment for. Up to 128 characters of letters, digits and '.', '_', ':' or '-'. It is a body field: no Idempotency-Key header is read.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "125.00"
  },
  "linkLifetime": "Session",
  "label": "Order #1042",
  "idempotencyKey": "order-1042",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Embedded iframe checkout_

A session embedded in an iframe on the merchant's site. parentOrigin must be a strict HTTPS origin (scheme + host, no path) whose host matches the page's allowed embedding domains; it enables postMessage lifecycle events (ready, payment_succeeded, etc.). enableFieldEvents opts into per-field focus/blur events (field identifiers only, never values). presentationMode=Embedded drops the standalone page chrome (surface, full-viewport height, page gutters) so the form sits flush inside the frame and stays readable down to 320 px; it is chrome only, so the flow, the collected fields and every compliance disclosure are unchanged, and it is independent of parentOrigin (an iframe that wants no postMessage events may set it alone). expirySeconds must stay within the purpose's TTL bounds (60 to 900 seconds for the default CheckoutLink purpose).

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "expirySeconds": 900,
  "linkLifetime": "Session",
  "correlationId": "cart-7c1f2a",
  "parentOrigin": "https://shop.example.com",
  "enableFieldEvents": true,
  "presentationMode": "Embedded",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Charge and store the card (card on file)_

Charges the customer and vaults the card as a reusable payment token when the payment succeeds. requestedCredentialStorage renders the consent prompt on the checkout page and records the consented usage scopes; UnscheduledCOF permits later merchant-initiated charges for pre-agreed events (top-ups, no-show fees, delayed charges). If tokenizeOnPayment is true with no declared scope, the scope defaults to UnscheduledCOF server-side.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "label": "Account top-up with card on file",
  "requestedCredentialStorage": "UnscheduledCOF",
  "tokenizeOnPayment": true,
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Charge and store for recurring billing (bound customer)_

Vaults the card with consent scoped to both scheduled recurring charges and unscheduled card-on-file charges. The flags combine, so declare every scope the stored credential will be used under: a later merchant-initiated charge is rejected unless its reason maps to a consented scope. customerId binds the session to a known customer so the stored credential and consent land on exactly that record instead of an email-based find-or-create; the id must be an active customer under the page's merchant. requireConsent true forces the consent box to be mandatory: submit is blocked until the cardholder ticks it, regardless of the tenant StoredCredentialConsents.RequireConsent default.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "customerId": "00000000-0000-0000-0000-00000000000b",
  "linkLifetime": "Session",
  "label": "Membership renewal with stored card",
  "requestedCredentialStorage": "Recurring, UnscheduledCOF",
  "requireConsent": true,
  "tokenizeOnPayment": true,
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Offer optional card saving_

Shows the save-card box but leaves it optional: requireConsent false renders the prompt yet lets the cardholder decline. Declining completes a normal sale with no token vaulted and no consent record written; ticking it vaults the card for later unscheduled card-on-file charges. Omitting requireConsent instead inherits the tenant StoredCredentialConsents.RequireConsent setting.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "label": "Checkout with optional card saving",
  "requestedCredentialStorage": "UnscheduledCOF",
  "requireConsent": false,
  "tokenizeOnPayment": true,
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Never store the card_

Forces tokenization off for this session regardless of the merchant's tokenize-on-payment default. Use for one-off payments where a stored credential is not wanted. Leaving tokenizeOnPayment null instead defers to the merchant default.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "label": "One-time guest payment",
  "tokenizeOnPayment": false,
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Save a card without charging (save card only)_

Stores the card with no charge: the gateway runs a zero-dollar account verification (authorize $0 with AVS/CVV, immediate void), vaults the card, and captures consent. Requires the merchant's processor to support zero-dollar verification; the request is rejected at creation otherwise. Must not be combined with a non-zero base_amount prefill. The consent scope defaults to UnscheduledCOF when none is declared.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "customerId": "00000000-0000-0000-0000-00000000000b",
  "linkLifetime": "Session",
  "label": "Add card to wallet",
  "saveCardOnly": true,
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Save Card purpose override on a Payment page_

Runs a save-card-only flow against a page whose own purpose is Payment, so one page can back both checkout and card-capture sessions without a second page instance. The resolved purpose drives everything downstream (zero-dollar verification, consent, tokenization), and the same fail-closed checks a dedicated Save Card page enforces are re-checked at session create.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "customerId": "00000000-0000-0000-0000-00000000000b",
  "linkLifetime": "Session",
  "label": "Capture payment method",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "pagePurpose": "SaveCard",
  "amountMode": "CustomerEntered"
}
```

_Example: Save card with initial charge (subscription enrollment)_

Charges the first payment of a recurring schedule as a real sale, vaults the card with Recurring consent, and creates a contract for the remaining payments. The recurring plan override is required for this purpose and must have complete economics: a positive recurring amount, an interval of at least 1, and at least two total payments (the initial charge plus one recurring payment). initialChargeAmount optionally overrides payment one (for example a bundled setup fee); the target page must accept card only. Recurring consent is always captured because the initial charge depends on it; a requestedCredentialStorage sent alongside is unioned in rather than replacing Recurring, so declaring UnscheduledCOF here lets the vaulted card also authorize later ad-hoc merchant-initiated charges beyond the schedule.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "customerId": "00000000-0000-0000-0000-00000000000b",
  "linkLifetime": "Session",
  "label": "Gold plan enrollment",
  "requestedCredentialStorage": "Recurring, UnscheduledCOF",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "pagePurpose": "SaveCardWithInitialCharge",
  "recurringPlan": {
    "recurringAmount": 29.99,
    "frequency": "Monthly",
    "interval": 1,
    "numberOfPayments": 12,
    "initialChargeAmount": 49.99
  },
  "amountMode": "CustomerEntered"
}
```

_Example: Authorize now, capture later_

Overrides the capture mode for this session: the payment is authorized in full but not captured, leaving an Authorization eligible for a later capture or void through the standard transaction actions. Only valid for the chargeable Payment purpose. A null captureMode inherits the page's configured mode; send Sale explicitly to force authorize-and-capture on a page configured for delayed capture.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "label": "Pre-order hold",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "captureMode": "Authorize",
  "amountMode": "CustomerEntered"
}
```

_Example: Fixed amount the customer cannot change (invoice)_

Locks the amount for this session: base_amount is required and renders read-only on the page, and the server verifies the submitted amount matches before creating the transaction. Use for paying an exact invoice. Amount mode is only valid on the chargeable Payment flow; it is rejected on a save-card / card-capture session.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "125.00",
    "invoice_number": "INV-2071"
  },
  "linkLifetime": "Session",
  "label": "Invoice INV-2071",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "Locked"
}
```

_Example: Suggested amount the customer can change (donation)_

Pre-fills base_amount as a suggested amount but leaves it editable, so the cardholder can accept it or enter their own. Use for a suggested donation. base_amount is required for Suggested mode.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "50.00"
  },
  "linkLifetime": "Session",
  "label": "Suggested donation",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "Suggested"
}
```

_Example: Cart-priced tax and shipping on an editable amount_

Your checkout already priced the tax and the delivery, so both are locked: they render read-only and the server charges the session's tax and shipping whatever the page submits. The amount itself stays a suggestion the payer may change. A locked shipping amount wins over the page's flat rate, and zero is free shipping. Omit taxAmountMode or shippingAmountMode and that fee follows amountMode, as it always has. lockShippingAddress fixes the address the shipping was priced for.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "80.00",
    "tax": "6.40",
    "shipping": "0",
    "shipping_address1": "100 Main St",
    "shipping_city": "Phoenix",
    "shipping_state": "AZ",
    "shipping_zip": "85004",
    "shipping_country": "US"
  },
  "linkLifetime": "Session",
  "label": "Cart 4417",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "Suggested",
  "taxAmountMode": "Locked",
  "shippingAmountMode": "Locked",
  "lockShippingAddress": true
}
```

_Example: Link denominated in an explicit currency_

Names the currency the link is denominated in instead of leaving it implied. Only the merchant's own configured currency is accepted: a different code is rejected at create with HostedPaymentPage:HppSession:CurrencyNotSupported rather than accepted and then ignored at charge time. Omit the field and the session takes the merchant's currency anyway; either way the created session reports the currency it settled on in its effective block, so it can be read back rather than inferred.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "125.00"
  },
  "linkLifetime": "Session",
  "label": "Order #1042",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered",
  "currency": "USD"
}
```

_Example: Cart on a page that sells catalog products_

Starts the order on a page that sells catalog products at chosen quantities: two of the first product, and the optional add-on left out (quantity 0). Each entry must name a product the page sells. Quantities only: the prices are snapshotted from the catalog when this link is created, the amount mode is read as Locked on the server-computed subtotal, a supplied base_amount is overwritten, and the customer's final quantities are priced again at submit. Omit the field to start at the page's default quantities.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "label": "Order #1043",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered",
  "products": [
    {
      "productId": "00000000-0000-0000-0000-00000000000c",
      "quantity": 2
    },
    {
      "productId": "00000000-0000-0000-0000-00000000000d"
    }
  ]
}
```

**Content type:** `text/json`

Schema: `CreateHppSessionInput`

Properties:
- `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.
- `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`)
- `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.
- `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.
- `linkLifetime` (object): 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.
- `correlationId` (string): Optional merchant-supplied correlation ID for tracing/debugging. Conditional: When CorrelationId is not null. 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.
- `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.
- `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.
- `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.
- `requestedCredentialStorage` (object): 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.
- `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).
- `declineRetryMode` (object): 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.
- `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.
- `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).
- `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.
- `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` (object): 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.
- `hostChannel` (object): 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.
- `purpose` (object): 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.
- `level3Data` (object): 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.
- `pagePurpose` (object): 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.
- `recurringPlan` (object): 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).
- `captureMode` (object): 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.
- `amountMode` (object): 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.
- `taxAmountMode` (object): 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).
- `shippingAmountMode` (object): 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).
- `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` (object): 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.
- `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.
- `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.
- `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.
- `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.
- `products` (array<HppSessionProductInput>): 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.

_Example: Basic checkout session_

The simplest session: a single-use pay link for the targeted hosted page. The page's own configuration decides everything else (amount fields, capture mode, card storage). The label and correlation id are optional merchant-side references for tracing.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "correlationId": "order-1042",
  "label": "Order #1042",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Prefilled checkout session_

Pre-fills form fields so the customer only enters card details. Use the well-known field keys (base_amount, invoice_number, customer_email, billing/shipping address fields) or an enabled merchant custom field name. A well-known key is rejected when its field is hidden on the targeted page's configuration (base_amount is always accepted); unrecognized keys are ignored when the form renders.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "125.00",
    "invoice_number": "INV-2071",
    "customer_email": "pat.smith@example.com",
    "billing_zip": "55401"
  },
  "linkLifetime": "Session",
  "label": "Invoice INV-2071",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Lock shipping address_

For a cart that already collected the shipping address and priced shipping from it. lockShippingAddress shows the prefilled shipping address display-only, with a note to return to the cart to change it, and the transaction records that address whatever the submit carried. It requires non-blank shipping_address1 and shipping_zip prefilled fields and a page that shows the shipping address. "Same as billing" is not offered, and a digital wallet is not asked for a delivery address. To change the address, create a new session.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "125.00",
    "shipping_address1": "100 Main St",
    "shipping_city": "Minneapolis",
    "shipping_state": "MN",
    "shipping_zip": "55401",
    "shipping_country": "US"
  },
  "linkLifetime": "Session",
  "label": "Order #1042",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered",
  "lockShippingAddress": true
}
```

_Example: Retry-safe session for an order_

Adds an idempotencyKey so the call is safe to resend. The same key with the same body returns the session already opened, with the same session id, link and expiry, instead of opening a second one; the response's idempotencyStatus reports Replayed when that happens, and KeyIgnored when create idempotency is not yet enabled for the merchant. Reusing the key for a different body is refused, so derive it from the thing you are collecting payment for. Up to 128 characters of letters, digits and '.', '_', ':' or '-'. It is a body field: no Idempotency-Key header is read.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "125.00"
  },
  "linkLifetime": "Session",
  "label": "Order #1042",
  "idempotencyKey": "order-1042",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Embedded iframe checkout_

A session embedded in an iframe on the merchant's site. parentOrigin must be a strict HTTPS origin (scheme + host, no path) whose host matches the page's allowed embedding domains; it enables postMessage lifecycle events (ready, payment_succeeded, etc.). enableFieldEvents opts into per-field focus/blur events (field identifiers only, never values). presentationMode=Embedded drops the standalone page chrome (surface, full-viewport height, page gutters) so the form sits flush inside the frame and stays readable down to 320 px; it is chrome only, so the flow, the collected fields and every compliance disclosure are unchanged, and it is independent of parentOrigin (an iframe that wants no postMessage events may set it alone). expirySeconds must stay within the purpose's TTL bounds (60 to 900 seconds for the default CheckoutLink purpose).

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "expirySeconds": 900,
  "linkLifetime": "Session",
  "correlationId": "cart-7c1f2a",
  "parentOrigin": "https://shop.example.com",
  "enableFieldEvents": true,
  "presentationMode": "Embedded",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Charge and store the card (card on file)_

Charges the customer and vaults the card as a reusable payment token when the payment succeeds. requestedCredentialStorage renders the consent prompt on the checkout page and records the consented usage scopes; UnscheduledCOF permits later merchant-initiated charges for pre-agreed events (top-ups, no-show fees, delayed charges). If tokenizeOnPayment is true with no declared scope, the scope defaults to UnscheduledCOF server-side.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "label": "Account top-up with card on file",
  "requestedCredentialStorage": "UnscheduledCOF",
  "tokenizeOnPayment": true,
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Charge and store for recurring billing (bound customer)_

Vaults the card with consent scoped to both scheduled recurring charges and unscheduled card-on-file charges. The flags combine, so declare every scope the stored credential will be used under: a later merchant-initiated charge is rejected unless its reason maps to a consented scope. customerId binds the session to a known customer so the stored credential and consent land on exactly that record instead of an email-based find-or-create; the id must be an active customer under the page's merchant. requireConsent true forces the consent box to be mandatory: submit is blocked until the cardholder ticks it, regardless of the tenant StoredCredentialConsents.RequireConsent default.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "customerId": "00000000-0000-0000-0000-00000000000b",
  "linkLifetime": "Session",
  "label": "Membership renewal with stored card",
  "requestedCredentialStorage": "Recurring, UnscheduledCOF",
  "requireConsent": true,
  "tokenizeOnPayment": true,
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Offer optional card saving_

Shows the save-card box but leaves it optional: requireConsent false renders the prompt yet lets the cardholder decline. Declining completes a normal sale with no token vaulted and no consent record written; ticking it vaults the card for later unscheduled card-on-file charges. Omitting requireConsent instead inherits the tenant StoredCredentialConsents.RequireConsent setting.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "label": "Checkout with optional card saving",
  "requestedCredentialStorage": "UnscheduledCOF",
  "requireConsent": false,
  "tokenizeOnPayment": true,
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Never store the card_

Forces tokenization off for this session regardless of the merchant's tokenize-on-payment default. Use for one-off payments where a stored credential is not wanted. Leaving tokenizeOnPayment null instead defers to the merchant default.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "label": "One-time guest payment",
  "tokenizeOnPayment": false,
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Save a card without charging (save card only)_

Stores the card with no charge: the gateway runs a zero-dollar account verification (authorize $0 with AVS/CVV, immediate void), vaults the card, and captures consent. Requires the merchant's processor to support zero-dollar verification; the request is rejected at creation otherwise. Must not be combined with a non-zero base_amount prefill. The consent scope defaults to UnscheduledCOF when none is declared.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "customerId": "00000000-0000-0000-0000-00000000000b",
  "linkLifetime": "Session",
  "label": "Add card to wallet",
  "saveCardOnly": true,
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Save Card purpose override on a Payment page_

Runs a save-card-only flow against a page whose own purpose is Payment, so one page can back both checkout and card-capture sessions without a second page instance. The resolved purpose drives everything downstream (zero-dollar verification, consent, tokenization), and the same fail-closed checks a dedicated Save Card page enforces are re-checked at session create.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "customerId": "00000000-0000-0000-0000-00000000000b",
  "linkLifetime": "Session",
  "label": "Capture payment method",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "pagePurpose": "SaveCard",
  "amountMode": "CustomerEntered"
}
```

_Example: Save card with initial charge (subscription enrollment)_

Charges the first payment of a recurring schedule as a real sale, vaults the card with Recurring consent, and creates a contract for the remaining payments. The recurring plan override is required for this purpose and must have complete economics: a positive recurring amount, an interval of at least 1, and at least two total payments (the initial charge plus one recurring payment). initialChargeAmount optionally overrides payment one (for example a bundled setup fee); the target page must accept card only. Recurring consent is always captured because the initial charge depends on it; a requestedCredentialStorage sent alongside is unioned in rather than replacing Recurring, so declaring UnscheduledCOF here lets the vaulted card also authorize later ad-hoc merchant-initiated charges beyond the schedule.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "customerId": "00000000-0000-0000-0000-00000000000b",
  "linkLifetime": "Session",
  "label": "Gold plan enrollment",
  "requestedCredentialStorage": "Recurring, UnscheduledCOF",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "pagePurpose": "SaveCardWithInitialCharge",
  "recurringPlan": {
    "recurringAmount": 29.99,
    "frequency": "Monthly",
    "interval": 1,
    "numberOfPayments": 12,
    "initialChargeAmount": 49.99
  },
  "amountMode": "CustomerEntered"
}
```

_Example: Authorize now, capture later_

Overrides the capture mode for this session: the payment is authorized in full but not captured, leaving an Authorization eligible for a later capture or void through the standard transaction actions. Only valid for the chargeable Payment purpose. A null captureMode inherits the page's configured mode; send Sale explicitly to force authorize-and-capture on a page configured for delayed capture.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "label": "Pre-order hold",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "captureMode": "Authorize",
  "amountMode": "CustomerEntered"
}
```

_Example: Fixed amount the customer cannot change (invoice)_

Locks the amount for this session: base_amount is required and renders read-only on the page, and the server verifies the submitted amount matches before creating the transaction. Use for paying an exact invoice. Amount mode is only valid on the chargeable Payment flow; it is rejected on a save-card / card-capture session.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "125.00",
    "invoice_number": "INV-2071"
  },
  "linkLifetime": "Session",
  "label": "Invoice INV-2071",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "Locked"
}
```

_Example: Suggested amount the customer can change (donation)_

Pre-fills base_amount as a suggested amount but leaves it editable, so the cardholder can accept it or enter their own. Use for a suggested donation. base_amount is required for Suggested mode.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "50.00"
  },
  "linkLifetime": "Session",
  "label": "Suggested donation",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "Suggested"
}
```

_Example: Cart-priced tax and shipping on an editable amount_

Your checkout already priced the tax and the delivery, so both are locked: they render read-only and the server charges the session's tax and shipping whatever the page submits. The amount itself stays a suggestion the payer may change. A locked shipping amount wins over the page's flat rate, and zero is free shipping. Omit taxAmountMode or shippingAmountMode and that fee follows amountMode, as it always has. lockShippingAddress fixes the address the shipping was priced for.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "80.00",
    "tax": "6.40",
    "shipping": "0",
    "shipping_address1": "100 Main St",
    "shipping_city": "Phoenix",
    "shipping_state": "AZ",
    "shipping_zip": "85004",
    "shipping_country": "US"
  },
  "linkLifetime": "Session",
  "label": "Cart 4417",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "Suggested",
  "taxAmountMode": "Locked",
  "shippingAmountMode": "Locked",
  "lockShippingAddress": true
}
```

_Example: Link denominated in an explicit currency_

Names the currency the link is denominated in instead of leaving it implied. Only the merchant's own configured currency is accepted: a different code is rejected at create with HostedPaymentPage:HppSession:CurrencyNotSupported rather than accepted and then ignored at charge time. Omit the field and the session takes the merchant's currency anyway; either way the created session reports the currency it settled on in its effective block, so it can be read back rather than inferred.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "125.00"
  },
  "linkLifetime": "Session",
  "label": "Order #1042",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered",
  "currency": "USD"
}
```

_Example: Cart on a page that sells catalog products_

Starts the order on a page that sells catalog products at chosen quantities: two of the first product, and the optional add-on left out (quantity 0). Each entry must name a product the page sells. Quantities only: the prices are snapshotted from the catalog when this link is created, the amount mode is read as Locked on the server-computed subtotal, a supplied base_amount is overwritten, and the customer's final quantities are priced again at submit. Omit the field to start at the page's default quantities.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "label": "Order #1043",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered",
  "products": [
    {
      "productId": "00000000-0000-0000-0000-00000000000c",
      "quantity": 2
    },
    {
      "productId": "00000000-0000-0000-0000-00000000000d"
    }
  ]
}
```

**Content type:** `application/*+json`

Schema: `CreateHppSessionInput`

Properties:
- `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.
- `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`)
- `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.
- `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.
- `linkLifetime` (object): 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.
- `correlationId` (string): Optional merchant-supplied correlation ID for tracing/debugging. Conditional: When CorrelationId is not null. 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.
- `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.
- `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.
- `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.
- `requestedCredentialStorage` (object): 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.
- `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).
- `declineRetryMode` (object): 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.
- `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.
- `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).
- `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.
- `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` (object): 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.
- `hostChannel` (object): 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.
- `purpose` (object): 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.
- `level3Data` (object): 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.
- `pagePurpose` (object): 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.
- `recurringPlan` (object): 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).
- `captureMode` (object): 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.
- `amountMode` (object): 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.
- `taxAmountMode` (object): 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).
- `shippingAmountMode` (object): 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).
- `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` (object): 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.
- `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.
- `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.
- `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.
- `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.
- `products` (array<HppSessionProductInput>): 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.

_Example: Basic checkout session_

The simplest session: a single-use pay link for the targeted hosted page. The page's own configuration decides everything else (amount fields, capture mode, card storage). The label and correlation id are optional merchant-side references for tracing.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "correlationId": "order-1042",
  "label": "Order #1042",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Prefilled checkout session_

Pre-fills form fields so the customer only enters card details. Use the well-known field keys (base_amount, invoice_number, customer_email, billing/shipping address fields) or an enabled merchant custom field name. A well-known key is rejected when its field is hidden on the targeted page's configuration (base_amount is always accepted); unrecognized keys are ignored when the form renders.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "125.00",
    "invoice_number": "INV-2071",
    "customer_email": "pat.smith@example.com",
    "billing_zip": "55401"
  },
  "linkLifetime": "Session",
  "label": "Invoice INV-2071",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Lock shipping address_

For a cart that already collected the shipping address and priced shipping from it. lockShippingAddress shows the prefilled shipping address display-only, with a note to return to the cart to change it, and the transaction records that address whatever the submit carried. It requires non-blank shipping_address1 and shipping_zip prefilled fields and a page that shows the shipping address. "Same as billing" is not offered, and a digital wallet is not asked for a delivery address. To change the address, create a new session.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "125.00",
    "shipping_address1": "100 Main St",
    "shipping_city": "Minneapolis",
    "shipping_state": "MN",
    "shipping_zip": "55401",
    "shipping_country": "US"
  },
  "linkLifetime": "Session",
  "label": "Order #1042",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered",
  "lockShippingAddress": true
}
```

_Example: Retry-safe session for an order_

Adds an idempotencyKey so the call is safe to resend. The same key with the same body returns the session already opened, with the same session id, link and expiry, instead of opening a second one; the response's idempotencyStatus reports Replayed when that happens, and KeyIgnored when create idempotency is not yet enabled for the merchant. Reusing the key for a different body is refused, so derive it from the thing you are collecting payment for. Up to 128 characters of letters, digits and '.', '_', ':' or '-'. It is a body field: no Idempotency-Key header is read.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "125.00"
  },
  "linkLifetime": "Session",
  "label": "Order #1042",
  "idempotencyKey": "order-1042",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Embedded iframe checkout_

A session embedded in an iframe on the merchant's site. parentOrigin must be a strict HTTPS origin (scheme + host, no path) whose host matches the page's allowed embedding domains; it enables postMessage lifecycle events (ready, payment_succeeded, etc.). enableFieldEvents opts into per-field focus/blur events (field identifiers only, never values). presentationMode=Embedded drops the standalone page chrome (surface, full-viewport height, page gutters) so the form sits flush inside the frame and stays readable down to 320 px; it is chrome only, so the flow, the collected fields and every compliance disclosure are unchanged, and it is independent of parentOrigin (an iframe that wants no postMessage events may set it alone). expirySeconds must stay within the purpose's TTL bounds (60 to 900 seconds for the default CheckoutLink purpose).

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "expirySeconds": 900,
  "linkLifetime": "Session",
  "correlationId": "cart-7c1f2a",
  "parentOrigin": "https://shop.example.com",
  "enableFieldEvents": true,
  "presentationMode": "Embedded",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Charge and store the card (card on file)_

Charges the customer and vaults the card as a reusable payment token when the payment succeeds. requestedCredentialStorage renders the consent prompt on the checkout page and records the consented usage scopes; UnscheduledCOF permits later merchant-initiated charges for pre-agreed events (top-ups, no-show fees, delayed charges). If tokenizeOnPayment is true with no declared scope, the scope defaults to UnscheduledCOF server-side.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "label": "Account top-up with card on file",
  "requestedCredentialStorage": "UnscheduledCOF",
  "tokenizeOnPayment": true,
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Charge and store for recurring billing (bound customer)_

Vaults the card with consent scoped to both scheduled recurring charges and unscheduled card-on-file charges. The flags combine, so declare every scope the stored credential will be used under: a later merchant-initiated charge is rejected unless its reason maps to a consented scope. customerId binds the session to a known customer so the stored credential and consent land on exactly that record instead of an email-based find-or-create; the id must be an active customer under the page's merchant. requireConsent true forces the consent box to be mandatory: submit is blocked until the cardholder ticks it, regardless of the tenant StoredCredentialConsents.RequireConsent default.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "customerId": "00000000-0000-0000-0000-00000000000b",
  "linkLifetime": "Session",
  "label": "Membership renewal with stored card",
  "requestedCredentialStorage": "Recurring, UnscheduledCOF",
  "requireConsent": true,
  "tokenizeOnPayment": true,
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Offer optional card saving_

Shows the save-card box but leaves it optional: requireConsent false renders the prompt yet lets the cardholder decline. Declining completes a normal sale with no token vaulted and no consent record written; ticking it vaults the card for later unscheduled card-on-file charges. Omitting requireConsent instead inherits the tenant StoredCredentialConsents.RequireConsent setting.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "label": "Checkout with optional card saving",
  "requestedCredentialStorage": "UnscheduledCOF",
  "requireConsent": false,
  "tokenizeOnPayment": true,
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Never store the card_

Forces tokenization off for this session regardless of the merchant's tokenize-on-payment default. Use for one-off payments where a stored credential is not wanted. Leaving tokenizeOnPayment null instead defers to the merchant default.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "label": "One-time guest payment",
  "tokenizeOnPayment": false,
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Save a card without charging (save card only)_

Stores the card with no charge: the gateway runs a zero-dollar account verification (authorize $0 with AVS/CVV, immediate void), vaults the card, and captures consent. Requires the merchant's processor to support zero-dollar verification; the request is rejected at creation otherwise. Must not be combined with a non-zero base_amount prefill. The consent scope defaults to UnscheduledCOF when none is declared.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "customerId": "00000000-0000-0000-0000-00000000000b",
  "linkLifetime": "Session",
  "label": "Add card to wallet",
  "saveCardOnly": true,
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
```

_Example: Save Card purpose override on a Payment page_

Runs a save-card-only flow against a page whose own purpose is Payment, so one page can back both checkout and card-capture sessions without a second page instance. The resolved purpose drives everything downstream (zero-dollar verification, consent, tokenization), and the same fail-closed checks a dedicated Save Card page enforces are re-checked at session create.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "customerId": "00000000-0000-0000-0000-00000000000b",
  "linkLifetime": "Session",
  "label": "Capture payment method",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "pagePurpose": "SaveCard",
  "amountMode": "CustomerEntered"
}
```

_Example: Save card with initial charge (subscription enrollment)_

Charges the first payment of a recurring schedule as a real sale, vaults the card with Recurring consent, and creates a contract for the remaining payments. The recurring plan override is required for this purpose and must have complete economics: a positive recurring amount, an interval of at least 1, and at least two total payments (the initial charge plus one recurring payment). initialChargeAmount optionally overrides payment one (for example a bundled setup fee); the target page must accept card only. Recurring consent is always captured because the initial charge depends on it; a requestedCredentialStorage sent alongside is unioned in rather than replacing Recurring, so declaring UnscheduledCOF here lets the vaulted card also authorize later ad-hoc merchant-initiated charges beyond the schedule.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "customerId": "00000000-0000-0000-0000-00000000000b",
  "linkLifetime": "Session",
  "label": "Gold plan enrollment",
  "requestedCredentialStorage": "Recurring, UnscheduledCOF",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "pagePurpose": "SaveCardWithInitialCharge",
  "recurringPlan": {
    "recurringAmount": 29.99,
    "frequency": "Monthly",
    "interval": 1,
    "numberOfPayments": 12,
    "initialChargeAmount": 49.99
  },
  "amountMode": "CustomerEntered"
}
```

_Example: Authorize now, capture later_

Overrides the capture mode for this session: the payment is authorized in full but not captured, leaving an Authorization eligible for a later capture or void through the standard transaction actions. Only valid for the chargeable Payment purpose. A null captureMode inherits the page's configured mode; send Sale explicitly to force authorize-and-capture on a page configured for delayed capture.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "label": "Pre-order hold",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "captureMode": "Authorize",
  "amountMode": "CustomerEntered"
}
```

_Example: Fixed amount the customer cannot change (invoice)_

Locks the amount for this session: base_amount is required and renders read-only on the page, and the server verifies the submitted amount matches before creating the transaction. Use for paying an exact invoice. Amount mode is only valid on the chargeable Payment flow; it is rejected on a save-card / card-capture session.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "125.00",
    "invoice_number": "INV-2071"
  },
  "linkLifetime": "Session",
  "label": "Invoice INV-2071",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "Locked"
}
```

_Example: Suggested amount the customer can change (donation)_

Pre-fills base_amount as a suggested amount but leaves it editable, so the cardholder can accept it or enter their own. Use for a suggested donation. base_amount is required for Suggested mode.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "50.00"
  },
  "linkLifetime": "Session",
  "label": "Suggested donation",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "Suggested"
}
```

_Example: Cart-priced tax and shipping on an editable amount_

Your checkout already priced the tax and the delivery, so both are locked: they render read-only and the server charges the session's tax and shipping whatever the page submits. The amount itself stays a suggestion the payer may change. A locked shipping amount wins over the page's flat rate, and zero is free shipping. Omit taxAmountMode or shippingAmountMode and that fee follows amountMode, as it always has. lockShippingAddress fixes the address the shipping was priced for.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "80.00",
    "tax": "6.40",
    "shipping": "0",
    "shipping_address1": "100 Main St",
    "shipping_city": "Phoenix",
    "shipping_state": "AZ",
    "shipping_zip": "85004",
    "shipping_country": "US"
  },
  "linkLifetime": "Session",
  "label": "Cart 4417",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "Suggested",
  "taxAmountMode": "Locked",
  "shippingAmountMode": "Locked",
  "lockShippingAddress": true
}
```

_Example: Link denominated in an explicit currency_

Names the currency the link is denominated in instead of leaving it implied. Only the merchant's own configured currency is accepted: a different code is rejected at create with HostedPaymentPage:HppSession:CurrencyNotSupported rather than accepted and then ignored at charge time. Omit the field and the session takes the merchant's currency anyway; either way the created session reports the currency it settled on in its effective block, so it can be read back rather than inferred.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "prefilledFields": {
    "base_amount": "125.00"
  },
  "linkLifetime": "Session",
  "label": "Order #1042",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered",
  "currency": "USD"
}
```

_Example: Cart on a page that sells catalog products_

Starts the order on a page that sells catalog products at chosen quantities: two of the first product, and the optional add-on left out (quantity 0). Each entry must name a product the page sells. Quantities only: the prices are snapshotted from the catalog when this link is created, the amount mode is read as Locked on the server-computed subtotal, a supplied base_amount is overwritten, and the customer's final quantities are priced again at submit. Omit the field to start at the page's default quantities.

```json
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "label": "Order #1043",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered",
  "products": [
    {
      "productId": "00000000-0000-0000-0000-00000000000c",
      "quantity": 2
    },
    {
      "productId": "00000000-0000-0000-0000-00000000000d"
    }
  ]
}
```

## Responses

### 200

OK

**Content type:** `application/json`

Schema: `HppSessionCreatedDto`

Properties:
- `sessionId` (string(uuid)): The unique session identifier.
- `shortToken` (string): The short URL token for this session (12-character Base62).
- `hppUrl` (string): The absolute HPP payment-link URL using the short token, resolved against the platform's  configured public base URL (`HostedPaymentPage:PublicBaseUrl`, falling back to  `App:SelfUrl`). Example: `https://pay.example.com/pay/s/aB3kX9mZqR`. Callers can use  it directly without resolving it against the host they requested from.
- `expiresAt` (string(date-time)): UTC timestamp when the session will expire, or `null` when the session was created with  the `Permanent` lifetime and never expires on its own. Only a  request that explicitly asked for that lifetime can receive `null` here.
- `correlationId` (string): The correlation ID echoed back from the request, if provided.
- `idempotencyStatus` (object): What the `idempotencyKey` on the request actually did. `Replayed` means this response  is a session that already existed and nothing new was created; `KeyIgnored` means the key  was accepted but bought nothing, because create idempotency is not enabled for this merchant.  Always populated.
- `label` (string): The label echoed back from the request, if provided.
- `cancelUrl` (string): The Back link address stored on the created session, if one was supplied.
- `effective` (object): The shape the server actually resolved this session into, read off the created session rather  than off the request. Several inputs are legitimately accepted and then overridden (a  card-capture purpose forces required consent, a page can veto tokenization, a fixed-amount  page derives an amount mode, a credential-storage scope is defaulted or widened), and the  call still returns 2xx either way. Read this block to confirm the session is shaped the way  you intended, instead of loading the hosted page and inspecting it.

### 409

The idempotency key was already used for a different request
(`HostedPaymentPage:HppSession:CreateIdempotencyKeyReused`), the create it belongs to is
still running (`HostedPaymentPage:HppSession:CreateIdempotencyInProgress`), or the key can
no longer be resolved to a session and so cannot answer for it again
(`HostedPaymentPage:HppSession:CreateIdempotencySessionGone`, which calls for a new key
rather than a retry). Nothing was created in any of the three.

**Content type:** `application/json`

Schema: `RemoteServiceErrorResponse`

Properties:
- `error` (RemoteServiceErrorInfo)

### 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.

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

### cURL

```bash
curl -X POST "{{BASE_URL}}/api/hostedpaymentpages/sessions" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "correlationId": "order-1042",
  "label": "Order #1042",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}'
```

### PowerShell

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

$body = @'
{
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "correlationId": "order-1042",
  "label": "Order #1042",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}
'@

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

### 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.hppSessionCreate({
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "correlationId": "order-1042",
  "label": "Order #1042",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
});
```

### TypeScript (raw HTTP)

```typescript
const response = await fetch('{{BASE_URL}}/api/hostedpaymentpages/sessions', {
  method: 'POST',
  headers: {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "hostedPageId": "00000000-0000-0000-0000-00000000000a",
    "linkLifetime": "Session",
    "correlationId": "order-1042",
    "label": "Order #1042",
    "presentationMode": "Standalone",
    "hostChannel": "ParentWindow",
    "purpose": "CheckoutLink",
    "amountMode": "CustomerEntered"
  }),
});

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;
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<CreateHppSessionInput>("""
    {
      "hostedPageId": "00000000-0000-0000-0000-00000000000a",
      "linkLifetime": "Session",
      "correlationId": "order-1042",
      "label": "Order #1042",
      "presentationMode": "Standalone",
      "hostChannel": "ParentWindow",
      "purpose": "CheckoutLink",
      "amountMode": "CustomerEntered"
    }
    """);

var result = await api.HppSessionCreateAsync(body);
```

### C# (raw HTTP)

```csharp
using System.Text;

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

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

request.Content = new StringContent("""
    {
      "hostedPageId": "00000000-0000-0000-0000-00000000000a",
      "linkLifetime": "Session",
      "correlationId": "order-1042",
      "label": "Order #1042",
      "presentationMode": "Standalone",
      "hostChannel": "ParentWindow",
      "purpose": "CheckoutLink",
      "amountMode": "CustomerEntered"
    }
    """, Encoding.UTF8, "application/json");

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)
    body = winkpg_api.CreateHppSessionInput.from_dict({
      "hostedPageId": "00000000-0000-0000-0000-00000000000a",
      "linkLifetime": "Session",
      "correlationId": "order-1042",
      "label": "Order #1042",
      "presentationMode": "Standalone",
      "hostChannel": "ParentWindow",
      "purpose": "CheckoutLink",
      "amountMode": "CustomerEntered"
    })
    result = api.hpp_session_create(body)
```

### Python (raw HTTP)

```bash
pip install requests
```

```python
import requests

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

body = {
  "hostedPageId": "00000000-0000-0000-0000-00000000000a",
  "linkLifetime": "Session",
  "correlationId": "order-1042",
  "label": "Order #1042",
  "presentationMode": "Standalone",
  "hostChannel": "ParentWindow",
  "purpose": "CheckoutLink",
  "amountMode": "CustomerEntered"
}

response = requests.request(
    "POST",
    "{{BASE_URL}}/api/hostedpaymentpages/sessions",
    headers=headers,
    json=body,
)
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.