Skip to content
APIs/FraudSight/
Fraud assessment

Fraud assessment

Request

Request a risk assessment

Security
BasicAuth
Headers
Content-Typestringrequired
Example:application/vnd.worldpay.fraudsight-v1.hal+json
Acceptstringrequired
Example:application/vnd.worldpay.fraudsight-v1.hal+json
Bodyapplication/vnd.worldpay.fraudsight-v1.hal+json
transactionReferencestring, [ 1 .. 64 ] characters^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$required

A unique reference for authentication. For example, e-commerce order code.

merchantobjectrequired

An object that contains information about the merchant and API level configuration.

exemptionobject

An object that contains information about the type and placement of the requested exemption.

instructionobjectrequired

The object that contains all the payment information related to the authentication request.

doNotApplyExemptionboolean

Request an exemption but don't apply it in the payment. Used for the initial go-live to build up the data model and have more reliable exemption predictions.

riskDataobject

An object that holds risk related information that might help in improving the accuracy of fraud assessment.

deviceDataobject

Object containing device data information.

requestExemptionbooleandeprecated

Deprecated, use the exemption object.

Request an SCA Exemption as part of the same request. Only supports a capability of authorizationOnly.

Note: Not available for paymentInstrument.type card/plain+masked

Assessment using the card instrument

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "paymentInstrument": {
      "type": "card/front",
      "cardHolderName": "Sherlock Holmes",
      "cardNumber": "4444333322221111",
      "cardExpiryDate": {
        "month": 5,
        "year": 2035
      },
      "billingAddress": {
        "address1": "221B Baker Street",
        "address2": "Marylebone",
        "address3": "Westminster",
        "postalCode": "NW1 6XE",
        "city": "London",
        "state": "Greater London",
        "countryCode": "GB"
      }
    },
    "value": {
      "currency": "GBP",
      "amount": 250
    }
  },
  "deviceData": {
    "provider": {
      "name": "ravelin",
      "collectionReference": "rjs-25998f27-ed8d-4b71-a516-d3147f695f20"
    },
    "ipAddress": "192.0.0.0"
  },
  "riskData": {
    "account": {
      "email": "sherlock.holmes@example.com",
      "dateOfBirth": "1854-01-06",
      "shopperId": "id123"
    },
    "transaction": {
      "firstName": "Sherlock",
      "lastName": "Holmes",
      "phoneNumber": "02031234321"
    },
    "shipping": {
      "firstName": "James",
      "lastName": "Moriarty",
      "address": {
        "address1": "The Palatine Centre",
        "address2": "Durham University",
        "address3": "Stockton Road",
        "postalCode": "DH1 3LE",
        "city": "Durham",
        "state": "County Durham",
        "countryCode": "GB",
        "phoneNumber": "01911234321"
      }
    },
    "custom": {
      "number1": 1,
      "number2": 2,
      "number3": 3,
      "number4": 4,
      "number5": 5,
      "number6": 6,
      "number7": 7,
      "number8": 8,
      "number9": 9,
      "string1": "text1",
      "string2": "text2",
      "string3": "text3",
      "string4": "text4",
      "string5": "text5",
      "string6": "text6",
      "string7": "text7",
      "string8": "text8",
      "string9": "text9"
    }
  }
}

Responses

The authentication has been created

Bodyapplication/vnd.worldpay.fraudsight-v1.hal+json
outcomestringrequired

The outcome of the fraudsight assessment request. To understand more about the outcomes and how to reproduce them, see FraudSight testing.

Enum:"lowRisk""highRisk""review"
transactionReferencestring, [ 1 .. 64 ] charactersrequired

A unique reference for assessment that was passed in the request.

riskProfileobjectrequired

An object that holds the risk profile link.

scorenumber, [ 0 .. 100 ]

Percentage assessment score for the transaction. Higher the value the greater the assessed risk. The outcome value is based on the thresholds configured using this score.

reasonArray of strings, <= 10 items

Short description of the reason for the outcome. A reason can be returned for any 'outcome', even lowRisk. For example:

  • recent unexpected card activity
  • card unfamiliarity
  • card type often linked to fraud
  • unusual transaction for merchant
  • irregularities in cardholder-entered information
  • high risk email
  • unusual behavior for card
exemptionobject

An object that holds information about the exemption, if it is granted.

Response

Low risk outcome, proceed with the payment

{
  "outcome": "lowRisk",
  "transactionReference": "123456",
  "score": 44.2,
  "riskProfile": {
    "href": "https://access.worldpay.com/riskprofile/eyJrIjoxLCJkIjoialRBL0FFelBzcnZ"
  }
}