Menu

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

Fraud assessment

POST your request to the fraudsight:assessment action link.

Assessment example request

POST https://try.access.worldpay.com/fraudsight/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
    }
  },
  "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"
      }
    },
    "custom": {
      "number1": 1,
      "number2": 2,
      "number3": 3,
      "number4": 4,
      "number5": 5,
      "number6": 6,
      "number7": 7,
      "number8": 8,
      "number9": 9,
      "number10": 10,
      "string1": "text1",
      "string2": "text2",
      "string3": "text3",
      "string4": "text4",
      "string5": "text5",
      "string6": "text6",
      "string7": "text7",
      "string8": "text8",
      "string9": "text9",
      "string10": "text10"
    }
  }
}
{
  "transactionReference": "unique-transactionReference",
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "paymentInstrument": {
      "type": "card/tokenized",
      "href": "https://try.access.worldpay.com/tokens/MTIzNDU2Nzg5MDEyMzQ1Ng"
    },
    "value": {
      "currency": "GBP",
      "amount": 250
    }
  },
  "riskData": {
    "account": {
      "email": "test@test.com",
      "dateOfBirth": "1990-09-09"
    },
    "transaction": {
      "firstName": "John",
      "lastName": "Appleseed",
      "phoneNumber": "00000000000000"
    },
    "shipping": {
      "address": {
        "firstName": "Bob",
        "lastName": "Smith",
        "address1": "Worldpay",
        "address2": "1 Milton Road",
        "address3": "The Science Park",
        "postalCode": "CB4 0WE",
        "city": "Cambridge",
        "state": "Cambridgeshire",
        "countryCode": "GB",
        "phoneNumber": "00000000000000"
      }
    },
    "custom": {
      "number1": 1,
      "number2": 2,
      "number3": 3,
      "number4": 4,
      "number5": 5,
      "number6": 6,
      "number7": 7,
      "number8": 8,
      "number9": 9,
      "number10": 10,
      "string1": "text1",
      "string2": "text2",
      "string3": "text3",
      "string4": "text4",
      "string5": "text5",
      "string6": "text6",
      "string7": "text7",
      "string8": "text8",
      "string9": "text9",
      "string10": "text10"
    }
  }
}
{
  "transactionReference": "unique-transactionReference",
  "merchant": {
    "entity": "default"
  },
  "requestExemption": true,
  "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
    }
  },
  "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"
      }
    },
    "custom": {
      "number1": 1,
      "number2": 2,
      "number3": 3,
      "number4": 4,
      "number5": 5,
      "number6": 6,
      "number7": 7,
      "number8": 8,
      "number9": 9,
      "number10": 10,
      "string1": "text1",
      "string2": "text2",
      "string3": "text3",
      "string4": "text4",
      "string5": "text5",
      "string6": "text6",
      "string7": "text7",
      "string8": "text8",
      "string9": "text9",
      "string10": "text10"
    }
  }
}
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.
requestExemptionTo request anSCA Exemptionas part of the same request.
  • true
  • false
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:

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:

Assessment responses

The response contains the outcome of your assessment request.

Copied!
{
  "outcome": "lowRisk",
  "transactionReference": "123456",
  "score": 44.2,
  "riskProfile": {
    "href": "https://access.worldpay.com/riskprofile/eyJrIjoxLCJkIjoialRBL0FFelBzcnZ"
  }
}
{
  "outcome": "highRisk",
  "transactionReference": "123456",
  "reason": [
    "Recent unexpected card activity"
  ],
  "score": 97.4,
  "riskProfile": {
    "href": "https://access.worldpay.com/riskprofile/eyJrIjoxLCJkIjoialRBL0FFelBzcnZ"
  }
}
{
  "outcome": "review",
  "transactionReference": "123456",
  "reason": [
    "Recent unexpected card activity"
  ],
  "score": 85.5,
  "riskProfile": {
    "href": "https://access.worldpay.com/riskprofile/eyJrIjoxLCJkIjoialRBL0FFelBzcnZ"
  }
}
{
  "outcome": "lowRisk",
  "transactionReference": "123456",
  "score": 44.2,
  "exemption": {
    "placement": "authorization",
    "type": "lowValue"
  },
  "riskProfile": {
    "href": "https://access.worldpay.com/riskprofile/eyJrIjoxLCJkIjoialRBL0FFelBzcnZ"
  }
}
{
  "outcome": "highRisk",
  "transactionReference": "123456",
  "reason": [
    "Recent unexpected card activity"
  ],
  "score": 97.4,
  "exemption": {
    "placement": "authorization",
    "type": "lowValue"
  },
  "riskProfile": {
    "href": "https://access.worldpay.com/riskprofile/eyJrIjoxLCJkIjoialRBL0FFelBzcnZ"
  }
}
{
  "outcome": "review",
  "transactionReference": "123456",
  "reason": [
    "Recent unexpected card activity"
  ],
  "score": 85.5,
  "exemption": {
    "placement": "authorization",
    "type": "lowValue"
  },
  "riskProfile": {
    "href": "https://access.worldpay.com/riskprofile/eyJrIjoxLCJkIjoialRBL0FFelBzcnZ"
  }
}

Note: 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.

ParameterDescription
outcomeThe recommendation from FraudSight:
  • lowRisk - proceed with payment
  • highRisk - do not proceed
  • review - manual review required
To understand more about the outcomes and how to reproduce them, seeFraudSight testing.
reasonShort description of the reason for the outcome:
  • 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
A reason can be returned for any 'outcome', even lowRisk.
scorePercentage 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.
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 you can use in the payment authorization request that represents the outcome of the fraud assessment and exemption. Used to:
  • Apply the exemption (if provided)
  • Update the data model so future assessments are more accurate

Next steps

FraudSight testing