# Exemption assessment

Assess for exemption.

Endpoint: POST /exemptions/assessment
Version: 1
Security: BasicAuth

## Header parameters:

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

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

## Request fields (application/vnd.worldpay.exemptions-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. 

_Note: If this object is not used in the request the capability is limited to authorizationOnly_.

  - `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 authentication.

  - `instruction.value.amount` (integer, required)
    The authentication amount. This is a whole number with an exponent.

  - `instruction.value.currency` (string, required)
    The three digit currency code.

  - `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.email` (string)
    The customer's email address.

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

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

  - `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)
    Object containing custom fields

  - `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.

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

  - `outcome` (string, required)
    The outcome of the exemption assessment request.
    Enum: "noExemption", "exemption"

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

  - `riskProfile` (object, required)
    A resource you can use in the payment authorization request that represents the outcome of the exemption assessment. Used to:
- apply the exemption (if provided)
- update the data model so future assessments are more accurate

  - `riskProfile.href` (string, required)
    A link to a resource to be used in the payment authorisation request that represents the outcome of exemption assessment.

  - `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.exemptions-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.exemptions-v1.hal+json):

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

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

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

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

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