Fraud Detection API

Monitor and manage fraud detection for your store. Track suspicious transactions, review flagged orders, and configure fraud prevention settings.

Get Fraud Statistics

Get dashboard statistics for fraud detection activity.

GET /api/external/v1/fraud/dashboard

Example Request

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/fraud/dashboard" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "success": true,
  "data": {
    "stats": {
      "today": {
        "blocked": 3,
        "flagged": 7,
        "allowed": 156
      },
      "this_week": {
        "blocked": 12,
        "flagged": 28
      },
      "this_month": {
        "blocked": 45,
        "flagged": 89
      },
      "pending_review": 15,
      "high_risk_today": 5
    }
  }
}

List Fraud Checks

Get a paginated list of fraud checks for your store.

GET /api/external/v1/fraud/checks

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 20, max: 100)
risk_level	string	Filter by risk: low, medium, high, critical
action_taken	string	Filter by action: allowed, flagged, blocked, verification_required
is_reviewed	boolean	Filter by review status
start_date	string	Start date (YYYY-MM-DD)
end_date	string	End date (YYYY-MM-DD)

Example Request

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/fraud/checks?risk_level=high&is_reviewed=false" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "order_id": 123,
      "customer_id": 45,
      "ip_address": "192.168.1.1",
      "risk_score": 75,
      "risk_level": "high",
      "action_taken": "flagged",
      "detected_country": "US",
      "billing_country": "GB",
      "detected_city": "New York",
      "is_vpn": true,
      "is_proxy": false,
      "is_datacenter": false,
      "is_tor": false,
      "is_sanctioned_country": false,
      "has_geo_mismatch": true,
      "has_velocity_violation": false,
      "is_disposable_email": false,
      "is_reviewed": false,
      "reviewed_by": null,
      "reviewed_at": null,
      "review_outcome": null,
      "created_at": "2025-01-20T14:30:00Z",
      "order": {
        "id": 123,
        "order_number": "ORD-2025-001"
      },
      "customer": {
        "id": 45,
        "name": "John Doe"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 98
  }
}

Get Single Fraud Check

Get detailed information about a specific fraud check.

GET /api/external/v1/fraud/checks/{id}

Example Request

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/fraud/checks/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "success": true,
  "data": {
    "check": {
      "id": 1,
      "order_id": 123,
      "customer_id": 45,
      "ip_address": "192.168.1.1",
      "email": "customer@example.com",
      "user_agent": "Mozilla/5.0...",
      "risk_score": 75,
      "risk_level": "high",
      "action_taken": "flagged",
      "signals": {
        "vpn": 30,
        "geo_mismatch": 25,
        "header_anomalies": 20
      },
      "detected_country": "US",
      "billing_country": "GB",
      "detected_city": "New York",
      "asn_name": "Example ISP",
      "asn_number": 12345,
      "is_vpn": true,
      "is_proxy": false,
      "is_datacenter": false,
      "is_tor": false,
      "is_sanctioned_country": false,
      "has_geo_mismatch": true,
      "has_velocity_violation": false,
      "is_disposable_email": false,
      "is_reviewed": false,
      "reviewed_by": null,
      "reviewed_at": null,
      "review_outcome": null,
      "review_notes": null,
      "created_at": "2025-01-20T14:30:00Z",
      "order": {
        "id": 123,
        "order_number": "ORD-2025-001",
        "status": "completed",
        "total": "29.99"
      },
      "customer": {
        "id": 45,
        "name": "John Doe",
        "email": "customer@example.com"
      }
    },
    "detected_signals": ["VPN", "Geo Mismatch"],
    "risk_badge": {
      "label": "High",
      "color": "orange"
    },
    "action_badge": {
      "label": "Flagged",
      "color": "yellow"
    }
  }
}

Review Fraud Check

Mark a fraud check as reviewed with an outcome.

POST /api/external/v1/fraud/checks/{id}/review

Request Body

Parameter	Type	Required	Description
outcome	string	Yes	Review outcome: legitimate, fraud, inconclusive
notes	string	No	Review notes (max 1000 characters)

