SEON Fraud Prevention SDK


A powerful TypeScript/JavaScript SDK for integrating with SEON's comprehensive fraud prevention and anti-money laundering (AML) platform. Detect fraud in real-time with advanced device fingerprinting, digital footprint analysis, and behavioral analytics.

🌟 Features

- 🛡️ Real-time Fraud Detection - Stop fraud before it impacts your business
- 🔍 Digital Footprint Analysis - Deep email, phone, and IP intelligence
- 📱 Device Intelligence - Advanced device fingerprinting for web and mobile
- 🧠 AI-Powered Risk Scoring - Machine learning models with transparent explanations
- 🌍 Global Coverage - Comprehensive data sources and regional compliance
- ⚡ Lightning Fast - Sub-second response times
- 🔧 Easy Integration - Simple API with full TypeScript support
- 📊 Rich Data Insights - 900+ data signals in a single API call

🚀 Quick Start

$3

``bash


Using npm

npm install harper-concierge/seon-sdk

Using yarn

yarn add harper-concierge/seon-sdk

Using pnpm

pnpm add harper-concierge/seon-sdk
`

$3

`typescript
import { Seon, FraudApiRequest, FraudApiResponse } from "seon-sdk";

// Initialize the SEON client
const seon = new Seon(process.env.SEON_API_KEY);

// Basic fraud check
const request: FraudApiRequest = {
email: "user@example.com",
ip: "192.168.1.1",
transaction_id: "txn_123456",
transaction_amount: 99.99,
transaction_currency: "USD",
user_fullname: "John Doe",
};

try {
const response: FraudApiResponse = await seon.fraud(request);

if (response.success && response.data) {
console.log(Fraud Score: ${response.data.fraud_score});
console.log(Risk State: ${response.data.state});
console.log(Transaction ID: ${response.data.id});
} else {
console.error("Fraud check failed:", response.error);
}
} catch (error) {
console.error("Network error:", error);
}
`

📖 Advanced Usage

$3

`typescript
import { Seon, FraudApiRequest } from "seon-sdk";

const seon = new Seon(
process.env.SEON_API_KEY,
"https://api.seon.io/SeonRestService/fraud-api/v2/", // Optional: Custom endpoint
);

const comprehensiveRequest: FraudApiRequest = {
// Transaction details
transaction_id: "txn_987654321",
transaction_type: "purchase",
transaction_amount: 299.99,
transaction_currency: "USD",

// User information
email: "customer@company.com",
phone_number: "+1234567890",
user_fullname: "Jane Smith",
user_firstname: "Jane",
user_lastname: "Smith",
user_dob: "1990-05-15",
user_country: "US",
user_city: "New York",
user_region: "NY",
user_zip: "10001",

// Device and network
ip: "203.0.113.1",
session_id: "sess_abc123def456",
device_id: "dev_xyz789",

// Payment information
payment_mode: "credit_card",
payment_provider: "stripe",
card_bin: "414141",
card_last: "1234",
card_expire: "2025-12",

// Advanced configuration
config: {
// Enable specific APIs
email_api: true,
phone_api: true,
ip_api: true,
aml_api: true,
device_fingerprinting: true,

// Email analysis configuration
email: {
version: "v2",
timeout: 2000,
include: "flags,history,breach_details",
data_enrichment_mode: "detailed",
},

// Phone analysis configuration
phone: {
version: "v1",
timeout: 3000,
include: "hlr_details,cnam_lookup",
data_enrichment_mode: "detailed",
},

// IP analysis configuration
ip: {
version: "v1",
include: "flags,history",
flags_timeframe_days: 30,
},

// AML screening configuration
aml: {
version: "v1",
monitoring_required: true,
fuzzy_enabled: true,
phonetic_search_enabled: true,
scoring: {
result_limit: 10,
score_threshold: 0.85,
},
sources: {
sanction_enabled: true,
pep_enabled: true,
watchlist_enabled: true,
},
},

// Device fingerprinting options
device: {
include: "device_location,extended_device_location",
response_fields: "id,state,fraud_score",
},
},

// Custom business logic fields
custom_fields: {
loyalty_tier: "platinum",
referral_source: "google_ads",
marketing_consent: true,
account_age_days: 365,
previous_orders: 12,
},
};

