Fraud Detection

Overview

FraudShield provides comprehensive fraud detection capabilities including device fingerprinting, duplicate detection, velocity controls, and custom rules.

Key Features

Device Intelligence

Fingerprint devices and detect emulators, VPNs, and suspicious patterns

Duplicate Detection

Find when the same document or face is used across accounts

Velocity Controls

Prevent abuse with rate limiting and pattern detection

Custom Rules

Create rules tailored to your business logic

Device Fingerprinting

// Register a device fingerprint
const device = await txcloud.fraud.devices.register({
  fingerprint: {
    user_agent: navigator.userAgent,
    screen_resolution: `${screen.width}x${screen.height}`,
    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
    language: navigator.language,
    platform: navigator.platform,
    canvas_hash: await getCanvasHash(),
    webgl_hash: await getWebGLHash()
  },
  ip_address: clientIp,
  user_id: userId
});

console.log('Device ID:', device.id);
console.log('Risk Score:', device.risk_score);
console.log('Risk Level:', device.risk_level);

// Check for suspicious signals
if (device.signals.is_vpn) {
  console.log('VPN detected');
}
if (device.signals.is_emulator) {
  console.log('Emulator detected');
}

device = txcloud.fraud.devices.register(
    fingerprint={
        "user_agent": user_agent,
        "screen_resolution": screen_resolution,
        "timezone": timezone,
        "language": language,
        "platform": platform,
        "canvas_hash": canvas_hash,
        "webgl_hash": webgl_hash
    },
    ip_address=client_ip,
    user_id=user_id
)

print(f"Device ID: {device.id}")
print(f"Risk Score: {device.risk_score}")

if device.signals.is_vpn:
    print("VPN detected")

Device Response

{
  "id": "dev_a1b2c3d4e5f6",
  "risk_score": 250,
  "risk_level": "medium",
  "is_new": false,
  "first_seen": "2024-12-01T08:00:00Z",
  "times_seen": 47,
  
  "signals": {
    "is_bot": false,
    "is_emulator": false,
    "is_vpn": true,
    "is_proxy": false,
    "is_tor": false,
    "is_datacenter": false,
    "timezone_mismatch": false
  },
  
  "ip_analysis": {
    "ip": "102.45.67.89",
    "country": "MA",
    "city": "Casablanca",
    "isp": "Maroc Telecom",
    "is_vpn": true,
    "vpn_provider": "NordVPN"
  },
  
  "linked_users": ["usr_123", "usr_456"],
  "linked_accounts": 2
}

A device linked to multiple accounts may indicate account sharing or fraud.

Duplicate Detection

Find if a document or face has been used before:

// Search for duplicates
const duplicates = await txcloud.fraud.duplicates.search({
  type: 'face',  // or 'document'
  image: selfieBase64,
  threshold: 0.85  // similarity threshold
});

if (duplicates.matches.length > 0) {
  console.log('Duplicate found!');
  
  for (const match of duplicates.matches) {
    console.log(`Match ID: ${match.id}`);
    console.log(`Similarity: ${match.similarity}`);
    console.log(`Original verification: ${match.verification_id}`);
  }
}

Response

{
  "id": "dup_a1b2c3d4",
  "type": "face",
  "matches_found": true,
  "matches": [
    {
      "id": "match_xyz789",
      "verification_id": "ver_abc123",
      "similarity": 0.94,
      "created_at": "2024-11-15T10:00:00Z",
      "user_id": "usr_different_user"
    }
  ]
}

Velocity Controls

Prevent abuse with rate-based rules:

// Check velocity before allowing action
const velocityCheck = await txcloud.fraud.velocity.check({
  user_id: userId,
  action: 'verification_attempt',
  window: '1h',
  ip_address: clientIp,
  device_id: deviceId
});

if (!velocityCheck.allowed) {
  console.log('Rate limit exceeded');
  console.log(`Retry after: ${velocityCheck.retry_after}s`);
  throw new Error('Too many attempts. Please try again later.');
}

Create Velocity Rules

// Create a velocity rule
await txcloud.fraud.velocity.rules.create({
  name: 'Verification Limit',
  description: 'Max 3 verification attempts per hour',
  action: 'verification_attempt',
  limit: 3,
  window: '1h',
  scope: 'user_id',  // or 'ip_address', 'device_id'
  on_exceed: 'block',
  cooldown: '30m'
});

Custom Fraud Rules

Create rules tailored to your business:

// Create a custom rule
const rule = await txcloud.fraud.rules.create({
  name: 'High Risk New User',
  description: 'Flag new users with VPN and high-value transactions',
  condition: `
    user.age_days < 7 AND 
    device.is_vpn = true AND 
    transaction.amount > 10000
  `,
  action: 'flag',
  score_adjustment: 300,
  enabled: true
});

