Fraud Detection

The Fraud Detection module uses Machine Learning models (GBDT - Gradient Boosting Decision Trees) to analyze transactions in real-time and detect fraudulent patterns with 96% accuracy.

Features

Real-time Scoring

Analysis in less than 500ms

40+ Features Analyzed

Comprehensive behavioral analysis

Probabilistic Calibration

Scores from 0 to 1

Configurable Thresholds

By category

Choosing the Right Endpoint

DGuard provides two fraud detection endpoints optimized for different use cases. Choose the appropriate endpoint based on your integration requirements.

Real-time Endpoint

POST /fraud/score/realtime

+Single transaction analysis
+Response time: 30-100ms (p95)
+Rate limit: 1,000 requests/second
+Includes velocity checks

Best for:

Payment authorization, checkout flows, real-time blocking decisions

Batch Endpoint

POST /fraud/score

+Multiple transactions (up to 1,000)
+Response time: 200ms-2s (varies by batch size)
+Rate limit: 100 requests/minute
+Supports pagination and filtering

Best for:

Historical analysis, daily audits, bulk screening, compliance reports

Batch Analysis

POST/fraud/score

Analyze multiple transactions in a single request. Ideal for historical analysis, daily audits, and bulk screening operations.

Endpoint Specifications

Rate Limit

100 requests/minute

Max Batch Size

1,000 transactions

Response Time (p95)

200ms - 2s

Timeout

30 seconds

Request Example

json

{
  "filters": {
    "user_id": "usr_123456",
    "account_ids": ["acc_789012"],
    "transaction_ids": ["txn_abc123", "txn_def456"],
    "date_from": "2025-01-01T00:00:00Z",
    "date_to": "2025-01-31T23:59:59Z",
    "operation_types": ["transfer", "payment", "withdrawal"]
  },
  "options": {
    "alert_threshold": 0.005,
    "threshold_policy": "per_category",
    "include_reasons": true,
    "limit": 1000
  },
  "pagination": {
    "cursor": null,
    "page_size": 100
  }
}

Response Example (200 OK)

json

{
  "summary": {
    "total": 1500,
    "returned": 100,
    "alerts": 8,
    "alert_rate": 0.0053,
    "processing_time_ms": 342,
    "model_version": "v2.4.1"
  },
  "transactions": [
    {
      "transaction_id": "txn_abc123",
      "fraud_score": 0.87,
      "fraud_level": "critical",
      "is_alert": true,
      "threshold_applied": 0.156,
      "risk_factors": [
        "High amount >= 99.5 percentile (€5,234.00)",
        "New merchant + high amount",
        "Unusual transaction velocity (8 in last hour)"
      ]
    }
  ],
  "pagination": {
    "next_cursor": "eyJ0eG5faWQiOiJ0eG5fYWJjMTIzIiwidHMiOjE3MDY3MjAwMDB9",
    "has_more": true,
    "total_pages": 15
  }
}

Pagination

When your query matches more transactions than the page_size (max 1,000), the response includes a next_cursor. Pass this cursor in subsequent requests to retrieve the next page. Continue until has_more is false.

HTTP Status Codes

200

Request successful. Results returned in response body.

400

Bad Request

Invalid request parameters. Check filters and options format.

401

Unauthorized

Invalid or expired Bearer token.

403

Forbidden

Valid credentials but insufficient permissions for this endpoint.

404

Not Found

Specified user_id or account_ids do not exist.

422

Unprocessable Entity

Valid JSON but semantic errors (e.g., date_from > date_to).

429

Too Many Requests

Rate limit exceeded. Check Retry-After header.

500

Internal Server Error

Server error. Retry with exponential backoff.

503

Service Unavailable

Service temporarily unavailable. Check status page.

Error Response Examples

400Invalid Filter Parameters

json

{
  "error": {
    "code": "INVALID_FILTER_PARAMS",
    "message": "Invalid operation_types value",
    "details": {
      "field": "filters.operation_types",
      "value": ["invalid_type"],
      "allowed_values": ["transfer", "payment", "withdrawal", "deposit", "refund"]
    },
    "request_id": "req_abc123xyz"
  }
}

422Semantic Validation Error

json

{
  "error": {
    "code": "INVALID_DATE_RANGE",
    "message": "date_from must be before date_to",
    "details": {
      "date_from": "2025-01-31T00:00:00Z",
      "date_to": "2025-01-01T00:00:00Z"
    },
    "request_id": "req_def456xyz"
  }
}

429Rate Limit Exceeded

json

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after the specified time.",
    "details": {
      "limit": 100,
      "window": "1 minute",
      "retry_after_seconds": 42
    },
    "request_id": "req_ghi789xyz"
  }
}

The Retry-After header will also be present with the number of seconds to wait.

500Internal Server Error

json

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again.",
    "request_id": "req_jkl012xyz"
  }
}

Always include the request_id when contacting support about errors.

Fraud Levels

Note: Score ranges use inclusive lower bounds and exclusive upper bounds (e.g., "0.30 - 0.59" means score >= 0.30 and < 0.60). The boundary value always belongs to the higher level.

low0.00 - 0.29(score < 0.30)

Approve automatically

medium0.30 - 0.59(0.30 ≤ score < 0.60)

Monitor

high0.60 - 0.84(0.60 ≤ score < 0.85)

Requires manual review

critical0.85 - 1.00(score ≥ 0.85)

Block and notify

Classification Examples

0.29→low(below 0.30)

0.30→medium(boundary belongs to medium)

0.60→high(boundary belongs to high)

0.85→critical(boundary belongs to critical)

0.87→critical(above 0.85)

Real-time Transaction Analysis

POST/fraud/score/realtime

Optimized endpoint for real-time analysis of a single transaction. Use this endpoint when you need immediate fraud decisions during payment authorization or checkout flows.

Endpoint Specifications

Rate Limit

1,000 requests/second

Transactions per Request

1 (single)

Response Time (p95)

30 - 100ms

Timeout

5 seconds

Request Example

json

{
  "transaction": {
    "transaction_id": "txn_new_001",
    "user_id": "usr_123456",
    "account_id": "acc_789012",
    "amount": 150.00,
    "currency": "EUR",
    "operation_type": "payment",
    "merchant": {
      "id": "merch_abc",
      "name": "Online Store",
      "category": "retail"
    },
    "device": {
      "ip": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "fingerprint": "fp_xyz123"
    },
    "timestamp": "2025-01-15T14:30:00Z"
  },
  "options": {
    "include_reasons": true,
    "include_velocity": true
  }
}

Response Example (200 OK)

json

{
  "transaction_id": "txn_new_001",
  "fraud_score": 0.23,
  "fraud_level": "low",
  "is_alert": false,
  "recommendation": "approve",
  "confidence": 0.94,
  "processing_time_ms": 45,
  "risk_factors": [],
  "velocity_check": {
    "transactions_1h": 2,
    "transactions_24h": 5,
    "amount_24h": 3200.00,
    "is_unusual": false
  },
  "model_version": "v2.4.1",
  "request_id": "req_rt_abc123"
}

Recommendation Values

The recommendation field provides an actionable decision based on the fraud score and your configured thresholds:

approve

Transaction appears legitimate. Proceed with authorization.

review

Moderate risk detected. Queue for manual review before processing.

challenge

High risk. Require additional verification (e.g., 3DS, OTP).

deny

Critical risk. Block the transaction immediately.