Skip to main content
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.
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

​
number
Integer between 0 and 100. Higher values indicate greater risk. Used to derive the flag.
​
string
Categorical risk verdict. One of GREEN, AMBER, or RED. Branch your application logic on this value.
​
array
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.
​
string
A human-readable string describing the suggested action — for example, "Proceed with transaction", "Require additional verification", or "Block transaction immediately".
​
string
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)