Last Updated: 20 September 2023 | Change Log

Exemption Assessment

POST your request to the exemptions:assess action link.

Assessment example request

POST https://try.access.worldpay.com/exemptions/assessment

Risk assessment request body:

Card
Token

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
      "entity": "MindPalaceLtd"
  },
  "doNotApplyExemption": false, 
  "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"
  },
  "riskData": {
    "account": {
      "email": "sherlock.holmes@example.com",
      "dateOfBirth": "1990-09-09"
    },
    "transaction": {
      "firstName": "Sherlock",
      "lastName": "Holmes",
      "phoneNumber": "00000000000000"
    },
    "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"
      }
    }
  }
}

Parameter	Required	Description
`transactionReference`	✅	A reference for the assessment. For example, e-commerce order code.
`merchant.entity`	✅	Used to route the assessment request in Access Worldpay, created as part of on-boarding.
`doNotApplyExemption`	❌	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.
`instruction`	✅	The object that contains all the payment information related to the assessment request.
`instruction.paymentInstrument`	✅	An object that contains the card details or token location.
`paymentInstrument.type`	✅	An identifier for the `paymentInstrument` being used. `type` : `card/front` See assessment (card) above `type` : `card/tokenized` See assessment(token) above
`paymentInstrument.billingAddress`	❌	An object containing the billing address information. If included you must send at least: `address1` `city` `countryCode` `postalCode`
`instruction.value`	✅	An object that contains information about the value of the order.
`value.currency`	✅	The three digit currency code. See list of supported currencies.
`value.amount`	✅	The 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.collectionReference`	❌	Use 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.

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:

Parameter	Mandatory	Description
`account`	❌	Object containing all customer account related risk data.
`account.email`	❌	The customer's email address.
`account.dateOfBirth`	❌	The customer's date of birth.
`account.shopperId`	❌	A unique identifier for the customer. Use it to create manual fraud rules and identify your customers.

Transaction

Descriptions of your additional transaction riskData parameters:

Parameter	Required	Description
`transaction`	❌	Object containing all customer transaction related risk data.
`transaction.firstName`	❌	Customer's first name.
`transaction.lastName`	❌	Customer's last name.
`transaction.phoneNumber`	❌	Customer's phone number.

Shipping

Descriptions of your additional shipping riskData parameters:

Parameter	Required	Description
`shipping`	❌	Object containing all data related to how the order is shipped.
`shipping.firstName`	❌	First name used on the shipping address
`shipping.lastName`	❌	Last name used on the shipping address
`shipping.address`	❌	An object containing the shipping address information. If included you must send at least: `address1` `city` `countryCode` `postalCode`

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.

Exemption in Authorization (Payment)
No Exemption

{
  "outcome": "exemption",
  "transactionReference": "Memory265-13/08/1876",
  "exemption": {
    "placement": "authorization",
    "type": "lowValue"
  },
  "riskProfile": {
    "href": "https://access.worldpay.com/riskprofile/eyJrIjoxLCJkIjoialRBL0FFelBzcnZ"
  }
}

Parameter	Description
`outcome`	The recommendation from exemptions: `exemption` - exemption provided, proceed with payment or authentication (based on placement recommendation) `noExemption` - exemption not provided To understand more about the `outcomes` and how to reproduce them, see Exemptions testing.
`exemption.placement`	`authorization` - apply exemption to payment authorization `authentication` - apply exemption to 3DS authentication Note: Only placement 'authorization' will be configured to be returned for now until Access 3DS supports exemption placement
`exemption.type`	The type of exemption to apply `lowRisk` - Apply low risk exemption `lowValue` - Apply low value exemption
`riskProfile.href`	A resource to be used in the payment authorisation request that represents the outcome of exemption assessment. Used to: Apply the exemption (if provided) Update the data model so future assessments are more accurate

Applying the Exemption

Apply the riskProfile provided to the payment authorization request. This performs two functions:

Applies the exemption to the payment request
Allows the data model to learn from the outcome, improving future assessment requests.

Even if no exemption is provided you should apply the riskProfile to the payment request.

Soft decline

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

Next steps

Exemptions testing