vora-hosted.js — Hosted Checkout Drop-in

A lightweight drop-in script for creating checkout sessions and redirecting buyers directly from the browser. No backend required.

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:

Script	Loaded from	Buyer experience
`vora-hosted.js` (this page)	`https://js.vonpay.com/v1/vora-hosted.js`	Redirects to a hosted checkout page on `checkout.vonpay.com`. Easiest integration.
`vora.js` (`@vonpay/vora-js`)	`https://js.vonpay.com/v1/vora.js`	No 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.

Installation

Add the script tag to your HTML:

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

This makes the VonPay object available globally.

Renamed from vonpay.js

This script was previously served at https://checkout.vonpay.com/vonpay.js. That legacy URL keeps serving its original script through a deprecation window, so existing SRI-pinned integrations keep working unchanged — no rush to migrate. New integrations should use https://js.vonpay.com/v1/vora-hosted.js. Only the script URL changed; the global object stays VonPay and every method below is identical.

Key requirements

vora-hosted.js requires a publishable key (vp_pk_test_* or vp_pk_live_*). It rejects secret keys (vp_sk_*) and legacy keys (vp_key_*) with a thrown error, because either would expose full API credentials in the browser.

Create a publishable key at /dashboard/developers/api-keys.

VonPay.configure(options)

Call once before any other method:

VonPay.configure({
  apiKey: "vp_pk_live_xxx",                    // publishable key only
  baseUrl: "https://checkout.vonpay.com",      // optional, this is the default
});

The baseUrl is the API host that creates sessions and serves the hosted checkout page — it stays checkout.vonpay.com and is unrelated to the script URL.

VonPay.checkout(options)

Creates a session and immediately redirects the buyer to the checkout page.

VonPay.checkout({
  amount: 1499,
  currency: "USD",
  successUrl: "https://mystore.com/confirm",
  cancelUrl: "https://mystore.com/cart",
  buyerName: "Jane Doe",
  buyerEmail: "jane@example.com",
  lineItems: [
    { name: "Premium Widget", quantity: 1, unitAmount: 1499 },
  ],
  metadata: { orderId: "order_123" },
});

Options

Option	Type	Required	Description
`amount`	number	Yes	Amount in minor units (cents)
`currency`	string	Yes	ISO 4217 (`USD`, `EUR`)
`country`	string	No	ISO 3166-1 alpha-2 (e.g. `"US"`), defaults to `"US"`
`successUrl`	string	No	Redirect after success
`cancelUrl`	string	No	Redirect on cancel
`buyerId`	string	No	Your stable, unique-per-user account ID — same value every visit, never per-visit/random
`buyerName`	string	No	Pre-fills billing form
`buyerEmail`	string	No	Buyer's email
`lineItems`	array	No	Order items
`metadata`	object	No	Key-value pairs

The hosted drop-in forwards only the options above. To set server-only fields such as mode, description, locale, or expiresIn, create the session on your server with POST /v1/sessions and redirect to the returned checkoutUrl instead.

VonPay.button(selector, options)

Attach checkout to a button click:

<button id="pay-btn">Buy Now — $14.99</button>

<script>
  VonPay.configure({ apiKey: "vp_pk_live_xxx" });

  VonPay.button("#pay-btn", {
    amount: 1499,
    currency: "USD",
    successUrl: "https://mystore.com/confirm",
    onError: function(err) {
      alert("Checkout failed: " + err.message);
    },
  });
</script>

The button is automatically disabled and dimmed while the session is being created. On error, it's re-enabled and the onError callback fires.

Full Example

<!DOCTYPE html>
<html>
<head>
  <title>My Store</title>
</head>
<body>
  <h1>Premium Widget — $14.99</h1>
  <button id="pay-btn">Pay Now</button>

  <script src="https://js.vonpay.com/v1/vora-hosted.js"></script>
  <script>
    VonPay.configure({ apiKey: "vp_pk_test_xxx" });

    VonPay.button("#pay-btn", {
      amount: 1499,
      currency: "USD",
      successUrl: "https://mystore.com/order/123/confirm",
      cancelUrl: "https://mystore.com/cart",
      lineItems: [
        { name: "Premium Widget", quantity: 1, unitAmount: 1499 }
      ],
    });
  </script>
</body>
</html>

Security Note

vora-hosted.js requires a publishable key (vp_pk_*). A publishable key cannot act on your merchant API: it cannot retrieve full session details, issue refunds, create payment intents, or take any other server-authorized action — those return auth_key_type_forbidden (HTTP 403). That is what makes it safe to ship in browser code.

In this integration the key is used exactly once — to create the session. The browser then navigates to the hosted checkout page, which runs on our origin and never presents your key at all.

Its reach is wider in Embedded Fields, though, so do not carry this page's mental model over: there a publishable key is the required credential for the browser-facing /v1/public/* routes, and some of those move money. See API Key Types for every route it unlocks and what each one does.

Secret keys (vp_sk_*) must never appear in frontend code; vora-hosted.js will refuse to run with one.

Browser Support

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

Installation​

Key requirements​

VonPay.configure(options)​

VonPay.checkout(options)​

Options​

VonPay.button(selector, options)​

Full Example​

Security Note​

Browser Support​