Skip to main content

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​

ParameterTypeDescription
containerstring | ElementCSS 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​

ParameterTypeDescription
eventNameKName of the event to listen for
callbackPaymentElementEventsCallback[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();

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​

ParameterTypeDescription
options?PurseHeadlessCheckoutUIOptionsConfiguration 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