Last Updated: 15 February 2023 | 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:

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
      "entity": "MindPalaceLtd"
  },
  "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"
    }
  }
}
ParameterRequiredDescription
transactionReferenceA reference for the assessment. For example, e-commerce order code.
merchant.entityUsed to route the assessment request in Access Worldpay, created as part of on-boarding.
requestExemptionTo request an SCA Exemption as part of the same request.
  • true
  • false
instructionThe object that contains all the payment information related to the assessment request.
instruction.paymentInstrumentAn object that contains the card details or token location.
paymentInstrument.typeAn identifier for the paymentInstrument being used.

type : card/front type : card/tokenized
paymentInstrument.billingAddressAn object containing the billing address information. If included you must send at least:
instruction.valueAn object that contains information about the value of the order.
value.currencyThe three digit currency code.
See list of supported currencies.
value.amountThe order amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50. You can find the relevant exponent in our currency table.
The amount used in the assessment request must match the payment amount in the access payments request when applying the riskProfile.
deviceData.collectionReferenceUse the sessionId specified in the ThreatMetrix Device Data Collection to link this data to the assessment.
Note
If no value is provided the assessment is still performed but will not benefit from additional risk analysis or any manual rules (e.g. location) based on it.
deviceData.ipAddressA unique identifier for your customer's physical location that can be used in a fraud assessment. Must be in IPv4 format. E.g. 192.0.0.0

Additional fields in Assessment request

We recommend providing this data, if you have it, as it improves the accuracy of the fraud assessment.

There are four riskData objects you can include in your request:

Account

Descriptions of your additional account riskData parameters:

ParameterMandatoryDescription
accountObject containing all customer account related risk data.
account.emailThe customer's email address.
account.dateOfBirthThe customer's date of birth.
account.shopperIdA unique identifier for the customer. Use it to create manual fraud rules and identify your customers.
Transaction

Descriptions of your additional transaction riskData parameters:

ParameterRequiredDescription
transactionObject containing all customer transaction related risk data.
transaction.firstNameCustomer's first name.
transaction.lastNameCustomer's last name.
transaction.phoneNumberCustomer's phone number.
Shipping

Descriptions of your additional shipping riskData parameters:

ParameterRequiredDescription
shippingObject containing all data related to how the order is shipped.
shipping.firstNameFirst name used on the shipping address
shipping.lastNameLast name used on the shipping address
shipping.addressAn object containing the shipping address information. If included you must send at least:
Custom

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

ParameterRequiredDescription
customObject containing all data that can be used to configure manual fraud rules
custom.string1-99 available slots for custom string values to be used to configure manual fraud rules
custom.number1-99 available slots for custom number values to be used to configure manual fraud rules

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.

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.

ParameterDescription
outcomeThe recommendation from FraudSight:
  • lowRisk - proceed with payment
  • highRisk - do not proceed
  • review - manual review required
To understand more about the outcomes and how to reproduce them, see FraudSight testing.
reasonShort description of the reason for the outcome:
  • 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 behaviour for card
A reason can be returned for any 'outcome', even lowRisk.
scorePercentage 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.
exemption.placement
  • authorization - apply exemption to payment authorization
  • authentication - apply exemption to 3DS authentication
Info
Only placement 'authorization' will be configured to be returned for now until Access 3DS supports exemption placement
exemption.typeThe type of exemption to apply
  • lowRisk - Apply low risk exemption
  • lowValue - Apply low value exemption
riskProfile.hrefA resource you can use in the payment authorization request that represents the outcome of the fraud assessment and exemption. Used to:
  • Apply the exemption (if provided)
  • Update the data model so future assessments are more accurate

Linking the FraudSight assessment

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

If using Access Payments apply the riskProfile provided to the payment authorization request.

If using another payment provider use the FraudSight update resources.

Next steps


FraudSight testing