PurseHeadlessCheckoutPaymentElement

Interface for managing and interacting with a payment partner's UI component. Provides methods to render, configure, and handle events from payment UIs like credit card forms or digital wallet buttons.

Example

// Get a payment element from a payment method
const paymentElement = method.getPaymentElement();

// Configure the UI See {@link PurseHeadlessCheckoutUIOptions}
paymentElement.setOptions({
  hostedForm: {
    panPlaceholder: 'Enter your card number',
    cvvPlaceholder: 'Enter your CVV'
    // Add more options here
  },
  theme:{
    global:{
       fontSize: "12px"
    }
  }
});

// Render the UI
paymentElement.appendTo('#payment-form');

// Listen for events
paymentElement.on('formValid', () => {
  console.log('Payment UI form is valid');
});

Methods

appendTo()

appendTo(container): 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.

Parameters

Parameter	Type	Description
container	string | Element	CSS selector (e.g., '#payment-form') or HTML element to render the UI into

Returns

void

Throws

If the container element cannot be found or is invalid

Example

// Using a CSS selector
paymentElement.appendTo('#payment-form');

// Using an HTML element
const container = document.getElementById('payment-form');
paymentElement.appendTo(container);

---

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
}

---

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

void

Example

// Listen for the UI ready event
paymentElement.on('formValid', () => {
  console.log('Payment UI form is valid');
});

---

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();

---

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
  }
});

---

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');
}

---

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 layout
• false → the element never rendered; remove the slot entirely

Returns

boolean