Skip to main content

Risk & Fraud

Layers that keep lending decisions honest: real-time fraud detection on every verification, portfolio-level risk analytics, AML/PEP sanctions screening, and hex-level usage analytics.

Fraud detection​

Fraud checks run automatically inside KYC and Proximity verification. Results surface as a fraud_check block:

{
  "fraud_check": {
    "blocked": false,
    "risk_score": 0.12,
    "risk_level": "low",
    "signals": [
      { "type": "ip_geo_match", "severity": "low", "description": "IP country matches address country", "score": 0.05 }
    ],
    "recommendation": "approve"
  }
}

Signals include:

  • GPS spoofing — implausible coordinates for the device's IP location.
  • VPN / proxy detection — traffic from known anonymising endpoints.
  • Velocity abuse — implausible request rates or geo-impossible travel between consecutive events.
  • Mock location — device reports is_mock_location: true (proximity flow).

risk_level is low | medium | high | critical; blocked is true only for critical signals. High-risk verifications persist a fraud alert for review (admin: GET /v2/admin/fraud/alerts).

Portfolio risk​

POST /v2/analytics/portfolio-risk aggregates risk across a loan portfolio — fraud flags, drift events, verification quality — into a portfolio heatmap:

curl -X POST "https://api.afrihex.com/v2/analytics/portfolio-risk" \
  -H "X-API-Key: $AFRIHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "loan_ids": ["loan_456", "loan_789"] }'

Use it to triage: which loans are drifting, which verifications were weak, where the concentration of risk is.

AML / PEP screening​

POST /v2/aml/screen screens a name against a self-hosted OpenSanctions dataset (sanctions + politically exposed persons). Advisory by design — results flag for manual review, they don't auto-block:

curl -X POST "https://api.afrihex.com/v2/aml/screen" \
  -H "X-API-Key: $AFRIHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "full_name": "Kofi Mensah", "customer_id": "cust_123" }'

Review outcomes with POST /v2/aml/screenings/{id}/review, and list past screenings with GET /v2/aml/screenings.

Hex analytics​

Understand where traffic comes from:

  • GET /v2/analytics/hotspots — busiest hex cells over time:
{
  "success": true,
  "data": {
    "resolution": 7,
    "days": 30,
    "count": 20,
    "cells": [
      {
        "h3_index": "877576973ffffff",
        "resolution": 7,
        "center": { "lat": 5.587652594702177, "lng": -0.2021282623530355 },
        "request_count": 433,
        "first_seen": "2026-04-26 12:44:42",
        "last_seen": "2026-07-31 15:59:25"
      }
    ]
  }
}
  • GET /v2/analytics/heatmap?bbox=...&res=7 — request-density heatmap (bbox format north,south,east,west).
  • GET /v2/analytics/cell/{h3index} — stats for a single cell.
  • GET /v2/analytics/poi-density — point-of-interest density in a bounding box.

API reference​

See Risk & Fraud — API Reference for every endpoint in this group.