Device data

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.

Absent and malformed payloads

The gateway accepts a payment request with no deviceData. In that case it processes the payment without those browser signals; absence alone does not fail the charge. Only the device-data-specific evaluation and enrichment described below is skipped, and other payment risk controls can still apply.

When deviceData is present, the gateway validates it. Extra properties are stripped. A present but malformed deviceData object returns an HTTP 400 validation error. Schema violations include a missing required property, an invalid IPv4 address, an overlong user agent or referrer, a negative/non-integer time value, or an unsupported pasted-field name. A present but malformed payload does not fall back to the absent-payload path.

Risk evaluation outcomes

When deviceData is absent, HighWire skips this device-data-specific pre-authorization evaluation and enrichment path. Other payment risk controls can still apply. When the device-data-specific pre-authorization Stripe Payment Evaluations path is enabled, a block returns a distinct HTTP 400 decline. The response includes these identifying fields:

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

This decline happens before authorization, so no authorization or money movement occurs. If this device-data-specific evaluation is unavailable, HighWire fails open and continues through the normal payment path.

Handle this response as a decline rather than a validation error. See HighWire returns a high-risk decline for recovery guidance.

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.