Signet

Fraud Service Developer Guide

This guide shows you how to implement comprehensive fraud detection and risk management using the Fraud service endpoints.

Quick Start

Want to get up and running fast? Follow this 5-minute setup:

  1. Blacklist a user → Restrict access for suspicious activity
  2. Flag a device → Mark suspicious devices
  3. Flag an IP → Block malicious IP addresses
  4. Report fraud → Submit fraud incidents
  5. Check risk scores → Evaluate user risk levels

Prerequisites

  • Base URL: https://localhost:4301/fraud/v1
  • Content-Type: application/json
  • Authentication: Required for all endpoints (partner API key via Bearer token)

User Blacklist Management

Blacklist a User

Purpose: Restrict user access by adding them to the blacklist for security violations.

Endpoint: POST /blacklist

Request:

curl -X POST https://localhost:4301/fraud/v1/blacklist \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "reason": "Suspicious payment activity"
  }'

Response:

{
  "success": true,
  "data": {
    "message": "User blacklisted successfully. Partner ID: your-partner-id"
  }
}

What you get:

  • Confirmation of successful blacklisting
  • Partner ID association for tracking
  • Immediate access restriction for the user
Check Blacklist Status

Purpose: Check if a user is currently blacklisted and get details about their status.

Endpoint: PATCH /blacklist/:id

Request:

curl -X PATCH "https://localhost:4301/fraud/v1/blacklist/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "isBlacklisted": true,
    "reason": "Suspicious payment activity",
    "blacklistedAt": "2024-01-15T10:30:00Z"
  }
}

What you get:

  • Current blacklist status (true/false)
  • Reason for blacklisting
  • Timestamp of when user was blacklisted
Remove User from Blacklist

Purpose: Remove a user from the blacklist to restore their access.

Endpoint: DELETE /blacklist/:id

Request:

curl -X DELETE "https://localhost:4301/fraud/v1/blacklist/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "message": "User removed from blacklist successfully"
  }
}

What you get:

  • Confirmation of successful removal
  • User access restored immediately
  • Updated blacklist status
Get All Blacklisted Users

Purpose: Retrieve a complete list of all blacklisted users with their details.

Endpoint: GET /blacklist

Request:

curl -X GET https://localhost:4301/fraud/v1/blacklist \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": [
    {
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "reason": "Suspicious payment activity",
      "blacklistedAt": "2024-01-15T10:30:00Z",
      "partnerId": "your-partner-id",
      "userDetails": {
        "name": "John Doe",
        "email": "john@example.com",
        "entityType": "user"
      }
    }
  ]
}

What you get:

  • Complete blacklist with user details
  • Integration with VC service for user information
  • Audit trail with timestamps
  • Partner-specific blacklist data

Device Management

Flag a Device

Purpose: Mark a device as suspicious to prevent fraud across multiple sessions.

Endpoint: POST /flag-device

Request:

curl -X POST https://localhost:4301/fraud/v1/flag-device \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "deviceId": "device-12345",
    "reason": "Multiple failed login attempts"
  }'

Response:

{
  "success": true,
  "data": {
    "deviceId": "device-12345",
    "reason": "Multiple failed login attempts",
    "flaggedAt": "2024-01-15T10:30:00Z"
  }
}

What you get:

  • Device flagged with reason
  • Timestamp of flagging
  • Device ID for future reference
Check Device Status

Purpose: Check if a device is currently flagged and get details about its status.

Endpoint: GET /device-check?deviceId=DEVICE_ID

Request:

curl -X GET "https://localhost:4301/fraud/v1/device-check?deviceId=device-12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "isFlagged": true,
    "reason": "Multiple failed login attempts",
    "flaggedAt": "2024-01-15T10:30:00Z"
  }
}

What you get:

  • Current device flag status (true/false)
  • Reason for flagging
  • Timestamp of when device was flagged
Unflag a Device

Purpose: Remove the flagged status from a device to restore normal access.

Endpoint: POST /unflag-device

Request:

curl -X POST https://localhost:4301/fraud/v1/unflag-device \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "deviceId": "device-12345"
  }'

Response:

{
  "success": true,
  "data": {
    "message": "Device unflagged successfully"
  }
}

What you get:

  • Confirmation of successful unflagging
  • Device access restored
  • Updated flag status

Use cases:

  • Prevent device reuse for fraud
  • Track suspicious device patterns
  • Enhance security monitoring
  • Block compromised devices