Example Request

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/fraud/checks/1/review" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "legitimate",
    "notes": "Customer confirmed via support ticket - using VPN for privacy"
  }'

Response

{
  "success": true,
  "message": "Fraud check marked as reviewed",
  "data": {
    "id": 1,
    "is_reviewed": true,
    "reviewed_by": 12,
    "reviewed_at": "2025-01-20T15:45:00Z",
    "review_outcome": "legitimate",
    "review_notes": "Customer confirmed via support ticket - using VPN for privacy"
  }
}

Get Fraud Settings

Get current fraud detection configuration for your store.

GET /api/external/v1/fraud/settings

Example Request

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/fraud/settings" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "success": true,
  "data": {
    "settings": {
      "fraud_detection_enabled": true,
      "fraud_sensitivity_level": "medium",
      "fraud_action": "flag",
      "fraud_block_vpn": true,
      "fraud_block_proxy": true,
      "fraud_block_datacenter": false,
      "fraud_block_tor": true,
      "fraud_block_sanctioned_countries": true,
      "fraud_check_geo_mismatch": true,
      "fraud_check_velocity": true,
      "fraud_check_disposable_email": true,
      "fraud_velocity_limit_orders_per_ip": 5,
      "fraud_velocity_limit_orders_per_email": 3,
      "fraud_velocity_window_minutes": 60,
      "fraud_custom_blocked_countries": ["KP", "IR"],
      "fraud_whitelisted_ips_count": 12,
      "fraud_whitelisted_emails_count": 5
    },
    "sanctioned_countries": ["KP", "IR", "SY", "CU"],
    "high_risk_countries": ["NG", "RU", "UA", "BY"]
  }
}

Update Fraud Settings

Update fraud detection configuration for your store.

PUT /api/external/v1/fraud/settings

Request Body

Parameter	Type	Description
fraud_detection_enabled	boolean	Enable/disable fraud detection
fraud_sensitivity_level	string	Sensitivity: low, medium, high
fraud_action	string	Default action: block, flag, verify
fraud_block_vpn	boolean	Block VPN connections
fraud_block_proxy	boolean	Block proxy connections
fraud_block_datacenter	boolean	Block datacenter IPs
fraud_block_tor	boolean	Block Tor exit nodes
fraud_block_sanctioned_countries	boolean	Block sanctioned countries
fraud_check_geo_mismatch	boolean	Check for geo/billing mismatch
fraud_check_velocity	boolean	Enable velocity checks
fraud_check_disposable_email	boolean	Check for disposable emails
fraud_velocity_limit_orders_per_ip	integer	Max orders per IP (1-100)
fraud_velocity_limit_orders_per_email	integer	Max orders per email (1-50)
fraud_velocity_window_minutes	integer	Velocity window in minutes (15-1440)
fraud_custom_blocked_countries	array	Array of ISO country codes to block
fraud_whitelisted_ips	array	Array of whitelisted IP addresses
fraud_whitelisted_emails	array	Array of whitelisted email addresses

Example Request

curl -X PUT "https://yourstore.pixlpay.net/api/external/v1/fraud/settings" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fraud_detection_enabled": true,
    "fraud_sensitivity_level": "high",
    "fraud_block_vpn": true,
    "fraud_velocity_limit_orders_per_ip": 3,
    "fraud_velocity_window_minutes": 30
  }'

Response

{
  "success": true,
  "message": "Fraud settings updated successfully",
  "data": {
    "fraud_detection_enabled": true,
    "fraud_sensitivity_level": "high",
    "fraud_block_vpn": true,
    "fraud_velocity_limit_orders_per_ip": 3,
    "fraud_velocity_window_minutes": 30
  }
}

Whitelist Management

Add IP to Whitelist

POST /api/external/v1/fraud/whitelist/ip

Request Body

Parameter	Type	Required	Description
ip	string	Yes	Valid IP address to whitelist

Example Request

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/fraud/whitelist/ip" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ip": "192.168.1.100"}'

