{"openapi":"3.0.3","info":{"title":"Fraud Detection API","version":"1.0.0","description":"Real-time financial transaction fraud scoring API.\n\nSubmit a transaction and receive a fraud probability score (0–1), risk level classification (LOW / MEDIUM / HIGH / CRITICAL), and the specific signals that triggered the score.\n\nThe scoring engine evaluates 8 weighted signals per transaction:\n- Amount anomaly vs user's historical average (25%)\n- New device detection (15%)\n- Location anomaly (15%)\n- High transaction frequency in last 10 minutes (15%)\n- New IP address (10%)\n- Night-time activity 1–5 AM UTC (10%)\n- Absolute high-amount thresholds (5%)\n- Transaction type risk (wire_transfer > p2p > online > atm > in_store) (5%)\n\nUser behaviour profiles are learned automatically from transaction history stored in MongoDB.\nCRITICAL risk transactions are automatically blocked and the user is flagged.\nHIGH and CRITICAL transactions trigger webhook alerts if WEBHOOK_URL is configured.","contact":{"name":"Aethernalytics Support","email":"aethernalytics@gmail.com","url":"https://rapidapi.com/Aethernalytics/api/fraud-detection-transaction-risk-scoring-api"}},"servers":[{"url":"https://fraud-detection-api.up.railway.app/api/v1","description":"Production"},{"url":"http://localhost:3000/api/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key obtained from RapidAPI or via the seed script for local dev. Pass as: Authorization: Bearer <key>"}},"schemas":{"TransactionRequest":{"type":"object","required":["user_id","amount","currency","location","device","ip_address","timestamp","merchant","transaction_type"],"properties":{"user_id":{"type":"string","description":"Your internal user identifier","example":"user_001"},"amount":{"type":"number","description":"Transaction amount (must be > 0)","example":5000},"currency":{"type":"string","description":"ISO 4217 currency code","example":"USD"},"location":{"type":"string","description":"City or region of the transaction","example":"Lagos"},"device":{"type":"string","description":"Device identifier or name","example":"iPhone 15"},"ip_address":{"type":"string","description":"IPv4 or IPv6 address of the request","example":"41.58.100.200"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 transaction timestamp","example":"2026-01-20T03:00:00Z"},"merchant":{"type":"string","description":"Merchant name","example":"Amazon"},"transaction_type":{"type":"string","enum":["online","in_store","atm","wire_transfer","p2p"],"description":"Type of transaction. wire_transfer and p2p carry higher baseline risk.","example":"wire_transfer"}}},"FraudAnalysisResponse":{"type":"object","properties":{"transaction_id":{"type":"string","description":"MongoDB ObjectId of the stored transaction","example":"64f1a2b3c4d5e6f7a8b9c0d1"},"fraud_probability":{"type":"number","minimum":0,"maximum":1,"description":"Fraud probability score between 0 (safe) and 1 (certain fraud)","example":0.82},"risk_level":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"],"description":"LOW <0.35 | MEDIUM 0.35–0.59 | HIGH 0.60–0.79 | CRITICAL ≥0.80","example":"CRITICAL"},"reasons":{"type":"array","items":{"type":"string"},"description":"Human-readable list of signals that elevated the score","example":["Unusual transaction amount","New device detected","Location anomaly"]},"blocked":{"type":"boolean","description":"True when risk_level is CRITICAL. The transaction is denied and the user is flagged.","example":true},"analyzed_at":{"type":"string","format":"date-time","description":"Timestamp of the analysis","example":"2026-01-20T03:00:01.123Z"},"score_breakdown":{"type":"object","description":"Per-signal scores (Pro plan only). Each value is 0–1.","properties":{"amount_anomaly":{"type":"number","example":1},"new_device":{"type":"number","example":0.9},"new_ip":{"type":"number","example":0.7},"location_anomaly":{"type":"number","example":0.8},"high_frequency":{"type":"number","example":0},"night_activity":{"type":"number","example":0.8},"high_amount":{"type":"number","example":0.3},"transaction_type_risk":{"type":"number","example":0.7}}},"_upgrade_note":{"type":"string","description":"Present on Basic plan when Pro-only fields are omitted"}}},"UserRiskProfile":{"type":"object","properties":{"user_id":{"type":"string","example":"user_001"},"avg_transaction_amount":{"type":"number","example":150.75},"max_transaction_amount":{"type":"number","example":5000},"total_transactions":{"type":"number","example":47},"known_devices_count":{"type":"number","example":2},"known_locations_count":{"type":"number","example":3},"is_blocked":{"type":"boolean","example":false},"high_risk_transactions_30d":{"type":"number","example":1},"known_devices":{"type":"array","items":{"type":"string"},"description":"Pro plan only","example":["iPhone 15","MacBook Pro"]},"known_locations":{"type":"array","items":{"type":"string"},"description":"Pro plan only","example":["New York","Boston"]},"profile_created":{"type":"string","format":"date-time"},"last_updated":{"type":"string","format":"date-time"}}},"Transaction":{"type":"object","properties":{"_id":{"type":"string","example":"64f1a2b3c4d5e6f7a8b9c0d1"},"user_id":{"type":"string","example":"user_001"},"amount":{"type":"number","example":120},"currency":{"type":"string","example":"USD"},"location":{"type":"string","example":"New York"},"device":{"type":"string","example":"iPhone 15"},"merchant":{"type":"string","example":"Amazon"},"transaction_type":{"type":"string","example":"online"},"fraud_probability":{"type":"number","example":0.05},"risk_level":{"type":"string","example":"LOW"},"reasons":{"type":"array","items":{"type":"string"}},"blocked":{"type":"boolean","example":false},"timestamp":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","example":"Missing required fields"},"details":{"type":"string","description":"Additional context (development only)"}}}}},"paths":{"/health":{"get":{"summary":"Health check","description":"Returns service health and MongoDB connection status. No authentication required.","operationId":"getHealth","security":[],"tags":["System"],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"healthy"},"uptime":{"type":"number","example":3600.5},"database":{"type":"string","example":"connected"},"timestamp":{"type":"string","format":"date-time"}}}}}},"503":{"description":"Service degraded — database not connected"}}}},"/analyze-transaction":{"post":{"summary":"Analyze a transaction for fraud","description":"Core endpoint. Scores a transaction across 8 signals and returns a fraud probability.\n\n**How the score is computed:**\nEach signal returns a value 0–1. Signals are multiplied by their weights and summed:\n`fraud_probability = Σ(signal_score × weight)`\n\n**Automatic actions:**\n- risk_level CRITICAL → transaction is blocked, user is flagged in DB, webhook fired\n- risk_level HIGH → webhook alert fired (if WEBHOOK_URL is set)\n\n**User profile learning:**\nAfter each transaction, the user's profile is updated (known devices, IPs, locations, avg amount). Subsequent transactions for the same user_id will be scored against this learned baseline.","operationId":"analyzeTransaction","tags":["Fraud Detection"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionRequest"},"examples":{"suspicious":{"summary":"Suspicious transaction (expect HIGH/CRITICAL)","value":{"user_id":"user_001","amount":5000,"currency":"USD","location":"Lagos","device":"Unknown Device","ip_address":"41.58.100.200","timestamp":"2026-01-20T03:00:00Z","merchant":"Crypto Exchange","transaction_type":"wire_transfer"}},"normal":{"summary":"Normal transaction (expect LOW)","value":{"user_id":"user_001","amount":120,"currency":"USD","location":"New York","device":"iPhone 15","ip_address":"192.168.1.10","timestamp":"2026-01-20T14:30:00Z","merchant":"Amazon","transaction_type":"online"}}}}}},"responses":{"200":{"description":"Transaction analyzed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FraudAnalysisResponse"}}}},"400":{"description":"Validation error — missing or invalid fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"User account is blocked due to prior CRITICAL transaction"},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal server error"}}}},"/transactions/{user_id}":{"get":{"summary":"Get transaction history","description":"Returns paginated transaction history for a user, sorted by timestamp descending. Basic plan: max 10 per page. Pro plan: max 100 per page.","operationId":"getTransactionHistory","tags":["Transactions"],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string"},"example":"user_001"},{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":10},"description":"Results per page (max 10 Basic / 100 Pro)"}],"responses":{"200":{"description":"Transaction list","content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string"},"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}}}}}}},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limit exceeded"}}}},"/users/{user_id}/risk-profile":{"get":{"summary":"Get user risk profile","description":"Returns the learned behavioral profile for a user — average spend, max spend, known device count, known location count, and 30-day high-risk transaction count. Pro plan also returns the actual lists of known devices and locations.","operationId":"getUserRiskProfile","tags":["Users"],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string"},"example":"user_001"}],"responses":{"200":{"description":"User risk profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserRiskProfile"}}}},"401":{"description":"Missing or invalid API key"},"404":{"description":"User not found — no transactions have been analyzed for this user_id yet"},"429":{"description":"Rate limit exceeded"}}}},"/dashboard/stats":{"get":{"summary":"Dashboard statistics","description":"Aggregated fraud metrics. All plans get 24h and 7-day stats. Pro plan also gets a day-by-day 30-day risk trend.","operationId":"getDashboardStats","tags":["Analytics"],"responses":{"200":{"description":"Dashboard metrics","content":{"application/json":{"schema":{"type":"object","properties":{"overview":{"type":"object","properties":{"total_transactions":{"type":"number","example":1500},"transactions_24h":{"type":"number","example":42},"high_risk_24h":{"type":"number","example":3},"blocked_users":{"type":"number","example":2}}},"risk_distribution_7d":{"type":"object","properties":{"LOW":{"type":"number","example":980},"MEDIUM":{"type":"number","example":200},"HIGH":{"type":"number","example":80},"CRITICAL":{"type":"number","example":12}}},"risk_trend_30d":{"type":"array","description":"Pro plan only. Day-by-day breakdown.","items":{"type":"object"}},"generated_at":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limit exceeded"}}}},"/batch/analyze":{"post":{"summary":"Batch transaction analysis","description":"Analyze multiple transactions in one request. Basic plan: max 5. Pro plan: max 50. Results are processed in parallel and returned in the same order as submitted.","operationId":"batchAnalyze","tags":["Fraud Detection"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["transactions"],"properties":{"transactions":{"type":"array","items":{"$ref":"#/components/schemas/TransactionRequest"},"maxItems":50}}}}}},"responses":{"200":{"description":"Batch results with summary","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","properties":{"total":{"type":"number"},"low":{"type":"number"},"medium":{"type":"number"},"high":{"type":"number"},"critical":{"type":"number"},"blocked":{"type":"number"},"errors":{"type":"number"}}},"results":{"type":"array","items":{"$ref":"#/components/schemas/FraudAnalysisResponse"}}}}}}},"400":{"description":"Validation error or batch limit exceeded"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limit exceeded"}}}},"/network/device/{fingerprint}":{"get":{"summary":"Device network lookup (Pro)","description":"Returns how many distinct user accounts have used this device fingerprint and the associated risk distribution. Raw user IDs are never exposed.","operationId":"getNetworkByDevice","tags":["Network Detection"],"parameters":[{"name":"fingerprint","in":"path","required":true,"schema":{"type":"string"},"example":"Unknown Device"}],"responses":{"200":{"description":"Network stats for this device"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Pro plan required"}}}},"/network/ip/{address}":{"get":{"summary":"IP network lookup (Pro)","description":"Returns how many distinct user accounts have transacted from this IP address. Raw user IDs are never exposed.","operationId":"getNetworkByIP","tags":["Network Detection"],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"example":"41.58.100.200"}],"responses":{"200":{"description":"Network stats for this IP"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Pro plan required"}}}},"/network/user/{user_id}":{"get":{"summary":"Full network graph for a user (Pro)","description":"Returns all devices, IPs, and locations this user has used, and how many other users share each value. Identifies if a user is part of a fraud network.","operationId":"getUserNetworkGraph","tags":["Network Detection"],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string"},"example":"user_001"}],"responses":{"200":{"description":"Network graph with shared connections"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Pro plan required"},"404":{"description":"No transactions found for this user"}}}},"/webhooks":{"post":{"summary":"Register a webhook (Pro)","description":"Register a URL to receive real-time fraud alerts. Your server will receive a POST request with fraud details and an X-Fraud-Signature HMAC-SHA256 header for verification.","operationId":"registerWebhook","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","example":"https://your-server.com/fraud-alerts"},"events":{"type":"array","items":{"type":"string","enum":["MEDIUM","HIGH","CRITICAL"]},"example":["HIGH","CRITICAL"]}}}}}},"responses":{"201":{"description":"Webhook registered. Response includes the signing secret — store it securely."},"400":{"description":"Invalid URL or event types"},"403":{"description":"Pro plan required"}}},"get":{"summary":"List webhooks (Pro)","operationId":"listWebhooks","tags":["Webhooks"],"responses":{"200":{"description":"List of registered webhooks (secret not returned)"},"403":{"description":"Pro plan required"}}}},"/webhooks/{id}":{"delete":{"summary":"Delete a webhook (Pro)","operationId":"deleteWebhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook deleted"},"404":{"description":"Webhook not found"}}}},"/rules":{"post":{"summary":"Create a custom rule (Pro)","description":"Create a rule that runs on every transaction for your subscriber account.\n\n**Condition syntax:**\n- `amount > 10000`\n- `transaction_type == \"wire_transfer\"`\n- `location NOT IN known_locations`\n- `device NOT IN known_devices`\n- `transaction_type IN [\"wire_transfer\", \"p2p\"]`\n- `fraud_probability > 0.5`\n- `amount > 5000 AND location NOT IN known_locations`\n\n**Actions:**\n- `block` — force CRITICAL, transaction blocked\n- `escalate` — add escalate_by (default 0.3) to fraud_probability","operationId":"createRule","tags":["Custom Rules"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","condition","action"],"properties":{"name":{"type":"string","example":"Block large wire transfers"},"condition":{"type":"string","example":"amount > 10000 AND transaction_type == \"wire_transfer\""},"action":{"type":"string","enum":["block","escalate"]},"escalate_by":{"type":"number","minimum":0,"maximum":1,"default":0.3},"priority":{"type":"integer","default":0,"description":"Higher priority rules run first"}}}}}},"responses":{"201":{"description":"Rule created"},"400":{"description":"Invalid condition syntax or missing fields"},"403":{"description":"Pro plan required"}}},"get":{"summary":"List custom rules (Pro)","operationId":"listRules","tags":["Custom Rules"],"responses":{"200":{"description":"List of rules sorted by priority"},"403":{"description":"Pro plan required"}}}},"/rules/test":{"post":{"summary":"Test a rule condition (Pro)","description":"Evaluate a condition string against a sample transaction without saving anything. Use this to validate your rule before creating it.","operationId":"testRule","tags":["Custom Rules"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["condition","transaction"],"properties":{"condition":{"type":"string","example":"amount > 5000 AND location NOT IN known_locations"},"transaction":{"$ref":"#/components/schemas/TransactionRequest"},"user_profile":{"type":"object","description":"Optional user profile for known_devices / known_locations checks"}}}}}},"responses":{"200":{"description":"Returns { matched: boolean, condition, transaction }"},"400":{"description":"Invalid condition syntax"},"403":{"description":"Pro plan required"}}}},"/users/{user_id}/recalibrate":{"post":{"summary":"Recalibrate user profile (Pro)","description":"Rebuild a user's behavioural baseline from scratch using only verified-clean transactions (LOW and optionally MEDIUM risk). Excludes HIGH/CRITICAL transactions which may have been fraud. Also unblocks the user.","operationId":"recalibrateUser","tags":["Users"],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"include_medium","in":"query","schema":{"type":"boolean","default":true},"description":"Include MEDIUM risk transactions in the baseline"}],"responses":{"200":{"description":"Profile recalibrated. Returns before/after comparison."},"400":{"description":"No clean transactions found to recalibrate from"},"403":{"description":"Pro plan required"},"404":{"description":"User not found"}}}},"/users/{user_id}/unblock":{"post":{"summary":"Unblock a user (Pro)","description":"Manually unblock a user that was blocked due to a CRITICAL-risk transaction. After unblocking, transactions will be evaluated normally.","operationId":"unblockUser","tags":["Users"],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string"},"example":"user_001"}],"responses":{"200":{"description":"User unblocked successfully","content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string"},"is_blocked":{"type":"boolean","example":false},"unblocked_at":{"type":"string","format":"date-time"},"message":{"type":"string"}}}}}},"400":{"description":"User is not currently blocked"},"403":{"description":"Pro plan required"},"404":{"description":"User not found"}}}},"/users/{user_id}":{"delete":{"summary":"Delete user data (GDPR / CCPA)","description":"Permanently deletes the user profile and all associated transaction records. Use for right-to-erasure requests. Scoped to your subscriber account — cannot delete another subscriber's users.","operationId":"deleteUser","tags":["Users"],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string"},"example":"user_001"}],"responses":{"200":{"description":"All user data permanently deleted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"deleted":{"type":"object","properties":{"user_profile":{"type":"number"},"transactions":{"type":"number"}}}}}}}},"401":{"description":"Missing or invalid API key"},"404":{"description":"No data found for this user_id"}}}},"/network/location/{location}":{"get":{"summary":"Location network lookup (Pro)","description":"Returns how many distinct user accounts have transacted from this location string, plus risk distribution. Use to detect clusters of fraud from a specific region.","operationId":"getNetworkByLocation","tags":["Network Detection"],"parameters":[{"name":"location","in":"path","required":true,"schema":{"type":"string"},"example":"Lagos"}],"responses":{"200":{"description":"Network stats for this location"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Pro plan required"}}}},"/webhooks/{id}/toggle":{"patch":{"summary":"Toggle webhook active state (Pro)","description":"Enable or disable a registered webhook without deleting it. Toggling off stops deliveries; toggling on resumes them.","operationId":"toggleWebhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook ObjectId"}],"responses":{"200":{"description":"Webhook toggled","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"is_active":{"type":"boolean"}}}}}},"403":{"description":"Pro plan required"},"404":{"description":"Webhook not found"}}}},"/rules/{id}":{"patch":{"summary":"Update a custom rule (Pro)","description":"Update any field of an existing rule. Accepts: name, condition, action, escalate_by, priority, is_active. Condition is re-validated on update.","operationId":"updateRule","tags":["Custom Rules"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Rule ObjectId"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"condition":{"type":"string"},"action":{"type":"string","enum":["block","escalate"]},"escalate_by":{"type":"number","minimum":0,"maximum":1},"priority":{"type":"integer"},"is_active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Rule updated"},"400":{"description":"Invalid condition or action"},"403":{"description":"Pro plan required"},"404":{"description":"Rule not found"}}},"delete":{"summary":"Delete a custom rule (Pro)","operationId":"deleteRule","tags":["Custom Rules"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Rule deleted"},"403":{"description":"Pro plan required"},"404":{"description":"Rule not found"}}}},"/transactions/{id}/outcome":{"post":{"summary":"Report chargeback outcome (Pro)","description":"Report the real-world outcome of a previously scored transaction. If a chargeback occurred on a LOW or MEDIUM risk transaction (false negative), the API recalibrates your scoring model to be more aggressive going forward. Can only be reported once per transaction.","operationId":"reportOutcome","tags":["Calibration"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Transaction ObjectId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chargeback"],"properties":{"chargeback":{"type":"boolean","description":"true if a chargeback occurred, false if the transaction was legitimate","example":true}}}}}},"responses":{"200":{"description":"Outcome recorded and calibration updated"},"400":{"description":"chargeback must be a boolean"},"403":{"description":"Pro plan required"},"404":{"description":"Transaction not found"},"409":{"description":"Outcome already reported for this transaction"}}}},"/outcomes/stats":{"get":{"summary":"Get calibration statistics (Pro)","description":"Returns your subscriber-level calibration summary — total outcomes reported, chargeback rate, false negative rate, and the current score_boost multiplier applied to your transactions.","operationId":"getCalibrationStats","tags":["Calibration"],"responses":{"200":{"description":"Calibration stats","content":{"application/json":{"schema":{"type":"object","properties":{"total_outcomes":{"type":"number"},"total_chargebacks":{"type":"number"},"chargeback_rate":{"type":"number"},"false_negative_rate":{"type":"number"},"score_boost":{"type":"number","description":"Multiplier applied to all fraud scores (1.0 = no boost)"}}}}}},"403":{"description":"Pro plan required"}}}},"/reputation/device/{fingerprint}":{"get":{"summary":"Device reputation (Pro)","description":"Platform-wide fraud statistics for a device fingerprint across all subscribers. Returns total transactions, unique user count, high-risk transaction count, fraud rate, and a reputation risk level.","operationId":"getDeviceReputation","tags":["Reputation"],"parameters":[{"name":"fingerprint","in":"path","required":true,"schema":{"type":"string"},"example":"iPhone-15-ABC123"}],"responses":{"200":{"description":"Device reputation data"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Pro plan required"}}}},"/reputation/ip/{address}":{"get":{"summary":"IP reputation (Pro)","description":"Platform-wide fraud statistics for an IP address combined with geolocation data (country, region, city, timezone, coordinates). Includes risk signals like high_platform_fraud_rate.","operationId":"getIpReputation","tags":["Reputation"],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"example":"41.58.100.200"}],"responses":{"200":{"description":"IP reputation and geo data"},"400":{"description":"Invalid IP address format"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Pro plan required"}}}},"/velocity":{"get":{"summary":"Get velocity config (Pro)","description":"Returns the active velocity rule for your subscriber account — max transactions per hour and/or max daily spend per user.","operationId":"getVelocityConfig","tags":["Velocity"],"responses":{"200":{"description":"Active velocity configuration"},"403":{"description":"Pro plan required"},"404":{"description":"No velocity config set"}}},"put":{"summary":"Set velocity config (Pro)","description":"Create or replace the velocity rule for your account. When a user exceeds the configured threshold, their transaction is immediately forced to CRITICAL risk.","operationId":"upsertVelocityConfig","tags":["Velocity"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"max_transactions_per_hour":{"type":"integer","description":"Max transactions a user can make per hour","example":10},"max_daily_spend":{"type":"number","description":"Max total spend per user per calendar day (UTC)","example":5000},"is_active":{"type":"boolean","default":true}}},"examples":{"hourly_limit":{"summary":"Limit to 10 transactions/hour","value":{"max_transactions_per_hour":10}},"spend_limit":{"summary":"Limit daily spend to $5000","value":{"max_daily_spend":5000}},"both":{"summary":"Both limits","value":{"max_transactions_per_hour":10,"max_daily_spend":5000}}}}}},"responses":{"200":{"description":"Velocity config saved"},"400":{"description":"At least one of max_transactions_per_hour or max_daily_spend is required"},"403":{"description":"Pro plan required"}}},"delete":{"summary":"Delete velocity config (Pro)","description":"Remove the velocity rule for your account. Transactions will no longer be checked against velocity limits.","operationId":"deleteVelocityConfig","tags":["Velocity"],"responses":{"200":{"description":"Velocity config deleted"},"403":{"description":"Pro plan required"},"404":{"description":"No velocity config to delete"}}}},"/export/transactions/{user_id}":{"get":{"summary":"Export transactions as CSV (Pro)","description":"Download all transactions for a user as a CSV file. Supports date filtering and row limits. The CSV includes transaction details, fraud scores, risk levels, and chargeback outcomes.","operationId":"exportTransactions","tags":["Export"],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string"},"example":"user_001"},{"name":"start","in":"query","schema":{"type":"string","format":"date"},"description":"Include transactions on or after this date (YYYY-MM-DD UTC)","example":"2026-01-01"},{"name":"end","in":"query","schema":{"type":"string","format":"date"},"description":"Include transactions on or before this date (YYYY-MM-DD UTC)","example":"2026-04-30"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":500},"description":"Max rows to return"},{"name":"format","in":"query","schema":{"type":"string","enum":["csv"],"default":"csv"}}],"responses":{"200":{"description":"CSV file download","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Invalid date format or unsupported format"},"403":{"description":"Pro plan required"}}}},"/merchants/{name}/stats":{"get":{"summary":"Merchant risk statistics (Pro)","description":"Aggregated fraud statistics for a merchant name across your subscriber account — transaction volume, risk distribution, fraud rate, and average transaction amount.","operationId":"getMerchantStats","tags":["Analytics"],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"},"example":"Crypto Exchange"}],"responses":{"200":{"description":"Merchant risk stats"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Pro plan required"},"404":{"description":"No transactions found for this merchant"}}}}}}