# POST /api/hostedpaymentpages/sessions

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

**Required permissions**: `HostedPaymentPage.HppSessions`, `HostedPaymentPage.HppSessions.Create`  
**Scope**: merchant

**Operation ID:** `POST_api_hostedpaymentpages_sessions`

## 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: `PhoeniXGateHostedPaymentPageCreateHppSessionInput`

_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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": "order-1042",
  "label": "Order #1042",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": {
    "base_amount": "125.00",
    "invoice_number": "INV-2071",
    "customer_email": "pat.smith@example.com",
    "billing_zip": "55401"
  },
  "expirySeconds": null,
  "correlationId": null,
  "label": "Invoice INV-2071",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": 900,
  "correlationId": "cart-7c1f2a",
  "label": null,
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": "https://shop.example.com",
  "enableFieldEvents": true,
  "presentationMode": "Embedded",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Account top-up with card on file",
  "requestedCredentialStorage": "UnscheduledCOF",
  "requireConsent": null,
  "tokenizeOnPayment": true,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Membership renewal with stored card",
  "requestedCredentialStorage": "Recurring, UnscheduledCOF",
  "requireConsent": true,
  "tokenizeOnPayment": true,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Checkout with optional card saving",
  "requestedCredentialStorage": "UnscheduledCOF",
  "requireConsent": false,
  "tokenizeOnPayment": true,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "One-time guest payment",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": false,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Add card to wallet",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": true,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Capture payment method",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": "SaveCard",
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Gold plan enrollment",
  "requestedCredentialStorage": "Recurring, UnscheduledCOF",
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": "SaveCardWithInitialCharge",
  "recurringPlan": {
    "recurringAmount": 29.99,
    "frequency": "Monthly",
    "interval": 1,
    "numberOfPayments": 12,
    "initialChargeAmount": 49.99
  },
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Pre-order hold",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "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",
  "customerId": null,
  "prefilledFields": {
    "base_amount": "125.00",
    "invoice_number": "INV-2071"
  },
  "expirySeconds": null,
  "correlationId": null,
  "label": "Invoice INV-2071",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": {
    "base_amount": "50.00"
  },
  "expirySeconds": null,
  "correlationId": null,
  "label": "Suggested donation",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "amountMode": "Suggested"
}
```

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

Schema: `PhoeniXGateHostedPaymentPageCreateHppSessionInput`

_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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": "order-1042",
  "label": "Order #1042",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": {
    "base_amount": "125.00",
    "invoice_number": "INV-2071",
    "customer_email": "pat.smith@example.com",
    "billing_zip": "55401"
  },
  "expirySeconds": null,
  "correlationId": null,
  "label": "Invoice INV-2071",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": 900,
  "correlationId": "cart-7c1f2a",
  "label": null,
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": "https://shop.example.com",
  "enableFieldEvents": true,
  "presentationMode": "Embedded",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Account top-up with card on file",
  "requestedCredentialStorage": "UnscheduledCOF",
  "requireConsent": null,
  "tokenizeOnPayment": true,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Membership renewal with stored card",
  "requestedCredentialStorage": "Recurring, UnscheduledCOF",
  "requireConsent": true,
  "tokenizeOnPayment": true,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Checkout with optional card saving",
  "requestedCredentialStorage": "UnscheduledCOF",
  "requireConsent": false,
  "tokenizeOnPayment": true,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "One-time guest payment",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": false,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Add card to wallet",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": true,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Capture payment method",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": "SaveCard",
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Gold plan enrollment",
  "requestedCredentialStorage": "Recurring, UnscheduledCOF",
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": "SaveCardWithInitialCharge",
  "recurringPlan": {
    "recurringAmount": 29.99,
    "frequency": "Monthly",
    "interval": 1,
    "numberOfPayments": 12,
    "initialChargeAmount": 49.99
  },
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Pre-order hold",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "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",
  "customerId": null,
  "prefilledFields": {
    "base_amount": "125.00",
    "invoice_number": "INV-2071"
  },
  "expirySeconds": null,
  "correlationId": null,
  "label": "Invoice INV-2071",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": {
    "base_amount": "50.00"
  },
  "expirySeconds": null,
  "correlationId": null,
  "label": "Suggested donation",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "amountMode": "Suggested"
}
```

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

