> For the complete documentation index, see [llms.txt](https://docs.omni.integratedcommerce.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omni.integratedcommerce.io/glossary/hosted-forms-and-sdk.md).

# Hosted forms and SDK

Definitions of hosted payment sessions, browser integration, wallets, and cardholder authentication.

These terms describe the browser components that collect payment information and the authentication checks used with online card payments.

## 3D Secure and 3DS2

A card-network protocol through which the issuer authenticates the cardholder during an online card payment. These docs use 3DS2 for the version supported by the hosted form. Enable it with `formConfig.enable3DSecure`; the outcome is returned in `threeDs` when applicable. Cardholder authentication and payment approval are separate decisions. See [3D Secure](/hosted-payment-form/3d-secure.md).

## ACS

The Access Control Server used by the issuer to handle 3D Secure cardholder authentication. It assesses the authentication request and can require an interactive challenge. References to an ACS rejection or timeout describe the authentication stage of a card payment.

## Billing information capture level

The setting that determines which address fields the hosted form collects. `billingInfoCaptureLevel: Full` collects the complete billing address; `Minimal` collects country and ZIP or postal code. ACH requires `Full`. In this setting, "capture" means collecting information; it does not mean capturing an authorized card payment. See [Form configuration](/hosted-payment-form/form-configuration.md).

## Browser callback

A notification delivered to JavaScript on the checkout page so it can update the customer's experience. The Hosted Payment Form uses a `postMessage` event when callbacks are enabled; the Payment SDK calls functions supplied during mounting. A callback depends on the browser remaining available. Use verified webhooks and authenticated API retrieval for backend payment records.

## Cardholder challenge

An interactive step in which the issuer asks the customer to prove they are the cardholder during 3D Secure authentication. The hosted form displays the challenge in an overlay and resumes processing when it completes. A token payment that requires a challenge can return `resultCode: 4100` with `threeDsChallenge.redirectUrl`.

## Digital wallet

A customer payment service, such as Apple Pay or Google Pay, that lets the customer select a stored card through the wallet's checkout flow. The Payment SDK displays wallet buttons for eligible card-sale sessions when device, browser, configuration, and domain requirements are met. Wallet buttons are not available for authorization, tokenization, or ACH sessions. See [Wallet availability](/payment-sdk/configuration.md#wallet-availability).

## Domain validation

The process of registering and verifying the website domain where wallet payments will be offered. For Apple Pay, Fiska supplies a validation file that the ISV hosts at the required path on that domain. This enables the wallet integration to recognize the checkout website. See [Apple Pay and Google Pay](/going-live/wallets.md).

## Form configuration

The `formConfig` request object that controls how a hosted session collects billing information, which additional contact fields it requests, and whether it uses 3D Secure. Omitted settings can inherit the payment method's defaults. It controls collection and authentication behavior; the SDK's `theme` controls appearance. See [Form configuration](/hosted-payment-form/form-configuration.md).

## Frictionless authentication

A 3D Secure outcome reached through the issuer's assessment without asking the customer to complete an interactive challenge. The form can continue the payment flow without displaying a challenge overlay. The resulting authentication classification appears in `threeDs.status`.

## Hosted card fields

Card-entry inputs supplied by the payment integration so the customer enters payment details into the payment service's fields. The SDK embeds these inputs in its form and passes supported theme settings to them. Their validation and tokenization failures appear in the SDK's card error codes.

## Hosted Payment Form

A payment page hosted by the payment service and embedded in the ISV's checkout using an iframe URL returned by the API. It collects card or bank-account information for a particular sale, authorization, or tokenization session. Results reach the checkout through configured redirects or browser messages, while configured webhooks notify the backend. See [Hosted Payment Form](/hosted-payment-form/hosted-payment-form.md).

## Iframe

An HTML element that displays a separate webpage inside the checkout page. In the Hosted Payment Form integration, its source is the session URL returned by the API. The form runs in its own browser frame and communicates supported results to the parent page through redirects or `postMessage`.

## Liability shift

The transfer of responsibility for eligible fraud chargebacks from the merchant to the issuer following qualifying 3D Secure authentication. The API exposes the authentication classification through `threeDs.status`. This term describes responsibility for a dispute; it does not confirm payment approval or a merchant deposit. See [3D Secure](/hosted-payment-form/3d-secure.md#what-it-changes).

## Mount and unmount

Mounting displays the Payment SDK form inside the checkout container using `ic.payment.v1.mount(...)`. It returns a `MountController`. Call that controller's `unmount()` when the checkout view is closed or replaced to remove the form and wallet buttons and stop their event handling. See [Payment SDK](/payment-sdk/payment-sdk.md).

## Origin and parent page

An origin is a webpage's scheme, hostname, and port. The parent page is the ISV checkout page containing the payment iframe. When receiving a form message, that page checks the sender's exact origin and source window before reading the result. Derive the expected origin from the returned session URL. See [Origin validation](/hosted-payment-form/best-practices.md#implement-proper-origin-validation).

## Payment SDK

The JavaScript software development kit that mounts the payment form as a web component in the ISV's checkout. It consumes a session created by the backend and provides theming, lifecycle callbacks, and eligible Apple Pay and Google Pay buttons. It uses the same hosted-session endpoints as the iframe integration. See [Payment SDK](/payment-sdk/payment-sdk.md).

## PCI compliance and PCI DSS

Payment Card Industry Data Security Standard (PCI DSS) is the security standard concerned with protecting payment card data. In these docs, PCI compliance refers to the associated security and validation obligations, and `PciCompliance` groups fees for compliance services or non-compliance assessments. The hosted payment flow collects card details outside the ISV's backend. See [Fee categories](/settlement-reporting/fee-charges.md#general-fee-categories).

## PII

Personally identifiable information: information that identifies a person, such as contact details. The form's `piiFields` setting selects the additional `Email` and `Phone` fields to collect. Merchant lifecycle webhook payloads omit underwriting documents, bank details, and tax identifiers, although they can contain business display information.

## postMessage

The browser messaging mechanism used to send a Hosted Payment Form result from the iframe to its parent page. With `useJavaScriptCallback` enabled, the form sends an envelope whose inner `data` contains the result. The parent validates the origin, source window, and message type before using it. See [JavaScript callbacks](/hosted-payment-form/javascript-callbacks.md).

## Redirect and return URL

A redirect moves the customer's browser from the form to another page. The request's `returnUrl` selects the destination used after the flow, and supported result parameters are added to its query string. It lets the ISV show the next checkout screen; browser arrival at that URL alone does not establish a payment outcome. See [Flow completion](/hosted-payment-form/hosted-payment-form.md#flow-completion).

## Redirect hash

The `hash` parameter on server-generated form redirects, calculated with HMAC-SHA256 over `referenceId + resultCode` using the initiating payment method ID as the key. It covers those two values only, and that key can be visible in browser data. Verify it when present and confirm payment through the authenticated API or a verified webhook. See [Verifying the redirect](/hosted-payment-form/redirect-verification.md).

## SAQ and scan

A Self-Assessment Questionnaire (SAQ) is a questionnaire used in PCI compliance validation. A scan is a security check referenced by that validation process. These terms appear in the reported `SaqScanIncomplete` fee name; the name alone does not specify the merchant's obligations or the fee calculation. See [Fee examples by category](/settlement-reporting/fee-charges.md#fees-billed-on-a-monthly-statement-or-invoice).

## SDK callbacks

Functions your application supplies to receive the SDK's browser-side notifications. Each callback has a specific meaning:

| Callback         | Definition                                                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `onReady`        | Notification that the form is ready for the customer to use.                                                              |
| `onComplete`     | Notification containing a transaction result from the gateway, including approvals, declines, and accepted ACH transfers. |
| `onError`        | Notification of an SDK, session, or processing failure. The payment's final outcome can still be unknown.                 |
| `onPaymentEvent` | Optional notification of SDK lifecycle events, such as mounting, readiness, a payment result, or destruction.             |

See [Callback payloads](/payment-sdk/responses.md) for how to interpret the result.

## Session and session expiry

A short-lived checkout context created by the backend for one hosted operation. It fixes the initiating payment method, requested action, amount when applicable, and form settings. The creation response includes an iframe URL, opaque `sessionId`, and `expirationTimestamp`; it does not report a payment result.

Sessions expire 10 minutes after creation, and the SDK session can be loaded once. Reconcile any earlier submission before creating a replacement for an expired or already-used session. See [Session timeouts](/hosted-payment-form/best-practices.md#handle-timeouts-gracefully).

## Shadow DOM

The browser mechanism the Payment SDK uses to keep its component's styles separate from the surrounding checkout page. It prevents ordinary page styles from targeting the form's internal elements. Apply supported appearance changes through `theme`; internal DOM structure is not part of the SDK's public interface. See [Theming](/payment-sdk/theming.md).

## Theme

The SDK configuration object for changing supported visual properties of the payment form and card fields, such as their colors. A theme changes presentation without changing the payment operation or amount. See [Theming](/payment-sdk/theming.md).

## threeDs authentication data

The optional `threeDs` object records the result and evidence of 3D Secure authentication for a card transaction. `threeDs.status` supplies the API's outcome classification. Other fields carry issuer or network evidence when available:

| Term                                                     | Definition                                                                                                         |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| CAVV (`cavv`)                                            | Cardholder Authentication Verification Value: cryptographic evidence that cardholder authentication was performed. |
| ECI (`eci`)                                              | E-commerce Indicator: a card-scheme value describing the authentication and associated liability-shift treatment.  |
| Directory Server transaction ID (`dsTransId`)            | The 3DS2 identifier that connects the authentication exchange with the payment authorization.                      |
| XID (`xid`)                                              | A 3DS1 transaction identifier that some issuers still supply for compatibility.                                    |
| Authentication reason (`threeDReasonId`, `threeDReason`) | The issuer's code and explanation for an authentication failure, when provided.                                    |

See [3D Secure](/hosted-payment-form/3d-secure.md) for its use in the payment flow.

## threeDs authentication status

The API's classification of a cardholder authentication result, exposed as `threeDs.status`. It describes the authentication check, separately from the transaction's processing lifecycle and payment response code:

| Value              | Definition                                                                               |
| ------------------ | ---------------------------------------------------------------------------------------- |
| `Authenticated`    | The issuer fully authenticated the cardholder, with or without an interactive challenge. |
| `Attempted`        | Authentication was attempted but did not fully authenticate the cardholder.              |
| `NotAuthenticated` | The check completed without authenticating the cardholder.                               |
| `Failed`           | The issuer rejected cardholder authentication.                                           |
| `Unavailable`      | An upstream technical issue prevented authentication from completing.                    |
| `NotEnrolled`      | The card was not enrolled in 3D Secure.                                                  |

## Web component

A browser Custom Element that packages the payment form's interface and behavior for mounting in an existing page. The Payment SDK uses a web component with Shadow DOM and exposes its supported configuration and callbacks through `ic.payment.v1.mount(...)`.

## Related

* [Payments and transactions](/glossary/payments-and-transactions.md) - payment operations and stored methods
* [Webhooks and outcomes](/glossary/webhooks-and-outcomes.md) - interpreting results independently of the browser
* [Accounts and API access](/glossary/accounts-and-api-access.md) - environments, authentication, and certification