Rule Conditions

Variable	Description
`user.age_days`	Days since registration
`user.verification_count`	Number of verifications
`device.is_vpn`	VPN detected
`device.is_emulator`	Emulator detected
`device.linked_accounts`	Accounts using device
`transaction.amount`	Transaction amount
`velocity.daily_count`	Actions today

Rule Actions

Action	Description
`flag`	Add flag, continue processing
`review`	Queue for manual review
`block`	Block the action
`challenge`	Require additional verification

Blocklist Management

Manage blocked entities:

// Add to blocklist
await txcloud.fraud.blocklist.add({
  type: 'device',
  value: deviceId,
  reason: 'confirmed_fraud',
  expires_in: null  // permanent
});

// Check blocklist
const check = await txcloud.fraud.blocklist.check({
  type: 'device',
  value: deviceId
});

if (check.blocked) {
  console.log('Device is blocked');
  console.log(`Reason: ${check.reason}`);
}

Blocklist Types

Type	Example
`device`	Device fingerprint ID
`ip`	IP address or CIDR
`email`	Email address
`phone`	Phone number
`document`	Document number

Fraud Signals

Report and track fraud signals:

// Report a fraud signal
const signal = await txcloud.fraud.signals.report({
  type: 'chargeback',
  user_id: userId,
  verification_id: verificationId,
  details: {
    amount: 5000,
    currency: 'MAD',
    transaction_id: 'txn_123'
  }
});

// Later, confirm or dismiss
await txcloud.fraud.signals.confirm(signal.id, {
  notes: 'Confirmed chargeback from bank'
});

// Or dismiss false positive
await txcloud.fraud.signals.dismiss(signal.id, {
  notes: 'Customer resolved dispute'
});

Integration with Identity

FraudShield integrates automatically with Identity verification:

// Fraud signals are included in verification response
const verification = await txcloud.identity.verify({
  document_front: doc,
  country: 'MA',
  checks: ['ocr', 'face_match', 'liveness', 'fraud']
});

// Access fraud signals
console.log('Fraud check:', verification.checks.fraud);
// {
//   status: 'passed',
//   risk_score: 150,
//   duplicate_detected: false,
//   device_risk: 'low',
//   signals: ['known_device', 'normal_velocity']
// }

Analytics

Monitor fraud patterns:

const summary = await txcloud.fraud.analytics.summary({
  period: '30d'
});

console.log('Total signals:', summary.signals.total);
console.log('Confirmed fraud:', summary.signals.confirmed);
console.log('False positive rate:', summary.false_positive_rate);

// Get trends
const trends = await txcloud.fraud.analytics.trends({
  period: '30d',
  granularity: 'daily'
});

Best Practices

Layer Your Defenses

Use multiple fraud signals together:

Device fingerprinting
Velocity controls
Duplicate detection
Custom rules

Tune Your Thresholds

Start conservative and adjust based on data:

Week 1-2: Log all flags, don’t block
Week 3-4: Analyze patterns
Week 5+: Implement blocking rules

Monitor False Positives

Track and minimize false positives:

Review blocked users regularly
Provide appeal process
Adjust rules based on feedback

Feed Back Confirmed Fraud

Report confirmed fraud to improve detection:

Use signals.report() for new fraud
Confirm or dismiss flagged signals
This trains the ML models

Next Steps

Transaction Monitoring

Add real-time transaction scoring

API Reference

Explore FraudShield endpoints

Getting Started

Core Concepts

Guides

SDKs

Resources

Fraud Detection

Overview

Key Features

Device Intelligence

Duplicate Detection

Velocity Controls

Custom Rules

Device Fingerprinting

Device Response

Duplicate Detection

Response

Velocity Controls

Create Velocity Rules

Custom Fraud Rules

Rule Conditions

Rule Actions

Blocklist Management

Blocklist Types

Fraud Signals

Integration with Identity

Analytics

Best Practices

Next Steps

Transaction Monitoring

API Reference

​Overview

​Key Features

Device Intelligence

Duplicate Detection

Velocity Controls

Custom Rules

​Device Fingerprinting

​Device Response

​Duplicate Detection

​Response

​Velocity Controls

​Create Velocity Rules

​Custom Fraud Rules

​Rule Conditions

​Rule Actions

​Blocklist Management

​Blocklist Types

​Fraud Signals

​Integration with Identity

​Analytics

​Best Practices

​Next Steps

Transaction Monitoring

API Reference

Overview

Key Features

Device Fingerprinting

Device Response

Duplicate Detection

Response

Velocity Controls

Create Velocity Rules

Custom Fraud Rules

Rule Conditions

Rule Actions

Blocklist Management

Blocklist Types

Fraud Signals

Integration with Identity

Analytics

Best Practices

Next Steps