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:

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 => 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 card form and begins payment.

    If the payment process ends successfully, resolves the promise with EmbedPayResult.

    Otherwise, if the process fails, the promise is rejected with EmbedError. It is essential to catch and handle any possible rejections.

    Finally, if a 3DS challenge is required, the promise is never resolved nor rejected, instead, the user is redirected to the bank to authorize the payment. Afterwards, Paytool moves the user back to one of the redirectUrls (E.g. from the merchant's config) based on the result.

    Simplified example:

    /* once the form is valid */
    const { token } = await cardForm.getFormState();
    const transactionId = await getTransactionIdFromYourServer(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:

    • make sure to set up your redirectUrls for 3DS postbacks
    • you can preemptively use disable after the user submits the form and before requesting a new transaction id
    • you can check whether the form is valid via event listeners or callbacks, or by calling getFormState each time the user submits the form

    Parameters

    • transactionId: string

    Returns Promise<EmbedPayResult>

Settings

Member Visibility

Theme

On This Page

destroydisableenablegetFormStatepay