@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

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).

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.

Development

cd packages/sdk
npm install
npm run build
npm test

From the repo root:

npm run build:sdk
npm run test:sdk