> ## 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.

# Vouch SDK Fraud Assessment: Score and Flag Transactions

> Score transactions and user sessions for fraud risk using device signals, VPN detection, and impossible travel analysis before processing payments.

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)`

```typescript theme={null}
import Vouch from 'vouch-sdk';

const vouch = new Vouch('your-api-key');

async function checkTransaction(userId: string, amount: number) {
  const assessment = await vouch.fraud.assess({
    platformUserId: userId,
    transactionAmount: amount,
  });

  switch (assessment.flag) {
    case 'GREEN':
      // Low risk — proceed automatically
      await processPayment(userId, amount);
      break;

    case 'AMBER':
      // Elevated risk — require step-up verification
      await promptStepUpVerification(userId);
      break;

    case 'RED':
      // High risk — block and alert
      await blockAndNotify(userId, assessment.triggeredSignals);
      break;
  }

  console.log(`Score: ${assessment.score} | Category: ${assessment.category}`);
  console.log('Recommendation:', assessment.recommendation);
  console.log('Triggered signals:', assessment.triggeredSignals);
}
```

### Parameters

<ParamField body="platformUserId" type="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.
</ParamField>

<ParamField body="transactionAmount" type="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.
</ParamField>

<ParamField body="agreementId" type="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.
</ParamField>

<ParamField body="simulateVpn" type="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.
</ParamField>

<ParamField body="simulateImpossibleTravel" type="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.
</ParamField>

<Note>
  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.
</Note>

***

## Response fields

<ResponseField name="score" type="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.
</ResponseField>

<ResponseField name="flag" type="string">
  The primary decision signal. One of `"GREEN"`, `"AMBER"`, or `"RED"`. See the flag reference table below for recommended actions per flag.
</ResponseField>

<ResponseField name="category" type="string">
  A human-readable risk category corresponding to the score range. One of `"Low Risk"`, `"Elevated Risk"`, `"High Risk"`, or `"Critical"`.
</ResponseField>

<ResponseField name="triggeredSignals" type="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.
</ResponseField>

<ResponseField name="recommendation" type="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.
</ResponseField>

***

## Flag reference

| Flag    | Score range | Recommended action                                           |
| ------- | ----------- | ------------------------------------------------------------ |
| `GREEN` | 0 – 39      | Auto-approve the transaction.                                |
| `AMBER` | 40 – 69     | Require step-up verification (e.g., OTP, identity re-check). |
| `RED`   | 70 – 100    | Block the transaction and notify your risk team.             |

<Warning>
  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.
</Warning>

<Tip>
  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.
</Tip>