@tap-payments/browser-info

Browser fingerprinting SDK for Tap Payments. Collects device, browser, and location data and returns it as Tap-formatted headers ready for payment requests.

Install

yarn add @tap-payments/browser-info

npm install @tap-payments/browser-info

Quick start

import { BrowserInfo } from "@tap-payments/browser-info"

const headers = await new BrowserInfo({
  app: {
    name: "CheckoutWebSDK",
    language: "en",
    identifier: "checkout-web-sdk",
    version: "2.0.0"
  },
  credentials: {
    pk: "pk_test_xxx",
    mdn: "example.com"
  },
  encrypt: (key, value) => value,
  location: {
    ip: "203.0.113.1",
    latitude: "25.276987",
    longitude: "55.296249"
  }
}).get()

Input options

| Option | Field | Type | Description | |--------|-------|------|-------------| | app | name | string | Application display name → maps to an | | app | language | string | Locale code → maps to al | | app | identifier | string? | Product/SDK slug → maps to aid | | app | version | string? | App version → maps to av | | credentials | pk | string | Public key → maps to authorization | | credentials | mdn | string | Merchant domain or bundle ID → maps to mdn | | location | ip | string | Client IP address → maps to ci | | location | latitude | string | Latitude → combined into l | | location | longitude | string | Longitude → combined into l | | location | (URL) | string | Fetch URL returning { ip, latitude, longitude } | | encrypt | — | (key, value) => string | Called per field except authorization |

Note: Input uses location.ip, but the output header key is ci (Connection IP), not ip.

Location options

Pass location as an object:

location: {
  ip: "203.0.113.1",
  latitude: "25.276987",
  longitude: "55.296249"
}

Or as a URL that returns JSON:

location: "https://your-api.com/geo"
// Expected response: { "ip": "...", "latitude": "...", "longitude": "..." }

If omitted, IP and coordinates default to "n/a".

Response headers reference

All fields returned by .get():

| Key | Full name | Description | Source | Required | Example | Encrypted | |-----|-----------|-------------|--------|----------|---------|-----------| | authorization | Authorization | Merchant public key | credentials.pk | Yes | pk_test_xxx | No | | mdn | Merchant Domain Name | Merchant domain or mobile bundle ID | credentials.mdn | Yes | example.com | Yes | | cu | Current URL | Active page origin or URL | window.location.origin | Yes | https://shop.example.com | Yes | | al | Application Locale | App language/locale | app.language (default "en") | Yes | en | Yes | | at | Application Type | Runtime environment type | Hardcoded "browser" | Yes | browser | Yes | | aid | Application Identifier | SDK/product identifier slug | app.identifier | Optional | checkout-web-sdk | Yes | | an | Application Name | Display name of the integrating app | app.name | Optional | CheckoutWebSDK | Yes | | av | Application Version | Semantic version of the app/SDK | app.version | Optional | 2.0.0 | Yes | | rn | Requirer Name | Device name from UA parser | Reserved — always "" | Optional | "" | Yes | | rt | Requirer Type | Device type (desktop, smartphone, tablet) | device.type from UA | Optional | smartphone | Yes | | rb | Requirer Brand | Device manufacturer/brand | device.brand from UA | Optional | Apple | Yes | | rm | Requirer Model | Device model | device.model from UA | Optional | iPhone | Yes | | ro | Requirer OS | Operating system name | os.name from UA | Optional | iOS | Yes | | rov | Requirer OS Version | Operating system version | os.version from UA | Optional | 17.0 | Yes | | bn | Browser Name | Browser/client name | client.name from UA | Optional | Mobile Safari | Yes | | bb | Browser Brand | Browser vendor/brand | Reserved — always "" | Optional | "" | Yes | | bv | Browser Version | Browser/client version | client.version from UA | Optional | 17.0 | Yes | | bua | Browser User Agent | Truncated user-agent string (max 80 chars) | navigator.userAgent | Optional | Mozilla/5.0 (...) | Yes | | bi | Browser ID | Unique browser/device fingerprint | FingerprintJS visitorId | Yes | abc123def456 | Yes | | ci | Connection IP | Client IP address | location.ip or fetched from URL | Optional | 203.0.113.1 | Yes | | cm | Connection MAC | MAC address | Not available in browsers — always "" | Optional | "" | Yes | | l | Location | Geo coordinates as "latitude-longitude" | location.latitude + location.longitude | Optional | 25.276987-55.296249 | Yes |

Field name clarifications

• rn vs ro — rn is requirer/device name (unused today); ro is requirer OS name (e.g. iOS, Android)
• rb vs bb — rb is device brand (Apple, Samsung); bb is browser brand (reserved, empty in browser context)
• rm vs rt — rm is device model; rt is device type (smartphone, desktop)
• bn vs an — bn is browser name (Safari, Chrome); an is application name from your config
• bi vs aid — bi is an auto-generated fingerprint ID; aid is your SDK/product identifier string
• ci vs l — ci is the IP address (location.ip → ci); l is the lat/long pair joined by -
• cu vs mdn — cu is the current page URL/origin; mdn is the merchant domain or bundle ID from credentials
• cm — always empty in browsers (MAC addresses are not exposed to JavaScript)

TypeScript

import { BrowserInfo } from "@tap-payments/browser-info"
import type {
  BrowserInfoOptions,
  BrowserInfoHeaders,
  AppConfig,
  LocationConfig
} from "@tap-payments/browser-info"

const options: BrowserInfoOptions = {
  app: { name: "MyApp", language: "en" },
  credentials: { pk: "pk_test_xxx", mdn: "example.com" },
  encrypt: (_key, value) => value
}

const headers: BrowserInfoHeaders = await new BrowserInfo(options).get()

Browser support

Works in all modern browsers that support ES2018+. Requires window, navigator, and fetch.

License

ISC