const response = await seon.fraud(comprehensiveRequest);
`

$3

`typescript
import { Seon, FraudApiRequest } from "seon-sdk";

class EcommerceFraudCheck {
private seon: Seon;

constructor(apiKey: string) {
this.seon = new Seon(apiKey);
}

async checkoutFraudAnalysis(orderData: any) {
const request: FraudApiRequest = {
action_type: "payment",
transaction_id: orderData.orderId,
transaction_amount: orderData.total,
transaction_currency: orderData.currency,

// Customer data
email: orderData.customer.email,
phone_number: orderData.customer.phone,
user_fullname: orderData.customer.name,
ip: orderData.customer.ipAddress,

// Billing information
billing_country: orderData.billing.country,
billing_city: orderData.billing.city,
billing_zip: orderData.billing.zipCode,
billing_street: orderData.billing.address,

// Shipping information
shipping_country: orderData.shipping.country,
shipping_city: orderData.shipping.city,
shipping_zip: orderData.shipping.zipCode,
shipping_method: orderData.shipping.method,

// Payment details
payment_provider: orderData.payment.provider,
card_bin: orderData.payment.cardBin,
card_last: orderData.payment.cardLast4,

// Order items
items: orderData.items.map((item) => ({
item_id: item.id,
item_name: item.name,
item_quantity: item.quantity,
item_price: item.price,
item_category: item.category,
item_store: "Online Store",
item_store_country: "US",
item_url: https://shop.example.com/products/${item.id},
item_custom_fields: {
brand: item.brand,
size: item.size,
color: item.color,
},
})),

config: {
email_api: true,
ip_api: true,
device_fingerprinting: true,
email: { version: "v2", include: "breach_details" },
ip: { version: "v1", include: "flags" },
},
};

const result = await this.seon.fraud(request);

return {
fraudScore: result.data?.fraud_score || 0,
riskLevel: this.getRiskLevel(result.data?.fraud_score || 0),
recommendation: this.getRecommendation(result.data?.state || ""),
transactionId: result.data?.id,
appliedRules: result.data?.applied_rules || [],
deviceInsights: result.data?.device_details,
emailInsights: result.data?.email_details,
ipInsights: result.data?.ip_details,
};
}

private getRiskLevel(score: number): string {
if (score >= 80) return "high";
if (score >= 50) return "medium";
if (score >= 20) return "low";
return "minimal";
}

private getRecommendation(state: string): string {
switch (state) {
case "APPROVE":
return "approve";
case "DECLINE":
return "decline";
case "REVIEW":
return "manual_review";
default:
return "unknown";
}
}
}

// Usage
const fraudChecker = new EcommerceFraudCheck(process.env.SEON_API_KEY!);
const fraudAnalysis = await fraudChecker.checkoutFraudAnalysis(orderData);

if (fraudAnalysis.riskLevel === "high") {
// Block transaction
console.log("Transaction blocked due to high fraud risk");
} else if (fraudAnalysis.recommendation === "manual_review") {
// Queue for manual review
console.log("Transaction queued for manual review");
} else {
// Approve transaction
console.log("Transaction approved");
}
`

$3

`typescript
import { Seon, FraudApiRequest } from "seon-sdk";