IP Address Management

Flag an IP Address

Purpose: Mark an IP address as suspicious to prevent fraud from specific locations.

Endpoint: POST /ip-flag

Request:

curl -X POST https://localhost:4301/fraud/v1/ip-flag \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "ip": "192.168.1.100",
    "reason": "Suspicious login from unknown location"
  }'

Response:

{
  "success": true,
  "data": {
    "message": "IP address flagged successfully",
    "ip": "192.168.1.100",
    "flaggedAt": "2024-01-15T10:30:00Z"
  }
}

What you get:

  • IP address flagged with reason
  • Timestamp of flagging
  • Associated user ID for tracking
Check IP Status

Purpose: Check if an IP address is currently flagged and get details about its status.

Endpoint: GET /ip-check?ip=IP_ADDRESS

Request:

curl -X GET "https://localhost:4301/fraud/v1/ip-check?ip=192.168.1.100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "isFlagged": true,
    "reason": "Suspicious login from unknown location",
    "flaggedAt": "2024-01-15T10:30:00Z"
  }
}

What you get:

  • Current IP flag status (true/false)
  • Reason for flagging
  • Timestamp of when IP was flagged
Unflag an IP Address

Purpose: Remove the flagged status from an IP address to restore normal access.

Endpoint: DELETE /ip-flag/:id

Request:

curl -X DELETE "https://localhost:4301/fraud/v1/ip-flag/192.168.1.100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "message": "IP address unflagged successfully"
  }
}

What you get:

  • Confirmation of successful IP unflagging
  • IP access restored
  • Updated flag status

Available flagging options:

  • userId - Associated user ID
  • ip - IP address to flag
  • reason - Reason for flagging

Note: IP flagging helps prevent location-based fraud and enhances security monitoring.

Geolocation Verification

Verify Geolocation

Purpose: Verify user location to detect potential location-based fraud or compliance violations.

Endpoint: GET /geo-verify

Request:

curl -X GET "https://localhost:4301/fraud/v1/geo-verify?ipAddress=192.168.1.100&expectedCountry=United%20States&expectedCity=New%20York" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "verified": true,
    "actualCountry": "United States",
    "actualCity": "New York",
    "confidence": 0.95,
    "message": "Location verification successful"
  }
}

What you get:

  • Location verification result (true/false)
  • Actual country and city detected
  • Confidence score (0-1)
  • Verification success message

Use cases:

  • Location-based fraud detection
  • Compliance verification
  • Geographic access control
  • Risk assessment enhancement

User Reporting & Moderation

Report a User

Purpose: Submit a report about suspicious user activity for moderation review.

Endpoint: POST /report-user

Request:

curl -X POST https://localhost:4301/fraud/v1/report-user \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "description": "User attempting to use stolen credit cards"
  }'

Response:

{
  "success": true,
  "data": {
    "message": "User reported successfully",
    "reportId": "report-uuid-123",
    "reportedAt": "2024-01-15T10:30:00Z"
  }
}

What you get:

  • User report submitted successfully
  • Unique report ID for tracking
  • Timestamp of report submission
Check User Status

Purpose: Check if a user has any reports and get their current flagged status.

Endpoint: POST /check-user

Request:

curl -X POST https://localhost:4301/fraud/v1/check-user \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response:

{
  "success": true,
  "data": {
    "hasReports": true,
    "reportCount": 2,
    "isFlagged": true,
    "lastReported": "2024-01-15T10:30:00Z"
  }
}

What you get:

  • User report status and count
  • Flagged status (true/false)
  • Last reported timestamp
  • Complete report history
Get User Reports

Purpose: Retrieve all reports submitted for a specific user.

Endpoint: POST /get-reports-by-user

Request:

curl -X POST https://localhost:4301/fraud/v1/get-reports-by-user \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response:

{
  "success": true,
  "data": [
    {
      "reportId": "report-uuid-123",
      "description": "User attempting to use stolen credit cards",
      "reportedAt": "2024-01-15T10:30:00Z",
      "status": "active"
    }
  ]
}

What you get:

  • Complete list of user reports
  • Report details and descriptions
  • Report status and timestamps
  • Full audit trail
Remove a Report

Purpose: Remove a specific report from a user's record.

Endpoint: POST /remove-report

Request:

curl -X POST https://localhost:4301/fraud/v1/remove-report \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response:

