Skip to main content

Embedded Fields — Error handling

Embedded Fields' error surface is VoraMirrorError — a typed exception with a stable code, a human-readable message, and optional sub-hints. Server-side errors from your own calls to /v1/* are a different surface: Reference → Error codes. FrameError is a deprecated alias of the same class.

Detection​

The browser SDK is a <script> from js.vonpay.com, so the helpers live on the Vora global:

const { VoraMirrorError, isVoraMirrorError } = Vora;

try {
await vora.sessions.retrieve(sessionId); // required before creating a card element
const elements = vora.elements.create();
const card = elements.create("card", {});
card.mount("#card-element");

// submit() RETURNS tokenize / validation / 3DS errors on result.error — it does
// NOT throw for those. Branch on the result for the payment-path errors:
const result = await elements.submit();
if (result.error) {
// result.error is a VoraMirrorError; result.error.code is one of the union below
console.error(result.error.code, result.error.message);
}
} catch (err) {
// Thrown errors: session-retrieve failures, frame_session_not_ready (create()
// before retrieve), insecure-context / CSP mount failures, and programming
// bugs (TypeError on construction, etc.).
if (isVoraMirrorError(err)) {
console.error(err.code, err.message);
} else {
throw err;
}
}

Always use isVoraMirrorError() — instanceof VoraMirrorError can fail across module boundaries (bundle-splitting / multiple package copies).

Code union​

type VoraMirrorErrorCode =
| "frame_insecure_context"
| "frame_session_not_found"
| "frame_session_expired"
| "frame_session_not_ready"
| "frame_provider_request_rejected"
| "frame_binder_load_failed"
| "frame_field_validation_failed"
| "frame_save_consent_required"
| "frame_card_brand_not_accepted"
| "frame_tokenization_failed"
| "frame_3ds_challenge_failed"
| "frame_3ds_challenge_timeout"
| "frame_3ds_challenge_cancelled"
| "frame_3ds_required"
| "frame_next_action_outcome_unknown"
| "frame_payment_declined"
| "frame_consent_requires_buyer"
| "frame_buyer_required_for_saved_card"
| "frame_sandbox_account_required"
| "frame_charge_in_progress"
| "frame_payment_in_progress"
| "frame_other_payment_in_progress"
| "frame_payment_form_not_ready"
| "frame_session_update_conflict"
| "frame_recurring_session_unavailable"
| "frame_subscription_consent_required"
| "frame_recurring_terms_changed"
| "frame_invalid_recurring"
| "frame_recurring_already_subscribed"
| "frame_recurring_signup_in_progress"
| "frame_recurring_not_enabled"
| "frame_capability_not_supported"
| "frame_wallet_total_mismatch"
| "frame_wallet_confirm_failed"
| "frame_wallet_unavailable"
| "frame_wallet_domain_unverified"
| "frame_wallet_rendered_by_card_element"
| "frame_style_invalid"
| "frame_unsupported_element"
| "frame_method_not_supported_for_session"
| "frame_card_form_conflict"
| "frame_page_tampered"
| "frame_client_secret_invalid"
| "frame_client_secret_required"
| "frame_unexpected_redirect"
| "frame_rate_limited"
| "frame_bot_check_failed"
| "frame_bot_check_unavailable";

The frame_* strings are the stable contract; VoraMirrorErrorCode is the TypeScript name and FrameErrorCode its deprecated alias.

Codes by recovery family​

Configuration / setup errors (fix the integration)​

