Embedded Fields — Quickstart
A working card-only Embedded Fields integration: the buyer stays on your domain, card data never touches your server, and tokenization happens inside an iframe mounted by the browser SDK. The alternative is hosted checkout, where the buyer is redirected to checkout.vonpay.com.
Architecture in one diagram
The browser never sees your secret key: the publishable key (vp_pk_*) authenticates only the browser-facing /v1/public/* routes (API Key Types).
submit() can already have charged — read the result before you charge server-sideThe diagram is the tokenize-only flow. On a charge-and-save session the embed charges the card at submit (and, with a buyer on the session, vaults a reusable token in the same step; on charge at submit, only when someone agreed to save the card): result.charged === true or a token on a charge-and-save session means the money has moved — skip Step 7 or you charge the buyer twice, and confirm settlement via the webhook. See Charge-and-save.
Step 0 — Get your test keys
You need both keys from app.vonpay.com/dashboard/developers: vp_sk_test_* (your server) and vp_pk_test_* (your browser bundle). See Quickstart §0.
Step 1 — Load the browser SDK
<script src="https://js.vonpay.com/v1/vora.js" crossorigin="anonymous"></script>
/v1/vora.js updates as new versions ship. To stay on a version you tested, with the browser checking the file's hash, load a pinned version instead (Script-tag integration).
vora.js always loads from js.vonpay.com, and it is the only script you load: the processor is selected server-side, and a processor SDK's own tokens are rejected by POST /v1/payment_intents.
Or load it from npm, with TypeScript types
In a bundler, the @vonpay/vora package loads the same script for you and types everything it returns. The package does not contain the SDK: loadVora() adds the https://js.vonpay.com/v1/vora.js tag (or uses one already on the page) and resolves with a Vora instance.
npm install @vonpay/vora
import { loadVora } from "@vonpay/vora";
const vora = await loadVora({ publishableKey: "vp_pk_test_…" }); // same config as new Vora()
if (vora) {
// the rest of this guide, typed
}
loadVora() resolves null on the server, so it is safe in frameworks that render there. Importing the package starts the download in the browser; import from @vonpay/vora/pure to wait for the first loadVora() call instead. A script that cannot load rejects with a VoraLoadError whose code is network, csp, global_missing, version_mismatch or timeout. There is no time limit by default; loadVora.setLoadParameters({ timeoutMs: 15000 }) (from @vonpay/vora/pure) makes a load that takes longer reject with timeout.
Step 2 — Create a session on your server
A session is one buyer's checkout attempt; create it when the buyer is ready to pay, not on every page view (it has a 30-minute TTL — when to create it). Your server creates it with the secret key:
// server/api/create-session.ts (Node example)
import express from "express";
const app = express();
app.use(express.json());
const SECRET = process.env.VON_PAY_SECRET_KEY; // vp_sk_test_*
const API = process.env.VONPAY_API_BASE ?? "https://checkout.vonpay.com";
app.post("/api/create-session", async (req, res) => {
const response = await fetch(`${API}/v1/sessions`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${SECRET}`,
},
body: JSON.stringify({
amount: 4999, // $49.99 in cents
currency: "USD",
successUrl: "https://mystore.com/thank-you",
cancelUrl: "https://mystore.com/cart",
// integrationMode defaults to "embed" (one combined card box).
// Set "elements" for discrete, individually-placed fields — see Custom checkout with Elements.
}),
});
const session = await response.json();
// Store session.id with your order: the charge in Step 7 sends it back.
// session.id is vp_cs_test_*, safe to send to the browser.
res.json({ session_id: session.id });
});
The session id is vp_cs_test_* for sandbox keys, vp_cs_live_* for live keys. This Quickstart omits integrationMode, so the session renders in the default embed mode — one card box that renders the whole payment surface. For discrete, individually-placed fields create the session with integrationMode: "elements" (Custom checkout with Elements).
Step 3 — Initialize VORA in the browser
The script from Step 1 attaches the Vora constructor to window (with the npm loader, await loadVora({ ... }) takes the same options):
// `Vora` is the global the CDN script attached (see Step 1).
const vora = new window.Vora({
publishableKey: "vp_pk_test_…", // your publishable key
apiBaseUrl: "https://checkout.vonpay.com", // this is the default — it is NOT inferred from
// your key. It must name the same host your
// server called in Step 2.
});
Constructor validations:
publishableKeyis required and must start withvp_pk_test_orvp_pk_live_. A secret key throws aTypeErrorimmediately.- The page must be served over HTTPS (or
localhostfor development); an insecure context throwsframe_insecure_context. apiBaseUrldefaults tohttps://checkout.vonpay.comand is not derived from your key — both key modes are served by the same host. If your browser and your server name different hosts, your server calls succeed and every browser call fails401 auth_invalid_key_publishable(Which environment am I talking to?).
Typing window.Vora
If you load the script tag but want types, install @vonpay/vora and reference it once; window.Vora is then typed (optional, since it is undefined until the script has run):
/// <reference types="@vonpay/vora" />
Telemetry (optional)
The SDK sends fire-and-forget, PII-free diagnostics — failure events (tokenize / binder-load errors) and load timings: error codes, the operation name, the SDK version, the browser family, elapsed milliseconds and the checkout session id, never card data or buyer identifiers. Failure telemetry is on for vp_pk_test_* keys and off for vp_pk_live_*; load-timing telemetry is on for both.
From vora.js 1.53.0, the Apple Pay and Google Pay buttons also report each tap and how the payment sheet ended: approved, cancelled or failed. Each report is a short fixed code with the SDK version, the browser family and the checkout session id. It never includes card or wallet data, the amount or the shopper's details. Tap reports are sent on live keys too; telemetry: false turns them off.
const vora = new Vora({
publishableKey: "vp_pk_live_…",
telemetry: false, // full opt-out — disables BOTH failure and load-timing telemetry
// performanceSampleRate: 0, // alternatively, keep failure telemetry but silence load timings
// (0..1 sampling fraction; default 1)
});
Step 4 — Retrieve the session
This fetches /v1/public/sessions/:id and lazy-loads the binder adapter for your account's active card processor — your code does not pick a binder:
// Browser — fetch the session_id from your server first
const res = await fetch("/api/create-session", { method: "POST" });
const { session_id } = await res.json();
const session = await vora.sessions.retrieve(session_id);
// session.id, session.amount, session.currency, session.binderConfig (opaque), …
Step 5 — Mount the card field
<div id="card-element"></div>
<button id="pay-button" disabled>Pay</button>
const elements = vora.elements.create();
const card = elements.create("card", {
style: {
font: { size: "16px", family: "system-ui, sans-serif" },
color: { text: "#1a1a1a", placeholder: "#9ca3af" },
},
// Exactly three keys are accepted: number, expiry, cvc.
// Any other key is not applied — the SDK logs a console.warn naming these three.
placeholder: { number: "4242 4242 4242 4242", expiry: "MM / YY", cvc: "CVC" },
});
card.mount("#card-element");
// Unlock the pay button once the field is ready
card.on("ready", () => {
document.getElementById("pay-button").disabled = false;
});
card.on("change", (event) => {
// event.complete = true when number/expiry/cvc all valid
document.getElementById("pay-button").disabled = !event.complete;
});
Both style and placeholder are optional: the SDK applies its own default look and your values override it property by property (Default style). Style the box around the field from your own stylesheet — the SDK stamps vora-field on the container you mounted into, plus vora-field--focus, --invalid and --complete as the field's state changes inside the iframe:
.vora-field {
box-sizing: border-box;
min-height: 44px;
padding: 12px;
border: 1px solid #d1d5db;
border-radius: 6px;
background: #fff;
transition: border-color 0.15s, box-shadow 0.15s;
}
.vora-field--focus { border-color: #2563eb; box-shadow: 0 0 0 3px rgb(37 99 235 / 0.15); }
.vora-field--invalid { border-color: #b91c1c; }
.vora-field--complete { border-color: #059669; }
The full class list is on Customize the look → The container's own classes.
In the default embed mode this one iframe is your entire payment surface: card number / expiry / CVC together and — where your account supports them — cardholder name, billing address, the payment-method picker, saved methods and the Apple Pay / Google Pay buttons (when the device and your domain are eligible — eligibility model). The only elements you place separately are email and save-for-future-use; the card mount already collects the name and address, so mounting cardholder or address as well renders a second field, and payment-method-picker throws at create time. To lay those out yourself, see the Elements reference.
Step 6 — Tokenize on submit
Branch on the result in this order: error, then chargeStatus, then token, then charged. Never read result.token on its own. Any chargeStatus means this submit already charged the card or started to, so a token beside it is never one to charge now:
document.getElementById("pay-button").addEventListener("click", async () => {
const result = await elements.submit();
if (result.error) {
// Submit failed before any charge happened.
if (result.error.code === "frame_field_validation_failed") {
alert("Please check the card details.");
} else if (result.error.code === "frame_3ds_challenge_cancelled") {
// The buyer closed the bank's confirmation step. Nothing was charged.
// Abandoned, not failed — let them try again without an error message.
} else if (result.error.code === "frame_3ds_challenge_failed") {
alert("3DS authentication failed. Try a different card.");
} else {
console.error(result.error);
}
// A client-side error is not proof that nothing was charged — a timeout can
// land after the charge succeeded. Never mark the order failed on it and
// never start a new session blindly; reconcile via the webhook.
return;
}
// Any chargeStatus: this submit already charged (or started to). Never
// charge again from your server, even when a token is present.
if (result.chargeStatus === "requires_action") {
window.location.href = result.redirectUrl; // 3-D Secure; nothing charged yet
return;
}
if (result.chargeStatus === "pending") {
// In flight: await the charge.* webhook. Do NOT charge again.
showAwaitingConfirmation();
return;
}
if (result.chargeStatus === "succeeded") {
// Placed: do NOT charge again. A token here is the card saved for a later
// payment. charged: false is a hold on a captureMethod: "manual" session.
showAwaitingConfirmation();
return;
}
if (result.token && result.charged !== true) {
// Tokenize-only flow (this quickstart): charge the vp_pmt_* on your server.
await chargeServer(result.token, yourOrderId);
return;
}
if (result.charged) {
// The submit ALREADY charged the buyer, with or without a token.
// Do NOT call POST /v1/payment_intents: that double-charges.
// Confirm settlement via the webhook before fulfilling.
showAwaitingConfirmation();
}
});
A vp_pmt_* token on the tokenize-only flow is single-use by default and bound to the session that minted it — your server charges it once. On a charge-and-save session a guest submit returns { charged: true } with no token and a with-buyer submit returns a reusable token whose card was already charged, only when someone agreed to save the card (in embed mode, from vora.js 1.44.0, before the form loaded). Whichever arm you land in, the client result is a UX signal — confirm settlement via the webhook before fulfilling. Reusable tokens, consent and reuse rules: Tokenization.
Pass the token to your server:
async function chargeServer(token, orderId) {
const res = await fetch("/api/charge", {
method: "POST",
headers: { "Content-Type": "application/json" },
// Send your own order reference: the server loads the order from it (Step 7).
body: JSON.stringify({ payment_method: token, order_id: orderId }),
});
const body = await res.json();
if (body.redirect) vora.redirectToChallenge(body.redirect); // 3-D Secure: the bank's page
}
Step 7 — Charge with the token
On your server the token becomes the payment_method on a payment intent.
Idempotency-KeyFrom the 28 October 2026 cut-off it is required on every charge, and a keyless charge can be refused with 400 idempotency_key_required; some connections already refuse one — and on every connection it is what turns a timed-out retry into a replay instead of a second charge. Key it to the operation (order_123_charge) and send the same value on every retry. See Idempotency.
// server/api/charge.ts
app.post("/api/charge", async (req, res) => {
// Load the order on your server: your own lookup, refused unless the order
// belongs to this shopper. Amount, session and return URL come from it.
const order = await loadOrder(req.body.order_id, req);
const response = await fetch(`${API}/v1/payment_intents`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${SECRET}`,
// Built from YOUR order id. Names the OPERATION, not the attempt: reuse
// this exact value on every retry after a timeout or a 5xx. Only after a
// confirmed decline (status "failed") does the next attempt take a new key.
"Idempotency-Key": `${order.id}_charge`,
},
body: JSON.stringify({
amount: order.amount,
currency: order.currency,
payment_method: { id: req.body.payment_method }, // object form: { id: "vp_pmt_..." }
// The session you stored in Step 2. If it already charged at submit,
// this charge is refused (409 session_already_completed), not taken twice.
session_id: order.vonpaySessionId,
// Where the bank sends the buyer back after a 3-D Secure challenge.
// Without it, a card that needs a challenge is refused.
return_url: `https://mystore.com/orders/${order.id}/return`,
}),
});
const intent = await response.json();
// intent.status === "requires_action": the bank wants 3-D Secure. Send the
// buyer to its page; they come back to return_url, and the webhook is the outcome.
if (intent.status === "requires_action" && intent.next_action?.type === "redirect_to_url") {
return res.json({
id: intent.id,
status: intent.status,
redirect: intent.next_action.redirect_to_url.url,
});
}
// requires_action with no next_action: still processing. Do not retry; wait
// for the webhook.
res.json({ id: intent.id, status: intent.status });
});
chargeServer above sends the buyer to redirect when it is present. session_id is the double-charge guard: send it whenever the token came from a session. Fulfill from the webhook, not the return: 3D Secure. Server-side lifecycle (capture, refund, void): /v1/payment_intents.
Test cards
In test mode your processor's test environment decides the outcome. Use one of the sandbox test cards (common numbers such as 4242 4242 4242 4242 are declined); with those, an ordinary total approves. Use a decline-trigger total to exercise the failure paths.
Before going live
Confirm that every element mounts, that validation fires as the buyer types, and, on your merchant account's test path, that a card needing 3-D Secure sends the buyer to the bank's page and back, and that the order settles from the webhook rather than the return. 3D Secure walks those paths.
What's next
- Elements reference — every element, its options and collect shape
- Error handling —
VoraMirrorErrorcodes and recovery /v1/payment_intentsreference — server-side payment lifecycle- Webhooks — async settlement events