PurseHeadlessCheckoutHostedFields
Extends
Omit<PurseHeadlessCheckoutPaymentElement,"appendTo">
Properties
detectedBrands
detectedBrands: Readable<CardScheme[]>;
selectedBrand
selectedBrand: Readable<CardScheme | null>;
supportedBrands
supportedBrands: Readable<CardScheme[]>;
Methods
hasUI()
hasUI(): boolean;
Checks if the payment partner provides a visual UI component. Use this to determine if you need to allocate space in your layout for the payment UI. Some payment methods (like redirect-based flows) might not have a UI component.
Returns
boolean
true if the payment method has a UI component to display, false otherwise
Example
if (paymentElement.hasUI()) {
// Add conditional styles or layout adjustments
// based on the presence of a payment UI
}
Inherited from
PurseHeadlessCheckoutPaymentElement.hasUI
on()
on<K>(eventName, callback): () => void;
Registers an event listener for payment UI events. Listen for events like 'ready', 'change', 'blur', 'focus', etc.
Type Parameters
| Type Parameter |
|---|
K extends PaymentElementEventName |
Parameters
| Parameter | Type | Description |
|---|---|---|
eventName | K | Name of the event to listen for |
callback | PaymentElementEventsCallback[K] | Function to be called when the event occurs |
Returns
A function that unregisters this callback. Call it when the host
component unmounts: registering again on the same element without it leaves the
previous callback live, and one event then fans out to every past registration.
remove() does not unregister for you — the element instance is reused across
remounts, so the callbacks it holds outlive it.
() => void
Example
// Listen for the UI ready event
const off = paymentElement.on('formValid', () => {
console.log('Payment UI form is valid');
});
// …later, on teardown
off();
Inherited from
PurseHeadlessCheckoutPaymentElement.on
remove()
remove(): void;
Removes the payment UI from the DOM and cleans up any associated resources. Call this when the payment UI is no longer needed or when switching payment methods.
Returns
void
Example
// Clean up the payment UI when switching methods
paymentElement.remove();
Inherited from
PurseHeadlessCheckoutPaymentElement.remove
render()
render(): void;
Renders the payment UI into the specified container element. The container can be either a CSS selector string or a direct reference to an HTML element.
Returns
void
Example
// Using a CSS selector
hostedFields.render();
setOptions()
setOptions(options?): void;
Configures the appearance and behavior of the payment UI. Use this to customize the look and feel of the payment form to match your application's design.
Parameters
| Parameter | Type | Description |
|---|---|---|
options? | PurseHeadlessCheckoutUIOptions | Configuration options for the payment UI See PurseHeadlessCheckoutUIOptions for available customization options |
Returns
void
Example
paymentElement.setOptions({
hostedForm: {
panPlaceholder: 'Enter your card number',
cvvPlaceholder: 'Enter your CVV'
// Add more options here
}
});
Inherited from
PurseHeadlessCheckoutPaymentElement.setOptions
setSelectedBrand()
setSelectedBrand(brand): void;
When the card is "co-branded" the user is allowed to set the selected brand.
Parameters
| Parameter | Type | Description |
|---|---|---|
brand | CardScheme | The brand to set as selected |
Returns
void
Example
// Set the selected brand to "VISA"
hostedFields.setSelectedBrand('VISA');
Throws
PurseHeadlessCheckoutError NOT_SUPPORTED_BRAND when the provided brand is not in the supported brands list.
Throws
PurseHeadlessCheckoutError BRAND_NOT_BELONGS_TO_DETECTED when brands are detected and the provided brand is not in the detected list.
validateUi()
validateUi(): Promise<boolean | CreditCardValidateUiResult>;
Force the payment UI to validate the form fields. For credit cards, this checks if all required fields are filled and valid. For other payment methods, this verifies if the UI is in a valid state for submission.
Returns
Promise<boolean | CreditCardValidateUiResult>
A promise that resolves to:
- boolean: true if validation passed, false if failed
- CreditCardValidateUiResult: detailed validation results for credit card forms
Example
const isValid = await paymentElement.validateUi();
if (isValid) {
// show success message
console.log('Payment form is valid');
} else {
// show error message
console.error('Payment form is invalid');
}
Inherited from
PurseHeadlessCheckoutPaymentElement.validateUi
wasEverReady()
wasEverReady(): boolean;
Returns whether the payment UI has ever emitted the ready event.
Used to determine layout behaviour on session termination:
true→ the element was visible; deactivate in place to preserve layoutfalse→ the element never rendered; remove the slot entirely
Returns
boolean