> ## Documentation Index
> Fetch the complete documentation index at: https://vouch-sdk.vercel.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Fraud Detection: Real-Time Risk Scoring & Signals
> Understand how Vouch scores transactions in real time using device fingerprinting, behavioral signals, and identity data to return a GREEN, AMBER, or RED risk flag.
Fraud detection gives you a real-time risk score for any user action — a login, a payment, an account update, or an escrow funding event. For each call to `vouch.fraud.assess()`, Vouch collects device and behavioral data, evaluates it against a library of fraud signals, and returns a numeric score alongside a categorical flag and a human-readable recommendation. You branch your application logic on the flag: proceed, review, or block.
## How the scoring engine works
Vouch evaluates each call to `vouch.fraud.assess()` against a library of device, network, behavioral, and identity signals. When a signal fires, it contributes to the overall risk score. Multiple signals compound — a single elevated signal may produce an AMBER result, while several serious signals firing together can push the score into RED territory.
The final score is an integer between 0 and 100. Vouch returns this score alongside a categorical flag so your application can branch on a simple GREEN / AMBER / RED value rather than implementing its own scoring thresholds.
Fail-safe behaviour: if the scoring engine encounters an internal error at any point during evaluation, Vouch defaults to an `AMBER` flag. The engine never auto-approves a transaction on failure — your manual review queue will catch edge cases before any funds move.
## Understanding the three flags
Every call to `vouch.fraud.assess()` returns a `flag` value. Use the descriptions below to decide what your application should do at each threshold.
### 🟢 GREEN — score 0–39
The action carries low risk. You can proceed automatically without additional friction for the user.
**Recommended action:** Auto-approve the transaction or action.
### 🟡 AMBER — score 40–69
The action carries elevated risk. At least one signal has fired that warrants a closer look, but the evidence is not strong enough to block outright.
**Recommended action:** Require step-up verification before proceeding. This might mean sending an OTP, prompting the user to complete identity verification if they haven't already, or routing the transaction to your manual review queue.
### 🔴 RED — score 70–100
The action carries high risk. One or more serious signals have been triggered. Allowing the action would expose you or your users to probable fraud.
**Recommended action:** Block the transaction immediately and surface a clear error to the user. Log the `triggeredSignals` array for your compliance and investigations team.
Never silently drop a RED transaction without informing the user. Return a clear message explaining that the action could not be completed. If the block was triggered in error (for example, a legitimate user travelling internationally), your support team can review the `triggeredSignals` and clear the flag manually.
## Device fingerprinting
Vouch automatically collects a device fingerprint for every fraud assessment using FingerprintJS. The fingerprint captures browser and hardware attributes — screen resolution, installed fonts, GPU renderer, timezone, language settings, and dozens more — and hashes them into a stable device identifier.
You do not need to initialise FingerprintJS yourself or pass a fingerprint token. Including the Vouch SDK in your browser bundle is sufficient. The fingerprint is collected at the moment you call `vouch.fraud.assess()` and is matched against the device history on the user's profile to power the `device_mismatch` and `new_device` signals.
## Fraud signals
The `triggeredSignals` array in the response lists every signal that contributed to the score. Use the descriptions below to interpret and act on each one.
| Signal | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vpn_detected` | The request originated from a known VPN exit node. VPN use is common in high-risk fraud patterns, particularly for account takeover. |
| `proxy_detected` | The request was routed through a web proxy or anonymising service. Similar risk profile to VPN usage. |
| `impossible_travel` | The user's current location is geographically inconsistent with their previous session location given the elapsed time — for example, two sessions in different countries within 30 minutes. |
| `device_mismatch` | The current device fingerprint does not match any device previously associated with this user. |
| `velocity_anomaly` | The user has performed an unusually high number of actions (logins, assessments, or transactions) within a short time window, suggesting scripted or automated activity. |
| `identity_not_verified` | The `externalUserId` passed to the assessment has not completed identity verification, or their verification was not successful. |
| `new_device` | This is the first time this device fingerprint has been seen across the entire platform, not just for this user. |
| `new_account` | The user account associated with `externalUserId` was created very recently. New accounts carry a higher baseline risk for certain transaction types. |
| `high_value_transaction` | The `amount` passed in the assessment params exceeds the threshold for high-value transactions on your platform configuration. |
Signals compound. A `new_account` signal alone might contribute only a few points to the score, but `new_account` combined with `vpn_detected` and `high_value_transaction` will push the score into RED territory. Always review the full `triggeredSignals` array rather than reacting to any single signal in isolation.
## Response fields
Integer between 0 and 100. Higher values indicate greater risk. Used to derive the `flag`.
Categorical risk verdict. One of `GREEN`, `AMBER`, or `RED`. Branch your application logic on this value.
List of signal identifiers that contributed to the score. Use this array to understand why a score was elevated and to inform step-up verification or manual review decisions.
A human-readable string describing the suggested action — for example, `"Proceed with transaction"`, `"Require additional verification"`, or `"Block transaction immediately"`.
A human-readable risk category label corresponding to the flag — for example, `"Low Risk"`, `"Elevated Risk"`, or `"High Risk"`. Use this value for display in dashboards or audit logs.
## Testing in development
When running against the sandbox environment, pass `simulateVpn: true` or `simulateImpossibleTravel: true` in your `vouch.fraud.assess()` params to force those signals to fire. This lets you test your AMBER and RED handling paths without needing to actually route traffic through a VPN or spoof geolocation data.
Use the simulation flags to verify that your application:
* Surfaces the correct UI for AMBER (step-up verification prompt)
* Blocks the action and shows the right error message for RED
* Logs `triggeredSignals` correctly for your compliance pipeline
* Handles the AMBER fail-safe case (engine error defaulting to AMBER)