Schema: `PhoeniXGateHostedPaymentPageCreateHppSessionInput`

_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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": "order-1042",
  "label": "Order #1042",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": {
    "base_amount": "125.00",
    "invoice_number": "INV-2071",
    "customer_email": "pat.smith@example.com",
    "billing_zip": "55401"
  },
  "expirySeconds": null,
  "correlationId": null,
  "label": "Invoice INV-2071",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": 900,
  "correlationId": "cart-7c1f2a",
  "label": null,
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": "https://shop.example.com",
  "enableFieldEvents": true,
  "presentationMode": "Embedded",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Account top-up with card on file",
  "requestedCredentialStorage": "UnscheduledCOF",
  "requireConsent": null,
  "tokenizeOnPayment": true,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Membership renewal with stored card",
  "requestedCredentialStorage": "Recurring, UnscheduledCOF",
  "requireConsent": true,
  "tokenizeOnPayment": true,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Checkout with optional card saving",
  "requestedCredentialStorage": "UnscheduledCOF",
  "requireConsent": false,
  "tokenizeOnPayment": true,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "One-time guest payment",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": false,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Add card to wallet",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": true,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Capture payment method",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": "SaveCard",
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Gold plan enrollment",
  "requestedCredentialStorage": "Recurring, UnscheduledCOF",
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": "SaveCardWithInitialCharge",
  "recurringPlan": {
    "recurringAmount": 29.99,
    "frequency": "Monthly",
    "interval": 1,
    "numberOfPayments": 12,
    "initialChargeAmount": 49.99
  },
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": null,
  "expirySeconds": null,
  "correlationId": null,
  "label": "Pre-order hold",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "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",
  "customerId": null,
  "prefilledFields": {
    "base_amount": "125.00",
    "invoice_number": "INV-2071"
  },
  "expirySeconds": null,
  "correlationId": null,
  "label": "Invoice INV-2071",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "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",
  "customerId": null,
  "prefilledFields": {
    "base_amount": "50.00"
  },
  "expirySeconds": null,
  "correlationId": null,
  "label": "Suggested donation",
  "requestedCredentialStorage": null,
  "requireConsent": null,
  "tokenizeOnPayment": null,
  "saveCardOnly": null,
  "parentOrigin": null,
  "enableFieldEvents": false,
  "presentationMode": "Standalone",
  "purpose": "CheckoutLink",
  "level3Data": null,
  "pagePurpose": null,
  "recurringPlan": null,
  "captureMode": null,
  "amountMode": "Suggested"
}
```

## Responses

### 200

OK

**Content type:** `text/plain`

Schema: `PhoeniXGateHostedPaymentPageHppSessionCreatedDto`

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

Schema: `PhoeniXGateHostedPaymentPageHppSessionCreatedDto`

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

Schema: `PhoeniXGateHostedPaymentPageHppSessionCreatedDto`

### 403

Forbidden

**Content type:** `text/plain`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

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

Schema: `WinkPGHttpRemoteServiceErrorResponse`

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

Schema: `WinkPGHttpRemoteServiceErrorResponse`

### 401

Unauthorized

**Content type:** `text/plain`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

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

Schema: `WinkPGHttpRemoteServiceErrorResponse`

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

Schema: `WinkPGHttpRemoteServiceErrorResponse`

### 400

Bad Request

**Content type:** `text/plain`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

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

Schema: `WinkPGHttpRemoteServiceErrorResponse`

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

Schema: `WinkPGHttpRemoteServiceErrorResponse`

### 404

Not Found

**Content type:** `text/plain`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

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

Schema: `WinkPGHttpRemoteServiceErrorResponse`

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

Schema: `WinkPGHttpRemoteServiceErrorResponse`

### 501

Not Implemented

**Content type:** `text/plain`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

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

Schema: `WinkPGHttpRemoteServiceErrorResponse`

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

Schema: `WinkPGHttpRemoteServiceErrorResponse`

### 500

Internal Server Error

**Content type:** `text/plain`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

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

Schema: `WinkPGHttpRemoteServiceErrorResponse`

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

Schema: `WinkPGHttpRemoteServiceErrorResponse`

### 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: `WinkPGHttpRemoteServiceErrorResponse`

## See also

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