# Fraud assessment

Enterprise

SMB (Worldpay eCommerce)

## How to enable

Using the `instruction.fraud` object and setting the `type` value to `fraudSight` enables a risk assessment to run as part of the payment request.

## Sequence diagram

FraudSight (highRisk)
Card payment with [FraudSight enabled](/products/payments/enable-features/fraud-assessment) that results in a highRisk assessment outcome that stops the payment.


```mermaid

sequenceDiagram
    participant Browser
    participant Merchant_Frontend as Merchant Frontend
    participant Merchant_Backend as Merchant Backend
    participant Payments_API as Payments API
    Browser->>Merchant_Frontend: Click Pay
    Merchant_Frontend->>Merchant_Backend: Pay 
    Merchant_Backend->>Payments_API: Payment request
    Payments_API->>Payments_API: Fraud assessment
    Note over Payments_API: outcome: highRisk <br> Payment stopped
    Payments_API->>Merchant_Backend: Payment response
    Merchant_Backend->>Merchant_Frontend: Transaction failed
    Note left of Merchant_Frontend: Transaction failed
```

FraudSight (lowRisk/review)
Card payment with [FraudSight enabled](/products/payments/enable-features/fraud-assessment) that results in a lowRisk assessment outcome and continues with the payment.


```mermaid

sequenceDiagram
    participant Browser
    participant Merchant_Frontend as Merchant Frontend
    participant Merchant_Backend as Merchant Backend
    participant Payments_API as Payments API
    participant Issuer
    Browser->>Merchant_Frontend: Click Pay
    Merchant_Frontend->>Merchant_Backend: Pay 
    Merchant_Backend->>Payments_API: Payment request
    Payments_API->>Payments_API: fraud assessment
    Note over Payments_API: outcome: lowRisk or review <br> Proceed with payment
    Payments_API->>Issuer: Authorization Request
    Issuer->>Payments_API: Authorization Response
    Payments_API->>Merchant_Backend: Payment response
    Merchant_Backend->>Payments_API: Settlements request
    Payments_API->>Merchant_Backend: Settlements response
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
```

### Fraud object (Required)


```
"instruction": {
  ....
  "fraud": {
      "type": "fraudSight",
  }
}
```

Fraud assessment is only available for `instruction.method` = `card` and will return a validation error response if used with others.

### Additional Values used by the assessment

As well as core payment details such as the `cardNumber`, `billingAddress` and any settings in the `instruction.fraud` object, the following key:values are used as part of the risk assessment. By providing these, it means more data points and a slight increase in spotting potential fraud.

|  |  |  |
|  --- | --- | --- |
| `instruction.customer` | firstName, lastName, email, phone, dateOfBirth, customerId, ipAddress |  |
| `instruction.shipping` | firstName, lastName, address |  |


### SilentMode

Setting `instruction.fraud.silentMode` to `true` allows an assessment to be run but the outcome (highRisk) is not stopping the transaction. This is primarily used when first going live and a certain amount of real data is required to mature the data model and make the assessments more accurate. Normally a few weeks is enough but this varies with the number of transactions sent.

### Threatmetrix Device Data

To provide even more data points for an assessment, Threatmetrix can be run on the customers browser or device. This will create a fingerprint of a customer, based on data like ipAddress, browser details and perform a GeoIP lookup for a rough idea of the location.

[FraudSight Device Data](/products/fraudsight/device-data)

The sessionId representing this fingerprint is provided in `instruction.fraud.tmxSessionId`.

## Additional Responses

If the fraud assessment score is high enough a `highRisk` response is sent and the transaction will not continue.


```
{
  "outcome": "fraudHighRisk",
  "transactionReference": "2847f678-fd97-4558-b913-8945c8b11dc9",
  "score": 97.0,
  "reason": [
    "Recent unexpected card activity"
  ]
}
```

## Outcome details

Unless flagged as `fraudHigRisk`, the final payment response includes basic details of what happened during the risk assessment.


```
...
"fraud": {
  "outcome": "lowRisk",
  "score": 44.0
}
...
```

**Next steps**

- [Testing (FraudSight tab)](/products/payments/testing) for scenario details and magic test values