Risk Management

Advanced fraud prevention and risk scoring for your payment processing.

Overview

AuxVault's Risk Management system provides comprehensive fraud prevention through:

• 🎯 Risk Scoring - Real-time transaction risk assessment
• 🚨 Fraud Detection - Pattern recognition and anomaly detection
• 🛡️ Rule Engine - Custom fraud prevention rules
• 📊 Velocity Checks - Limit transactions by frequency/amount
• 🔍 Device Fingerprinting - Track suspicious devices
• 🌍 Geolocation - Block high-risk countries/regions

Risk Scoring

Every transaction receives a risk score (0-100):

Get Risk Settings

Endpoint

GET /api/v1/merchants/:merchantId/risk-settings

curl https://dev.auxcore.net/api/v1/merchants/merchant_123/risk-settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response:

{
  "success": true,
  "data": {
    "enabled": true,
    "riskThresholds": {
      "autoApprove": 30,
      "manualReview": 60,
      "autoDecline": 85
    },
    "velocityRules": {
      "maxTransactionsPerHour": 10,
      "maxAmountPerDay": 5000.00
    },
    "blockedCountries": ["KP", "IR", "SY"],
    "deviceFingerprinting": true
  }
}

Update Risk Settings

Endpoint

PUT /api/v1/merchants/:merchantId/risk-settings

curl -X PUT https://dev.auxcore.net/api/v1/merchants/merchant_123/risk-settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "riskThresholds": {
      "autoApprove": 25,
      "manualReview": 50,
      "autoDecline": 80
    }
  }'

Risk Factors

Transaction Risk Factors

Velocity Rules

Limit transaction frequency and amounts:

Configuration

{
  "velocityRules": {
    "maxTransactionsPerHour": 10,
    "maxTransactionsPerDay": 50,
    "maxAmountPerHour": 1000.00,
    "maxAmountPerDay": 5000.00,
    "maxFailedAttemptsPerHour": 3
  }
}

Example: Daily Limit Exceeded

curl -X POST https://dev.auxcore.net/api/v1/transactions \
  -d '{
    "amount": 6000.00,
    ...
  }'

Response:

{
  "success": false,
  "error": {
    "code": "VELOCITY_LIMIT_EXCEEDED",
    "message": "Daily transaction amount limit exceeded",
    "details": {
      "limit": 5000.00,
      "current": 4500.00,
      "requested": 6000.00
    }
  }
}

Country Blocking

Block transactions from high-risk countries:

Blocked Countries Configuration

{
  "blockedCountries": ["KP", "IR", "SY", "SD", "CU"],
  "allowedCountries": ["US", "CA", "GB"]
}

Use either:

• blockedCountries - Block specific countries (blacklist)
• allowedCountries - Only allow specific countries (whitelist)

Example: Blocked Country

curl -X POST https://dev.auxcore.net/api/v1/transactions \
  -d '{
    "billing": {
      "country": "KP"
    },
    ...
  }'

Response:

{
  "success": false,
  "error": {
    "code": "COUNTRY_BLOCKED",
    "message": "Transactions from this country are not allowed",
    "country": "KP"
  }
}

Device Fingerprinting

Track devices to detect suspicious patterns:

Enable Device Fingerprinting

{
  "deviceFingerprinting": true
}

Transaction with Device Data

curl -X POST https://dev.auxcore.net/api/v1/transactions \
  -d '{
    "amount": 100.00,
    "deviceData": {
      "fingerprint": "abc123def456",
      "ipAddress": "192.168.1.1",
      "userAgent": "Mozilla/5.0..."
    },
    ...
  }'

Risk indicators:

• Multiple cards from same device
• Multiple failed attempts from device
• Device on known fraud list
• Proxy/VPN detected

Transaction Response with Risk Data

When risk management is enabled:

{
  "success": true,
  "data": {
    "transactionId": "txn_abc123",
    "status": "approved",
    "riskAssessment": {
      "score": 25,
      "level": "low",
      "factors": [
        {
          "type": "cvv_match",
          "impact": "positive",
          "weight": -10
        },
        {
          "type": "new_customer",
          "impact": "neutral",
          "weight": 5
        }
      ],
      "action": "approved"
    }
  }
}

