Interface CardFormEmbedOptions

Options for embedCardForm and CardFormEmbed.

interface CardFormEmbedOptions {
    onCardNumberChange?: ((event) => void);
    onFormStateChange?: ((state) => void);
    onSubmit?: ((state) => void);
    optionalElements?: boolean | {
        cardNetworksInfo?: boolean;
        cedulaField?: boolean;
        dccInfo?: boolean;
        emailField?: boolean;
        firstNameField?: boolean;
        lastNameField?: boolean;
        storeField?: boolean;
        submitLoader?: boolean;
        transactionAgreement?: boolean;
    };
    paymentMethods?: null | PaymentMethods;
    target: HTMLElement;
}

Properties

onCardNumberChange? onFormStateChange? onSubmit? optionalElements? paymentMethods? target

Properties

Optional onCardNumberChange

onCardNumberChange?: ((event) => void)

Callback function for each card number change.

Emits when:

  • the typed card number validity transitions (invalid -> valid, valid -> invalid, valid -> another valid)
  • the selected saved card changes while viewing the saved cards list

Payload shape depends on whether saved payment methods support is enabled (i.e. paymentMethods is provided):

  • Deprecated (no paymentMethods): { token: string | null } — if token is null, the card number is invalid. Note: The token-only payload is deprecated and will be removed in a future version. Pass paymentMethods so you can rely on CardNumberInfo and use CardFormEmbedState.cardNumberInfo / CardFormEmbedState.paymentMethodData instead.
  • With saved methods: CardNumberInfo — describes either a stored card selection (type: 'STORED_PAYMENT_METHOD') or a new card (type: 'ENCRYPTED_CARD_NUMBER').

Make sure to always use the latest value (token/id) and discard any older ones.

Type declaration

    • (event): void

    • Parameters

      Returns void

Optional onFormStateChange

onFormStateChange?: ((state) => void)

Callback function for each form state change.

Emits when:

Note: token is deprecated and will be removed in a future release. Prefer using CardFormEmbedState.cardNumberInfo for client-side branching and CardFormEmbedState.paymentMethodData as the value you send to your backend.

Type declaration

Optional onSubmit

onSubmit?: ((state) => void)

Callback function for when the user submits a valid form, most of the time using the ↩ Enter key. Optional, improves UX.

Type declaration

Optional optionalElements

optionalElements?: boolean | {
    cardNetworksInfo?: boolean;
    cedulaField?: boolean;
    dccInfo?: boolean;
    emailField?: boolean;
    firstNameField?: boolean;
    lastNameField?: boolean;
    storeField?: boolean;
    submitLoader?: boolean;
    transactionAgreement?: boolean;
}

Controls the visibility of various form elements.

  • true (default): uses each element's default visibility (most are shown; cedulaField is hidden unless explicitly enabled).
  • false: all optional elements are hidden.
  • object: toggle elements individually.

Type declaration

  • Optional cardNetworksInfo?: boolean

    Displays a group of card network logos at the bottom of the form.

  • Optional cedulaField?: boolean

    Note: This field is hidden by default. Set to true to explicitly show it.

  • Optional dccInfo?: boolean

    Displays some info about dynamic currency conversion at the bottom of the form.

  • Optional emailField?: boolean

    Displays an additional text field for the user to enter their email address.

    Do not disable this unless you already provide the user's email address through another method, such as when setting up a new transaction on your backend.

  • Optional firstNameField?: boolean
  • Optional lastNameField?: boolean
  • Optional storeField?: boolean

    Displays a checkbox allowing the user to save the card for future payments.

  • Optional submitLoader?: boolean

    Displays a loading indicator over the form, after triggering the CardFormEmbed.pay method.

  • Optional transactionAgreement?: boolean

    Displays the transaction terms and conditions for the user to accept.

    Do not disable this unless you are already displaying it somewhere else.

Optional paymentMethods

paymentMethods?: null | PaymentMethods

Initial list of saved payment methods used to populate the card form on mount. PaymentMethods

Example

 {
   "paymentMethods": [
     {
       "type": "CARD",
       "storedPaymentMethodData": [
         {
           "type": "CARD",
           "id": "693f3244-9919-49ba-91c8-b095a5cf2ffb",
           "maskedCardNumber": "************9507",
           "expirationDate": "12/26",
           "cvcRequiredForPayment": false,
           "cardBrand": "MASTERCARD",
           "paymentMethodDataOwner": { "name": "Jan Kowal" }
         }
       ]
     }
   ]
 }

target

target: HTMLElement

Specifies a container for the form.

Settings

Member Visibility

Theme

On This Page

onCardNumberChangeonFormStateChangeonSubmitoptionalElementspaymentMethodstarget