Last Updated: 30 September 2025 | 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.

exemptionobject

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

capabilitystringrequired

Indicates whether the exemption requested from us can return a placement of authorization (payment) and/or authentication (3DS).

Enum Value	Description
authorizationOnly	The SCA Exemptions service can only return a `placement` of `authorization`.
authenticationOnly	The SCA Exemptions service can only return a `placement` of `authentication` .
authorizationAndAuthentication	The SCA Exemptions service can return either a `placement` of `authorization` or `authentication`.

requestobject

An object used to control the placement and type of the requested exemption. If not provided, we decide the best placement and type (optimized).

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.

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 or IPv6 format.

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 responses

Best practice

We return 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.

Manual rules - highRisk

When manually created risk assessment rules are triggered, the score is ignored. It is therefore possible to see an assessment with a low score but still with a highRisk outcome.

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

If the exemption object is used in the request:

    {
        "outcome": "lowRisk",
        "transactionReference": "123456",
        "score": 44.2,
        "exemption": {
            "placement": "authorization",
            "type": "lowValue"
        },
        "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.

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.

hrefstring(uri)[ 30 .. 1024 ] charactersrequired

A resource to apply in either a card payment request OR additional fraudsight requests. This represents the outcome of the fraud assessment and exemption. Used to:

apply the SCA exemption (if provided)
update the data model so future risk assessments are more accurate

Warning: Not providing this will significantly harm the accuracy of future assessments.

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.

placementstringrequired

Indicates whether the exemption is provided to be placed in a payment authorization request or 3DS authentication request.

Enum Value	Description
authorization	Apply the exemption in the payment authorization.
authentication	Apply the exemption in the 3DS authentication.

typestringrequired

The type of exemption to apply.

Enum Value	Description
lowValue	Apply a lowValue exemption. (only applicable to a placement in authorization)
lowRisk	Apply a lowRisk exemption.

Linking the FraudSight assessment

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

If your are using our Card Payments API apply the riskProfile provided in the payment authorization request.
If you are using another payment provider use the FraudSight update resources.

Applying the Exemption (if applicable)

This is only a consideration if you're using the exemption object in the request:

If the placement is `authorization`

apply the riskProfile in the payment authorization request

In the event that the exemption is not successful (honoured + authorized) when applied to the payment, the issuer responds with a soft decline (refusal code 65). The next logical step is to proceed with 3DS authentication.

If the placement is `authentication`

set the challenge.preference in the 3DS authentication to noChallengeRequestedTRAPerformed
apply the riskProfile in the payment authorization request

If no exemption is provided

perform 3DS authentication
apply the riskProfile in the payment authorization request. Without this, the data model will not improve over time

Next steps

FraudSight testing