API reference

HighWire(options?)

Creates a HighWireInstance. Importing the ESM build and calling HighWire() do not access DOM APIs or make network requests. Loading the UMD build registers window.HighWire, but does not collect context or make a request until merchant code calls a method.

HighWire(options?: HighWireOptions): HighWireInstance

interface HighWireOptions {
  apiBase?: string;
}

No publishable key is required for the current collection flow.

hw.collect(options?)

Gathers the supported device, page, and observed paste-event signals. The supported merchant call remains:

const deviceData = await hw.collect();

The shipped declaration uses this non-exported alias and exported interface:

collect(options?: CollectOptions): Promise<CollectedPayload | null>

interface CollectOptions {
  pastedFields?: PastedField[];
}

type PastedField = 'number' | 'cvc' | 'exp' | 'zip';

There are no supported merchant-settable collection options in v0.2.3. The exposed parameter is a compatibility artifact: caller-provided pastedFields is replaced by the instance's observeField() snapshot. Call collect() with no argument and use observeField() as the only supported source of paste names.

Collection has three observable outcomes:

1. When the required IP address and user agent are available, it resolves to CollectedPayload.
2. For handled provider or required-context failures, the promise resolves to null.
3. A missing or broken platform primitive can reject the promise. Payment code must catch that rejection and continue without deviceData.

Collection reads the user agent, attempts ipify, then attempts ifconfig.co if needed, with a five-second timeout per provider. Provider-side CORS can still prevent a permitted origin from returning a readable response.

Forward a successful object without modifying it. For either unavailable outcome, omit deviceData; do not send null, an empty object, or a substitute. Device data defines the complete payload.

hw.observeField(element, fieldName)

Registers a paste-event observer for a checkout field.

observeField(element: Element, fieldName: string): Unobserve

Guard DOM queries before passing an element:

const cardNumber = document.querySelector('#card-number');
if (cardNumber) {
  const unobserve = hw.observeField(cardNumber, 'number');
}

The returned Unobserve function has the type () => void. Calling it detaches that listener and stops future events from that element. It does not clear paste names already recorded by the instance.

Accepted field names

Only "number", "cvc", "exp", and "zip" are recorded. PastedField is not importable in v0.2.3, so consumer code that needs a named type should spell out those four literals.

ESM exports

Use the delivered ESM file and adjacent declaration for TypeScript. Typed CommonJS consumption is not documented for v0.2.3 because the shared declaration models the ESM module rather than the callable CommonJS runtime export.

Unsupported artifact member

The v0.2.3 instance also exposes _transport in its runtime object and declaration. It is not a supported merchant API; createPaymentSession() and confirmPayment() always reject. Do not call, feature-detect, or build against _transport.

Browser-only collection

collect() must run in the cardholder's browser. It relies on globalThis, Promise, fetch, AbortController, navigator.userAgent, and optional page globals; modern Node.js can return valid-looking server context instead of throwing, so server components, API routes, getServerSideProps, and other server paths must not call it.

observeField() requires an actual browser Element/event target to record useful events. Import and construction may remain outside the event handler, but collection and observation belong in client-rendered checkout code. See Browser support and React and Next.js.