Skip to main content
The fraud module lets you assess how risky a transaction or user action is before you commit to it. You submit context about the user and the transaction, and Vouch returns a numeric score, a color-coded flag, and a plain-English recommendation. Use the flag to drive automated decisions — auto-approve low-risk sessions, prompt for extra verification on elevated ones, and block high-risk attempts outright. Device fingerprinting runs automatically in the background when you call assess. You do not need to collect or pass a fingerprint yourself.

vouch.fraud.assess(params)

Parameters

string
required
Your platform’s unique identifier for the user initiating the transaction. Vouch uses this to build a behavioral history and detect anomalies across sessions.
number
required
The value of the transaction in the base currency unit (e.g., kobo for NGN, cents for USD). Unusually large amounts relative to a user’s history contribute to the risk score.
string
The ID of an escrow agreement to associate with this assessment. Pass this when assessing the payment step of an escrow flow — it links the fraud check to the agreement record.
boolean
When set to true, forces the assessment to treat the session as if a VPN is detected. Sandbox and testing use only. Do not set this in production.
boolean
When set to true, forces the assessment to treat the session as if impossible travel is detected. Sandbox and testing use only. Do not set this in production.
Device fingerprint is collected automatically from the browser environment every time you call assess. In Node.js, a static server-side fingerprint is used instead. You never need to pass fingerprint data manually.

Response fields

number
An integer from 0 to 100 representing the overall risk level for this session. Higher values indicate greater risk. Use this for logging, analytics, or fine-grained thresholding beyond the three-flag system.
string
The primary decision signal. One of "GREEN", "AMBER", or "RED". See the flag reference table below for recommended actions per flag.
string
A human-readable risk category corresponding to the score range. One of "Low Risk", "Elevated Risk", "High Risk", or "Critical".
string[]
An array of signal names that contributed to the score, such as "VPN_DETECTED" or "IMPOSSIBLE_TRAVEL". Use this array for detailed audit logs and to explain decisions to your compliance team.
string
A plain-English action recommendation generated by Vouch based on the score and signals, for example "Allow transaction" or "Block and review". Display this in internal dashboards or log it alongside the score.

Flag reference

Never rely solely on the score number for automated decisions — always branch on flag. Score thresholds may be recalibrated over time, but the flag semantics remain stable.
Log triggeredSignals alongside every assessment, even for GREEN outcomes. Patterns in signals over time can reveal coordinated low-score attacks that individual assessments would miss.