class GamingFraudPrevention {
private seon: Seon;

constructor(apiKey: string) {
this.seon = new Seon(apiKey);
}

async playerRegistrationCheck(playerData: any) {
const request: FraudApiRequest = {
action_type: "register",
email: playerData.email,
phone_number: playerData.phone,
user_fullname: playerData.fullName,
user_dob: playerData.dateOfBirth,
user_country: playerData.country,
ip: playerData.ipAddress,
session_id: playerData.sessionId,

config: {
email_api: true,
phone_api: true,
ip_api: true,
aml_api: true,
device_fingerprinting: true,

aml: {
version: "v1",
monitoring_required: true,
sources: {
sanction_enabled: true,
pep_enabled: true,
watchlist_enabled: true,
},
},
},

custom_fields: {
affiliate_code: playerData.affiliateCode,
bonus_claimed: playerData.claimedBonus,
marketing_source: playerData.marketingSource,
},
};

return await this.seon.fraud(request);
}

async depositTransactionCheck(depositData: any) {
const request: FraudApiRequest = {
action_type: "deposit",
transaction_id: depositData.transactionId,
transaction_amount: depositData.amount,
transaction_currency: depositData.currency,
user_id: depositData.playerId,
payment_provider: depositData.paymentMethod,
ip: depositData.ipAddress,

config: {
ip_api: true,
device_fingerprinting: true,
ip: {
version: "v1",
include: "flags,history",
},
},

custom_fields: {
deposit_count: depositData.previousDeposits,
account_age_hours: depositData.accountAgeHours,
last_login: depositData.lastLoginTimestamp,
},
};

return await this.seon.fraud(request);
}
}
`

🔧 Configuration Options

$3

The SDK supports different SEON environments:

`typescript
// US Environment (default for US customers)
const seonUS = new Seon(
apiKey,
"https://api.us-east-1-main.seon.io/SeonRestService/fraud-api/v2/",
);

// EU Environment (default)
const seonEU = new Seon(
apiKey,
"https://api.seon.io/SeonRestService/fraud-api/v2/",
);

// Or use default (auto-detects based on your account)
const seon = new Seon(apiKey);
`

$3

The config object allows fine-tuning of SEON's modules:

| Module | Description | Key Options |
| ----------------------- | ------------------------------------ | ------------------------------------------------------- |
| email_api | Email reputation and intelligence | version, timeout, include, data_enrichment_mode |
| phone_api | Phone number validation and insights | version, timeout, include, hlr_details |
| ip_api | IP geolocation and risk analysis | version, include, flags_timeframe_days |
| aml_api | Anti-money laundering screening | monitoring_required, fuzzy_enabled, sources |
| device_fingerprinting | Device and behavioral analysis | include, response_fields |

📊 Response Data Structure

The SEON API returns comprehensive fraud intelligence with full TypeScript support:

`typescript
interface FraudApiResponse {
success: boolean;
error: ErrorDetails;
data?: {
id: string; // Unique transaction identifier
state: string; // APPROVE, DECLINE, or REVIEW
fraud_score: number; // Risk score (0-100)
version: string; // API version used

// Risk analysis
applied_rules: Array;

// Device intelligence
device_details: DeviceDetails;

// Digital footprint
email_details: EmailDetails;
phone_details: PhoneDetails;
ip_details: IpDetails;

// Additional insights
bin_details: BinDetails;
geolocation_details: GeolocationDetails;
aml_details: AmlDetails | null;
calculation_time: number;
seon_id: number;
};
}
`

All response interfaces are fully typed for optimal TypeScript development experience.

🛡️ Error Handling

The SDK provides comprehensive error handling:

`typescript
try {
const response = await seon.fraud(request);

if (!response.success) {
// API returned an error
console.error("SEON API Error:", response.error);

// Handle specific error cases
if (response.error["401 - Unauthorized"]) {
console.log("Invalid API key");
} else if (response.error["429 - Too Many Requests"]) {
console.log("Rate limit exceeded");
}
}
} catch (error) {
// Network or other errors
console.error("Network error:", error);
}
`

🧪 Testing

The SDK includes comprehensive test coverage with 185+ tests:

`bash


Run tests

npm test

Run tests with coverage

npm run test:coverage

Run tests in watch mode

npm run test:watch

Lint and format code

npm run format

Type checking

npm run type
`

$3

`typescript
import { Seon } from "seon-sdk";

// Mock fetch for testing
global.fetch = jest.fn(() =>
Promise.resolve({
ok: true,
json: () =>
Promise.resolve({
success: true,
data: { fraud_score: 25, state: "APPROVE" },
}),
}),
) as jest.Mock;

