Skip to main content

vora-hosted.js — Hosted Checkout Drop-in

A small script that sends the buyer from your page to the hosted checkout page. Your server creates the checkout session with your secret key, using prices from your own records; the script only redirects the buyer to it. The browser sends no price and no API key.

This is not an npm package. It is a script served from the Von Payments CDN that you include via a <script> tag.

vora-hosted.js ≠ vora.js — similar names, different products

Two browser scripts live side by side under js.vonpay.com/v1/. They do different things — pick by what you want the buyer to see:

ScriptLoaded fromBuyer experience
vora-hosted.js (this page)https://js.vonpay.com/v1/vora-hosted.jsRedirects to a hosted checkout page on checkout.vonpay.com. Easiest integration.
vora.js (@vonpay/vora-js)https://js.vonpay.com/v1/vora.jsNo redirect. Mounts iframe card / address / wallet fields on your own page. See Embedded Fields quickstart.

If you want the buyer to stay on your domain, you want vora.js, not vora-hosted.js.

How it works​

  1. Your server creates the session with your secret key and returns its checkoutUrl.
  2. Your page calls VonPay.button(...) or VonPay.checkout(...), which asks your server for that URL and redirects the buyer there.

1. Your server​

Create the session from your own order, never from a price the browser sent:

// Express, with @vonpay/checkout-node
app.post("/api/checkout-session", async (req, res) => {
// Look the order up in your records, and check it belongs to this buyer.
const order = await loadOrder(req.body.cartId);
if (!order || order.ownerId !== req.session.userId) {
return res.status(404).json({ error: "Order not found" });
}
const session = await vonpay.sessions.create(
{
amount: order.totalMinor, // minor units: 1499 = $14.99
currency: "USD",
successUrl: `https://mystore.com/order/${order.id}/confirm`,
cancelUrl: "https://mystore.com/cart",
},
{ idempotencyKey: `session:${order.id}` },
);
res.json({ checkoutUrl: session.checkoutUrl });
});

Everything about the session is set here: line items, metadata, the buyer, expiresIn. See Create a session.

2. Your page​

<button id="pay-button">Pay now</button>

<script src="https://js.vonpay.com/v1/vora-hosted.js"></script>
<script>
VonPay.button("#pay-button", {
sessionEndpoint: "/api/checkout-session",
body: { cartId: "cart_123" },
onError: function (err) {
alert("Checkout failed: " + err.message);
},
});
</script>

VonPay.button() sends a POST with your body as JSON to sessionEndpoint (same-origin cookies included), reads { "checkoutUrl": "..." } from the reply, checks the address and redirects. The button is disabled and dimmed while that happens, and re-enabled if it fails.

To start it yourself instead of on a click:

VonPay.checkout({ sessionEndpoint: "/api/checkout-session", body: { cartId: "cart_123" } });

// or, when the page already has the URL your server created:
VonPay.checkout({ checkoutUrl: checkoutUrlFromYourServer });

Options​

OptionWhat it is
sessionEndpointURL of your server endpoint. Called with POST and a JSON body; must reply { "checkoutUrl": "..." }.
bodyObject sent to sessionEndpoint, such as a cart id. Your server must not trust a price in it.
checkoutUrlInstead of sessionEndpoint: the checkoutUrl your server received from sessions.create. Pass it exactly as returned.
onErrorbutton() only: a function called with the error when checkout fails.

Pass exactly one of sessionEndpoint or checkoutUrl. Any other option is an error, including the session fields (amount, currency, successUrl, lineItems, metadata, the buyer fields and so on), so a typo or a leftover price is never silently ignored:

  • checkout() throws.
  • button() never throws, so the rest of your page script keeps running. It logs the problem when it is attached, and on click it calls onError (or, with no onError, shows the buyer "Checkout is not available on this page right now. Please contact the store."). It never redirects and sends nothing. A selector that matches nothing is logged, not thrown.

Where the buyer can be sent​

The script redirects only to an https address on exactly https://checkout.vonpay.com or https://checkout-staging.vonpay.com. Any other address is refused, including other vonpay.com addresses, another port and http.

If your account uses a branded checkout address, live sessions return a checkoutUrl on https://{your-name}.vonpay.com. Declare that host once, before checkout() or button() runs:

VonPay.configure({ checkoutHost: "acme.vonpay.com" });

The script then also trusts exactly https://acme.vonpay.com. checkoutHost must be one name followed by .vonpay.com, with no https://, port, path or wildcard, or configure() throws. null clears it.

Keys​

The script needs no API key and calls no Von Payments API. VonPay.configure() is optional; it refuses a secret key (vp_sk_*) if one is passed, so a secret key can never end up in your page. Your secret key belongs on your server, in the sessions.create call above.

Loading the script​

<script src="https://js.vonpay.com/v1/vora-hosted.js"></script>

This makes the VonPay object available globally. /v1/vora-hosted.js updates as new versions ship.

Pinning a version​

To stay on a build you tested, load the version's own address with its integrity hash instead:

<script
src="https://js.vonpay.com/vX.Y.Z/vora-hosted.js"
integrity="sha384-…"
crossorigin="anonymous"></script>

vX.Y.Z and the hash are placeholders: copy both from the registry below, never from this page. Each version's hash is in the voraHosted section of https://js.vonpay.com/integrity.json (voraHosted.versions, not the top-level versions, which lists vora.js). vora-hosted.js loads no other script, so the hash covers all of its code. You move to each new version yourself. For which channel suits you, see Script-tag integration.

With a Content Security Policy, allow https://js.vonpay.com in script-src. The script's only request goes to your own sessionEndpoint, so connect-src needs nothing for Von Payments.

Upgrading from 1.x​

Version 1.x created the session in the browser, with a publishable key and the amount from the page. That no longer works: the API refuses a price sent with a publishable key (403 auth_key_type_forbidden). In 2.0 your server creates it:

  1. Add a server endpoint that creates the session with your secret key and returns { checkoutUrl } (above). Move the amount, currency, URLs, line items and metadata there, taken from your own records.
  2. In the page, replace the session fields passed to VonPay.checkout() / VonPay.button() with sessionEndpoint (and any body your endpoint needs), or pass the checkoutUrl your server returned.
  3. Remove VonPay.configure({ apiKey }) (optional now) and baseUrl (it throws).

A page still passing a price gets the clear error described in Options instead of a checkout, and the buyer is never redirected.

The older https://checkout.vonpay.com/vonpay.js address serves the 1.0 script, which creates the session in the browser; move to the server flow above.

Browser Support​

Works in all modern browsers (Chrome, Firefox, Safari, Edge). No dependencies.