@fraudsio/sdk

Official SDK for Frauds.io — Fraud prevention for EU e-commerce merchants.

Zero-knowledge architecture: All personally identifiable information (email, phone, address) is hashed locally before transmission. Your customer data never leaves your server in readable form.

Installation

npm install @fraudsio/sdk

Quick Start

import { FraudsIO } from '@fraudsio/sdk';

const frauds = new FraudsIO('sk_live_your_api_key');

// Check a customer's fraud risk
const result = await frauds.check({
  email: '[email protected]',
  phone: '+31612345678',
});

console.log(result.risk_score);      // 0-100
console.log(result.recommendation);  // "ACCEPT" | "REVIEW" | "BLOCK"
console.log(result.report_count);    // Number of fraud reports

Features

• Automatic hashing — PII is SHA-256 hashed before sending. Server applies HMAC pepper.
• Retry with backoff — Automatic retry on network errors and rate limits.
• TypeScript first — Full type definitions included.
• Zero dependencies — Uses built-in Web Crypto API (Node 18+).
• GDPR compliant — No readable PII transmitted or stored.

API Reference

new FraudsIO(apiKey)

Create a client with just an API key:

const frauds = new FraudsIO('sk_live_...');

Or with full configuration:

const frauds = new FraudsIO({
  apiKey: 'sk_live_...',
  timeout: 5000,       // Request timeout in ms (default: 10000)
  maxRetries: 2,       // Retry attempts (default: 3)
  debug: true,         // Enable debug logging
});

frauds.check(input): Promise<CheckResult>

Check a customer's fraud risk score. All PII fields are hashed automatically.

const result = await frauds.check({
  email: '[email protected]',       // Hashed before sending
  phone: '+31612345678',               // Hashed before sending
  street: 'Kerkstraat 12',            // Combined with city + postal, then hashed
  city: 'Amsterdam',
  postal_code: '1012AB',
  order_amount: 149.99,               // Optional: for risk weighting
  order_id: 'ORD-12345',              // Optional: for reference
});

Response:

{
  risk_score: 87,
  risk_level: 'critical',             // clear | low | medium | high | critical
  recommendation: 'BLOCK',            // ACCEPT | REVIEW | BLOCK
  report_count: 4,
  details: {
    fraud_categories: { dna_scam: 3, chargeback_abuse: 1 },
    countries: { NL: 3, BE: 1 },
    last_reported: '2026-04-10T14:23:00Z',
    first_reported: '2025-11-03T09:15:00Z',
  },
  meta: {
    checked_at: '2026-04-12T15:30:00Z',
    hashes_checked: { email: true, phone: true, address: true },
  }
}

frauds.report(input): Promise<ReportResult>

Report a fraudulent customer to the network.

await frauds.report({
  email: '[email protected]',
  phone: '+31698765432',
  street: 'Kerkstraat 12',
  city: 'Amsterdam',
  postal_code: '1012AB',
  country: 'NL',
  fraud_category: 'dna_scam',
  order_amount: 149.99,
  order_id: 'ORD-12345',
  carrier_barcode: '3SXXX123456',
  notes: 'PostNL confirms delivery, customer claims not received',
});

Fraud categories:

| Category | Description | |----------|-------------| | chargeback_abuse | Chargeback filed despite receiving product | | switch_return | Different/cheaper product returned | | dna_scam | Claims "did not arrive" despite delivery proof | | review_blackmail | Threatens negative review for refund | | empty_box | Returns empty or near-empty box | | social_media_hostage | Threatens social media exposure | | false_damage | Claims product damaged when it wasn't | | partial_return | Returns incomplete product | | review_bombing | Coordinated negative reviews | | wardrobing | Uses product then returns it | | other | Other fraud type |

frauds.verifyWebhook(rawBody, hmacHeader, secret): Promise<boolean>

Verify a Shopify webhook signature:

const isValid = await frauds.verifyWebhook(
  rawBody,
  req.headers['x-shopify-hmac-sha256'],
  process.env.SHOPIFY_WEBHOOK_SECRET
);

if (!isValid) {
  res.status(401).send('Invalid signature');
  return;
}

Error Handling

import { FraudsIO, AuthenticationError, RateLimitError, ValidationError } from '@fraudsio/sdk';

try {
  const result = await frauds.check({ email: '[email protected]' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid API key → check your key at frauds.io/dashboard
  } else if (error instanceof RateLimitError) {
    // Too many requests → wait error.retryAfter seconds
    console.log(`Retry after ${error.retryAfter}s`);
  } else if (error instanceof ValidationError) {
    // Invalid input → check your parameters
  }
}

Integration Examples

Shopify (Node.js)

import { FraudsIO } from '@fraudsio/sdk';

const frauds = new FraudsIO(process.env.FRAUDS_IO_API_KEY);

app.post('/webhooks/orders/create', async (req, res) => {
  const order = req.body;

  const risk = await frauds.check({
    email: order.email,
    phone: order.phone,
    street: order.shipping_address?.address1,
    city: order.shipping_address?.city,
    postal_code: order.shipping_address?.zip,
    order_amount: parseFloat(order.total_price),
    order_id: order.name,
  });

  if (risk.recommendation === 'BLOCK') {
    // Tag order for manual review
    await tagOrder(order.id, [`fraud-risk-${risk.risk_score}`]);
  }

  res.status(200).send('OK');
});

WooCommerce (PHP — coming soon)

// composer require fraudsio/sdk
$frauds = new FraudsIO('sk_live_...');
$result = $frauds->check(['email' => $order->get_billing_email()]);

Requirements

• Node.js 18 or later (uses Web Crypto API)
• API key from frauds.io/dashboard

Support

• Documentation: frauds.io/docs
• Email: [email protected]
• Issues: GitHub Issues

License

MIT