# Fraud assessment

Request a risk assessment

Endpoint: POST /fraudsight/assessment
Version: v1
Security: BasicAuth

## Header parameters:

  - `Content-Type` (string, required)
    Example: "application/vnd.worldpay.fraudsight-v1.hal+json"

  - `Accept` (string, required)
    Example: "application/vnd.worldpay.fraudsight-v1.hal+json"

## Request fields (application/vnd.worldpay.fraudsight-v1.hal+json):

  - `transactionReference` (string, required)
    A unique reference for authentication. For example, e-commerce order code.

  - `merchant` (object, required)
    An object that contains information about the merchant and API level configuration.

  - `merchant.entity` (string, required)
    Used to route the request in Access Worldpay, created as part of on-boarding.

  - `exemption` (object)
    An object that contains information about the type and placement of the requested exemption.

  - `exemption.capability` (string, required)
    Indicates whether the exemption requested from us can return a placement of authorization (payment) and/or authentication (3DS).
    Enum: "authorizationOnly", "authenticationOnly", "authorizationAndAuthentication"

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

  - `exemption.request.placement` (string)
    Defines where the exemption is being requested.
    Enum: "optimized", "authorization", "authentication"

  - `exemption.request.type` (string)
    Defines which type of exemption is being requested.
    Enum: "optimized", "lowValue", "lowRisk"

  - `instruction` (object, required)
    The object that contains all the payment information related to the authentication request.

  - `instruction.value` (object, required)
    An object that contains information about the value of the assessment.

  - `instruction.value.amount` (integer, required)
    The authentication 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](/products/reference/supported-countries-currencies#iso-currency-codes). The assessment amount should be equal to the authorization amount. We recommend you delay assessment until the amount is known, or ensure it's greater than the total transaction amount.

  - `instruction.value.currency` (string, required)
    The three digit currency code. See list of [supported currencies](/products/reference/supported-countries-currencies#iso-currency-codes).

  - `instruction.paymentInstrument` (any, required)
    An object that contains the card details or token location.

  - `doNotApplyExemption` (boolean)
    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.

  - `riskData` (object)
    An object that holds risk related information that might help in improving the accuracy of fraud assessment.

  - `riskData.account` (object)
    Object containing all customer account related risk data.

  - `riskData.account.shopperId` (string)
    A unique identifier for the customer. Use it to create manual fraud rules and identify your customers.

  - `riskData.account.email` (string)
    The customer's email address.

  - `riskData.account.dateOfBirth` (string)
    The customer's date of birth.

  - `riskData.transaction` (object)
    Object containing all customer transaction related risk data.

  - `riskData.transaction.firstName` (string)
    Customer's first name.

  - `riskData.transaction.lastName` (string)
    Customer's last name.

  - `riskData.transaction.phoneNumber` (string)
    Customer's phone number.

  - `riskData.shipping` (object)
    Object containing all data related to how the order is shipped.

  - `riskData.shipping.firstName` (string)
    First name of the shipping recipient.

  - `riskData.shipping.lastName` (string)
    Last name of the shipping recipient.

  - `riskData.shipping.address` (object)
    An object containing the shipping address information.

  - `riskData.shipping.address.city` (string, required)
    Shipping address city.

  - `riskData.shipping.address.address1` (string, required)
    Shipping address line 1.

  - `riskData.shipping.address.postalCode` (string, required)
    Postcode of shipping address.

  - `riskData.shipping.address.countryCode` (string, required)
    Shipping address country code.

  - `riskData.shipping.address.state` (string)
    Shipping address state. Should only be provided following the ISO-3611-2 two-character sub division (e.g.“CA” for California).

  - `riskData.shipping.address.address2` (string)
    Shipping address line 2.

  - `riskData.shipping.address.address3` (string)
    Shipping address line 3.

  - `riskData.shipping.address.phoneNumber` (string)
    Shipping recipient's phone number.

  - `riskData.custom` (object)
    Additional values specific to your order that can be used to create manual fraud rules.

  - `riskData.custom.number1` (integer)
    Custom number field 1.

  - `riskData.custom.number2` (integer)
    Custom number field 2.

  - `riskData.custom.number3` (integer)
    Custom number field 3.

  - `riskData.custom.number4` (integer)
    Custom number field 4.

  - `riskData.custom.number5` (integer)
    Custom number field 5.

  - `riskData.custom.number6` (integer)
    Custom number field 6.

  - `riskData.custom.number7` (integer)
    Custom number field 7.

  - `riskData.custom.number8` (integer)
    Custom number field 8.

  - `riskData.custom.number9` (integer)
    Custom number field 9.

  - `riskData.custom.number10` (integer)
    Custom number field 10.

  - `riskData.custom.string1` (string)
    Custom string field 1.

  - `riskData.custom.string2` (string)
    Custom string field 2.

  - `riskData.custom.string3` (string)
    Custom string field 3.

  - `riskData.custom.string4` (string)
    Custom string field 4.

  - `riskData.custom.string5` (string)
    Custom string field 5

  - `riskData.custom.string6` (string)
    Custom string field 6.

  - `riskData.custom.string7` (string)
    Custom string field 7.

  - `riskData.custom.string8` (string)
    Custom string field 8.

  - `riskData.custom.string9` (string)
    Custom string field 9.

  - `riskData.custom.string10` (string)
    Custom string field 10.

  - `deviceData` (object)
    Object containing device data information.

  - `deviceData.collectionReference` (string)
    Use the sessionId specified in the ThreatMetrix Device Data Collection to link this data to the assessment.

  - `deviceData.ipAddress` (string)
    A unique identifier for your customer's physical location that can be used in a fraud assessment. Must be in IPv4 or IPv6 format.

  - `requestExemption` (boolean)
    __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

## Response 200 fields (application/vnd.worldpay.fraudsight-v1.hal+json):

  - `outcome` (string, required)
    The outcome of the fraudsight assessment request. To understand more about the outcomes and how to reproduce them, see [FraudSight testing](/products/fraudsight/testing).
    Enum: "lowRisk", "highRisk", "review"

  - `transactionReference` (string, required)
    A unique reference for assessment that was passed in the request.

  - `riskProfile` (object, required)
    An object that holds the risk profile link.

  - `riskProfile.href` (string, required)
    A resource to apply in either a [card payment request](/products/card-payments/authorize-a-payment#fraudsight) __OR__ [additional fraudsight requests](/products/fraudsight/update). 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.

  - `score` (number)
    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.

  - `reason` (array)
    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

  - `exemption` (object)
    An object that holds information about the exemption, if it is granted.

  - `exemption.placement` (string, required)
    Indicates whether the exemption is provided to be placed in a payment authorization request or 3DS authentication request.
    Enum: "authorization", "authentication"

  - `exemption.type` (string, required)
    The type of exemption to apply.
    Enum: "lowValue", "lowRisk"

## Response 400 fields (application/vnd.worldpay.fraudsight-v1.hal+json):

  - `message` (string, required)
    The error description message.

  - `errorName` (string, required)
    The unique error name.

  - `validationErrors` (array)
    Object containing details of validation errors occurred

  - `validationErrors.errorName` (string, required)
    Unique name of the validation error.

  - `validationErrors.jsonPath` (string, required)
    Location of the field in request body for which the error occurred.

  - `validationErrors.message` (string, required)
    Error description message.

## Response 401 fields (application/vnd.worldpay.fraudsight-v1.hal+json):

  - `message` (string, required)
    The error description message.

  - `errorName` (string, required)
    The unique error name.

## Response 503 fields (application/vnd.worldpay.fraudsight-v1.hal+json):

  - `message` (string, required)
    The error description message.

  - `errorName` (string, required)
    The unique error name.