AI Fraud & Risk Intelligence API

Calibrated Probabilities Expected Loss (EV) Graph Risk Policy DSL Step-Up Orchestration Audit Artifacts
Operated by Spyface Tech Company, LLC • 30 N Gould St Ste N, Sheridan, WY 82801 USA • Support: hello@spyface.com

1) Capabilities

2) Signals & Feature Families

3) Graph Risk (Ring & Cluster Detection)

Graph risk detects organized fraud by modeling relationships across entities such as users, devices, payment instruments, emails, phones, addresses, and IPs.

// Conceptual graph model
// nodes: user, device, payment, email, phone, address, ip
// edges: observed relationships
ring_score = community_risk_mass(user_node)

4) Calibration

Calibration ensures that predicted probabilities match observed outcomes. For example, transactions scored at p_fraud = 0.70 should converge toward ~70% fraud incidence within that risk band over time.

// Example concept (not implementation detail)
calibrated_p = calibrate(raw_model_score)

5) Expected Loss & Decision Economics

Decisions are optimized against expected economic impact, not just risk ranking.

expected_loss =
  p_fraud * (amount * loss_given_fraud)
+ p_dispute * dispute_cost
+ ops_cost(decision)

6) Policy DSL

Policy DSL provides deterministic controls for compliance, merchant requirements, and business logic. Policies can require step-ups, enforce hard blocks, or route to review.

policy:
  - if product == "MEDICAL_TRAVEL" and lead_time_days < 2:
      require_step_up: "DOC_VERIFY"
  - if amount > 1500 and device.trust == "LOW":
      require_step_up: "3DS"
  - if graph.ring_score > 0.85:
      action: "BLOCK"

7) Step-Up Orchestration

The API can recommend the most cost-effective intervention to reduce risk while preserving conversion.

8) Endpoints

9) Schemas

Request (minimal)

{
  "request_id":"req_risk_2201",
  "transaction":{
    "id":"tx_88921",
    "amount":640,
    "currency":"USD",
    "product":"HOTEL_BOOKING",
    "lead_time_days":2
  },
  "user":{
    "user_id":"u_7781",
    "account_age_days":1,
    "country":"US"
  },
  "device":{
    "fingerprint":"dfp_9a1...",
    "ip":"203.0.113.44",
    "asn":7922
  },
  "payment":{
    "bin":"411111",
    "country":"US"
  }
}

Response (decision)

{
  "request_id":"req_risk_2201",
  "p_fraud":0.18,
  "p_dispute":0.06,
  "expected_loss_usd":14.2,
  "decision":"CHALLENGE",
  "recommended_step_up":"3DS",
  "reason_codes":[
    "DEVICE_NEW_ACCOUNT",
    "LEAD_TIME_SHORT",
    "GRAPH_WEAK_LINKS"
  ],
  "policy_trace":[
    "RULE_02: amount>1500 && device.trust==LOW -> require 3DS (not triggered)"
  ]
}

10) Code Examples

Node.js — Real-time decision

const res = await fetch("https://api.spyface.com/v1/risk/decision", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SPYFACE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});

const out = await res.json();

if (out.decision === "APPROVE") {
  approve();
} else if (out.decision === "CHALLENGE") {
  // Use out.recommended_step_up: 3DS / OTP / DOC_VERIFY
  runStepUp(out.recommended_step_up);
} else if (out.decision === "REVIEW") {
  queueManualReview(out);
} else {
  block(out);
}

Python — Outcome feedback (calibration loop)

import os, requests

event = {
  "transaction_id":"tx_88921",
  "outcome":"CHARGEBACK",  # LEGIT / FRAUD_CONFIRMED / REFUND_ABUSE / CHARGEBACK
  "amount":640,
  "currency":"USD"
}

requests.post(
  "https://api.spyface.com/v1/events",
  headers={"Authorization": f"Bearer {os.environ['SPYFACE_API_KEY']}"},
  json=event,
  timeout=10
)

11) Audit & Explainability

{
  "decision_hash":"sha256:...",
  "reason_codes":["LEAD_TIME_SHORT","DEVICE_NEW_ACCOUNT"],
  "policy_trace":["RULE_07: graph.ring_score>0.85 -> BLOCK (not triggered)"],
  "top_contributors":[
    {"signal":"account_age_days","impact":0.07},
    {"signal":"lead_time_days","impact":0.05}
  ]
}

12) Monitoring & Model Risk Management