Card Element

The Card element provides a secure, encrypted form for collecting payment details including card number, expiry, and CVC. Card data is encrypted before it reaches your servers.

The element can be optionally extended to also collect:

  • A billing address with Mapbox-powered autocomplete — enabled by passing billing: true.
  • Identity fields for name, email, and phone — enabled by passing identityFields. Identity values are returned in a shape ready for the Accounts API.

All extensions are off by default. The bare Card element behavior is unchanged when billing and identityFields are omitted.

FULL EXAMPLE
<body>
  <div id="app">
    <form>
      <div id="card-details"></div>
    </form>
  </div>
  <script src="https://js.framepayments.com/v1/index.js"></script>
  <script>
    (async () => {
      const frame = await Frame.init("<PUBLISHABLE_KEY>");
      const card = await frame.createElement("card", { cardTheme: frame.cardTheme("clean") });
      card.on("complete", payload => {
        console.log(payload)
      })
      card.mount("#card-details");
    })();
  </script>
</body>

Configuration recipes

Card only — basic card input.

CARD ONLY
const card = await frame.createElement("card", {
  cardTheme: frame.cardTheme("minimal"),
});
card.mount("#card-details");

Card + billing address — adds an address form below the card with Mapbox autocomplete. The Mapbox access token is bundled by Frame; you do not need to provide one.

CARD + BILLING
const card = await frame.createElement("card", {
  cardTheme: frame.cardTheme("minimal"),
  billing: true,
});
card.mount("#card-details");

Card + identity — adds personal information fields above the card without a billing form. Each field is opt-in via show: true. Setting required: true gates the complete event on that field being filled.

CARD + IDENTITY
const card = await frame.createElement("card", {
  cardTheme: frame.cardTheme("minimal"),
  identityFields: {
    firstName: { show: true, required: true },
    lastName:  { show: true, required: true },
    email:     { show: true, required: true },
  },
});
card.mount("#card-details");

Card + billing + identity — the full configuration. Billing and identity each operate independently and can be combined.

CARD + BILLING + IDENTITY
const card = await frame.createElement("card", {
  cardTheme: frame.cardTheme("minimal"),
  billing: true,
  identityFields: {
    firstName: { show: true, required: true },
    lastName:  { show: true, required: true },
    email:     { show: true, required: false },
    phoneCountryCode: { show: true },
    phoneNumber:      { show: true },
  },
});
card.mount("#card-details");

API Reference

frame.cardTheme(preset)

Returns a theme object to pass as cardTheme when creating a card element. The theme controls the visual appearance of the card input only — it does not apply to the billing address form or identity fields.

Parameters
presetStringoptional

Required. One of "clean", "minimal", or "material".

CARD THEME
// Apply a preset to the card input
const card = await frame.createElement("card", {
  cardTheme: frame.cardTheme("minimal"),
});

// Extend a preset with custom styles
const card = await frame.createElement("card", {
  cardTheme: frame.cardTheme("minimal", {
    styles: {
      input: { color: "#333", fontSize: "16px" },
    },
  }),
});

frame.createElement("card", options)

Initializes a Card UI Component, simplifying the collection of payment details.

options

The cardTheme, autoFocus, fields, and translations options configure the card input only. They do not affect the billing address form or identity fields.

Options
cardThemeObjectoptional

Controls the visual appearance of the card input. Pass the return value of frame.cardTheme(). Does not apply to the billing address form or identity fields.

autoFocusBooleanoptional

If set to true, the card iframe will automatically steal focus when it mounts.

fieldsString[]optional

Allows you to configure the fields displayed in the card iframe. Possible values are name, number, expiry, and cvc. By default only number, expiry and cvc will be shown.

translationsObjectoptional

Allows you to customize the text shown inside the card iframe.

billingBooleanoptional

When true, renders a billing address form below the card with Mapbox-powered address autocomplete. The card's change and complete payloads will include billingAddress and isBillingComplete. The complete event will only fire once both the card and the billing address are valid. Defaults to false.

