Fraud assessment

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.

Fraud object (Required)

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

outcomestring

outcome of the fraud assessment. highRisk outcomes stop the transaction before payment.

Enum"lowRisk""highRisk""review""error""lowRisk(silentMode)""highRisk(silentMode)""review(silentMode)""error(silentMode)"

scorenumber(double)

The score calculated by the fraud assessment, set score thresholds are used to define lowRisk, highRisk and review outcomes

Example:

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

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