Unfortunately, this feature is not supported on mobile devices. For the best experience, please use a computer.

FraudSight

FraudSight (v1)

Request a risk assessment

Download OpenAPI description

openapi.json

openapi.yaml

Overview

License Worldpay

Servers

testing (try)

https://try.access.worldpay.com/

live

https://access.worldpay.com/

Fraud assessment

Request

Request a risk assessment

Headers

Content-Typestringrequired

Example:

application/vnd.worldpay.fraudsight-v1.hal+json

Acceptstringrequired

Example:

application/vnd.worldpay.fraudsight-v1.hal+json

Bodyapplication/vnd.worldpay.fraudsight-v1.hal+json

transactionReferencestring[ 1 .. 64 ] characters^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$required

A unique reference for authentication. For example, e-commerce order code.

merchantobjectrequired

An object that contains information about the merchant and API level configuration.

entitystring[ 1 .. 64 ] characters^[A-Za-z0-9 ]*$required

Used to route the request in Access Worldpay, created as part of on-boarding.

instructionobjectrequired

The object that contains all the payment information related to the authentication request.

valueobjectrequired

An object that contains information about the value of the assessment.

amountinteger[ 0 .. 99999999999 ]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. 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.

currencystring= 3 characters^[A-Z]{3}$required

The three digit currency code. See list of supported currencies

paymentInstrumentanyrequired

An object that contains the card details or token location.

typestring(card/front)required

An identifier for the paymentInstrument being used.

Discriminator

cardExpiryDateobjectrequired

Object containing card expiry information

cardNumberstring[ 10 .. 19 ] characters^[0-9]*$required

Clear card number (PAN)

billingAddressobject

An object containing the billing address information.

cardHolderNamestring[ 1 .. 255 ] charactersrequired

The name on the customer's card.

requestExemptionboolean

Whether to request an SCA Exemption as part of the same request.

doNotApplyExemptionboolean

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.

riskDataobject

An object that holds risk related information that might help in improving the accuracy of fraud assessment.

accountobject

Object containing all customer account related risk data.

shopperIdstring[ 1 .. 128 ] characters

A unique identifier for the customer. Use it to create manual fraud rules and identify your customers.

emailstring[ 3 .. 254 ] characters^.+@.+$

The customer's email address.

dateOfBirthstring(date)[ 1 .. 20 ] characters

The customer's date of birth.

transactionobject

Object containing all customer transaction related risk data.

firstNamestring[ 1 .. 22 ] characters^[a-zA-Z]*$

Customer's first name.

lastNamestring[ 1 .. 22 ] characters^[a-zA-Z]*$

Customer's last name.

phoneNumberstring[ 4 .. 20 ] characters^[0-9]*$

Customer's phone number.

shippingobject

Object containing all data related to how the order is shipped.

firstNamestring[ 1 .. 22 ] characters^[a-zA-Z]*$

First name of the shipping recipient.

lastNamestring[ 1 .. 22 ] characters^[a-zA-Z]*$

Last name of the shipping recipient.

addressobject

An object containing the shipping address information.

customobject

Additional values specific to your order that can be used to create manual fraud rules.

number1integer[ -2147483648 .. 2147483647 ]

Custom number field 1

number2integer[ -2147483648 .. 2147483647 ]

Custom number field 2

number3integer[ -2147483648 .. 2147483647 ]

Custom number field 3

number4integer[ -2147483648 .. 2147483647 ]

Custom number field 4

number5integer[ -2147483648 .. 2147483647 ]

Custom number field 5

number6integer[ -2147483648 .. 2147483647 ]

Custom number field 6

number7integer[ -2147483648 .. 2147483647 ]

Custom number field 7

number8integer[ -2147483648 .. 2147483647 ]

Custom number field 8

number9integer[ -2147483648 .. 2147483647 ]

Custom number field 9

number10integer[ -2147483648 .. 2147483647 ]

Custom number field 10

string1string[ 1 .. 100 ] characters

Custom string field 1

string2string[ 1 .. 100 ] characters

Custom string field 2

string3string[ 1 .. 100 ] characters

Custom string field 3

string4string[ 1 .. 100 ] characters

Custom string field 4

string5string[ 1 .. 100 ] characters

Custom string field 5

string6string[ 1 .. 100 ] characters

Custom string field 6

string7string[ 1 .. 100 ] characters

Custom string field 7

string8string[ 1 .. 100 ] characters

Custom string field 8

string9string[ 1 .. 100 ] characters

Custom string field 9

string10string[ 1 .. 100 ] characters

Custom string field 10

deviceDataobject

Object containing device data information.

collectionReferencestring[ 30 .. 128 ] characters^[A-Za-z0-9_-]*$

Use the sessionId specified in the ThreatMetrix Device Data Collection to link this data to the assessment.

ipAddressstringnon-empty

A unique identifier for your customer's physical location that can be used in a fraud assessment. Must be in IPv4 format.

application/vnd.worldpay.fraudsight-v1.hal+json

Assessment using the card instrument

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "default"
  },
  "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",
    "ipAddress": "192.0.0.0"
  },
  "riskData": {
    "account": {
      "email": "sherlock.holmes@example.com",
      "dateOfBirth": "1854-01-06",
      "shopperId": "id123"
    },
    "transaction": {
      "firstName": "Sherlock",
      "lastName": "Holmes",
      "phoneNumber": "02031234321"
    },
    "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"
      }
    },
    "custom": {
      "number1": 1,
      "number2": 2,
      "number3": 3,
      "number4": 4,
      "number5": 5,
      "number6": 6,
      "number7": 7,
      "number8": 8,
      "number9": 9,
      "string1": "text1",
      "string2": "text2",
      "string3": "text3",
      "string4": "text4",
      "string5": "text5",
      "string6": "text6",
      "string7": "text7",
      "string8": "text8",
      "string9": "text9"
    }
  }
}

Responses

The authentication has been created

Bodyapplication/vnd.worldpay.fraudsight-v1.hal+json

outcomestringrequired

The outcome of the fraudsight assessment request. To understand more about the outcomes and how to reproduce them, see FraudSight testing.

Enum"lowRisk""highRisk""review"

transactionReferencestring[ 1 .. 64 ] charactersrequired

A unique reference for assessment that was passed in the request.

riskProfileobjectrequired

An object that holds the risk profile link.

hrefstring(uri)[ 30 .. 1024 ] charactersrequired

A resource to apply in either a card payment request OR additional fraudsight requests. 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.

scorenumber[ 0 .. 100 ]

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.

reasonArray of strings<= 10 items

Short description of the reason for the outcome. A reason can be returned for any 'outcome', even lowRisk

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

exemptionobject

An object that holds information about the exemption if it is granted.

placementstringrequired

Whether the exemption is provided to be placed in a payment authorization request or 3DS authentication request. Note: Only placement 'authorization' will be returned for now until Access 3DS supports in authentication exemptions.

Enum"authorization""authentication"

typestringrequired

The type of exemption to apply.

Enum"lowValue""lowRisk"

Response

application/vnd.worldpay.fraudsight-v1.hal+json

low risk outcome, proceed with the payment

{
  "outcome": "lowRisk",
  "transactionReference": "123456",
  "score": 44.2,
  "riskProfile": {
    "href": "https://access.worldpay.com/riskprofile/eyJrIjoxLCJkIjoialRBL0FFelBzcnZ"
  }
}

Update

Operations

FraudSight (v1)

Fraud assessment

Request

Responses

Was this helpful?

Update