Last Updated: 17 December 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:
- testing (try) https://try.access.worldpay.com/fraudsight/assessment
- live https://access.worldpay.com/fraudsight/assessment
- Payload
- curl
- Python
- Java
- Node.js
- Go
- PHP
- Ruby
- C#
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
A unique reference for authentication. For example, e-commerce order code.
An object that contains information about the merchant and API level configuration.
Used to route the request in Access Worldpay, created as part of on-boarding.
The object that contains all the payment information related to the authentication request.
An object that contains information about the value of the assessment.
An object that contains the card details or token location.
Whether to request an SCA Exemption as part of the same request.
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.
An object that holds risk related information that might help in improving the accuracy of fraud assessment.
Object containing all customer account related risk data.
Object containing all customer transaction related risk data.
Object containing all data related to how the order is shipped.
Additional values specific to your order that can be used to create manual fraud rules.
Object containing device data information.
Use the sessionId specified in the ThreatMetrix Device Data Collection to link this data to the assessment.
A unique identifier for your customer's physical location that can be used in a fraud assessment. Must be in IPv4 format.
Assessment responses
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" } }
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.
The outcome of the fraudsight assessment request. To understand more about the outcomes and how to reproduce them, see FraudSight testing.
A unique reference for assessment that was passed in the request.
An object that holds the risk profile link.
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.
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.
Short description of the reason for the outcome. A reason can be returned for any 'outcome', even lowRisk
- 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
An object that holds information about the exemption if it is granted.
Indicates whether the exemption is provided to be placed in a payment authorization request or 3DS authentication request.
Note: Only placement 'authorization' will be configured to be returned for now until Access 3DS supports exemption placement
| Value | Description |
|---|---|
| authorization | Apply the exemption in the payment authorization |
The type of exemption to apply.
| Enum Value | Description |
|---|---|
| lowValue | Apply a lowValue exemption |
| 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 using Access Payments apply the
riskProfileprovided to the payment authorization request.If using another payment provider use the FraudSight update resources.
Next steps