Card
The card-collection element. Wraps an Evervault card iframe and, when configured, renders billing-address and identity-field sections alongside it.
Construct via frame.createElement('card', options) — do not call the constructor directly.
Listen for change and complete events to drive your submit button's enabled state. On complete, send the tokenized payload to your backend, which runs the Account + PaymentMethod + Transfer calls; the charge confirms server-side. Call frame.confirmCardPayment only if the Transfer returns a 3D Secure challenge.
import Frame from '@framepayments/frame-js';
const frame = await Frame.init('pk_sandbox_...');
const card = await frame.createElement('card', { billing: true });
card.on('complete', () => {
submitButton.disabled = false;
});
card.mount('#card-container');
Element options
Account ID whose saved payment methods and identity belong to this card. Saved methods load with the publishable key while your account still allows that legacy read (:legacy_client_credential_pii). When it is off, the element shows the card form without saved methods. Pass clientSecret to load them with the checkout session instead, and to prefill name and email. Selecting a saved method hides the card input and billing form (they reappear when the customer chooses "Add new payment method").
When true, the card input is always visible below the saved methods list even when a saved method is selected. The customer's selection still satisfies the completion requirement — they do not need to fill in the card input as well. Defaults to false, where selecting a saved method hides the card input and shows an "Add new payment method" row instead.
When true, renders a billing address form below the card iframe.
Theme object for the Evervault card iframe. Use frame.cardTheme(preset) to construct one. Styles only the card iframe — does not affect billing address or identity fields.
Checkout client secret (chk_sess_…) minted by your backend with the secret key (POST /v1/checkout_sessions). When set with accountId, the card element loads that account's name and email and prefers this token for saved payment methods. Without it, saved methods still load with the publishable key while :legacy_client_credential_pii is enabled for your account. When that read is off, the element shows the card form without saved methods. Name and email require this token. The token is short-lived. Frame.js has no secret key and cannot mint a replacement.
Unix timestamp (seconds) when clientSecret expires. When it is now or earlier, the element does not send the token. It calls refreshClientSecret once instead, then reads with the replacement.
When set, renders an identity-fields section above the card iframe.
Mints a replacement checkout client secret on your backend. Called once when clientSecret is expired, and once when a read returns 401. Return the new chk_sess_… token, or { clientSecret, expiresAt }.
Controls which saved payment method types are shown when accountId is set. Defaults to 'card'. Pass 'card_and_ach' to also surface saved ACH bank accounts alongside cards.
Renders a "save this payment method" toggle (checkbox) directly beneath the card input, letting the customer decide whether the card they're entering should be saved to the account. Only takes effect when accountId is set — the toggle appears alongside the saved payment methods list.
The customer's choice rides the change / complete payload as savePaymentMethod. The SDK does not persist anything itself; forward the boolean to your backend, which decides whether to store the tokenized card as a reusable payment method. The toggle is hidden (and reported as false) while an already-saved method is selected.
Defaults to a shown-but-unchecked toggle whenever accountId is set. Pass false to suppress it, or an object to set the default checked state and/or a custom label.
Any remaining keys are forwarded to the Evervault card iframe (autoFocus, fields, translations, etc.). See Evervault's docs for the full list.