@fraud-intercept/sdk

Typed Node.js client for the Fraud Intercept Submit Event API (POST /api/v1/events).

Published on npm as @fraud-intercept/sdk. API reference: fraud-intercept.com/api-docs.

Requirements

• Node.js 18+ (uses global fetch)
• A Fraud Intercept API key from your brand dashboard (see authentication)

Install

npm install @fraud-intercept/sdk

Quick start

import FraudIntercept from '@fraud-intercept/sdk'

const client = new FraudIntercept({
  apiKey: process.env.FRAUD_INTERCEPT_API_KEY!,
  baseUrl: 'https://fraud-intercept.com',
})

const result = await client.checkRegistration({
  eventId: 'fingerprint-request-id-or-unique-id',
  email: '[email protected]',
  customerName: 'Jane Doe',
})

if (result.recommendation === 'block') {
  // Deny the action
}

Event types

Send the appropriate helper at each integration point:

| Helper | eventType | |--------|-------------| | checkRegistration() | register | | checkLogin() | login | | checkDeposit() | deposit | | checkWithdrawal() | withdrawal |

Or use submitEvent({ eventType, eventId, ... }) directly.

EVENT_TYPES in this package must stay in sync with lib/utils/event-type.ts in the main app.

Configuration

| Option | Required | Default | |--------|----------|---------| | apiKey | Yes | — | | baseUrl | No | https://fraud-intercept.com | | timeout | No | 10000 (ms) | | retries | No | 2 (network errors only) |

Idempotency

Pass a stable key per logical operation to avoid duplicate events on retries:

await client.submitEvent(
  { eventType: 'deposit', eventId: 'fp_abc', email: '[email protected]' },
  { idempotencyKey: 'deposit-user-123-2026-06-03' },
)

Response fields

The client returns the API data object, including:

• recommendation — allow | review | block
• score, riskLevel, triggeredRules, flags
• matchedThreat — Known Threat match (legacy alias: matchedFraudster)
• device, multiAccount, coverage, notes
• binDetails: issuer BIN metadata for the submitted cardBin, or null (see BIN intelligence)

Errors

• FraudInterceptError — validation and API errors (status, code)
• AuthenticationError — invalid or missing API key (401)
• RateLimitError — rate limit exceeded (429)

Client-side validation runs before any HTTP call (missing eventId, invalid eventType, no identifiers, invalid creditCardHash format, malformed cardBin/customerCountry).

BIN intelligence (optional)

Send the card's BIN (first 6-8 digits, never a full PAN) and the customer's declared country to get issuer-level card metadata and a country-mismatch signal back:

const result = await client.checkDeposit({
  eventId: 'fp_abc',
  email: '[email protected]',
  cardBin: '411111',
  customerCountry: 'us',
})

result.binDetails
// {
//   bin: '411111',
//   cardBrand: 'Visa',
//   cardType: 'credit',
//   prepaid: false,
//   bankName: 'Example Bank',
//   country: { code: 'US', name: 'United States' },
//   countryMismatch: false,
// }

• cardBin: 6-8 digits only. Spaces and interior dashes are stripped client-side ('4111-11' → '411111'); anything longer than 8 digits (e.g. a full card number) is rejected before any HTTP call is made.
• customerCountry: a 2-letter ISO country code, uppercased automatically ('us' → 'US').
• binDetails is null when cardBin was not sent, or the BIN is not in the reference dataset.
• coverage.paymentIntelligence reflects whether BIN enrichment ran for the event (true for all tiers today).

Payment network matching

Cross-brand payment linking requires FI Payment Fingerprint v1 — the same 64-character hash for the same funding PAN across all brands on the network.

Algorithm

1. Use the funding PAN (primary account number) only — not wallet DPANs or processor tokens.
2. Strip all non-digit characters from the PAN string.
3. Validate the result is 13–19 digits.
4. Compute SHA-256 over the UTF-8 encoding of that digit string.
5. Send the digest as lowercase hexadecimal, exactly 64 characters, in creditCardHash.

Do not include expiry, CVV, cardholder name, billing ZIP, or merchant-specific salts.

Reference vector

| Input PAN (digits only) | Fingerprint v1 | |-------------------------|----------------| | 4111111111111111 | 9bbef19476623ca56c17da75fd57734dbf82530686043a6e491c6d71befe8f6e |

Use the SDK helpers to compute or validate hashes:

import {
  hashCreditCardPan,
  FI_PAYMENT_FINGERPRINT_V1_REFERENCE_HASH,
  validateCreditCardHash,
} from '@fraud-intercept/sdk'

const fingerprint = hashCreditCardPan('4111 1111 1111 1111')
// → 9bbef19476623ca56c17da75fd57734dbf82530686043a6e491c6d71befe8f6e

Anti-patterns (will not network-match)

These identifiers will not correlate with other brands in the identity graph:

• Payment processor tokens / network tokens
• Apple Pay / Google Pay device account numbers (DPANs)
• HMAC-SHA256(PAN, merchant_secret) or other per-merchant salted hashes
• BIN + last4 only (ambiguous, not a PAN fingerprint)
• Prefixed digests such as sha256:... (rejected by the API)

Full contract: Payment fingerprint — API docs.

Embedded Risk Panel (Core tier+)

Mint a short-lived token (10-minute expiry) for a read-only risk view you embed inside your own back-office for a specific customer:

const { embedUrl } = await client.createEmbedToken({
  customerEmail: '[email protected]',
})

Provide at least one of customerEmail or customerUserId. theme ('light' | 'dark', default 'dark') is accepted and carried in the token, but the panel currently renders in the dark theme only — light theme is planned.

Call createEmbedToken from your backend only. It requires your API key, so never call it from a browser. Hand the resulting embedUrl to a small loader script on your page instead:

<script src="https://fraud-intercept.com/embed.js"></script>
<div id="risk-panel"></div>
<script>
  // Mint the embed URL server-side with your API key:
  // client.createEmbedToken({ customerEmail: '[email protected]' })
  FraudIntercept.mount({ container: '#risk-panel', embedUrl: embedUrlFromYourBackend })
</script>

Before embedding works, add the origins of the pages that will host the panel in your dashboard's Integration Settings (Embedded Risk Panel section). Requests from unlisted origins are blocked.

Development

cd packages/sdk
npm install
npm run build
npm test

From the repo root:

npm run build:sdk
npm run test:sdk