{
  "success": true,
  "data": {
    "message": "Report removed successfully"
  }
}

What you get:

  • Confirmation of report removal
  • Updated user report count
  • Cleaned report history
Unflag a User

Purpose: Remove the flagged status from a user to restore normal access.

Endpoint: POST /unflag-user

Request:

curl -X POST https://localhost:4301/fraud/v1/unflag-user \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response:

{
  "success": true,
  "data": {
    "message": "User unflagged successfully"
  }
}

What you get:

  • Confirmation of successful user unflagging
  • User access restored
  • Updated flag status

Available reporting options:

  • userId - User to report
  • description - Detailed description of the issue
  • Report management and user flagging

Note: User reporting helps build comprehensive fraud profiles and enables proactive risk management.

Risk Assessment & Fraud Reporting

Check Risk Score

Purpose: Evaluate a user's risk level based on all available fraud indicators.

Endpoint: POST /check-risk-score

Request:

curl -X POST https://localhost:4301/fraud/v1/check-risk-score \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response:

{
  "success": true,
  "data": {
    "riskScore": 85,
    "riskLevel": "high",
    "factors": [
      "User has multiple reports",
      "Device flagged",
      "IP address flagged"
    ],
    "recommendation": "Consider additional verification"
  }
}

What you get:

  • Risk score (0-100)
  • Risk level classification (low/medium/high)
  • Contributing risk factors
  • Recommended actions
Report Fraud

Purpose: Submit a fraud incident report for analysis and tracking.

Endpoint: POST /report-fraud

Request:

curl -X POST https://localhost:4301/fraud/v1/report-fraud \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "reasons": ["suspicious_activity", "location_mismatch"]
  }'

Response:

{
  "success": true,
  "data": {
    "message": "Fraud report submitted successfully",
    "fraudId": "fraud-uuid-456",
    "submittedAt": "2024-01-15T10:30:00Z",
    "priority": "high"
  }
}

What you get:

  • Fraud report submitted successfully
  • Unique fraud ID for tracking
  • Priority level assigned
  • Timestamp of submission

Risk levels:

  • low - Score 0-30, minimal risk
  • medium - Score 31-70, moderate risk
  • high - Score 71-100, high risk

Available fraud reasons:

  • suspicious_activity - General suspicious behavior
  • location_mismatch - Geographic inconsistencies
  • payment_fraud - Payment-related fraud
  • identity_theft - Identity verification issues

Note: Risk scores are calculated based on all available fraud indicators and reports.

Complete Working Example

Here's a complete fraud detection flow you can copy-paste and run:

1. Blacklist a Suspicious User

curl -X POST https://localhost:4301/fraud/v1/blacklist \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "reason": "Multiple failed payment attempts"
  }'

2. Flag the User's Device

curl -X POST https://localhost:4301/fraud/v1/flag-device \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "deviceId": "device-12345",
    "reason": "Associated with blacklisted user"
  }'

3. Flag the User's IP Address

curl -X POST https://localhost:4301/fraud/v1/ip-flag \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "ip": "192.168.1.100",
    "reason": "Associated with blacklisted user"
  }'

4. Submit a Fraud Report

curl -X POST https://localhost:4301/fraud/v1/report-fraud \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "reasons": ["suspicious_activity", "location_mismatch"]
  }'

5. Check Overall Risk Score

curl -X POST https://localhost:4301/fraud/v1/check-risk-score \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Common Errors & Solutions

401 Unauthorized

Problem: Invalid or missing Bearer token

Solution: Ensure your API key is valid and included in Authorization header

400 Bad Request

Problem: Invalid request format, missing fields, or user already blacklisted

Solution: Check JSON syntax, ensure all required fields are present, verify user status

403 Forbidden

Problem: Missing partnerId from authentication context

Solution: Ensure proper authentication and partner ID is available

404 Not Found

Problem: User not found in VC enrollments

Solution: Verify the user ID exists and is enrolled with your partner

409 Conflict

Problem: User already blacklisted or device already flagged

Solution: Check current status before attempting to flag/blacklist

500 Internal Server Error

Problem: Database connection or system error

Solution: Check service logs and ensure the system is accessible

That's it! You now have a comprehensive fraud detection and risk management system. The service handles all the complexity of user management, device tracking, IP monitoring, and risk assessment - you just make HTTPs requests and get powerful fraud protection!

← Back to Tutorials

Was this page helpful?