Response

{
  "success": true,
  "message": "IP added to whitelist",
  "data": {
    "whitelisted_ips": ["192.168.1.100", "10.0.0.50"]
  }
}

Remove IP from Whitelist

DELETE /api/external/v1/fraud/whitelist/ip

Request Body

Parameter	Type	Required	Description
ip	string	Yes	IP address to remove

Example Request

curl -X DELETE "https://yourstore.pixlpay.net/api/external/v1/fraud/whitelist/ip" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ip": "192.168.1.100"}'

Add Email to Whitelist

POST /api/external/v1/fraud/whitelist/email

Request Body

Parameter	Type	Required	Description
email	string	Yes	Valid email address to whitelist

Example Request

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/fraud/whitelist/email" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "trusted@example.com"}'

Remove Email from Whitelist

DELETE /api/external/v1/fraud/whitelist/email

Request Body

Parameter	Type	Required	Description
email	string	Yes	Email address to remove

Blocked Countries Management

Add Country to Block List

POST /api/external/v1/fraud/blocked-countries

Request Body

Parameter	Type	Required	Description
country_code	string	Yes	ISO 3166-1 alpha-2 country code (e.g., "RU")

Example Request

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/fraud/blocked-countries" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"country_code": "RU"}'

Response

{
  "success": true,
  "message": "Country added to blocked list",
  "data": {
    "blocked_countries": ["KP", "IR", "RU"]
  }
}

Remove Country from Block List

DELETE /api/external/v1/fraud/blocked-countries

Request Body

Parameter	Type	Required	Description
country_code	string	Yes	ISO 3166-1 alpha-2 country code

Example Request

curl -X DELETE "https://yourstore.pixlpay.net/api/external/v1/fraud/blocked-countries" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"country_code": "RU"}'

Fraud Check Object

Field	Type	Description
id	integer	Unique identifier
order_id	integer	Associated order ID
customer_id	integer	Associated customer ID
ip_address	string	IP address of the transaction
email	string	Customer email (detailed view only)
user_agent	string	Browser user agent
risk_score	integer	Risk score (0-100)
risk_level	string	low, medium, high, critical
action_taken	string	allowed, flagged, blocked, verification_required
signals	object	Detected fraud signals with scores
detected_country	string	Country code from IP geolocation
billing_country	string	Country code from billing address
detected_city	string	City from IP geolocation
asn_name	string	ISP/ASN name
asn_number	integer	ASN number
is_vpn	boolean	VPN detected
is_proxy	boolean	Proxy detected
is_datacenter	boolean	Datacenter IP detected
is_tor	boolean	Tor exit node detected
is_sanctioned_country	boolean	Sanctioned country detected
has_geo_mismatch	boolean	Geographic mismatch between IP and billing
has_velocity_violation	boolean	Order velocity limit exceeded
is_disposable_email	boolean	Disposable email detected
is_reviewed	boolean	Whether check has been reviewed
reviewed_by	integer	User ID who reviewed
reviewed_at	string	ISO 8601 review timestamp
review_outcome	string	legitimate, fraud, inconclusive
review_notes	string	Review notes
created_at	string	ISO 8601 creation timestamp

Risk Levels

Level	Score Range	Description
low	0-39	Transaction appears safe
medium	40-59	Minor risk signals detected
high	60-79	Significant risk signals detected
critical	80-100	High probability of fraud

Action Types

Action	Description
allowed	Transaction was allowed to proceed
flagged	Transaction flagged for review but allowed
blocked	Transaction was blocked
verification_required	Additional verification required

Sensitivity Levels

Level	Description
low	Only block obvious fraud (score >= 80)
medium	Balanced protection (score >= 60 to block)
high	Aggressive protection (score >= 40 to block)

Errors

Status	Error	Description
401	Unauthorized	Invalid or missing token
403	Forbidden	Token lacks fraud:read or fraud:write scope
404	Not Found	Fraud check doesn't exist
422	Validation Error	Invalid request parameters