Troubleshooting

Use the browser console and Network panel together with the merchant backend's HighWire response to identify where an integration stopped. The sections below separate browser loading, collection, observation, runtime, and gateway-validation failures.

HighWire is not a function

Likely cause. In a script-tag integration, the checkout called HighWire() before the external UMD script loaded, executed, and registered window.HighWire. An incorrect self-hosted asset path or a script-src block can leave the factory unregistered for the same reason.

Check. In the browser Network panel, confirm that the configured script URL returns the expected JavaScript file. Then check the console for a Content Security Policy error and confirm that initialization runs after the script has loaded.

Recovery. Correct the self-hosted asset path or allow the merchant origin for the script. Initialize HighWire() only after the external script has loaded and executed, such as from its load event or from code that runs later. If the checkout uses the ESM build, import the factory instead of expecting a window.HighWire global. Follow the canonical UMD and ESM setup and review the Content Security Policy requirements.

The browser reports an integrity mismatch

Likely cause. The integrity value does not match the downloaded UMD bytes. The hash may have been copied incorrectly, paired with another release, or invalidated by transforming the delivered file.

Check. Confirm that the attribute contains the complete delivered value, including the sha384- prefix and any trailing = padding. Verify that the script URL serves the matching, unmodified release file.

Recovery. Replace both the file and hash with the matching pair delivered by HighWire, and do not minify, transform, or otherwise rewrite the file after the hash is generated. Review Subresource Integrity and the canonical self-hosting setup.

Collection returns null

Likely cause. Collection could not produce a required browser value. Common causes include both IP providers being blocked, unavailable, timed out, or unable to return a valid IPv4 address; an offline or IPv6-only client; or an unavailable browser user agent.

Check. In the Network panel, inspect the requests to api.ipify.org and, after a failure, ifconfig.co. Check the console for connect-src violations and confirm that navigator.userAgent is available.

Recovery. Preserve the merchant endpoint and both attempted provider origins in connect-src. CSP permission does not override provider-side CORS. Whether collection resolves to null or rejects unexpectedly, omit deviceData and continue the existing payment request.

pastedFields is missing or omitted

Likely cause. No supported name was present in the instance's snapshot. Registration may have run before the element existed, used an unsupported case-sensitive name, or no paste may have occurred before collect() was invoked.

Check. Confirm that registration runs after the element exists and before the relevant paste. Names are captured at invocation, deduplicated, sorted lexicographically, and retained for the life of the instance.

Recovery. Register each relevant field after mount. unobserve() stops future events but does not erase a name already recorded; create a new HighWire() instance when the checkout needs a fresh paste-history boundary.

Collection ran outside the browser

Likely cause. Server-side code called collect(). Modern Node.js may supply navigator, performance, and fetch, so the result can contain valid-looking server IP/user-agent/page context instead of throwing.

Check. Trace the call site, not merely the import. Importing ESM and constructing the factory do not access DOM APIs, collect context, or make network requests; collection is the browser-only boundary. Loading UMD has the expected global-registration effect.

Recovery. Move collect() into a cardholder-browser event handler. In Next.js, use a client component and never collect from a server component, API route, or getServerSideProps. See Browser-only collection and React and Next.js.

HighWire rejects deviceData

Likely cause. A present deviceData object was modified, reconstructed, or malformed before it reached the HighWire gateway. Unlike an absent payload, a payload that fails validation causes the payment request to return HTTP 400.

Check. Inspect the object at the merchant-backend handoff and compare it with the value returned by collect(). Confirm it was forwarded unchanged, then review the canonical required fields, optional fields, and accepted values in Device data.

Recovery. Forward the successful collection result as the top-level deviceData property without selecting, renaming, supplementing, or rebuilding its properties. When collection returns null, omit the property entirely. Follow Forward the payload unchanged and the integration handoff.

HighWire returns a high-risk decline

Symptom. The gateway returns an HTTP 400 decline for an expected-valid request. The response includes these identifying fields:

{
  "status": "DECLINED",
  "declinedReason": "Transaction flagged as high risk."
}

Meaning. When pre-authorization risk evaluation is enabled, this response is a risk decline that occurs before authorization. It is distinct from the HTTP 400 validation error returned for malformed deviceData, and no authorization or money movement occurs.

Recovery. Treat this response as a payment decline, not as evidence that deviceData is malformed. Do not strip or alter valid deviceData to bypass the decline. Confirm that the collected object was forwarded unchanged; if an expected-valid request is unexpectedly blocked, contact your HighWire representative for support.