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 VORA Mirror 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 byte-identical content through a 12-month deprecation window (until 21 May 2027), 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"`)
`successUrl`	string	No	Redirect after success
`cancelUrl`	string	No	Redirect on cancel
`mode`	string	No	Payment mode (default `"payment"`)
`description`	string	No	Payment description for bank statements
`locale`	string	No	Checkout page language (e.g. `"en"`, `"fr"`)
`expiresIn`	number	No	Session TTL in seconds (300-3600, default 1800)
`buyerId`	string	No	Your customer ID
`buyerName`	string	No	Pre-fills billing form
`buyerEmail`	string	No	Buyer's email
`lineItems`	array	No	Order items
`metadata`	object	No	Key-value pairs

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_*). Publishable keys can only create checkout sessions — they cannot read session data, issue refunds, or perform any destructive operation. This is what makes it safe to ship in browser code.

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​