Skip to main content

​
Overview

TXCloud uses a unified risk scoring system across all APIs. Risk scores help you make informed decisions about users, transactions, and businesses.

​
Score Scale

All TXCloud risk scores use a 0-1000 scale:
Score RangeRisk LevelDescription
0-200🟢 Very LowHighly trusted, minimal risk
201-400🟢 LowNormal, proceed with confidence
401-600🟡 MediumSome concerns, consider review
601-800🟠 HighSignificant risk, additional verification
801-1000🔴 CriticalVery high risk, likely block
Higher scores = Higher risk. A score of 0 is the safest, 1000 is the riskiest.

​
Risk Score by API

​
Identity Verification

{
  "id": "ver_abc123",
  "status": "verified",
  "risk_score": 150,
  "risk_level": "low",
  "risk_factors": [
    { "code": "new_device", "weight": 50 },
    { "code": "document_age", "weight": 100 }
  ]
}

​
Transaction Scoring

{
  "id": "trs_abc123",
  "decision": "approve",
  "risk_score": 320,
  "risk_level": "medium",
  "signals": {
    "positive": ["known_recipient", "normal_amount"],
    "negative": ["new_device"],
    "neutral": ["weekend_transaction"]
  }
}

​
Credit Assessment

{
  "id": "lra_abc123",
  "credit_score": 720,  // 300-850 scale (traditional credit)
  "risk_score": 180,    // 0-1000 TXCloud scale
  "risk_level": "low",
  "grade": "B+"
}

​
Score Components

Risk scores are calculated from multiple signals:

​
Identity Signals

SignalImpactDescription
Document fraud+300-500Tampering detected
Face mismatch+200-400Selfie doesn’t match document
Liveness failed+300-500Not a live person
Data inconsistency+100-200Extracted data conflicts

​
Device Signals

SignalImpactDescription
Known device-50Previously verified device
New device+50First time seeing device
VPN detected+100-200VPN connection active
Emulator+300Running in emulator
Rooted/jailbroken+200Modified device

​
Behavioral Signals

SignalImpactDescription
Unusual amount+100-200Outside normal range
Unusual time+50-100Late night transaction
Velocity exceeded+200-400Too many attempts
New recipient+50First transfer to recipient

​
Using Risk Scores

​
Decision Thresholds

Configure thresholds for automated decisions: 
const THRESHOLDS = {
  AUTO_APPROVE: 300,    // Score <= 300: auto-approve
  MANUAL_REVIEW: 600,   // 301-600: queue for review
  AUTO_DECLINE: 800     // Score > 800: auto-decline
};

function makeDecision(riskScore) {
  if (riskScore <= THRESHOLDS.AUTO_APPROVE) {
    return 'approve';
  } else if (riskScore <= THRESHOLDS.MANUAL_REVIEW) {
    return 'review';
  } else {
    return 'decline';
  }
}

​
Custom Rules

Create rules that adjust scores based on your business logic: 
// Create a custom rule
await txcloud.fraud.rules.create({
  name: 'High Value New User',
  condition: 'user.age_days < 7 AND transaction.amount > 10000',
  action: 'review',
  score_adjustment: 200  // Add 200 to risk score
});

​
Score Explanations

Always provide context for your decisions: 
const verification = await txcloud.identity.verify({ ... });

// Get human-readable explanation
const explanation = verification.risk_factors
  .map(f => `${f.code}: +${f.weight} points`)
  .join('\n');

console.log('Risk Factors:');
console.log(explanation);
// Output:
// Risk Factors:
// new_device: +50 points
// vpn_detected: +150 points
// unusual_time: +75 points

​
Best Practices

Begin with strict thresholds and loosen as you gather data:
  • Week 1-2: Manual review at score > 400
  • Week 3-4: Analyze false positive rate
  • Week 5+: Adjust thresholds based on data
Don’t rely on score alone — consider:
  • User history
  • Transaction type
  • Business context
  • Time sensitivity
Store risk scores and factors for:
  • Compliance audits
  • Model improvement
  • Dispute resolution
Track your score distribution over time:
  • Sudden spikes may indicate attacks
  • Gradual shifts may indicate model drift

​
Analytics

Track your risk metrics in the dashboard: 
const analytics = await txcloud.transactions.analytics.summary({
  period: '30d'
});

console.log('Risk Distribution:', analytics.risk_distribution);
// { low: 85000, medium: 12000, high: 2500, critical: 500 }

console.log('Fraud Rate:', analytics.fraud.fraud_rate);
// 0.00036 (0.036%)

View Analytics Dashboard

Access detailed risk analytics in your dashboard