Skip to main content

Script-tag integration — auto-update vs pinned (SRI)

You only ever load vora.js

The vora.js bundle is code-split internally — it loads the sub-chunks it needs on demand at session-load time. Those internal chunks are not standalone integration entry points; vora.js is the only script you reference.

Do not import a payment-processor's own SDK directly (via npm / pnpm or its own <script> tag) and do not call a processor SDK's APIs from your integration. The card field is rendered inside vora.js's iframe; a third-party processor SDK is not part of your integration surface. See the Embedded Fields quickstart for the supported flow.

Embedded Fields' browser SDK ships from https://js.vonpay.com/. There are two channels you can load it through:

ChannelURL shapeUpdatesSupply-chain check
Auto-update/v1/vora.jsTracks the latest v1.x.x automaticallyContinuous integrity monitoring by Von Payments
Pinned (SRI)/vX.Y.Z/vora.js + integrity="sha384-…"Byte-exact: stays on the exact build you tested againstBrowser-enforced — refuses to execute if bytes don't match

Pick the one that matches your security posture. Most merchants use auto-update; compliance-sensitive merchants (PCI-DSS scope expansion concerns, banks, healthcare, etc.) typically pin.

Auto-update channel (default)​

<script src="https://js.vonpay.com/v1/vora.js" crossorigin="anonymous"></script>

What this means:

  • The script auto-tracks the latest v1.x.x release. New features, bug fixes, and security patches reach your checkout the moment they ship.
  • Integrity is enforced by Von Payments' continuous integrity monitor — the bundle is verified against its published hash on every request.
  • crossorigin="anonymous" is recommended so browsers can report integrity failures (it's required if you later add integrity for pinning; setting it now avoids re-deploying when you pin).

This is the right default for most integrations. The whole purpose of the channel is to keep merchants on the safest current version automatically.

Pinned channel (SRI)​

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

vX.Y.Z is a placeholder — vora.js ships new versions regularly. Copy BOTH the current version number AND its matching integrity hash from the live registry at https://js.vonpay.com/integrity.json. Never transcribe a version or a hash from this page — both are illustrative and will be out of date.

What this means:

  • Byte-exact pin. The browser computes the SHA-384 of the fetched bytes and compares against your integrity= value. Mismatch → script is rejected; the SDK never loads.
  • Manual updates. You bump the version number AND the integrity= hash on each release. Stale pins keep working but miss new features.
  • Required for any audit posture that demands "no untrusted code runs without explicit operator action."

Both the version number and the hash come from the published registry at https://js.vonpay.com/integrity.json — see Where the hashes come from below for the registry shape.

Where the hashes come from​

The published integrity registry lives at:

https://js.vonpay.com/integrity.json

Shape (truncated to a single version for illustration):

{
  "versions": {
    "vX.Y.Z": {
      "builtAt": "2026-06-04T08:35:21.677Z",
      "sha384": "sha384-…",
      "bytes": 77756,
      "artifacts": [
        {
          "role": "core",
          "path": "vora.js",
          "sha384": "sha384-…",
          "bytes": 77756
        }
      ]
    }
  }
}

The sha384-… placeholders above stand in for the real hashes — copy the current values from the live https://js.vonpay.com/integrity.json for the version you pin.

  • sha384 at the top level is the core-bundle hash — the value you pin in the integrity= attribute. artifacts[] carries per-file hashes for the core bundle and its internal sub-chunks.
  • builtAt is the publish timestamp.
  • bytes is informational — you don't pass it to the browser, but it lets you sanity-check before pinning (a 0-byte or absurdly small entry is the canonical signal that the registry got corrupted).
  • The registry is append-only — old version entries stay published forever so pinned snippets in deployed customer code don't break.

Automating updates​

If you're on the pinned channel, the version + hash should be checked into source control alongside the snippet. A typical CI flow:

  1. On each release, your build pipeline fetches https://js.vonpay.com/integrity.json.
  2. Pipeline reads the latest versions.{v} entry.
  3. Pipeline rewrites the <script> tag's src and integrity attributes in your HTML template.
  4. Commit + redeploy.

You decide the cadence — daily / weekly / per-release-tag of your own product. The auto-update channel exists for merchants who want this automatic; the pinned channel exists for merchants who want explicit operator action on every SDK update.

Content Security Policy​

script-src must allowlist js.vonpay.com (regardless of channel):

script-src 'self' js.vonpay.com;

Plus your active binder's CDN. See Errors → CSP requirements for the full list.

Pinned-channel snippets do NOT change the CSP — the integrity attribute is applied by the browser AFTER the script is fetched, and the script is fetched from the same js.vonpay.com origin in both modes.

When to pick which​

PosturePick
Most merchantsAuto-update. Stay current, let Von Payments' integrity monitor handle continuous verification.
PCI-DSS compliance evidence requires "no untrusted code without operator action"Pinned. Update SHA on each release through your normal change-control.
Compliance team requires byte-exact reproducibility of every checkout renderPinned. Same answer.
Your CI pipeline writes the script tag dynamically and you can read integrity.json from itPinned with automated update. Best of both worlds.
You're shipping a self-hosted SDK fork (don't)We don't support this. Use one of the two channels above.

What's next​