Menu

Note: This API is for preview purposes only and is subject to change.

Exemption assessment

API v1
Coming soon
Change log

POST your request to the exemptions:assess action link.

Assessment example request

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

Risk assessment request body:

Copied!
{
  "transactionReference": "unique-transactionReference",
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "paymentInstrument": {
      "type": "card/front",
      "cardHolderName": "John Appleseed",
      "cardNumber": "4444333322221111",
      "cardExpiryDate": {
        "month": 5,
        "year": 2035
      },
      "billingAddress": {
        "address1": "Worldpay",
        "address2": "1 Milton Road",
        "address3": "The Science Park",
        "postalCode": "CB4 0WE",
        "city": "Cambridge",
        "state": "Cambridgeshire",
        "countryCode": "GB"
      }
    },
    "value": {
      "currency": "GBP",
      "amount": 250
    }
  },
  "deviceData": {
    "collectionReference": "0_4XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX8G6",
  },
  "riskData": {
    "account": {
      "email": "test@test.com",
      "dateOfBirth": "1990-09-09"
    },
    "transaction": {
      "firstName": "John",
      "lastName": "Appleseed",
      "phoneNumber": "00000000000000"
    },
    "shipping": {
      "firstName": "Bob",
      "lastName": "Smith",
      "address": {
        "address1": "Worldpay",
        "address2": "1 Milton Road",
        "address3": "The Science Park",
        "postalCode": "CB4 0WE",
        "city": "Cambridge",
        "state": "Cambridgeshire",
        "countryCode": "GB",
        "phoneNumber": "00000000000000"
      }
    }
  }
}
{
  "transactionReference": "unique-transactionReference",
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "paymentInstrument": {
      "type": "card/tokenized",
      "href": "https://try.access.worldpay.com/tokens/MTIzNDU2Nzg5MDEyMzQ1Ng"
    },
    "value": {
      "currency": "GBP",
      "amount": 250
    }
  },
  "deviceData": {
    "collectionReference": "0_4XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX8G6",
  },
  "riskData": {
    "account": {
      "email": "test@test.com",
      "dateOfBirth": "1990-09-09"
    },
    "transaction": {
      "firstName": "John",
      "lastName": "Appleseed",
      "phoneNumber": "00000000000000"
    },
    "shipping": {
      "firstName": "Bob",
      "lastName": "Smith",
      "address": {
        "address1": "Worldpay",
        "address2": "1 Milton Road",
        "address3": "The Science Park",
        "postalCode": "CB4 0WE",
        "city": "Cambridge",
        "state": "Cambridgeshire",
        "countryCode": "GB",
        "phoneNumber": "00000000000000"
      }
    }
  }
}
ParameterRequiredDescription
transactionReferenceA reference for the assessment. For example, e-commerce order code.
merchant.entityUsed to route the assessment request in Access Worldpay, created as part of on-boarding.
instructionThe object that contains all the payment information related to the assessment request.
instruction.paymentInstrumentAn object that contains the card details or token location.
paymentInstrument.typeAn identifier for the paymentInstrument being used.

type : card/fronttype : card/tokenized
paymentInstrument.billingAddressAn object containing the billing address information. If included you must send at least:
instruction.valueAn object that contains information about the value of the order.
value.currencyThe three digit currency code.
See list ofsupported currencies.
value.amountThe 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 ourcurrency table.
The amount used in the assessment request must match the payment amount in the access payments request when applying the riskProfile.
deviceData.collectionReferenceUse the sessionId specified in the ThreatmatrixDevice Data Collectionto 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 exemption assessment.

There are three riskData objects you can include in your request:

Assessment responses

The response contains the outcome of your assessment request.

Copied!
{
  "outcome": "exemption",
  "transactionReference": "123456",
  "exemption": {
    "placement": "authorization",
    "type": "lowValue"
  },
  "riskProfile": {
    "href": "https://access.worldpay.com/riskprofile/eyJrIjoxLCJkIjoialRBL0FFelBzcnZ"
  }
}
{
  "outcome": "noExemption",
  "transactionReference": "123456",
  "riskProfile": {
    "href": "https://access.worldpay.com/riskprofile/eyJrIjoxLCJkIjoialRBL0FFelBzcnZ"
  }
}
ParameterDescription
outcomeThe 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, seeExemptions 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.typeThe type of exemption to apply
  • lowRisk - Apply low risk exemption
  • lowValue - Apply low value exemption
riskProfile.hrefA 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 thepayment authorizationrequest. 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 with3DS authentication.

Next steps

Exemptions testing