Card configurations

The Card element provides a secure, encrypted form for collecting payment details — card number, expiry, and CVC. Card data is encrypted before it leaves the browser. The element can be optionally extended in-place to also collect a billing address with Mapbox-powered autocomplete (billing: true) and identity fields for name, email, and phone (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. Pick the recipe that matches your checkout — the four below cover the common shapes.

For the full options surface, see the Card reference.

Card only

Basic card input. No billing form, no identity fields. The complete event fires once the card number, expiry, and CVC are all valid.

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-powered address autocomplete. The Mapbox access token is bundled by Frame — you do not need to provide one.

The complete event only fires once both the card and the billing address are valid. The change-event payload gains billingAddress and isBillingComplete.

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 — show: true alone renders the field but never blocks completion.

Identity values are returned in the change-event payload under individual, structured to drop straight into a POST /v1/accounts body.

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. The complete event fires once the card, the billing address, and all required: true identity fields are valid.

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");

What changes across the recipes

The billing and identityFields options are set at creation time and cannot be updated after mount. If you need to switch modes mid-flow, unmount and recreate the element. The card iframe's own options (cardTheme, translations, fields, autoFocus) can be updated in place with card.update().

The change and complete payloads grow as you opt in to more sections — the card object is always present, and billingAddress / individual appear only when their configuration is enabled. See the Card reference for the full payload shapes.