Transaction Layer

Fraud-AI

Active

Real-time fraud detection across payment, identity, account takeover, synthetic identity and money mule typologies. Analyses transaction signals, device fingerprints, IP geolocation and velocity patterns to produce a fraud score and recommended action within 200ms.

Endpoint

POST/api/fraud/detect

Fraud typologies

fraud_type	Description
`payment`	Card-not-present fraud, authorised push payment (APP) fraud, merchant fraud.
`identity`	Impersonation, stolen identity use, false document submission.
`account_takeover`	Credential stuffing, SIM swap, session hijacking.
`synthetic_id`	Fabricated identity combining real and false information.
`money_mule`	Account used to receive and forward proceeds of crime.

Request parameters

Parameter	Type	Required	Description
`entity_id`	string	Yes	Your unique identifier for the entity being assessed.
`customer_id`	string	Yes	Customer identifier for velocity pattern analysis across sessions.
`jurisdiction`	string	Yes	One of: CA (Canada), AE (UAE), SA (KSA). Sets fraud thresholds and regulatory context.
`fraud_type`	string	No	One of: payment, identity, account_takeover, synthetic_id, money_mule, other (default: payment).
`transaction_id`	string	No	Transaction reference. Links the fraud check to an AML scan if provided.
`amount`	number	No	Transaction amount. High amounts increase the fraud score.
`currency`	string	No	ISO 4217 currency code.
`ip_address`	string	No	Customer IP address. Used for geolocation and VPN/proxy detection.
`device_id`	string	No	Device fingerprint identifier. Detects device switching between sessions.
`merchant_id`	string	No	Merchant identifier. Used to detect merchant-specific fraud patterns.
`transaction_count_24h`	number	No	Number of transactions in the past 24 hours. High velocity increases fraud score.

Response fields

Parameter	Type	Required	Description
`success`	boolean	Yes	Whether the API call succeeded.
`data.status`	string	Yes	Detection decision: approved, rejected, or review_required.
`data.risk_level`	string	Yes	Risk level: low, medium, high, or critical.
`data.fraud_score`	integer	Yes	Fraud risk score 0–100. Above 70 triggers review_required; above 85 triggers rejected.
`data.fraud_type`	string	Yes	The fraud typology assessed.
`data.risk_factors`	array	Yes	List of specific risk signals detected, e.g. high_velocity_24h, tor_exit_node_ip.
`data.compliance_flags`	array	Yes	List of compliance issues found. Each flag has: rule_id, severity, message, suggestion.
`data.requires_human_review`	boolean	Yes	If true, the case is added to the review queue for a compliance officer.
`data.ai_recommendation`	string	Yes	Recommended action: allow, step-up authentication, block, or manual review.
`processing_time_ms`	integer	Yes	Total processing time in milliseconds.

Score thresholds

0 – 50approvedLow fraud risk. Allow the transaction.

51 – 70review_requiredModerate risk. Step-up authentication recommended.

71 – 85review_requiredHigh risk. Manual review before proceeding.

86 – 100rejectedCritical risk. Block and escalate immediately.

Code example

curl -X POST \
  https://shield.kodexa.systems/api/fraud/detect \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "ENT-AE-001",
    "customer_id": "CUST-AE-001",
    "jurisdiction": "AE",
    "fraud_type": "payment",
    "transaction_id": "TXN-2024-001",
    "amount": 45000,
    "currency": "AED",
    "ip_address": "185.220.101.45",
    "transaction_count_24h": 12
  }'

Example response

json

{
  "success": true,
  "data": {
    "status": "rejected",
    "risk_level": "critical",
    "fraud_score": 88,
    "fraud_type": "payment",
    "risk_factors": [
      "high_velocity_24h",
      "tor_exit_node_ip",
      "amount_anomaly"
    ],
    "ai_recommendation": "Block transaction. IP address matches Tor exit node. 12 transactions in 24h is 6x the customer baseline. Amount is 8x their average. Classic account takeover pattern.",
    "compliance_flags": [
      {
        "rule_id": "FRAUD-ATO-VELOCITY",
        "severity": "critical",
        "message": "Account takeover indicators: high velocity and anomalous IP",
        "suggestion": "Block transaction, freeze account, notify customer via registered contact only"
      }
    ],
    "requires_human_review": true,
    "review_reasons": ["critical_fraud_score", "tor_ip_detected"],
    "request_id": "fraud_1716000000_abc123",
    "created_at": "2026-05-22T04:00:00.000Z"
  },
  "processing_time_ms": 198,
  "jurisdiction": "AE",
  "plugin": "fraud"
}