Access Worldpay
/
Fraud assessment

Last Updated: 04 July 2024 | Change Log

Fraud assessment

POST your request to the fraudsight:assess action link.

Assessment example request

POST https://try.access.worldpay.com/fraudsight/assessment

Risk assessment request body:

application/vnd.worldpay.fraudsight-v1.hal+json

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": {
    "collectionReference": "0_4XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX8G6",
    "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"
    }
  }
}

Schema

Full API Reference here

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.

entitystring[ 1 .. 64 ] characters^[A-Za-z0-9 ]*$required

Used to route the request in Access Worldpay, created as part of on-boarding.

instructionobjectrequired

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

valueobjectrequired

An object that contains information about the value of the assessment.

paymentInstrumentanyrequired

An object that contains the card details or token location.

requestExemptionboolean

Whether to request an SCA Exemption as part of the same 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.

accountobject

Object containing all customer account related risk data.

transactionobject

Object containing all customer transaction related risk data.

shippingobject

Object containing all data related to how the order is shipped.

customobject

Additional values specific to your order that can be used to create manual fraud rules.

deviceDataobject

Object containing device data information.

collectionReferencestring[ 30 .. 128 ] characters^[A-Za-z0-9_-]*$

Use the sessionId specified in the ThreatMetrix Device Data Collection to link this data to the assessment.

ipAddressstringnon-empty

A unique identifier for your customer's physical location that can be used in a fraud assessment. Must be in IPv4 format.

Assessment responses

Best Practice

Access Worldpay returns a WP-CorrelationId in the headers of service responses. We highly recommend you log this. The WP-CorrelationId is used by us to examine individual service requests.

You can see the full response schema in the API Reference.

The response contains the outcome of your assessment request.

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

The outcome is always specific to the fraud assessment. If an exemption is provided the exemption.type and exemption.placement is included in the response.

Linking the FraudSight assessment

To improve future risk assessments we need to know the outcome of the payment authorization.

Next steps

FraudSight testing