Embedded Fields — Element reference
The catalog of UI elements you can create with vora.elements.create(): the options each accepts, the events it fires, and the value it contributes to the collection's submit() result. In the default "embed" render mode the card element is one iframe that renders the entire payment surface — card fields plus, when the buyer is eligible, Apple Pay / Google Pay — and only email and save-for-future-use are placed separately; in "elements" mode you place cardholder, address and the others as their own fields, and the card is either the combined card box or the three discrete card-number / card-expiry / card-cvc fields. Which mode renders which element, the per-binder capability matrix and the silent fallback: Render modes: embed vs elements; the elements-mode walkthrough: Custom checkout.
Status overview
Every kind you can pass to vora.elements.create(kind, options):
create() kind | What it is |
|---|---|
card | The combined card iframe (number + expiry + CVC in one box) — your payment surface. See card. |
card-number | Discrete PAN field — mount independently in "elements" mode. Adds showIcon. See Discrete card fields. |
card-expiry | Discrete expiry (MM / YY) field. See Discrete card fields. |
card-cvc | Discrete security-code (CVC) field. See Discrete card fields. |
email | VORA-rendered email input with validation. See email. |
address | Billing-address form rendered in your page ("elements" mode). See cardholder and address. |
cardholder | "Name on card" text input rendered in your page ("elements" mode). See cardholder and address. |
save-for-future-use | Compliance-locked opt-in checkbox. See save-for-future-use. |
saved-methods | Discrete saved-card picker for elements mode. It renders its unavailable state for every account — the saved-card read surface behind it is not enabled — never an empty list, so do not build a returning-buyer flow on it. In embed mode the card mount lists a returning buyer's saved cards only when you opt in (details). |
express-checkout | Standalone Apple Pay / Google Pay wallet button row. Use this only when you create the session with integrationMode: "elements" (discrete rendering) — in the default "embed" mode the wallet buttons render inside the card mount instead, with no separate element to add. See Standalone wallets. |
payment-method-picker | Method-selector button row. Surfaces the buyer's choice on submit() and does not tokenize. On the payment connection accounts use today, create() refuses it. Offer card and wallets through card and express-checkout instead. See payment-method-picker. |
The Apple Pay / Google Pay wallet button is the express-checkout element; Standalone wallets covers it. There is no wallet-* element.
Cardholder name and billing address are collected inside the
cardmount in the default"embed"integration mode, so you don't mount separate elements for them. If you create the session withintegrationMode: "elements"(and your account's gateway supports discrete rendering),cardholderandaddressmount as standalone fields instead; see Custom checkout (Elements mode).
Apple Pay & Google Pay — built into the card mount
In the default "embed" integration mode, when the buyer's device supports a wallet (Apple Pay on Safari / iOS, Google Pay with a saved card) and each wallet has a verified entry for your domain (gate 3 below), the wallet button appears as part of the card mount. There's no separate element to add — elements.create('card', …) is the only thing your integration needs. (In integrationMode: "elements" you instead mount the standalone express-checkout element for the wallet buttons.)
Placement inside the mount is decided by the gateway runtime so the buyer sees the same wallet UI they see on other checkouts — sometimes a row above the card inputs, sometimes a tab, sometimes a sheet that takes over the mount when tapped.
Eligibility gates (all must be true for the button to appear):
- The buyer's device + browser supports the wallet. Apple Pay needs Safari (macOS / iOS) or a Mac with Touch ID + paired iPhone. Google Pay needs a browser signed in to a Google account: Chrome, Edge and other Chromium browsers, and from vora.js 1.51.1 Safari and Firefox too, through Google's pop-up window.
- The buyer has a payment method on file with the wallet.
- Your serving domain has an entry for that wallet, one per domain and wallet (How domain entries work).
Failure-mode contract: if any gate fails, the wallet button doesn't appear and the buyer completes checkout via the card field. The button never appears pointing at the wrong destination, and nothing blocks the card field. (The wallet error codes and the wallet field on the result belong to the standalone express-checkout element in elements mode — the embed emits neither.)
Buyer flow when the button appears: the buyer taps the button, authenticates in the wallet sheet (Face ID, Touch ID, the Chrome dialog), and elements.submit() resolves with the same two arms as a card in embed mode: charged: true when nothing was saved, or token when the form saves the card (a buyer on the session and the agreement known when the form loads). The tap has already moved the money on a charge-and-save session — a returned token is a vaulted card, not a handle to charge this payment again; do not call POST /v1/payment_intents for it. Issuer authentication is usually satisfied by the wallet's device attestation; when a challenge is required the embed runs it inside its own iframe. Branch as in SubmitResult shape, and confirm settlement via the webhook before fulfilling.
Domain setup. Apple Pay also needs a verification file hosted on the domain: Apple Pay setup.
Testing. http://localhost shows the card field but not the wallet buttons (Apple Pay refuses non-HTTPS). To test them end-to-end, run your integration on an HTTPS dev domain (any tunnel with a public https:// URL), add that domain under Settings → Wallet Domains in the dashboard and complete the Apple Pay domain verification; for Google Pay, add the same domain with Google Pay selected (no file).
Creating elements
The card element is your payment surface. Create an elements collection, add the card element, and optionally mount email and save-for-future-use alongside it:
const elements = vora.elements.create({
theme: { font: { size: "16px" }, color: { text: "#1a1a1a" } },
});
const card = elements.create("card", {}); // no style → the SDK default look applies
card.mount("#card-element");
// Optional — separate SDK-rendered fields you place and style yourself:
const email = elements.create("email", {});
email.mount("#email-element");
const save = elements.create("save-for-future-use", {});
save.mount("#save-element");
// Submit collects from every mounted element and drives the charge.
// Branch the result in the order under "SubmitResult shape" below —
// error → chargeStatus → token → charged — and confirm settlement via the
// webhook before fulfilling.
const result = await elements.submit();
The elements collection shares theme defaults across child elements.
SubmitResult shape
interface SubmitResult {
token?: string; // vp_pmt_* — present only when a reusable method was vaulted
charged?: boolean; // did money move? true = captured; false = attempted, not moved (held / pending / 3DS); absent = no boolean from the server
chargeStatus?: "succeeded" | "pending" | "requires_action";
redirectUrl?: string; // present ONLY when chargeStatus === "requires_action"
recovered?: true; // outcome recovered by polling after an ambiguous failure
paymentIntentId?: string; // vpi_* — reconcilable reference for a charge
transactionId?: string; // vp_tx_* — reconcilable reference on a guest or recovered charge
last4?: string; // display-only
brand?: string; // "visa" | "mastercard" | … (display-only)
expMonth?: number; // 1-12, camelCase; from 1.45.1 on a save without chargeStatus,
expYear?: number; // absent otherwise: see Tokenization § Card expiry on the result
email?: string;
cardholder?: string; // cardholder name (a plain string, not an object)
billingAddress?: BillingAddressValue;
setupForFutureUse?: boolean; // from the checkout's confirmation only; absent = not confirmed
error?: VoraMirrorError; // present iff submit failed
}
submit() returns one result object, whichever elements you mounted. Discriminate at runtime in this order, handling every chargeStatus before you look at token / charged: requires_action and pending are not completed charges, and a succeeded result can carry a token for a card that has already been charged or held:
error— validation or charge failure. Surfaceresult.error.message. Nothing was charged.chargeStatus: "requires_action"— the charge needs a 3-D Secure challenge and nothing is charged until it completes. Send the buyer toresult.redirectUrl(single-use, bearer-equivalent — do not log or persist it).chargeStatus: "pending"— the charge was submitted and settlement is asynchronous;chargedisfalse. Notokencomes back on this arm; a saved card is read back once the payment settles (charge at submit → saved card). Await thecharge.*webhook, which is authoritative;paymentIntentIdis your reconcilable reference. Do not start a second payment.chargeStatus: "succeeded": charge at submit placed the payment.charged: truemeans the money moved.charged: falsewith apaymentIntentIdmeans acaptureMethod: "manual"session authorized and held it, and nothing moves until you capturepaymentIntentIdfrom your server. Atokenhere is the card saved for a later payment: do not also callPOST /v1/payment_intentsfor this session.tokenwith nochargeStatus: a reusablevp_pmt_*was vaulted. On a charge-and-save session the card was already charged in the same step, so do not also callPOST /v1/payment_intentsfor that session; on a tokenize-only session nothing has been charged and the token is what you charge server-side. Branch on which session you created: Tokenization. On anembedsession a hold never returns atoken: see capture later.charged—truemeans money moved. Alone, the card was charged once and nothing was saved: a payment nobody agreed to save the card on, or inembedmode a guest or a form that loaded without the agreement. Besidetoken, the card was also saved (charge at submit → saved card).falsemeans a charge was attempted and money has not moved;chargeStatussays why (pending,requires_action, orsucceededfor a hold). Absent means the SDK had no boolean from the server: treat it as unknown, never as paid or failed. Fulfill only oncharged === true.last4/brandare display-only.
recovered: true marks an outcome resolved by polling after an ambiguous failure the browser never saw a clean response for. The charge is real — never retry a recovered charge; the token, when a buyer was on the session, arrives on the charge.succeeded webhook. Do not act on charged for a recovered result either: it carries no paymentIntentId, only transactionId. Confirm the payment server-side first. The interface above lists the fields you branch on; email, cardholder, billingAddress, setupForFutureUse and picker ride the same object when their element or flow was involved. AVS/CVV results are not in it: read avs_result_code / cvv_result_code on your server from the charge.succeeded / charge.failed webhooks.
if (result.error) {
// failed — nothing was charged
} else if (result.chargeStatus === "requires_action") {
window.location.href = result.redirectUrl; // 3-D Secure; confirm on the webhook
return;
} else if (result.chargeStatus === "pending") {
// charge in flight — await the charge.* webhook. Do NOT charge again.
} else if (result.recovered) {
// resolved by polling after a lost response. Never fulfil on result.charged
// here; confirm server-side (result.transactionId). Do NOT charge again.
} else if (result.chargeStatus === "succeeded") {
// charge at submit: placed, so do NOT charge again. A token here is the card
// saved for a later payment, not for this one.
if (result.charged === false && result.paymentIntentId) {
holdForCapture(result.paymentIntentId); // captureMethod: "manual": held, not taken
}
} else if (result.token) {
// no chargeStatus. Tokenize-only: charge it server-side. Charge-and-save with
// a buyer: already charged, do NOT charge again (see Tokenization).
} else if (result.charged) {
// guest charge-only (no token)
}
The client result is a UX signal; confirm settlement via the webhook before fulfilling. Optional fields are present when the corresponding element was mounted, except setupForFutureUse: it is present only when consent was sent (the buyer ticked the save box, or your own wording was the consent, with no box mounted) and it comes only from the checkout's confirmation, after a card was registered or charged: true when the card may be charged again later, false when the checkout did not keep it for later. When this submit got no confirmation the field is absent: a payment that stopped for a bank check (chargeStatus: "requires_action"), a chosen saved card, or a wallet-only collection. Absent means "not confirmed by this submit", not "not saved": decide whether a card was saved on your server, from the payment_method.attached webhook or a secret-key read. The token's reusability scope lives server-side (Tokenization).
card — PAN / expiry / CVC iframe
Your payment surface. The iframe is served directly from the active binder's CDN; your DOM never sees the PAN.
Options
interface CardElementOptions {
style?: VoraFieldStyle;
classes?: { focus?: string; invalid?: string; complete?: string };
placeholder?: { number?: string; expiry?: string; cvc?: string }; // these three keys ONLY
challengeTimeout?: number; // ms — default 300_000 (5 minutes); clamped to 600_000 (10-min) max
locale?: string; // BCP-47, e.g. "en-US"; English only today
disable3dsModal?: boolean; // no effect where the processor draws its own challenge sheet
// Card-iframe rendering knobs. Each is opt-in (default off);
// the binder ignores a knob for UI it doesn't render.
disableAutofillAssist?: boolean; // suppress the binder's autofill / login-link pill
hidePostalCode?: boolean; // hide the inline postal-code input the card iframe renders
hideBrandIcon?: boolean; // hide the card-brand icon inside the card-number field
// Payment-method display controls. Monolith-embed binders only;
// direct-card binders ignore them.
display?: "all" | "addOnly" | "storedOnly" | "supportsTokenization"; // default "all"
autoSelectOption?: "first" | "firstStored" | "firstNonStored" | "none"; // default "first"
compactPaymentOptions?: boolean; // default true — tighten spacing between method rows
}
Placeholder text — three keys, and only three
placeholder on the combined card element takes an object, not a string. Exactly three keys are accepted:
const card = collection.create("card", {
placeholder: { number: "Card number", expiry: "MM / YY", cvc: "CVC" },
});
An unrecognised key is not applied — the field keeps its default label and the SDK logs a console.warn naming the accepted keys. The keys are number, expiry, cvc, not the processor's own names (expiryDate, securityCode).
Placeholder text is applied by binders that render their own field labels; a binder whose card iframe doesn't expose per-field placeholders ignores it, the same way it ignores any rendering knob for UI it doesn't draw. On the discrete fields (card-number / card-expiry / card-cvc) placeholder is a plain string on each element instead — see Custom checkout.
Don't confuse this with
style.color.placeholder, which sets the placeholder's colour. The two are unrelated and both can appear in the same options object.
Card-iframe rendering knobs
These three options suppress optional UI the binder renders inside its card iframe. Each is OPT-IN — set to true to suppress, omit (or set to false) to leave the binder's default behavior intact. A knob for UI the binder doesn't render is ignored silently.
| Option | What it does | Typical use case |
|---|---|---|
disableAutofillAssist | Hides the saved-card / login-link autofill pill the card iframe renders inline. | Merchants whose checkout already has its own saved-card UX, or who want a minimal-chrome card field with no autofill prompt. |
hidePostalCode | Removes the postal-code input the card iframe renders alongside PAN / expiry / CVC. | Merchants collecting postal code elsewhere in their own form — avoids asking for it twice. |
hideBrandIcon | Hides the card-brand icon (Visa / Mastercard / …) the binder renders inside the card-number field. | Merchants whose visual style requires a flat-text card field with no inline brand icon. |
Payment-method display controls
On a monolith-embed binder, the card mount renders the full payment-method list — the new-card form, any saved methods, and the Apple Pay / Google Pay buttons (see Apple Pay & Google Pay). These options shape that list. Direct-card binders render only the card field and ignore them. Saved cards are off by default (vora.js 1.50.0 and later). On a form that names a customer, Von Payments decides whether their saved cards are listed. They are listed only when your server created the session with a secret key, a buyerId, a declared save (setupForFutureUse or storedCredentialUse) and savedPaymentMethodOptions.paymentMethodRedisplay: "enabled", and every card on file for that customer was saved with the shopper's agreement to show it again (allow_redisplay: "always", which a ticked save box records). One card without it, such as an imported card or one saved before this was recorded, keeps the whole list off. Otherwise the form uses "addOnly", whatever display you pass. Your display can only narrow that answer: "addOnly" hides an allowed list, and "all" cannot show cards Von Payments did not allow. A form that names no customer keeps your display value.
Saving a card on this form needs your buyerId and the client secret, with or without the list. A session with a declared save (setupForFutureUse, storedCredentialUse or mode: "setup") on the embedded form needs a buyerId (or buyer.externalId): an email alone is refused at create with 422 saved_card_buyer_required. Its page must pass the session's client secret to vora.sessions.retrieve() (vora.js 1.45.1 or later). Without it the form is refused with 401 client_secret_required (frame_client_secret_required in vora.js), and nothing is charged.
| Option | Values | Default | What it does |
|---|---|---|---|
display | "all" · "addOnly" · "storedOnly" · "supportsTokenization" | "all" | Which method surfaces render. "all" shows the full list including the wallet buttons; "addOnly" hides saved methods only (wallet buttons can still show), and is what a customer-named form uses unless saved cards are allowed (above); "storedOnly" shows only saved methods; "supportsTokenization" shows only methods that support tokenization. UI-surface only: it does not change what is charged. |
autoSelectOption | "first" · "firstStored" · "firstNonStored" · "none" | "first" | Auto-selects a method on load so the buyer isn't forced to pick first. Selection is by position — "first" selects whatever the binder lists first (often a wallet when wallets precede the card). Defaults to "first"; pass "none" to leave nothing selected. |
compactPaymentOptions | true · false | true | Tightens the vertical spacing between method rows for a denser layout. Defaults to true; pass false for the spacious layout. |
Events
card.on("ready", () => { /* iframe loaded and accepting input */ });
card.on("change", (event) => {
// event.complete: boolean — all of number/expiry/cvc are valid
// event.error?: { code: string; message: string } // scrubbed validation error; undefined when the field is valid
});
card.on("focus", () => {});
card.on("blur", () => {});
Collect — use the collection's submit()
The canonical collect path is elements.submit() on the collection — see SubmitResult shape for the unified result and its branch order:
const elements = vora.elements.create();
const card = elements.create("card", {}); // no style → the SDK default look applies
card.mount("#card-element");
const result = await elements.submit(); // collection-level submit charges + (when a buyer is on the session) vaults
There is no card.submit() and a card created via elements.create() has no .tokenize() method — submit() is a collection method (elements.submit()), and it is what charges the card and resolves with the flat, five-outcome SubmitResult.
A vaulted vp_pmt_* is bound to the buyer on the session that minted it; its reusability is governed by setup_for_future_use — Tokenization.
Discrete card fields
card-number, card-expiry, and card-cvc are the split-field alternative to the combined card element. Instead of one iframe that renders PAN + expiry + CVC together, you mount three independently-placed secure fields — each into its own container — and style and position them anywhere on your page. The PAN, expiry, and CVC still live inside secure field iframes, so your DOM never sees card data.
The three fields share one secure-fields controller and tokenize together via a single collection.submit(), which resolves the same vp_pmt_* token the combined card element produces. You never tokenize a field on its own.
"elements" mode onlyDiscrete card fields require a session created with integrationMode: "elements" and a binder that renders discrete secure fields. If the active binder doesn't support them, .mount() throws frame_unsupported_element — fall back to the combined card element or route the buyer to a supported binder. In the default "embed" mode the card is always the one combined box.
The rules
- Mount all three.
card-number,card-expiry, andcard-cvcmust all be created and mounted beforesubmit(). Mounting only some can't produce a complete card, sosubmit()returnsframe_field_validation_failed. - Don't mix with the combined
card. A collection holds one card-entry surface — either the combinedcardelement or the three discrete fields, never both. Mixing them returnsframe_field_validation_failedfromsubmit()(they would tokenize twice). - One
submit()for all three. Because they share a controller,collection.submit()vaults all three fields in a single call — you call it once, not per field. - Give each container a fixed height. Each field is a frame that takes its height from its box, so a box with only a
min-heightrenders the field about 150px tall. Set aheight(for example44px) on each card-number, card-expiry and card-cvc container, using your own id or class (#card-number).
Options
Each discrete field takes the same base options; card-number adds showIcon:
interface DiscreteCardFieldOptions {
style?: VoraFieldStyle; // the same token set every element accepts
placeholder?: string; // placeholder shown when the field is empty
disabled?: boolean; // default false — no input accepted when true
}
// card-number only:
interface CardNumberElementOptions extends DiscreteCardFieldOptions {
showIcon?: boolean; // show the card-brand icon inside the field; default false
}
// card-expiry and card-cvc take DiscreteCardFieldOptions as-is.
| Option | Fields | Default | What it does |
|---|---|---|---|
style | all three | SDK default floor, then the collection theme | The unified VoraFieldStyle token set (font + color), merged per property over the SDK default. See Customize. |
placeholder | all three | SDK default (merged per key) — see Customize → Default | Placeholder text shown when the field is empty. |
disabled | all three | false | Disables input on the field. Honored on the direct-card binder only — the secure-fields binder has no native disabled state and drops it. |
showIcon | card-number only | false | Show the card-brand icon (Visa / Mastercard / …) inside the number field. |
Mount and submit
const collection = vora.elements.create({
theme: { font: { size: "16px" }, color: { text: "#1a1a1a" } },
});
// Create + mount all three, each into its own container:
collection.create("card-number", { placeholder: "Card number", showIcon: true }).mount("#card-number");
collection.create("card-expiry", { placeholder: "MM / YY" }).mount("#card-expiry");
collection.create("card-cvc", { placeholder: "CVC" }).mount("#card-cvc");
// One submit() tokenizes all three fields together. Discrete fields are
// elements mode, where a session can charge at submit, so branch every
// outcome (see "SubmitResult shape"):
const result = await collection.submit();
if (result.error) {
// Validation or tokenize failure — surface result.error.message
} else if (result.chargeStatus === "requires_action") {
window.location.href = result.redirectUrl; // 3-D Secure; nothing charged yet
} else if (result.chargeStatus === "pending") {
// charge in flight — await the charge.* webhook. Do NOT charge again.
} else if (result.recovered) {
// resolved by polling after a lost response. Never fulfil on result.charged
// here; confirm server-side (result.transactionId). Do NOT charge again.
} else if (result.chargeStatus === "succeeded") {
// charge at submit: placed, so do NOT charge again. A token here is the card
// saved for a later payment, not for this one.
if (result.charged === false && result.paymentIntentId) {
holdForCapture(result.paymentIntentId); // captureMethod: "manual": held, not taken
}
} else if (result.token) {
// vp_pmt_* minted from all three fields, nothing charged yet. Charge it
// server-side via POST /v1/payment_intents. result.last4 / result.brand are
// display-only.
}
The SubmitResult shape is the same as the combined card element's (SubmitResult shape). Optional sibling-element values (email, cardholder, billingAddress) are present when those elements were also mounted in the collection; setupForFutureUse follows the rule above.
The discrete fields expose the same on() event API as every element, but event granularity depends on the binder behind your account — field-scoped on the direct-card binder, whole-form on secure-fields, where focus / blur do not fire. Treat change as a form-level signal unless you gate on the binder; see Element events.
email — Email input
VORA-rendered <input type="email"> with HTML5-aligned validation. Renders as a standalone field on every binder profile.
Options
interface EmailElementOptions {
placeholder?: string; // default "you@example.com"
required?: boolean; // default true
}
Collect
Returns { email: string } in the submit result. This element renders and validates an email input and hands you the value back — it does not attach the email to the payment or the buyer on its own.
To associate an email with the buyer (so their transactions link together and duplicate-charge lookups work), set buyerEmail when you create the session — see Buyer identification. That is the field that flows to the buyer record.
Use this element when you want VORA to render + validate the email field for you: read result.email from the submit result and pass it as buyerEmail on your server's session-create call (or set buyerEmail directly if you already have the address).
cardholder and address — inputs in your page
Both are "elements"-mode fields, and where they render depends on the field. cardholder is always a plain <input type="text"> that the SDK creates and appends to your container; it carries autocomplete="cc-name", so a card the browser saved fills the name along with the card details, which still go only into the secure card field. address is a small form the SDK renders the same way on a connection whose capability map declares it proxy; on a connection that declares it native, the SDK mounts the processor's own address element in that container, and that element renders inside the processor's isolated iframe like the card field. Which one you get is decided per connection by the server, not by anything you pass.
For the fields that sit in your page (the cardholder name always; the address form on a proxy connection), any other script on the page can read them: a tag manager, an analytics vendor, a compromised dependency. Card number, expiry and CVC never leave the iframe and your SAQ-A scope is unchanged, but the buyer's name, and on those connections the billing address, are only as private as your page-script hygiene. If you cannot vouch for every script on the checkout page, use embed mode, where the card mount renders these fields inside the iframe. The security reference states the same rule, and the capability matrix says which rendering your connection declares.
Options
interface CardholderElementOptions {
placeholder?: string; // default "Name on card"
required?: boolean; // default true
}
interface AddressElementOptions {
mode: "billing"; // the only mode today
fields?: {
line1?: { required?: boolean };
line2?: { hidden?: boolean }; // hide the apartment / suite line
city?: { required?: boolean };
state?: { required?: boolean };
postalCode?: { required?: boolean };
country?: { default?: string }; // ISO 3166-1 alpha-2, default "US"
};
allowedCountries?: string[]; // ISO 3166-1 alpha-2; omit for all
}
Mount and collect
const collection = vora.elements.create();
const card = collection.create("card");
const cardholder = collection.create("cardholder", { placeholder: "Name on card" });
const address = collection.create("address", { mode: "billing", fields: { line2: { hidden: true } } });
card.mount("#card");
cardholder.mount("#cardholder");
address.mount("#billing-address");
const result = await collection.submit();
// result.cardholder → "Ada Lovelace"
// result.billingAddress → { line1, line2?, city, state, postalCode, country }
submit() forwards both values with the card token; you do not send them separately. The billing address is what address verification runs against, so read Address verification for which fields to collect per country.
save-for-future-use — Opt-in checkbox
VORA-rendered checkbox + label that controls the reusability of the token your submit returns; it is always SDK-rendered, on every binder, and has no scope option. Checked, the submit vaults the token as reusable (setup_for_future_use: off_session); unchecked, single-use (null) — usable only by the originating intent. On a charge at submit session an unchecked box saves nothing, unless you declared setupForFutureUse: "on_session" on the session. In embed mode (the default) the payment form decides when it loads, so only a box created with required: true before the card form saves the card (details). A server-side caller can set the scope without the checkbox via POST /v1/tokens. Full model: Tokenization — reusability.
Compliance lock
The checkbox starts unchecked and there is no defaultChecked option: storing a payment method for future merchant-initiated charges needs the buyer's active opt-in, and a pre-checked box would void that consent record.
Options
interface SaveForFutureUseElementOptions {
label?: string; // default "Save this card for future purchases"
displayScope?: "always" | "limited"; // default "always"; "limited" when the label names one arrangement
required?: boolean; // default false; true makes the tick a condition of paying
}
It is its own element: mount it anywhere on your page, for example directly above your pay button, with the label written as the offer. It renders as a plain checkbox and label in your container, so style it with your own CSS. See Put the box where the buyer commits.
Collect
Returns { setupForFutureUse: boolean } — true when the buyer checked the box.
Events
change, focus and blur carry checked: boolean beside complete, so your page can keep Pay disabled until the box is ticked. It reports the tick and cannot set it. With required: true, a card submit() is refused until the box is ticked and wallet buttons reading it are greyed; see Make the box a condition of paying.
payment-method-picker — Method-selector button row
A VORA-rendered button row that lets the buyer pick which payment method to use. Unlike the other elements, the picker does not tokenize or charge — it surfaces the buyer's choice on submit() and leaves your checkout UX to route the next step (mount the card element, hand off to express-checkout, and so on).
On the payment connection accounts use today, do not add the picker. Its capability map reports
"monolith"for the picker in bothembedandelementsmode, soelements.create('payment-method-picker', …)throwsframe_unsupported_element. The buyer pays by card in thecardmount, and by Apple Pay or Google Pay where the device and your domain are eligible (inside thecardmount inembedmode, throughexpress-checkoutinelementsmode). ReadpaymentMethodPickerin your session's capability map before you create the element. The picker renders only where the map reports"proxy".
Options
create() takes a required options object — elements.create('payment-method-picker', { … }).
interface PaymentMethodPickerElementOptions {
style?: VoraFieldStyle;
methods?: PaymentMethodType[]; // omitted/empty = every method the binder supports
defaultMethod?: PaymentMethodType; // pre-select on render (still mutable); default: no pre-selection
buttonLayout?: "horizontal" | "vertical"; // default "horizontal"
}
type PaymentMethodType =
| "card"
| "apple_pay"
| "google_pay"
| "link"
| "cashapp"
| "klarna"
| "affirm";
link, cashapp, klarna and affirm are in the type, but the picker offers none of them today. Do not list them in methods, and do not build a checkout step around them.
| Option | Values | Default | What it does |
|---|---|---|---|
methods | PaymentMethodType[] | every supported method | Methods to surface, in render order (left-to-right for horizontal, top-to-bottom for vertical). The list is capability-filtered against the active session's binder — see below. |
defaultMethod | a PaymentMethodType | none | Pre-selects a method on render so the buyer isn't forced to pick first. The selection is still mutable. A defaultMethod that isn't a recognized PaymentMethodType throws frame_field_validation_failed at create time. |
buttonLayout | "horizontal" · "vertical" | "horizontal" | Row of buttons (wraps on narrow viewports) vs. one button per row. |
Capability filtering
The methods you pass are intersected with the session's binder capability map: any method the binder declares not_available for is hidden even if you listed it, and methods you didn't list are hidden too. When you explicitly supply methods and one or more are dropped, the SDK emits a one-time console.warn naming the filtered methods so the filtering isn't silent. If the intersection is empty, mount() throws frame_unsupported_element — review your methods array or route the buyer to a binder that supports at least one of them.
Collect — the nested picker result
The picker contributes a nested picker group to the collection's SubmitResult, present only when the element was mounted. The picker neither charges nor vaults, so it never sets token / charged:
interface PickerSubmitResult {
selectedMethod: PaymentMethodType; // the method the buyer chose
}
const elements = vora.elements.create();
const picker = elements.create("payment-method-picker", {
methods: ["card", "apple_pay", "google_pay"],
defaultMethod: "card",
buttonLayout: "horizontal",
});
picker.mount("#picker-element");
const result = await elements.submit();
if (result.error === undefined) {
switch (result.picker?.selectedMethod) {
case "card":
// mount the `card` element and run the card path
break;
case "apple_pay":
case "google_pay":
// hand off to `express-checkout`
break;
}
}
Read result.picker?.selectedMethod to branch; the optional chaining covers the picker not being mounted.
Styling & theming
Every element accepts a style option — the VoraFieldStyle token set (font, color, spacing, border, background, per-layer surfaces) — plus a classes option for focus / invalid / complete pseudo-states. The complete styling reference — the full token set, format-validation rules, the inner-vs-outer-iframe model, the three reference themes, and an interactive playground — lives on one page:
What's next
- Error handling —
VoraMirrorErrorshape, codes, retry semantics - Quickstart — end-to-end integration walkthrough