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",
  }
}

type required	string Default: "FraudSight" Enable a FraudSight risk assessment Value: "FraudSight"
silentMode	boolean Default: false Perform the Fraud assessment but do not act on the outcome. Normally used for the initial launch.
tmxSessionId	string Device fingerprint provided by Threatmetrix.
	object (Custom) Additional values specific to your order that can be used to create manual fraud rules.

Attention

Fraud assessment isn't available for all scenarios and will return a validation error message when it can't be run, please check the documentation for the relevant scenario.

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