High-Risk Transaction

{
  "success": false,
  "data": {
    "transactionId": "txn_risky_456",
    "status": "declined",
    "riskAssessment": {
      "score": 88,
      "level": "critical",
      "factors": [
        {
          "type": "cvv_mismatch",
          "impact": "negative",
          "weight": 30
        },
        {
          "type": "avs_mismatch",
          "impact": "negative",
          "weight": 25
        },
        {
          "type": "velocity_violation",
          "impact": "critical",
          "weight": 40
        }
      ],
      "action": "declined",
      "reason": "Risk score exceeds auto-decline threshold"
    }
  }
}

Custom Fraud Rules

Create custom rules for your business:

Rule Examples

1. Block high-value transactions from new customers:

{
  "rule": "new_customer_high_value",
  "conditions": {
    "customerAge": "< 7 days",
    "amount": "> 500.00"
  },
  "action": "manual_review"
}

2. Auto-decline repeated failures:

{
  "rule": "multiple_failures",
  "conditions": {
    "failedAttemptsInLast10Minutes": "> 3"
  },
  "action": "decline"
}

3. Flag international cards:

{
  "rule": "international_card",
  "conditions": {
    "cardCountry": "!= merchantCountry"
  },
  "action": "flag_for_review"
}

Webhooks

fraud.alert

{
  "type": "fraud.alert",
  "data": {
    "transactionId": "txn_suspicious_123",
    "riskScore": 85,
    "riskLevel": "high",
    "riskFactors": [
      "Multiple declined attempts",
      "AVS mismatch",
      "High-risk IP address"
    ],
    "action": "flagged_for_review",
    "timestamp": "2026-01-28T15:00:00Z"
  }
}

Best Practices

✅ DO:

• Enable risk scoring - Essential fraud prevention
• Set appropriate thresholds - Balance fraud vs conversion
• Use velocity rules - Catch card testing
• Monitor risk alerts - Review flagged transactions
• Adjust rules - Based on your fraud patterns
• Combine with AVS/CVV - Multi-layered protection
• Use device fingerprinting - Track suspicious devices

❌ DON'T:

• Don't auto-decline everything - Hurts legitimate sales
• Don't ignore alerts - Review flagged transactions
• Don't set thresholds too low - False positives hurt conversion
• Don't rely on one factor - Use comprehensive approach
• Don't forget to test - Verify rules work as expected

Fraud Analytics

Track fraud prevention effectiveness:

curl "https://dev.auxcore.net/api/v1/analytics/fraud?startDate=2026-01-01&endDate=2026-01-31" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response:

{
  "success": true,
  "data": {
    "totalTransactions": 10000,
    "fraudAttempts": 150,
    "fraudPrevented": 145,
    "falsePositives": 25,
    "averageRiskScore": 18,
    "topRiskFactors": [
      "cvv_mismatch",
      "avs_mismatch",
      "velocity_violation"
    ],
    "fraudRate": 0.015,
    "preventionRate": 0.967
  }
}

Testing

Test High-Risk Transaction

curl -X POST https://dev.auxcore.net/api/v1/transactions \
  -d '{
    "amount": 10000.00,
    "card": {
      "number": "4111111111111111",
      "cvv": "999"
    },
    "billing": {
      "country": "KP"
    },
    "deviceData": {
      "ipAddress": "127.0.0.1"
    }
  }'
# Should be flagged or declined

Common Scenarios

Scenario 1: Card Testing Attack

Pattern: Multiple small transactions with different cards

Detection:

• Velocity rules trigger
• Multiple failed CVV attempts
• Same device/IP

Action: Auto-decline after 3 attempts, block IP

Scenario 2: Legitimate High-Value Purchase

Pattern: $5,000 purchase from new customer

Detection:

• High amount
• New customer
• But: CVV match, AVS match, legitimate IP

Action: Flag for manual review (not auto-decline)

Scenario 3: International Fraud

Pattern: Card from US, shipping to Nigeria

Detection:

• Country mismatch
• High-risk destination
• AVS doesn't match

Action: Auto-decline or require verification

Next Steps

• Configure AVS filters →
• Configure CVV filters →
• View fraud analytics →

Need help? Contact support@auxvault.com