CodeWhen it firesRecovery
frame_insecure_contextnew Vora(...) outside HTTPS / localhostServe the page over HTTPS in production. localhost is allowed for development.
frame_session_not_foundSession ID is unknown to VORAVerify the merchant's vp_sk_* is for the same merchant whose session you're loading. Check test/live mode parity (publishable key prefix vs session ID prefix must match).
frame_unsupported_elementelements.create(type, ...) called for an element the active session's binder doesn't support — or payment-method-picker's methods all filter out against per-binder capabilities, or an express-checkout element given collect, shippingOptions or onShippingAddressChange on a payment connection that cannot collect details in the wallet sheet. From vora.js 1.44.0 also at submit() in embed mode, when the payment asks to save the card otherwise than the form decided when it loaded; nothing is sentThe active binder declared not_available (or monolith, for elements whose surface the binder renders natively — e.g. a processor that renders its own payment-method picker as part of an all-in-one embed). Swap the element type, route the merchant to a binder that supports it, or — for picker-on-monolith — remove the element from your elements.create() list and rely on the binder's native UI. The error message identifies which binder and which element. For the embed save case, pass setupForFutureUse: "off_session" to elements.create(), or create a required save box, before the card form.
frame_method_not_supported_for_sessionThe deprecated card.tokenize() single-field path was called against a single-embed binder session. From vora.js 1.39.0 also: card.confirmPaymentIntent() or collection.submit({ paymentIntent }) was called on the embedded payment form's connection, which cannot check a payment in the browser. Nothing was charged by the refused call."card.tokenize() is deprecated. Use vora.elements.create() + collection.create('card') + collection.submit() to charge and save. Your server configuration is fine." This is an integration-time wrong-method condition (single-embed binder) — not a server bug, not high-severity, and should not page. Switch to the canonical vora.elements.create() + collection.create('card') + collection.submit() path. For a refused confirm: read the payment intent's status on your server, send the buyer to any nextAction with vora.redirectToChallenge(intent.nextAction), and to charge a card typed into the form, call collection.submit() without paymentIntent and charge the returned token from your server.
frame_card_form_conflictThe saved-card security-code field is on the same page as a card form: it refuses to start beside one, and card fields started after it disconnect it. Nothing was sent.Only one can run per page. Show the security-code field on a page or step without a card form.
frame_page_tamperedThe card fields of an elements session, or the saved-card security-code field, did not load because something on your page changed where they load from. mount() throws it (the security-code field emits it as error). Nothing was sent or charged. Reported on live keys too.Find and remove the script or page element that sets it (for example a tag-manager tag), then reload; retrying on the same page fails the same way. See frame-src under CSP requirements.
frame_style_invalidStyle option contains a key outside the allowlistThe thrown error's property field names the offending key. Drop it or alias to a supported VoraFieldStyle key.
frame_consent_requires_buyerNot raised from vora.js 1.44.0; it stays in the code union so existing switch statements compile. In 1.43.x and earlier: the buyer ticked the save-card box on a session with no buyer attached. It never threw, and the buyer was charged.Decide whether the card was saved from result.token or the payment_method.attached webhook; from 1.44.0 vora.js logs one console warning per page when the checkout refuses to save a guest's card, or the embedded form keeps no card for a guest. In embed mode, create the session with a buyerId (or buyer email) before offering the save-card control, or don't render the control on guest sessions. A buyer email alone saves the card to a buyer made for that one checkout, never to an existing buyer with the same email. ⚠ Consent is not repairable afterwards — it is recorded when the card is first vaulted and cannot be added later, so the buyer must present the card again. See Recurring & saved cards.
frame_client_secret_invalidThe value passed to vora.sessions.retrieve() looks like a client secret (it contains _secret) but is not a valid client secret, or it is a client secret and apiBaseUrl is not the Von Payments checkout API (a client secret is sent only there). Also the checkout's client_secret_invalid. Nothing was sent or charged. retryable is false.Pass the clientSecret your server received for this session, unchanged. A page with a custom apiBaseUrl cannot send a client secret: pass the session id, or remove the custom apiBaseUrl if the session requires its client secret.
frame_client_secret_requiredThe checkout session requires its client secret and the page did not pass it (the checkout's client_secret_required). Nothing was charged. retryable is false.Read clientSecret on your server, give it to this page, and pass it to vora.sessions.retrieve() in place of the session id.
frame_unexpected_redirectA call that carried the client secret was answered with a redirect, which the API never sends: a wrong apiBaseUrl, a proxy or a network filter answered instead. vora.js did not follow it and did not use the answer. retryable is false.If it was a payment, check the session or payment on your server before the buyer tries again. Then check apiBaseUrl (leave it unset) and anything between the page and the API.
frame_sandbox_account_requiredA test key was used where test payments cannot run: on a live account, or on a sandbox whose processor test account is not set up. Nothing was charged.Retrying never helps. Use your sandbox account's test keys; if it is your sandbox, open it in Developer Tools to finish setting up test payments. Server-side name: sandbox_account_required.
frame_buyer_required_for_saved_cardSame missing buyer, but on a session whose gateway vaults the card as part of taking the payment — so it refused outright. submit() rejects and nothing was charged.Do not fulfill. Do not retry this session: the buyer is fixed at session creation, so the same call fails the same way forever. Create a new session with buyerId and have the buyer enter the card again. Server-side name: buyer_required_for_saved_card.
Two codes, one missing buyer — only one of them charged the buyer

Which one you get depends on the gateway, so read the code before you decide what to do — the first means the buyer paid, the second means nothing was charged.

Transient errors (retry / refresh)​

CodeWhen it firesRecovery
frame_session_expiredThe session ended before tokenize, with nothing charged: its time limit passed, or it ended with no successful charge. A session that ended while a payment on it was still being decided gets frame_other_payment_in_progress insteadCreate a fresh session on your server, then vora.sessions.retrieve(newId). Sessions default to 30 minutes.
frame_session_not_readyAn action method (tokenize, confirmPaymentIntent, handleAction) was called before ready === true, or submit() was called while collection.fetchUpdates() or collection.switchSession() was still running (nothing was charged). From vora.js 1.39.0 also: vora.sessions.retrieve() on a session whose payment is still being processed (it waits up to 30 seconds first), and a second payment from an embed session's card form that already sent one (an accidental repeat: a double click, the form re-rendering on your page, a retry after a lost reply; nothing was sent). It guards against accidental repeats, not against your own page code starting a new payment. From vora.js 1.39.1 also: creating a card element for a new form after collection.unmount(), which released the old form's session.Wait for ready === true before exposing your submit button. In React, gate the button render on ready. After a total change, wait for fetchUpdates() to resolve, show the buyer the new total, then submit. From sessions.retrieve(): retrieve the session again in a moment and do not start another payment. On a card form that already paid: read the outcome on your server; do not resubmit. After an unmount(), call vora.sessions.retrieve(sessionId) again before creating the new form.
frame_binder_load_failedThe active processor's CDN script failed to load, or the wallet buttons themselves failed to load (from vora.js 1.45.1 a failed wallet tap is frame_wallet_unavailable; 1.44.1 and earlier reported it here). From vora.js 1.40.1 also: the payment provider's card fields failed while a card element was mounting; that case has no hint, your element is given back as it was, and the form is released (call vora.sessions.retrieve(sessionId) again, then create and mount a new form)Inspect the hint field — network_error / csp_blocked / script_blocked / timeout. Most commonly fixed by adding the processor's domain to your CSP script-src; see Reference → Security.
frame_3ds_challenge_timeoutBuyer didn't complete 3DS challenge within challengeTimeout (default 5 min / 300_000 ms)Surface a "the bank's authentication timed out" message; let the buyer retry.
frame_rate_limitedThe publishable-key endpoints (sessions.retrieve, binder-load, the embed-token poll) are per-IP rate-limited (HTTP 429) and the caller exceeded the ceiling — usually rapid reloads or a tight retry loopBack off and retry after a short delay; honor the Retry-After header if present. Do not retry immediately in a loop — that deepens the throttle. Not a CSP/binder/session problem.
frame_payment_in_progresssessions.retrieve() waited about 15 seconds and a payment on the session is still being processed. retryable: true.Tell the buyer to wait. Do not start another payment or a new session; retrieve again in a few seconds, or wait for your payment webhook.
frame_payment_form_not_readyAfter a declined attempt, the fresh card form was still being prepared after the wait. Nothing was charged. retryable: true.Retrieve the session again in a moment.
frame_session_update_conflictFrom vora.js 1.51.0: your server changed the checkout (for example named the guest with buyerEmail) just as the shopper pressed Pay. Nothing was charged, and the session and card form stay open. retryable: true. Before 1.51.0 this arrived as frame_tokenization_failed with status 409.Let the shopper press Pay again with the same card: re-enable the button and keep the form. Do not ask for another card or create a new session.

Buyer-action errors (surface a message)​

CodeWhen it firesRecovery
frame_field_validation_failedCard number / expiry / CVC failed VORA's pre-tokenize validation. On the card fields of an elements session, an empty form or a card the form reports as invalid (for example a number that fails the checksum) is refused here and nothing is sentAlready surfaced inline by the iframe. Disable the submit button until the change event reports complete: true.
frame_card_brand_not_acceptedFrom vora.js 1.52.0: your account does not accept the brand of the card the shopper typed (for example American Express). When the checkout session carries your refused brands, the card form reports it as soon as the brand is known: the element's change event carries this code in error with complete: false, and submit() returns it. Nothing was sent or charged, and no payment attempt was used. A card of a refused brand that still reaches Von Payments, for example a saved card, is refused with the same code.Show error.message and let the shopper enter a card of another brand on the same checkout. retryable: false means that same card will never be accepted. Do not start a new session. Typing a card of another brand clears the error. One session can have the card brand checked at most 30 times; after that the checkout answers session_attempt_limit_reached, and the shopper needs a new session.
frame_save_consent_requiredThe save-card box is required and the buyer has not ticked it. Raised only before anything is sent: a card submit() sends nothing, and a wallet tap is refused at the approval. Nothing was charged.The box asks the buyer to tick it. Once it is ticked, the buyer pays again (retryable: true). See Make the box a condition of paying.
frame_tokenization_failedThe adapter rejected the card before any charge — a genuine pre-charge rejection — or the card form was disconnected because the SDK was initialised twice (see below). Read error.message before telling the buyer anything. Before vora.js 1.51.0, a frame_tokenization_failed with status 409 was a frame_session_update_conflict: nothing was charged, and the same card can pay again.Show a generic "your card couldn't be authorized" message and suggest a different payment method. The full reason is logged server-side; do not leak adapter messages to buyers. From vora.js 1.39.0, on an elements session that charges at submit, it also fires after the card form expired: the SDK has already rebuilt the card fields on a fresh form, nothing was charged and the card was never judged. Read error.retryable: true means ask the buyer to enter the card again (not to use another card); false means reload the page to pay. On an embed session (the default mode) before vora.js 1.39.0, a card decline also arrives as this code, and the checkout cancels that card form: a second Pay in it is refused and nothing is charged, so create a new session for the buyer to pay again. From 1.39.0, on an embed session, it also fires when the connection failed before the payment reached the processor: nothing was charged and the same form can pay again. If the payment did go through, submit() returns it with recovered: true instead.
frame_3ds_challenge_failedThe challenge ran and was rejected, or failed technically. Not buyer cancellation — that has its own code below.Show "authentication failed — please try again or use a different card" and re-enable the submit button.
frame_3ds_challenge_cancelledThe buyer closed the bank's confirmation step. The card was not charged.An abandoned checkout, not a failure: re-enable the submit button and let them retry; do not show an error or alert on it. On the wallet buttons with the bank check in a pop-up, retryable: false means the session has ended: start a new session for the buyer to pay again.
frame_provider_request_rejectedThe provider refused the request itself — not a card decline. Common culprits: currency, amount, descriptor/metadata length. Or no payment connection on your account accepts this payment: from vora.js 1.45.2 only that case carries retryable: false. On an Apple Pay or Google Pay tap, vora.js also stops payment on the page: the buttons come down, and later taps and submit() calls with a card typed into the form get the same error, sending nothing. Nothing was charged. A card payment keeps its session.Do not retry unchanged, and do not ask the buyer for another card — the same request fails identically and the card was never the problem. Fix the offending field; if the culprit isn't obvious, quote the request id to support. With retryable: false, check the account's routing rules or contact support with the request id; after a wallet tap, start a new session once it is fixed.
frame_3ds_requiredA bank check (3-D Secure) was needed and could not run, so nothing was charged. From vora.js 1.39.0, error.reason says which case: try_another_payment_method (from submit(), the wallet button or card.tokenize(): no challenge link the SDK can safely open came back), not_supported_here (from submit(), before anything is sent: this session's payment connection cannot show the check in the page), challenge_url_unusable (from vora.redirectToChallenge(): it was given no usable link and did not navigate), or use_redirect (from the deprecated card.handleAction(), which cannot run the check on this connection). On the tokenize-only flow there is no SDK error for a required check; the server's status: "requires_action" is the signal, see 3D Secure.Re-running submit() will not help. try_another_payment_method: ask the buyer to pay another way (a card or method that does not need a bank check can succeed), and report the session id to support. not_supported_here: no retry on this session completes it; contact support with the session id. challenge_url_unusable: pass the payment intent's nextAction exactly as your server received it; if your server lost it, read the payment intent again and check its issuedAt first. use_redirect: send the buyer with vora.redirectToChallenge(intent.nextAction). See Charge at submit → 3-D Secure.
frame_payment_declinedThe charge was attempted and the issuer declined it (flows where the embed charges at submit). From vora.js 1.39.0 an embed session (the default mode) reports a decline with this code too, with a message that starts "The payment was declined." and names no decline code; before 1.39.0 it reported frame_tokenization_failed.Show a generic "your payment was declined — please try a different card" message. Then, on vora.js 1.38.0 and later, read error.retryable: true means the card form has already been reset on this session, so re-enable the submit button and do not create a new session; false means the checkout session is finished, so create a new session for the buyer to pay again (a resubmit on this one is refused before anything is sent). With retryable set, error.attemptsRemaining says how many more tries the session accepts, when known. On 1.37.0, re-enable the submit button. The decline reason is logged server-side. To tell why in your page, read error.declineCode, never the message. incorrect_card_details means a card detail was wrong: the card number, the expiry date, the security code or the postal code. It never says which one. authentication_not_completed means the buyer did not finish the bank's security check, so the same card can work. authentication_failed means the check did not pass and nothing was charged; the checkout session usually ends: when error.retryable is false, start a new session; when it is true, the card form was reset and the buyer can try again on it. See Decline reasons in the browser.
frame_bot_check_failedOnly when Von Payments has switched the optional bot check on for your account (vora.js 1.46.0 and later). The check did not pass, so the card payment or card save was refused. Nothing was charged and no card was saved.Show message and let the buyer press Pay again on the same session: every attempt runs a fresh check. Do not ask for a different card; the card was never checked.
frame_bot_check_unavailableOnly when the bot check is on for your account (vora.js 1.46.0 and later). The checkout could not verify the payment right now and did not take it. Nothing was charged and no card was saved.Ask the buyer to wait about a minute, then press Pay again. An immediate retry is likely to be refused the same way. Do not ask for a different card.

On the charge-and-save flow, a successful guest / no-buyer submit charges the card once and returns no token by design — { charged: true }, not frame_tokenization_failed. Branch on result.charged before treating an absent token as a failure, and never re-charge after a charged result.

frame_tokenization_failed also means "you initialised the SDK twice"​

One condition reports frame_tokenization_failed with a different message and a different fix:

The card form was disconnected before the card could be saved. This happens when a second card-fields instance is created on the same page — initialize the SDK once per page, then retry.

The buyer's card is fine. A second card-fields instance on the page tore down the first one's fields — the vendor holds one card-field set per page. Initialise once per page and reuse that instance. The code is the same, so only the message distinguishes them: read error.message before choosing what to show the buyer.

Checkout-setup refusals (nothing was charged)​

CodeWhen it firesRecovery
frame_capability_not_supportedFrom vora.js 1.53.0, on a card save, a wallet payment or the card charge: the checkout was set up for another way to pay. Refused before anything is charged, and no card is saved. Before 1.53.0 it arrived as frame_tokenization_failed or frame_session_not_ready. retryable: false.Pay it the way it was set up: a checkout that saves cards on the hosted payment page only, by sending the shopper to its checkoutUrl; one sent through your own payment gateway with a manual capture, by creating it without captureMethod: "manual".

Duplicate-charge guards (do not retry)​

CodeWhen it firesRecovery
frame_next_action_outcome_unknownOnly from vora.handleNextAction() (vora.js 1.53.0): the call ended without an outcome. The payment was created by your server and may already be paid: this never means nothing was charged. error.reason says why: next_action_unusable (no usable payment id and secret for this key's mode, or the read was refused), next_action_unavailable (the bank check could not be read), code_not_loaded (the pop-up's code did not load), or no_page (no page to show it in).Read the payment from your server before you take any new payment. While it still reads requires_action, call handleNextAction() again; for next_action_unusable, mint a new secret first.
frame_charge_in_progressA charge for this session is already in flight, and this request was refused to stop a duplicate. The first attempt has not failed — it has not returned yet.Do not retry, and do not create a new session. On some processor configurations a second attempt is a second charge that nothing can merge afterwards. Wait for the original request to return; if it never does, read the outcome from the session. The charge.* webhook is authoritative.
frame_other_payment_in_progressAnother payment on the checkout session is still running (for example a wallet bank check the buyer has not finished), or the session ended while a payment on it was still being decided, and this request charged nothing. A card charge or wallet payment that meets it is not failed: vora.js reads the session until it settles and reports that outcome. A card save, for example, gets the code. retryable: false.Do not retry, and do not start another payment or a new session. Tell the buyer a payment is being processed, and read the session (or wait for your payment webhook) until it settles.

Wallet errors (Apple Pay / Google Pay)​

None of these blocks the card flow. They arrive on the change event with complete: false, so analytics can record wallet-coverage gaps.

CodeWhen it firesRecovery
frame_wallet_domain_unverifiedAn express-checkout element mounted and either no wallet is domain-verified for this checkout, or no requested wallet is available on the buyer's device or browser — error.message says which.Domain case: register your domain with each wallet network (Apple Pay setup). Device case: no action — show your card form as the fallback. The card field keeps working either way.
frame_wallet_unavailableA wallet can't be used here, and nothing was charged: the wallet buttons were built but none painted on this device or browser; the session's currency is not offered for Apple Pay and Google Pay (the message names it); from vora.js 1.44.0, the payment provider refused to start Apple Pay or Google Pay for your page (most often because the site is not registered for wallet payments) or a wallet save came back without a saved wallet (1.43.x reported these two as frame_session_not_ready or frame_binder_load_failed); or, from vora.js 1.45.1, a wallet tap failed, and the error then carries a reason (1.44.1 and earlier reported a failed tap as frame_binder_load_failed). Which of this code and frame_wallet_domain_unverified a device without a wallet produces depends on the processor, so handle both as "no wallet here".Always show your card form. Without a reason: drop the wallet row, except after a wallet save that came back unsaved, where a new tap can work. Do not retry a refused wallet; if every tap reports it, check that your site's domain is registered for wallet payments (Apple Pay setup). With a test key, also check that Wallet holds an Apple test card, not a real card (Testing your setup). With a reason the buttons stay: show your card form beside them. After apple_session_refused, wallet_not_configured or google_merchant_error another tap fails the same way, so you may hide that wallet. Never retry in a loop or reload the page.
frame_wallet_total_mismatchThe checkout refused a payment whose total no longer matches the session's: the total changed after the buyer saw it, or while the wallet sheet was open. Nothing was charged. Also fires on a card payment once you use fetchUpdates().Show the buyer the current total and let them pay again. Server-side name: expected_amount_mismatch.
frame_wallet_confirm_failedYour onConfirm threw, timed out (15 seconds) or answered something other than { ok: true } / { ok: false }. Nothing was charged.Fix the hook, and keep it fast. See Buyer details and shipping in the wallet sheet.
frame_wallet_rendered_by_card_elementYou mounted a standalone wallet element, but the active binder renders Apple Pay / Google Pay inside the card mount.Remove the standalone element; wallets appear inside the card mount when eligible. See Elements reference → Apple Pay & Google Pay.

frame_wallet_unavailable: reason after a failed tap​

From vora.js 1.45.1, a wallet tap that fails reports frame_wallet_unavailable on the express-checkout element's change event with error.reason. Nothing was charged and the buttons stay. Branch on error.reason, never on message:

reasonWhat failedAnother tap
apple_session_refusedThe browser would not start an Apple Pay session (common in apps' built-in browsers)Fails the same way: you may hide Apple Pay
wallet_not_configuredYour Google Pay settings are missing from this sessionFails the same way: you may hide Google Pay
google_merchant_errorGoogle Pay refused your merchant configurationFails the same way: you may hide Google Pay
apple_begin_refusedThe browser refused to open the sheet, for example while another payment sheet was openMay work
merchant_validation_failedValidating your site with Apple for this page failed, usually a network hiccupMay work; if it repeats, contact support
google_buyer_account_errorGoogle Pay could not use the buyer's Google accountMay work once the buyer fixes or switches it
google_pay_errorGoogle Pay reported an errorMay work
unknownThe step that failed could not be toldMay work; if it repeats, treat it like the first three

Show your card form beside the buttons in every case. Treat a value you do not recognise like unknown.

On some payment connections a tap can fail after the buyer approved in the wallet sheet: the sheet shows the failure, nothing was charged, and the error comes with unknown. Tell the buyer the wallet payment did not go through, and offer the card form or another tap.

frame_binder_load_failed — sub-hints​

When this fires, inspect error.hint:

catch (err) {
if (isVoraMirrorError(err) && err.code === "frame_binder_load_failed") {
switch (err.hint) {
case "network_error":
case "timeout":
// Transient; suggest retry
break;
case "csp_blocked":
case "script_blocked":
// Configuration; merchant needs to update CSP / disable adblockers
break;
}
}
}

CSP requirements​

Von Payments publishes the Content Security Policy sources vora.js needs, for test keys and live keys. Read the modes.test or modes.live entry:

  • On the auto-updating script (/v1/vora.js), send https://js.vonpay.com/v1/csp.json. It covers every version the channel may serve you, including both versions while a release rolls out, and changes when a release moves forward or back. It is cached for 5 minutes, like /v1/vora.js, so fetch it when you build your header or refresh it every few minutes. If the answer is not 200, keep sending your last list: it never answers with a partial list, and answers 503 when a served version's list cannot be read.
  • On a pinned version, send that version's list: https://js.vonpay.com/v<version>/csp.json (from 1.39.0), for example v1.39.0/csp.json.
  • await Vora.cspSources({ mode: "live" }) (or "test") returns the running version's list in the browser, so on the auto-updating script use /v1/csp.json for your header instead.

Every source is tagged with the feature that needs it, so leave out what you do not use:

FeatureNeeded when
alwaysEvery integration: script-src https://js.vonpay.com and connect-src https://checkout.vonpay.com.
card-fieldsSessions created with integrationMode: "elements": the card fields (card, card-number, card-expiry, card-cvc). Also the saved-card security-code field.
payment-formSessions in the default "embed" mode: the card mount renders the full payment form.
apple-payAn embed session's payment form, in a browser other than Safari. Safari needs none of these sources.
google-payYou mount the Google Pay button in the express-checkout element.
stripeYour account's card processor is Stripe.
stripe-linkThe same, with Link turned on.
wallet-modalThe wallet bank check shown in a pop-up on your page (walletChallenge: "modal" on the express-checkout element). Add all of them: without them the bank check opens as a full page, and with only some of them it can end as pending.
bank-checkThe card-update bank check in a pop-up. A checkout page does not need these sources.
next-actionYou call vora.handleNextAction() (vora.js 1.53.0 and later) to show the bank check for a payment your server created: frame-src for the bank's page and the Von Payments return page.
bot-checkVon Payments has switched the optional bot check on for your account (vora.js 1.46.0 and later): frame-src https://js.vonpay.com for its hidden frame.

Add each directive's sources to the same directive in your existing header, space-separated; do not replace your header with the list. The payment-form and google-pay features need 'unsafe-inline' in style-src, which weakens your policy against injected styles; a page that uses only the card fields (integrationMode: "elements") does not need it.

The list also has an ifNoUnsafeInline section with one default-look source: a style-src hash for the one-line style element that places the built-in default look below your own CSS layers. Add it only if your style-src does not already allow 'unsafe-inline' (a hash next to 'unsafe-inline' switches 'unsafe-inline' off). Without it the default look still applies; only layered CSS (Tailwind v4 and similar) cannot override it.

As an extra guard for the card fields, list only the published sources in frame-src; the browser then refuses a card frame from anywhere else, whatever a script on the page does.

Test keys use the card processor's and Google Pay's sandbox hosts, so a page that runs on both keys needs both lists. With the @vonpay/vora npm loader, a policy that blocks js.vonpay.com itself rejects loadVora() with VoraLoadError code csp. A policy that blocks a source produces frame_binder_load_failed with hint: "csp_blocked" (when detectable) or hint: "script_blocked" (when the script tag was blocked outright).

Server-side errors​

VoraMirrorError is client-side. 4xx / 5xx responses from /v1/* (your server's calls) use the self-healing error envelope and are catalogued on Reference → Error codes. The browser-callable /v1/public/* routes accept publishable keys only — a secret key is refused with 403 auth_key_type_forbidden, and a missing or bad key returns the *_publishable variants (auth_missing_bearer_publishable, …) that steer to a publishable key.

What's next​