Class CardFormEmbed

CardFormEmbed is a web component that uses shadow DOM and iframes to properly encapsulate its styles and logic to keep the user safe and prevent CSS conflicts.

It displays the necessary text fields for the user to fill out to pay with the specified card. To initiate the payment after the user has entered the information, use the pay method.

It also extends HTMLElement, providing a familiar API for some custom needs, in addition to the API described on this page.

Styling

You can make use of the component's selector verestro-paytool-card-form-embed to style it based on your needs.

Keep in mind, that since we are working with iframes, the component won't be fully rendered immediately after it's attached to the DOM tree, therefore adding things like e.g. padding, border or margin might create an empty space for a split second. This is also the main reason why embedCardForm returns a promise. To mitigate this issue, the component sets the initialized class once it's fully rendered.

For most basic styles it's recommended to always use the initialized class in your CSS selectors, e.g.

verestro-paytool-card-form-embed.initialized {
  display: block;
  background: #F3F4F6;
  border: 2px solid #E8E8E8;
  border-radius: 4px;
  padding: 25px 28px 28px;
}

Events

Available custom event types and their payloads (event.detail):

embedCardForm already allows you to set up event listeners, but if for some reason you don't want to set them up immediately or your framework makes it unnecessarily hard to do, you can use the standard addEventListener method instead, e.g.:

const cardForm = await Paytool.embedCardForm(/* options */);
cardForm.addEventListener("statechange", event => {
  // event.detail is CardFormEmbedState
  console.log(event.detail);
});
cardForm.addEventListener("cardnumberchange", event => {
  // Deprecated: `token` shape may appear as `{ token: string | null }` when typing a new card number.
  // Prefer listening for `CardNumberInfo` by supplying `paymentMethods` in options.
  console.log(event.detail);
});
// Saved card selections are also surfaced via `cardnumberchange` when using saved methods
cardForm.addEventListener("submit", event => {
  // event.detail is CardFormEmbedState
  console.log(event.detail);
});

All the data you would normally receive from the callback functions of CardFormEmbedOptions is available under the CustomEvent.detail property.

Hierarchy

  • HTMLElement
    • CardFormEmbed

Methods

destroy disable enable getFormState pay

Methods

destroy

  • destroy(): void

  • Destroys the component, cleanly unmounting it from the DOM.

    Returns void

disable

  • disable(): Promise<void>

  • Disables card form, grays out its fields and prevents the user from changing the data.

    Has no effect if the form is already disabled.

    Returns Promise<void>

enable

  • enable(): Promise<void>

  • Enables card form.

    Has no effect if the form is already enabled.

    Returns Promise<void>

getFormState

  • getFormState(): Promise<CardFormEmbedState>

  • Gets current form state.

    Useful, e.g. for submitting, when you don't want to keep a copy of the form state and use the component as the only source of truth instead.

    Returns Promise<CardFormEmbedState>

pay

  • pay(transactionId): Promise<EmbedPayResult>

  • Disables the card form and begins payment.

    • Resolves with EmbedPayResult on non-failing outcomes.
    • Rejects with EmbedError on failure. Always wrap in try/catch.
    • May present overlays for required steps; the promise settles when each flow completes:
      • Dynamic Currency Conversion (DCC) selection
      • 3‑D Secure challenge (new card)
      • 3‑D Secure authentication (saved card)

    Simplified example using getFormState:

    /* once the form is valid */
    const { token, paymentMethodData } = await cardForm.getFormState();
    let transactionId;
    // Prefer using `paymentMethodData`; `token` is deprecated and will be removed.
    if (paymentMethodData) {
      transactionId = await initTransactionInYourServer(paymentMethodData);
    } else {
      transactionId = await initTransactionInYourServer(token);
    }

    try {
      const res = await cardForm.pay(transactionId);
      console.log('Transaction complete, status:', res.status);
    } catch (err) {
      if (!Paytool.isEmbedError(err)) throw err;
      console.log('Transaction failed with status:', err.status);
    }

    Tips:

    • You can preemptively call disable after submit and before you request a new transaction ID.
    • You can verify form validity via events/callbacks or by calling getFormState on submit.

    Parameters

    • transactionId: string

    Returns Promise<EmbedPayResult>

Settings

Member Visibility

Theme

On This Page

destroydisableenablegetFormStatepay