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

FraudSight (v1)

Request a risk assessment

Download OpenAPI description
Overview
License Worldpay
Languages
Servers
testing (try)
https://try.access.worldpay.com/
live
https://access.worldpay.com/

Fraud assessment

Request

Request a risk assessment

Headers
Content-Typestring
Example:

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

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

amountinteger[ 0 .. 999999999 ]required

The authentication amount. This is a whole number with an exponent.

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

The three digit currency code.

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

monthinteger[ 1 .. 12 ]required

Card expiry month

yearinteger[ 1 .. 9999 ]required

Card expiry year

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.

deviceDataobject

Object containing device data information.

curl -i -X POST \
  -u undefined:undefined \
  https://try.access.worldpay.com/fraudsight/assessment \
  -H 'Accept: application/vnd.worldpay.fraudsight-v1.hal+json' \
  -H 'Content-Type: application/vnd.worldpay.fraudsight-v1.hal+json' \
  -d '{
    "transactionReference": "reference",
    "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": {
        "string1": "text1",
        "string2": "text2",
        "string3": "text3",
        "string4": "text4",
        "string5": "text5",
        "string6": "text6",
        "string7": "text7",
        "string8": "text8",
        "string9": "text9",
        "string10": "text10",
        "number1": 1,
        "number2": 2,
        "number3": 3,
        "number4": 4,
        "number5": 5,
        "number6": 6,
        "number7": 7,
        "number8": 8,
        "number9": 9,
        "number10": 10
      }
    }
  }'

Responses

The authentication has been created

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

The outcome of the fraudsight assessment request.

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 you can use in the payment authorization request that represents the outcome of the fraud assessment and exemption.

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.

exemptionobject

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

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

An assessment request using a cardPaymentInstrument where review fraud assessment is returned

{ "outcome": "review", "transactionReference": "reference", "reason": [ "Fraud suspicion" ], "score": 50.5, "riskProfile": { "href": "https://access.worldpay.com/riskProfile/ewogICJ2IiA6IDEsCiAgImsiIDogMSwKICAiZCIgOiAiU1BtQ0VmZXl3WmlQeFJjVkZqQmExZkpyUlBLYkNjRUtyRVlkL25KY1lYeXBQcDVZTmUrTmVGMjRzRjEyb2VGTFRtSkhtcDMwaSsyZE5uOGl3bURVSXMzaDUyNk5jNVNlSU9Ec0dUVzAwYlNneFdVSlpOeEdHZk9GRGZuU0pNYXl6N2Faek9Qc1JFL1Iva01NYkxpNHNiM1d3MlVxSkk1VVRFNXlPYnM2NUpmZGxqWlBkc0FqaHV4cnl0OHFISEgvTi82d1ZTazJwb2t0RnFON2F6Q2RsZkZvdlVGMVl4ZnAvaGlUME1wdVZ1dTFKc2twa1k1OERubnVjNkRVaXphWnhHVUc5SVFNOERkMjNleEhSSzQ2bWpIRk5xY2QvOEFHWDJrcGd3Vk9KeGJ4NFNOUGRNc2NUM0lJdkpQTXBpTHQwWHFMbEUzQmQwOWdPSnJ1R0kyUlIwREdWZ2t6OUFzNjVmaWEwRmU3L2MvZFdBUHI1RHhmTzNDK0ZQWGNJck8rQ28zRDdnUW1mbGZHbzRtR25VTHZnZjFjKzNoSm5xNXpYR2ZoRWh1NWUzM0s3Um0zWVRvTENkR2YvNi9aa2Zyd3JZYzZmWW1HVUpkZjN2VjRJNVB1TkE9PSIKfQ" } }

Update

Operations

Provide details of the payment outcome

Request

Provide payment outcome information

Note: This should only be provided if using a different gateway for the payment

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.

riskProfilestring(uri)[ 39 .. 2048 ] charactersrequired

Represents the outcome of the original fraud assessment. Used to link subsequent Fraud related requests.

paymentOutcomestringrequired

Outcome of the payment authorization.

Enum"authorized""refused"
cvcResultstring

Outcome of the CVC check.

Enum"matched""not_matched""not_checked""not_supplied"
avsResultobject

Object containing outcome of the address verification service check.

authenticationobject

Include this object if 3DS authentication details were part of the payment.

curl -i -X POST \
  -u undefined:undefined \
  https://try.access.worldpay.com/fraudsight/update/payment \
  -H 'Content-Type: application/vnd.worldpay.fraudsight-v1.hal+json' \
  -d '{
    "transactionReference": "unique-transactionReference",
    "merchant": {
      "entity": "default"
    },
    "riskProfile": "https://try.access.worldpay.com/riskprofile/ewogICJ2IiA6IDEsCiAgImsiIDogMSwKICAiZCIgOiAieWdmQjlEdkZPSGd5OFZGRktwK05pZDhnUW9VelVySmNrRDMzRFhvTXA0bEhPOTZJK0t6aUUyR1ZvTjFSazNtUEhGVFJ3d0NwT0dITThOVnluMDNyTGtwbUVSVExWM1RLbC9td2RoOVZzWFNpbG9zVktUUkRrNVMwRllSeU5hMXZOYjFYWW1TSGgyRTc4SGdWaGwzV2FnWHNjUVQwYlFMdmc1UXN5VUF5Mk9yckRGWlJabzRMVlZ2eXBsU1U3ZjVYMXdFdjBoV3FHVXhYV3dpTitRYWZmMXlGZ0laN2Nkb0pIMG5EanNCZmdDcDd5MjM4U0ZNR2I2SDBTVUx0eE9vY3JBODk0N1JUaGU2NGlPNURONDNKS3c9PSIKfQ",
    "paymentOutcome": "authorized",
    "cvcResult": "matched",
    "avsResult": {
      "address": "matched",
      "postcode": "matched"
    },
    "authentication": {
      "version": "2.1.0",
      "eci": "05"
    }
  }'