identityFieldsObjectoptional

Configure optional identity fields rendered above the card input. If omitted, no identity fields are shown. The complete event will only fire once all required identity fields have been filled.

Fields with show: true but no required are rendered but never block the complete event.

CREATE CARD ELEMENT
const frame = await Frame.init("<PUBLISHABLE_KEY>");
const card = await frame.createElement("card", {
  cardTheme: frame.cardTheme("clean")
});

card.mount("#card-details");

card.mount()

Mounts the component to a specified DOM node.

MOUNT CARD ELEMENT
card.mount("#card-details");

card.on("change")

Subscribes to changes made to the component. Access encrypted card details from the payload passed to the callback. When billing or identityFields are configured, the payload also includes the corresponding sections.

Payload
cardObjectoptional

Information about the entered card, including meta data as well as the encrypted number and CVC.

errorsObject | nulloptional

Validation errors keyed by card field. null when there are no errors. Possible keys are number, cvc, and expiry. Each value is an error code string — see Error Handling for the available codes.

isValidBooleanoptional

Whether or not there are any errors shown. Validation occurs as the user loses focus on a field. You can force validation to occur with the .validate method.

isCompleteBooleanoptional

Whether or not all of the card fields have been filled out successfully with valid values.

billingAddressObjectoptional

Present only when billing: true is configured.

isBillingCompleteBooleanoptional

Present only when billing: true is configured. Whether all required billing address fields are filled.

individualObjectoptional

Present only when identityFields is configured. Structured for the Accounts API.

CARD CHANGE HANDLER
card.on("change", payload => {
  console.log(payload.card.number);
  // when billing is enabled:
  console.log(payload.billingAddress, payload.isBillingComplete);
  // when identityFields is configured:
  console.log(payload.individual);
});

card.on("complete")

Fires once when the form transitions from incomplete to fully valid — that is, when all of the following become true on the same input:

  • The card fields are filled correctly, and
  • The billing address is complete (if billing: true), and
  • All required: true identity fields are filled (if identityFields is configured).

complete fires once per transition. Subsequent edits that keep the form valid will not re-fire complete. If the form becomes incomplete and then valid again, complete will fire again.

The payload shape is identical to the change event.

CARD COMPLETE HANDLER
card.on("complete", payload => {
  console.log(payload.card.number);
  // when billing is enabled:
  console.log(payload.billingAddress);
  // when identityFields is configured:
  console.log(payload.individual);
});

card.on("ready")

Fires once the component has fully loaded and is ready to be displayed.

CARD READY HANDLER
card.on("ready", () => {
  document.getElementById("loading").addClass("hide");
  document.getElementById("card-details").removeClass("hide");
});

card.on("error")

Fires if the component fails to load. Use the change event to respond to validation errors instead.

CARD ERROR HANDLER
card.on("error", () => {
  alert("Opps, something went wrong!");
});

card.update(options)

Updates the configuration for the component after initialization. Any arguments passed will be merged with the initial configuration.

options

Options
cardThemeObjectoptional

Updates the card iframe theme. Pass the return value of frame.cardTheme(). Does not affect the billing address form or identity fields.

autoFocusBooleanoptional

If set to true, the card iframe will automatically steal focus when it mounts.

fieldsString[]optional

Allows you to configure the fields displayed in the card iframe. Possible values are name, number, expiry, and cvc. By default only number, expiry and cvc will be shown.

translationsObjectoptional

Allows you to customize the text shown inside the card iframe.

card.update() only updates the card iframe options. The billing and identityFields configurations are set at element creation time and cannot be updated after mount.

CARD UPDATE CONFIG
card.update({
  translations: {
    number: {
      label: "Your card number"
    }
  }
});

card.validate()

Manually triggers validation for the card details fields.

TRIGGER CARD VALIDATION
card.validate();

card.unmount()

Removes the component from the DOM.

UNMOUNT CARD ELEMENT
card.unmount();