Element events
Every element exposes the same event API — wire your checkout UI to it for loading states, button enablement, validation messages, and focus styling.
The API — on / off
const card = elements.create("card", {}); // no style → the SDK default look applies
const handler = (e) => { /* … */ };
card.on("change", handler); // subscribe
card.off("change", handler); // unsubscribe (pass the same handler reference)
card.mount("#card-element");
on(event, handler) and off(event, handler) are on every element type (card, email, cardholder, address, save-for-future-use, express-checkout, …).
The four events
| Event | Fires when | Typical use |
|---|---|---|
ready | The element has finished rendering and is interactive. | Hide your loading spinner / skeleton; mark the form ready. |
change | The element's value changes (and on unmount, with complete: false). | Enable the Pay button when complete; surface error for inline validation. |
focus | The field gains focus. | Apply a focus ring or floating-label state on your wrapper. |
blur | The field loses focus (or, on the express-checkout element, the buyer dismisses the wallet sheet). | Validate on blur; reset focus styling. |
The express-checkout element also emits click and close for each wallet attempt (below).
All four fire with the same payload:
interface ElementChangeEvent {
complete: boolean; // value passes its own validation and is non-empty (or empty + not required)
error?: { // scrubbed validation error, undefined when valid
code: string;
message: string;
reason?: ThreeDsRequiredReason | WalletUnavailableReason; // frame_3ds_required, or a failed wallet tap
retryable?: boolean; // false: the checkout session has ended, start a new one
attemptsRemaining?: number; // with retryable: true, further attempts the checkout accepts
};
checked?: boolean; // save-for-future-use only: whether the box is ticked
}
Gate the submit button + show validation
const card = elements.create("card", {}); // no style → the SDK default look applies
card.on("change", (e) => {
payButton.disabled = !e.complete; // enable only when valid
showFieldError(e.error ? e.error.message : null); // inline validation
});
card.on("ready", () => hideSpinner());
card.on("focus", () => cardWrapper.classList.add("focused"));
card.on("blur", () => cardWrapper.classList.remove("focused"));
card.mount("#card-element");
error.message is already scrubbed for display; error.code is the stable identifier to branch on. On frame_3ds_required, and on frame_wallet_unavailable from a failed Apple Pay or Google Pay tap, error.reason says which case it is: branch on it, not on message (3-D Secure reasons, wallet reasons).
Require the save box before Pay
When your checkout needs a saved card (a subscription, for example), create the save-for-future-use box with required: true: a card submit() is then refused until it is ticked, and wallet buttons reading it are greyed (Make the box a condition of paying). Gating your own Pay button on the tick alone leaves wallet buttons tappable. To keep Pay disabled as well, listen for the tick. Its change, focus and blur events carry checked, the same value submit() sends as the buyer's consent. ready carries none: the box always starts unticked.
let cardComplete = false;
let saveTicked = false;
const updatePay = () => { payButton.disabled = !(cardComplete && saveTicked); };
card.on("change", (e) => { cardComplete = e.complete; updatePay(); });
save.on("change", (e) => { saveTicked = e.checked === true; updatePay(); });
checked only reports the tick. Nothing sets it from your page, and reset() fires change with checked: false.
Wallet buttons (express-checkout) use the same events, plus click and close
The express-checkout element (standalone wallets) maps the native wallet sheet's lifecycle onto these same four events, so you wire it the same way, and adds click and close for each wallet attempt. When the buyer authorizes in the wallet sheet, it fires change with complete: true; call submit() on that collection to read the charge result:
const elements = vora.elements.create();
const express = elements.create("express-checkout", {});
express.on("change", async (e) => {
if (e.error) return; // buttons unavailable (e.g. frame_wallet_domain_unverified)
if (!e.complete) return; // buyer hasn't authorized yet
const result = await elements.submit(); // submit the collection this element belongs to
if (result.chargeStatus === "requires_action") {
// From vora.js 1.22.0 the express-checkout element navigates to
// result.redirectUrl FOR YOU. Nothing is charged yet either way.
// ⚠ This handler is async — if you await work here, pass
// { handleRedirect: false } on create() and navigate yourself once it
// finishes, or the navigation cancels it. See Standalone wallets.
return;
}
if (result.charged || result.chargeStatus === "pending") {
return awaitWebhookThenFulfil(); // money already moving — do NOT charge again
}
if (result.chargeStatus === "succeeded") {
// Placed, not confirmed as taken. Never charge again.
if (result.charged === false && result.paymentIntentId && !result.recovered) {
return holdForCapture(result.paymentIntentId); // captureMethod: "manual": held
}
return confirmOnYourServer(sessionId); // recovered: true, or no charged value
}
await chargeOnYourServer(result.token, result.wallet); // vault-only accounts
});
express.mount("#express-checkout");
On the default wallet path the tap moves the money, and the result may also carry a reusable vp_pmt_*. Branching on result.token therefore double-charges. Branch on charged / chargeStatus — see the full result table.
(If the buyer dismisses the sheet, you get blur; if it can't render, you get change with an error.)
Know when a wallet payment is under way: click and close
On some payment connections the wallet buttons are drawn inside the payment provider's own frame, so a click listener on your container never hears the tap. The element reports every attempt itself, on every connection that offers Apple Pay or Google Pay:
express.on("click", ({ wallet }) => {
// "apple_pay" | "google_pay": the buyer tapped a wallet button
walletAttemptOpen = true; // e.g. don't charge the card form on top of this
});
express.on("close", ({ wallet, outcome }) => {
walletAttemptOpen = false; // that attempt is over, however it ended
if (outcome === "unresolved") holdOrderForWebhook(); // this payment can still complete
});
- Every
clickis followed by exactly oneclose, however the attempt ended, with one exception: an element unmounted while an approved payment is in flight sends none (see the note after the table). Between the two a wallet payment may be under way; outside such a pair there is none. While an approved payment is in flight nothing ends the attempt early: not the buyer closing the sheet, not another tap. Itsclosewaits for the outcome. clickarrives inside the tap, before the sheet can be approved. Keep the handler short and synchronous: the browser lets the sheet open only during the tap. Nothing the handler returns or throws stops the sheet.- While a wallet approval is being handled, the card form is locked. A card
submit()on the same collection is refused withframe_session_not_readyand nothing is sent. To fall back to the card after a failed wallet attempt, do it onclose, not in thechangeerror handler. confirmandsubmit()still carry the payment.closesummarises how the attempt ended on this page; your webhook remains the record.
outcome on close:
outcome | Meaning |
|---|---|
succeeded | Reported on confirm with chargeStatus: "succeeded": charged, or held on manual capture. |
unresolved | Reported on confirm with chargeStatus "pending" or "requires_action". The payment can still complete: keep the order held for your webhook (or the buyer's return from the bank), and take no other payment for it. |
tokenized | Reported on confirm with a token and no chargeStatus. Nothing was charged here; your server charges the token. |
failed | Reported on change with an error, or refused by your own onConfirm. Treat it as a decline, not as proof that nothing was authorized: your webhook is the record. |
cancelled | No outcome was reported: the buyer closed the sheet or tapped again before approving, or the element was unmounted. |
An element unmounted while an approved payment is in flight sends no close: that payment completes regardless, and only the webhook reports it.
Discrete card fields — field vs form events
The discrete card fields (card-number / card-expiry / card-cvc) expose the same four events, but event granularity depends on the binder behind your account:
| Binder | change / ready | focus / blur |
|---|---|---|
| Direct-card binder | Field-scoped — each field fires its own, carrying that field's complete. | Fire per field. |
| Secure-fields | Whole-form — one event for all three fields, with a form-wide complete. | Do not fire. |
For button enablement and validation that works on every binder, treat change as a form-level signal — complete means the whole card is valid. Per-field UX (highlighting only the CVC field) needs to be gated on which binder backs your account; independent field placement works on both.
Localization (locale)
The SDK accepts a BCP-47 locale — on the client and per element:
const vora = new window.Vora({
publishableKey: "vp_pk_test_…",
locale: "fr-FR", // client-wide default
});
const card = elements.create("card", { locale: "de-DE" }); // per-element override
The value is forwarded to the processor's combined card iframe in embed mode, which localizes its own text where it supports the locale; in elements mode nothing is localized. The SDK's own labels, validation messages and error strings are English.
Related
- Customize the look & feel — styling, themes, the
styleallowlist - Elements reference — per-element options + collect shapes
- Standalone wallets — the
express-checkoutelement