Fraud Prevention

Score transactions in real time, screen against blacklists, and enforce rules before money moves — built specifically for African mobile money fraud patterns.

Overview

Every payment and payout can be evaluated by AfriRoute's risk engine, which combines device fingerprinting, velocity checks, geolocation, and behavioral history into a single risk score from 0 (safe) to 100 (high risk). You can score on demand or let rules auto-block, hold, or require verification.

Base URL: https://api.afriroute.ai — Auth: Authorization: Bearer $AFRIROUTE_API_KEY

Endpoints

Risk Check

POST /v1/payments/risk-check

Field	Type	Required	Description
phone_number	string	Yes	Customer phone (E.164)
amount	number	Yes	Transaction amount
currency	string	Yes	ISO 4217 code
device_id	string	No	Device fingerprint
ip_address	string	No	Customer IP for geolocation

curl -X POST https://api.afriroute.ai/api/v1/payments/risk-check \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+251911234567",
    "amount": 5000,
    "currency": "ETB",
    "ip_address": "196.188.0.1"
  }'

{
  "risk_score": 23,
  "risk_level": "low",
  "factors": ["New customer", "High amount for first transaction"],
  "recommendation": "proceed_with_verification",
  "checks": {
    "phone_verified": true,
    "device_fingerprint": "known",
    "velocity_check": "passed",
    "blacklist_check": "passed"
  }
}

Create a Rule

POST /v1/payments/fraud/rules

await fetch('https://api.afriroute.ai/api/v1/payments/fraud/rules', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer $AFRIROUTE_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Block high-risk large payouts',
    condition: { risk_score_gte: 70, amount_gte: 10000 },
    action: 'block'   // block | hold | require_otp
  })
});

import requests

requests.post(
    'https://api.afriroute.ai/api/v1/payments/fraud/rules',
    headers={'Authorization': 'Bearer $AFRIROUTE_API_KEY'},
    json={
        'name': 'Hold rapid repeat attempts',
        'condition': {'velocity_per_hour_gte': 5},
        'action': 'hold'
    }
)

Manage Blacklist

POST /v1/payments/fraud/blacklist

curl -X POST https://api.afriroute.ai/api/v1/payments/fraud/blacklist \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "phone_number", "value": "+251911000000", "reason": "Confirmed fraud" }'

Risk Levels

Score	Level	Suggested Action
0–29	low	Proceed
30–69	medium	Require OTP/verification
70–100	high	Block or manual review

Detection Signals

• Velocity checks (rapid repeat attempts)
• Device fingerprinting
• Geolocation vs. registered region
• Blacklist screening (phone, device, IP)
• Behavioral history and first-transaction risk

Best Practices

• Call risk-check before initiating high-value payouts, not just inbound payments.
• Start rules in hold mode and review outcomes before switching to block.
• Combine OTP step-up for medium risk to reduce false declines.
• Feed confirmed fraud back into the blacklist to improve future scoring.

Error Handling

Code	Description	Action
BLOCKED_BY_RULE	A fraud rule blocked the transaction	Review or override manually
BLACKLISTED	Entity is blacklisted	Reject the transaction
RISK_ENGINE_TIMEOUT	Scoring service slow	Apply your default fallback policy

Related Links

• Mobile Money
• Payouts
• Wallet
• Payments API Reference

---

Last Updated: May 2026