Fraud Detection

The Fraud Detection module uses Machine Learning models to analyze transactions in real-time and detect fraudulent patterns.

Features

Real-time Scoring

Analysis in less than 500ms

Probabilistic Calibration

Scores from 0 to 1

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
+Includes velocity checks

Batch Endpoint

POST /fraud/score

+Multiple transactions (up to 1,000)
+Supports pagination and filtering

When to Use Each Endpoint

Use Case	Endpoint	Why
Payment authorization	Real-time	Sub-500ms latency, includes velocity checks
Checkout flow	Real-time	Immediate decision required for UX
Daily audit / reporting	Batch	Efficient for analyzing thousands of transactions
Historical review	Batch	Supports date range filtering
Backfill / migration	Batch	Paginated results, handles large datasets

Batch Analysis

POST/fraud/score

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

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
  }
}

Cursor-Based 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.

ExpirationCursors are valid for 1 hour after generation

ReusabilityCursors are not reusable after reaching the end

ConcurrencySafe to paginate concurrently from the same initial cursor

On ExpiryReturns 400 error — restart pagination from first page

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": "Rate limit exceeded. Please retry after the specified time.",
    "details": {
      "limit_type": "minute",
      "limit": 1000,
      "current_usage": 1000,
      "retry_after_seconds": 42,
      "daily_remaining": 95234
    },
    "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

Score Classification: Ranges are defined as [lower, upper) — inclusive of the lower bound, exclusive of the upper. For example, a score of exactly 0.60 is classified as high, not medium.

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 - 0.29→low(below 0.30)

0.30 - 0.59→medium(boundary belongs to medium)

0.60 - 0.84→high(boundary belongs to high)

0.85+→critical(boundary belongs to critical)

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.

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.

Model Versioning

Every fraud score response includes a model_version field (e.g., v2.4.1). Understanding our versioning policy helps you plan for model updates.

Version Format (Semver)

v2.4.1Major.Minor.Patch

Patch (2.4.x): Bug fixes, no score impact
Minor (2.x.0): New features, minimal score drift
Major (x.0.0): Significant changes, scores may shift

Update Policy

Major updates announced 30 days in advance via email
Historical scores are not recalculated after updates
Subscribe to model.updated webhook event

Score Consistency

The same transaction analyzed with different model versions may produce different scores. For audit purposes, always store the model_version alongside the score.

Rate Limiting

Rate limits for the Fraud Detection module are enforced per application. All endpoints share the same quota based on your plan. For detailed specifications, see the Security & Compliance page.

Sandbox: 60 req/min

Production: 1,000 req/min