Responses

Successful update with payment information

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

Payment outcome details are provided to the fraudsight service

{}

Provide details of a payment that resulted in fraud

Request

Provide payment fraud information

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.

riskProfilestring(uri)[ 39 .. 2048 ] charactersrequired

Represents the outcome of the original fraud assessment. Used to link subsequent Fraud related requests.

sourcestringrequired

Source format of confirmed fraud cases.

Enum"SAFE""TC40"
sourceDatestring(date-time)<= 20 charactersrequired

Date/time of source fraud file (TC40/SAFE).

acquirerReferencestring[ 1 .. 128 ] charactersrequired

Acquirer Reference Number (ARN) - unique value assigned to a credit or debit card transaction.

fraudReasonCodestring[ 1 .. 16 ] charactersrequired

Visa and Mastercard reason codes.

valueobjectrequired

Object containing information about value of the transaction.

amountinteger[ 0 .. 999999999 ]required

The payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50.

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

The three digit currency code.

curl -i -X POST \
  -u undefined:undefined \
  https://try.access.worldpay.com/fraudsight/update/fraud \
  -H 'Content-Type: application/vnd.worldpay.fraudsight-v1.hal+json' \
  -d '{
    "transactionReference": "unique-transactionReference",
    "merchant": {
      "entity": "default"
    },
    "riskProfile": "https://try.access.worldpay.com/riskprofile/ewogICJ2IiA6IDEsCiAgImsiIDogMSwKICAiZCIgOiAieWdmQjlEdkZPSGd5OFZGRktwK05pZDhnUW9VelVySmNrRDMzRFhvTXA0bEhPOTZJK0t6aUUyR1ZvTjFSazNtUEhGVFJ3d0NwT0dITThOVnluMDNyTGtwbUVSVExWM1RLbC9td2RoOVZzWFNpbG9zVktUUkRrNVMwRllSeU5hMXZOYjFYWW1TSGgyRTc4SGdWaGwzV2FnWHNjUVQwYlFMdmc1UXN5VUF5Mk9yckRGWlJabzRMVlZ2eXBsU1U3ZjVYMXdFdjBoV3FHVXhYV3dpTitRYWZmMXlGZ0laN2Nkb0pIMG5EanNCZmdDcDd5MjM4U0ZNR2I2SDBTVUx0eE9vY3JBODk0N1JUaGU2NGlPNURONDNKS3c9PSIKfQ",
    "source": "TC40",
    "sourceDate": "2020-12-27T00:00:00Z",
    "acquirerReference": "02691780344910023278387",
    "fraudReasonCode": "5",
    "value": {
      "currency": "GBP",
      "amount": 250
    }
  }'

Responses

Successful update with fraud information

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

Provide details of a payment that resulted in fraud

{}

Provide details of a payment that resulted in a chargeback

Request

Provide payment chargeback information

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.

riskProfilestring(uri)[ 39 .. 2048 ] charactersrequired

Represents the outcome of the original fraud assessment. Used to link subsequent fraud related requests.

sourceDatestring(date-time)<= 20 charactersrequired

Date/time of source fraud file (TC40/SAFE).

acquirerReferencestring[ 1 .. 128 ] charactersrequired

Acquirer Reference Number (ARN) - unique value assigned to a credit or debit card transaction.

chargebackReasonCodestring[ 2 .. 4 ] charactersrequired

Visa and Mastercard reason codes.

chargebackCaseReferencestring[ 1 .. 64 ] charactersrequired

Case reference for a specific chargeback.

chargebackValueobjectrequired

Object containing value of the chargeback transaction.

amountinteger[ 0 .. 999999999 ]required

The chargeback amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50.

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

The three digit currency code.

curl -i -X POST \
  -u undefined:undefined \
  https://try.access.worldpay.com/fraudsight/update/chargeback \
  -H 'Content-Type: application/vnd.worldpay.fraudsight-v1.hal+json' \
  -d '{
    "transactionReference": "unique-transactionReference",
    "merchant": {
      "entity": "default"
    },
    "riskProfile": "https://try.access.worldpay.com/riskprofile/ewogICJ2IiA6IDEsCiAgImsiIDogMSwKICAiZCIgOiAieWdmQjlEdkZPSGd5OFZGRktwK05pZDhnUW9VelVySmNrRDMzRFhvTXA0bEhPOTZJK0t6aUUyR1ZvTjFSazNtUEhGVFJ3d0NwT0dITThOVnluMDNyTGtwbUVSVExWM1RLbC9td2RoOVZzWFNpbG9zVktUUkRrNVMwRllSeU5hMXZOYjFYWW1TSGgyRTc4SGdWaGwzV2FnWHNjUVQwYlFMdmc1UXN5VUF5Mk9yckRGWlJabzRMVlZ2eXBsU1U3ZjVYMXdFdjBoV3FHVXhYV3dpTitRYWZmMXlGZ0laN2Nkb0pIMG5EanNCZmdDcDd5MjM4U0ZNR2I2SDBTVUx0eE9vY3JBODk0N1JUaGU2NGlPNURONDNKS3c9PSIKfQ",
    "sourceDate": "2022-01-27T00:00:00Z",
    "acquirerReference": "02691780344910023278387",
    "chargebackReasonCode": "31",
    "chargebackCaseReference": "123456",
    "chargebackValue": {
      "currency": "GBP",
      "amount": 250
    }
  }'

Responses

Successful update with chargeback information

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

Provide details of a payment that resulted in a chargeback

{}