Device data

These guides apply to the standalone highwire.js v0.2.3 release delivered by HighWire. Use the matching release files; the API names and installation steps below are specific to that version.

Collected signals

hw.collect() gathers a fixed set of browser context:

• device.ip is the cardholder's public IPv4 address. Collection requests ipify first and attempts ifconfig.co if needed; each provider has a five-second timeout. A merchant CSP can permit an origin, but provider-side CORS still determines whether browser code can read the response.
• device.userAgent comes from navigator.userAgent and is truncated to 1024 characters.
• page.referrer comes from document.referrer immediately before payload assembly. It can contain URL data, is truncated to 2048 characters, and is omitted when empty.
• page.timeOnPageMs is computed immediately before payload assembly from performance.timeOrigin. It is a non-negative integer, includes IP-lookup latency, and is omitted when that browser value is unavailable.
• pastedFields reports paste events for checkout fields explicitly registered with observeField(). It contains field names only, never values or pasted content, and is omitted when no name has been recorded.

This is the entire signal set. The library does not collect card data, read input values, fingerprint the device, request geolocation, read or set cookies, or use browser storage.

Payload shape

The object returned when collection succeeds has this complete shape. Optional properties are omitted rather than sent with empty values:

{
  "device": {
    "ip": "203.0.113.42",             // required IPv4
    "userAgent": "Mozilla/5.0 …"      // required, at most 1024 characters
  },
  "page": {                            // optional block
    "referrer": "https://example.com/", // optional, at most 2048 characters
    "timeOnPageMs": 5000               // optional, non-negative integer
  },
  "pastedFields": ["cvc", "exp", "number", "zip"] // optional; any subset
}

Collection sequence

Each call follows this order:

1. The instance captures its cumulative paste-name snapshot when collect() is invoked.
2. Collection reads the user agent.
3. It requests ipify, then attempts ifconfig.co if needed, with a five-second timeout for each provider.
4. It reads the referrer and computes time on page immediately before assembling the payload.

Because page signals are read after public-IP resolution, timeOnPageMs includes IP-lookup latency. A paste event that occurs after the snapshot is absent from that in-flight result but can appear in a later collection on the same instance.

Required fields

When deviceData is present, device, device.ip, and device.userAgent are required. The IP must be a valid IPv4 address, and the user agent must fit within the 1024-character limit.

The IP represents the cardholder browser's public network vantage point. The gateway does not replace a missing value with an address derived from request headers.

Optional fields

The page block is optional. Within it, referrer and timeOnPageMs are each optional; if neither value is available, the complete block is omitted.

pastedFields is optional. Names are deduplicated and sorted lexicographically in the snapshot when collect() is invoked. Recorded names are cumulative and retained for the life of that HighWire instance. unobserve() stops future events but does not clear names already recorded. A new instance starts with no recorded paste names.

When collection returns null

Handled provider or required-context failures resolve to null. This includes invalid responses, timeouts, network failures, blocked requests, an unavailable user agent, or failure to produce a valid IPv4 address. The code attempts ifconfig.co after ipify, but the fallback provider's response can still be unavailable because of provider-side CORS; changing merchant CSP cannot repair provider CORS.

A missing or broken platform primitive, such as AbortController, can reject the collection promise instead of resolving to null. Payment examples catch either unavailable path and continue without deviceData. Do not send null, an empty object, or a hand-built substitute.

Gateway responses

Forward the payload unchanged and handle the payment response according to the Gateway API reference. A failed collection should omit deviceData; do not substitute an empty or hand-built object. A payment decline is separate from a browser collection failure. Do not remove or alter valid context to bypass a decline.

Forward the payload unchanged

Send the exact object returned by hw.collect() to your backend, then pass that object through as the top-level deviceData property on the HighWire direct-API request. Do not select, rename, supplement, or reconstruct its properties.

Follow the browser-to-backend and backend-to-HighWire handoffs in Integration.