const seon = new Seon("test-api-key");
const result = await seon.fraud({ email: "test@example.com" });
`

🌍 Use Cases

$3

- Account opening - KYC and identity verification
- Transaction monitoring - Real-time payment fraud detection
- AML compliance - Sanctions and PEP screening
- Loan applications - Risk assessment and fraud prevention

$3

- Checkout protection - Payment fraud prevention
- Account takeover - Suspicious login detection
- Chargeback reduction - Preemptive fraud identification
- Return fraud - Abuse pattern detection

$3

- Player verification - Identity and age verification
- Bonus abuse prevention - Multi-account detection
- Deposit monitoring - Payment fraud detection
- Regulatory compliance - Geolocation and sanctions screening

$3

- User registration - Fake account prevention
- Content moderation - Spam and abuse detection
- Marketplace safety - Seller and buyer verification
- Subscription fraud - Payment method validation

🔗 Integration Examples

$3

`typescript
import express from "express";
import { Seon } from "seon-sdk";

const app = express();
const seon = new Seon(process.env.SEON_API_KEY!);

const fraudCheckMiddleware = async (
req: express.Request,
res: express.Response,
next: express.NextFunction,
) => {
try {
const fraudCheck = await seon.fraud({
email: req.body.email,
ip: req.ip,
transaction_amount: req.body.amount,
config: { email_api: true, ip_api: true },
});

if (fraudCheck.data?.fraud_score && fraudCheck.data.fraud_score > 80) {
return res
.status(403)
.json({ error: "Transaction declined due to high fraud risk" });
}

req.fraudData = fraudCheck.data;
next();
} catch (error) {
console.error("Fraud check failed:", error);
next(); // Continue on error (fail open)
}
};

app.post("/api/payments", fraudCheckMiddleware, (req, res) => {
// Process payment with fraud insights
res.json({ success: true, fraudScore: req.fraudData?.fraud_score });
});
`

$3

`typescript
// pages/api/fraud-check.ts
import type { NextApiRequest, NextApiResponse } from "next";
import { Seon } from "seon-sdk";

const seon = new Seon(process.env.SEON_API_KEY!);

export default async function handler(
req: NextApiRequest,
res: NextApiResponse,
) {
if (req.method !== "POST") {
return res.status(405).json({ message: "Method not allowed" });
}

try {
const { email, amount, ip } = req.body;

const fraudCheck = await seon.fraud({
email,
transaction_amount: amount,
ip: ip || req.socket.remoteAddress,
config: {
email_api: true,
ip_api: true,
device_fingerprinting: true,
},
});

res.status(200).json({
fraudScore: fraudCheck.data?.fraud_score,
recommendation: fraudCheck.data?.state,
insights: {
email: fraudCheck.data?.email_details,
device: fraudCheck.data?.device_details,
ip: fraudCheck.data?.ip_details,
},
});
} catch (error) {
console.error("Fraud check error:", error);
res.status(500).json({ error: "Internal server error" });
}
}
`

📚 API Reference

$3

#### Constructor

`typescript
new Seon(apiKey: string, apiUrl?: string, enableErrorLogging?: boolean)
`

Parameters:

- apiKey - Your SEON API key for authentication
- apiUrl - Optional custom API endpoint URL (defaults to production)
- enableErrorLogging - Whether to log errors to console (defaults to true in non-test environments)

#### Methods

##### fraud(request: FraudApiRequest): Promise

Performs a fraud analysis on the provided request data.

Parameters:

- request: FraudApiRequest - The fraud check request object

Returns:

- Promise - The fraud analysis response

$3

#### hmacSha256(message: string, key?: string): string

Generates HMAC-SHA256 hash for message signing and verification.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

$3

`bash


Clone the repository

git clone https://github.com/harper-concierge/seon-sdk.git
cd seon-sdk

Install dependencies

npm install

Run tests

npm test

Build the project

npm build

Lint and format

npm format

Type checking

npm type
``

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support & Documentation

- 📖 Official API Documentation: SEON Fraud API Docs
- 💬 Contact Support: SEON Support Portal
- 🌐 SEON Website: https://seon.io
- 📊 API Status: SEON System Status
- 🔧 GitHub Issues: Report Issues

🔄 Changelog

See CHANGELOG.md for a detailed history of changes.

---