Getting started

Before you begin

HighWire currently delivers each release directly as a set of files rather than through a public CDN or npm. You need:

• the release bundle and SHA-384 integrity hash from HighWire;
• a browser-based checkout that already sends its payment request to your backend; and
• either a static-asset path for the UMD build or a frontend build pipeline for the ESM build.

No publishable key is required. Your backend continues to use its existing authentication when it calls HighWire.

What you received

Every pilot handoff contains the complete bundle:

1. highwire-v<version>.js — the UMD build for a plain <script> tag.
2. highwire-v<version>.js.map — the UMD sourcemap for browser debugging. Do not add it to the page as a script.
3. highwire-v<version>.es.js — the ESM build for frontend projects that bundle imports.
4. highwire-v<version>.es.js.map — the ESM sourcemap for browser debugging.
5. highwire-v<version>.es.d.ts — the TypeScript declarations for the ESM build. Keep it beside the .es.js file so TypeScript can resolve it. JavaScript-only projects can ignore it.
6. INTEGRITY.txt — the SHA-384 SRI value for the exact UMD bytes in the handoff.
7. docs/public/ — this complete documentation set, starting at docs/public/index.md.

Use either UMD or ESM on the checkout page. The handoff always includes both builds and all supporting files so the delivered release remains complete and auditable.

Choose a build

Use the UMD build, highwire-v<version>.js, when the checkout loads the library with a plain <script> tag. Self-host it on your origin and pair it with the SRI value from INTEGRITY.txt.

Use the ESM build, highwire-v<version>.es.js, when the frontend bundles JavaScript imports. Keep highwire-v<version>.es.d.ts beside it in TypeScript projects. Bundled imports do not use the separately delivered SRI value.

Choose one runtime build for the page. Keep the matching sourcemap available for debugging and retain the complete handoff for release auditability.

Self-host the UMD build

Copy the delivered UMD file into the static assets served by your checkout, then reference that exact file and hash:

<script
  src="/assets/highwire-v<version>.js"
  integrity="sha384-REPLACE_WITH_THE_HASH_HIGHWIRE_SENT_YOU"
  crossorigin="anonymous"
></script>

Do not minify or otherwise transform the delivered file after the hash is generated. The browser rejects it if the bytes and SRI hash do not match. The UMD build registers the HighWire factory on window.

Import the ESM build

Vendor the ESM file in your frontend source tree and import the factory from that local path:

import { HighWire } from './vendor/highwire/highwire-v<version>.es.js';

Keep the matching TypeScript declaration beside the JavaScript file when your project uses TypeScript. Bundled imports do not use the separately delivered SRI hash.

Create an instance

Create one instance in browser code after loading or importing the factory:

const hw = HighWire();

Importing the ESM build and creating an instance do not access DOM APIs, collect context, or make network requests, but call collect() only in the cardholder's browser. Loading the UMD build registers window.HighWire. A modern Node.js runtime can supply valid-looking server values instead of failing, so server-side collection would attach the wrong context.

Collect for the first time

Call collect() from your existing browser-side submit handler and await the result:

async function collectDeviceDataOrNull() {
  try {
    return await hw.collect();
  } catch {
    return null;
  }
}

async function submitCheckout(existingPaymentRequest) {
  const deviceData = await collectDeviceDataOrNull();

  return fetch('/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      ...existingPaymentRequest,
      ...(deviceData && { deviceData }),
    }),
  });
}

Normal provider or required-context failures resolve to null. A missing or broken platform primitive can instead reject the promise. The helper treats either outcome as unavailable context, so the checkout can continue without deviceData. Do not construct a substitute object.

Continue the integration

Next, follow Integration to observe checkout fields, collect during submission, send deviceData to your backend, and forward it to HighWire.