Integrating a Fraud Detection API: Step-by-Step Guide for Indian Developers

Adding fraud detection to an Indian fintech or banking application used to require either an expensive enterprise contract with a global fraud vendor, or a multi-month in-house machine learning project. Neither option makes sense for a Series A startup or a mid-size NBFC's IT team.

FraudIntel's API changes this. You can add real-time fraud scoring to any transaction, onboarding, or payment flow in under a day. This guide shows you exactly how, with working code in Node.js, Python, and Java.

What You're Building

Before any transaction, KYC submission, or loan application is processed, your backend calls the FraudIntel API with the entity being checked (phone number, UPI ID, email, domain, or text). You receive a risk score, risk level, detected signals, and recommended action. Your application acts on the result.

The integration sits at the authorization layer — between the user's request and your core processing. Average latency: 85–120ms. Acceptable for any payment or onboarding flow.

Step 1 — Get Your API Key

Sign up at fraudintel.in/app. Free tier includes 500 API calls/month — enough to test across your staging environment. API keys are scoped to your account and include built-in rate limiting.

Step 2 — Make Your First API Call

// Install: npm install node-fetch
import fetch from 'node-fetch';

async function checkFraud(entity, type, context = {}) {
  const response = await fetch('https://www.fraudintel.in/api/v1/check', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FRAUDINTEL_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ entity, type, context })
  });

  if (!response.ok) throw new Error(`FraudIntel API error: ${response.status}`);
  return response.json();
}

// Usage — check a UPI ID before processing payment
const result = await checkFraud('suspicious@paytm', 'upi', {
  amount_inr: 50000,
  is_new_beneficiary: true,
  transaction_type: 'p2p'
});

console.log(result.risk_level);  // 'HIGH' | 'MEDIUM' | 'LOW'
console.log(result.risk_score);  // 0-100
console.log(result.signals);     // ['upi_fraud', 'new_beneficiary_high_value']
console.log(result.action);      // 'BLOCK' | 'CHALLENGE' | 'ALLOW'

{
  "ok": true,
  "entity": "suspicious@paytm",
  "type": "upi",
  "risk_level": "HIGH",
  "risk_score": 82,
  "signals": [
    "upi_fraud",
    "entity_in_fraud_database",
    "high_value_new_beneficiary"
  ],
  "action": "BLOCK",
  "category": "upi_fraud",
  "times_seen": 47,
  "first_reported": "2026-01-15",
  "last_seen": "2026-04-12",
  "checked_at": "2026-04-14T02:56:00Z"
}

Step 3 — Wire Into Your Transaction Flow

Here is a complete UPI payment handler with fraud scoring integrated:

// Express.js payment route — complete example
app.post('/api/payment/upi/initiate', authMiddleware, async (req, res) => {
  const { beneficiary_upi, amount_inr, purpose } = req.body;

  // 1. Fraud check — runs before any payment processing
  let fraudResult;
  try {
    fraudResult = await checkFraud(beneficiary_upi, 'upi', {
      amount_inr,
      is_new_beneficiary: !(await isKnownBeneficiary(req.user.id, beneficiary_upi)),
      hour_ist: new Date().getUTCHours() + 5.5
    });
  } catch (err) {
    // Fail open — if fraud API is down, allow with logging
    console.error('Fraud check failed, proceeding:', err.message);
    fraudResult = { risk_level: 'UNKNOWN', action: 'ALLOW' };
  }

  // 2. Log fraud check for RBI audit trail
  await db.query(
    `INSERT INTO fraud_checks(user_id, entity, risk_level, risk_score, signals, action, created_at)
     VALUES($1, $2, $3, $4, $5, $6, NOW())`,
    [req.user.id, beneficiary_upi, fraudResult.risk_level,
     fraudResult.risk_score, JSON.stringify(fraudResult.signals), fraudResult.action]
  );

  // 3. Act on fraud result
  if (fraudResult.action === 'BLOCK') {
    return res.status(403).json({
      error: 'Transaction blocked — beneficiary flagged as high fraud risk',
      fraud_signals: fraudResult.signals,
      support: 'contact@yourbank.in'
    });
  }

  if (fraudResult.action === 'CHALLENGE') {
    // Trigger step-up auth — additional OTP, manager call, etc.
    return res.json({
      status: 'STEP_UP_REQUIRED',
      session_token: await createStepUpSession(req.user.id, beneficiary_upi, amount_inr),
      message: 'Additional verification required for this transaction'
    });
  }

  // 4. Proceed with payment (LOW risk or ALLOW)
  const paymentResult = await initiateUpiPayment(beneficiary_upi, amount_inr, purpose);
  res.json({ status: 'SUCCESS', ...paymentResult });
});

Step 4 — Add Loan Onboarding Fraud Check

For NBFCs and lending apps, run the fraud check at KYC submission — before disbursement:

# Python example — loan application fraud screening
import requests

def screen_loan_applicant(phone, email, pan):
    entities_to_check = [
        {'entity': phone, 'type': 'phone'},
        {'entity': email, 'type': 'email'}
    ]

    results = []
    for e in entities_to_check:
        r = requests.post(
            'https://www.fraudintel.in/api/v1/check',
            headers={'Authorization': f'Bearer {FRAUDINTEL_KEY}'},
            json=e,
            timeout=5
        )
        results.append(r.json())

    # If any entity is HIGH risk, flag for manual review
    max_risk = max(r.get('risk_score', 0) for r in results)
    if max_risk >= 70:
        return {'decision': 'MANUAL_REVIEW', 'max_risk_score': max_risk}
    elif max_risk >= 40:
        return {'decision': 'ENHANCED_DUE_DILIGENCE', 'max_risk_score': max_risk}
    else:
        return {'decision': 'PROCEED', 'max_risk_score': max_risk}

Step 5 — Free Text Fraud Detection

FraudIntel also analyzes free text — useful for chat messages, loan purpose descriptions, or customer support tickets:

// Check a suspicious message for fraud signals
const msgCheck = await fetch('https://www.fraudintel.in/api/v1/analyze', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    text: "Your KYC has expired. Send OTP to 9876543210 to reactivate your account."
  })
});
// Returns: signals: ['otp_request', 'kyc_fraud', 'urgency'], risk_level: 'HIGH'

Best Practices for Indian Fintech Integrations

• Always fail open. If the fraud API times out, log the failure and allow the transaction with a flag — don't block your entire payment flow because of an external API issue.
• Cache entity results for 1 hour. If the same UPI ID appears in 100 transactions in an hour, cache the result rather than making 100 API calls.
• Log every check for RBI compliance. Store entity, timestamp, risk score, signals, and action taken in your database. RBI auditors will ask for this.
• Set thresholds per workflow. A ₹500 UPI transfer can have a higher risk tolerance than a ₹5 lakh loan disbursement. Tune your BLOCK/CHALLENGE/ALLOW thresholds per transaction type.
• Use context fields. Pass amount_inr, is_new_beneficiary, and hour_ist — these improve scoring accuracy significantly.