Quick Reference
Authentication
All API requests require Bearer token authentication:
# Include in all requests
Authorization: Bearer <your_api_key>
Authorization: Bearer <your_api_key>
Score Transaction
POST
/api/v1/score
Score a single transaction for fraud risk in real-time.
Request Body
{
"transaction_id": "TXN-12345",
"card_id": "card_abc123",
"amount": 250.00,
"currency": "USD",
"merchant_id": "merch_xyz",
"merchant_category": "electronics",
"timestamp": "2024-01-15T10:30:00Z",
"location": {
"latitude": 37.7749,
"longitude": -122.4194,
"country": "US"
},
"device": {
"fingerprint": "fp_abc123",
"ip_address": "192.168.1.1",
"user_agent": "Mozilla/5.0..."
},
"card_present": false
}
Response
{
"transaction_id": "TXN-12345",
"score": 0.87,
"decision": "BLOCK",
"rules_triggered": [
{"rule_id": "R001", "name": "High Amount Alert"},
{"rule_id": "R015", "name": "New Device"}
],
"features": {
"velocity_1h": 5,
"distance_from_home_km": 2450,
"amount_zscore": 3.2
},
"latency_ms": 28,
"model_version": "v2.4.1"
}
Decision Values
APPROVE
Score < 0.45
REVIEW
0.45 ≤ Score < 0.65
BLOCK
Score ≥ 0.65
Batch Score
POST
/api/v1/score/batch
Score multiple transactions in a single request (up to 1000).
Request Body
{
"transactions": [
{ "transaction_id": "TXN-001", ... },
{ "transaction_id": "TXN-002", ... }
],
"options": {
"include_features": true,
"include_explanations": false
}
}
Get Entity Features
GET
/api/v1/features/{entity_type}/{entity_id}
Retrieve computed features for an entity.
Path Parameters
| entity_type | card, device, merchant, user |
| entity_id | The unique identifier |
Response
{
"entity_type": "card",
"entity_id": "card_abc123",
"features": {
"txn_count_1h": 3,
"txn_count_24h": 12,
"amount_sum_1h": 450.00,
"amount_avg_30d": 127.50,
"unique_merchants_7d": 8,
"fraud_rate_historical": 0.0,
"account_age_days": 456
},
"last_updated": "2024-01-15T10:29:45Z"
}
Report Feedback
POST
/api/v1/feedback
Report confirmed fraud or false positive for model improvement.
{
"transaction_id": "TXN-12345",
"label": "fraud", // or "legitimate"
"reported_by": "analyst_123",
"notes": "Confirmed by customer call"
}
List Rules
GET
/api/v1/rules
Retrieve all configured fraud detection rules.
{
"rules": [
{
"rule_id": "R001",
"name": "High Amount Alert",
"condition": "amount > 5000 AND card_present = false",
"action": "REVIEW",
"enabled": true,
"triggers_per_day": 342
}
]
}
Health Check
GET
/api/v1/health
{
"status": "healthy",
"model_version": "v2.4.1",
"uptime_seconds": 864000,
"latency_p50_ms": 28,
"latency_p99_ms": 68
}
Error Codes
| Code | Description |
|---|---|
| 400 | Invalid request body |
| 401 | Authentication failed |
| 403 | Insufficient permissions |
| 404 | Entity not found |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
| 503 | Service temporarily unavailable |
SDKs
Python
pip install fraud-sdk
Node.js
npm i @fraud/sdk
Java
fraud-sdk:2.4.0