FraudSight (v1)

Request a risk assessment and prevent fraud with this standalone API.

Authentication header

  Authorization: {your_credentials}

Replace {your_credentials} with your base64-encoded Basic Auth username and password given to you by your Implementation Manager.

You must use the Authorization header for any request you send to our FraudSight API.

Accept and Content-Type headers

Content-Type: application/vnd.worldpay.fraudsight-v1.hal+json
Accept: application/vnd.worldpay.fraudsight-v1.hal+json

We use the Accept header to identify which version of our API you are using. You must use the Accept header for any request you send to our FraudSight API.

We require the Content-Type header if the request you're sending includes a request body, and if the HTTP method is a POST or a PUT.

DNS whitelisting

Whitelist the following URLs:

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

Please ensure you use DNS whitelisting, not explicit IP whitelisting. When you make a request within Access Worldpay, you should always cache the response returned.

Download OpenAPI description

openapi.json

openapi.yaml

Servers

testing (try)

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

live

https://access.worldpay.com/

Fraud assessment

Request

Request a risk assessment

Security

BasicAuth

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.

exemptionobject

An object that contains information about the type and placement of the requested exemption.

capabilitystringrequired

Indicates whether the exemption requested from us can return a placement of authorization (payment) and/or authentication (3DS).

Enum Value	Description
authorizationOnly	The SCA Exemptions service can only return a `placement` of `authorization`.
authenticationOnly	The SCA Exemptions service can only return a `placement` of `authentication` .
authorizationAndAuthentication	The SCA Exemptions service can return either a `placement` of `authorization` or `authentication`.

requestobject

An object used to control the placement and type of the requested exemption. If not provided, we decide the best placement and type (optimized).

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.

paymentInstrumentanyrequired

An object that contains the card details or token location.

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.

transactionobject

Object containing all customer transaction related risk data.

shippingobject

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

customobject

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

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 or IPv6 format.

requestExemptionbooleanDeprecated

Deprecated, use the exemption object.

Request an SCA Exemption as part of the same request. Only supports a capability of authorizationOnly.

Note: Not available for paymentInstrument.type card/plain+masked

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. For example:

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 behavior for card

exemptionobject

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

placementstringrequired

Indicates whether the exemption is provided to be placed in a payment authorization request or 3DS authentication request.

Enum Value	Description
authorization	Apply the exemption in the payment authorization.
authentication	Apply the exemption in the 3DS authentication.

typestringrequired

The type of exemption to apply.

Enum Value	Description
lowValue	Apply a lowValue exemption. (only applicable to a placement in authorization)
lowRisk	Apply a lowRisk exemption.

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

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.

Security

BasicAuth

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.

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"

refusalCodestring[ 1 .. 2048 ] characters

The refusal response code from the acquirer.

Example: "5"

refusalDescriptionstring[ 1 .. 2048 ] characters

The description of the 'refusalCode'.

Example: "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.

addressstring

Outcome of the address check.

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

postcodestring

Outcome of the postcode check.

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

authenticationobject

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

versionstring[ 5 .. 10 ] characters^([0-9]{1,3})(\.)([0-9]){1,3}(\.)([0-9]{1,3})...

3DS version used by issuer, e.g. 1.0.2, 2.1.0 or 2.2.0.

ecistring= 2 characters

Electronic Commerce Indicator (ECI). Outcome of the 3DS authentication as applied in the payment.

02 or 05 - Fully Authenticated Transaction
01 or 06 - Attempted Authentication Transaction
00 or 07 - Non 3-D Secure Transaction
Mastercard - 02, 01, 00
Visa - 05, 06, 07
Amex - 05, 06, 07
JCB - 05, 06, 07
Diners - 05, 06, 07

Enum"00""01""02""05""06""07"

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

Authorized payment outcome details are provided to the FraudSight service. This could be from any Worldpay or 3rd party payment provider.

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "default"
  },
  "riskProfile": "https://access.worldpay.com/riskprofile/ewogICJ2ZXJzaW9uIiA6IDEsCiAgImtleSIgOiAxLAogICJkYXRhIiA6ICJ5d1NnSzMwYnNGZXVYalR0QUJ0QWdnT3UvK3VhcktrL3c1dCtmSFd4dUFXRmVMZUpuM0MyaEtnYnZlZEdnbGtRY1h4LzltN1pSZGVXZWRBQ1ZvTmxZdFNiZUxaSmFrZXZxenVndFQ2bG44NkpNTW5CeGJSRFVWWWY3dTd5SXVuVFJLK0NYZS9tODRkaHdTUWVnZlYyYTRCb1RaQVNKK0RpcGpmYUxkK1lETlJFclVyZ1c0TGIvOGhvNnFzbFVBU0dSem8zRVRkMEdIUTZXZ1dIT2t1UVBabUF1NXZuVFdBeGZrSEQ5SkdrT1BoV1pMMmIyZm9yNWNOMzZvWUhOY2dkT0lKdkhNMEg5TG1oRDM1RXA4T3R2WWptVmNXS25FZmtLZ0RrK09KRDNLb2pobG",
  "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.

Security

BasicAuth

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.

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

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.

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

TC40/SAFE fraud information provided to the FraudSight service. This could be from any Worldpay or 3rd party payment provider.

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "default"
  },
  "riskProfile": "https://access.worldpay.com/riskprofile/ewogICJ2ZXJzaW9uIiA6IDEsCiAgImtleSIgOiAxLAogICJkYXRhIiA6ICJ5d1NnSzMwYnNGZXVYalR0QUJ0QWdnT3UvK3VhcktrL3c1dCtmSFd4dUFXRmVMZUpuM0MyaEtnYnZlZEdnbGtRY1h4LzltN1pSZGVXZWRBQ1ZvTmxZdFNiZUxaSmFrZXZxenVndFQ2bG44NkpNTW5CeGJSRFVWWWY3dTd5SXVuVFJLK0NYZS9tODRkaHdTUWVnZlYyYTRCb1RaQVNKK0RpcGpmYUxkK1lETlJFclVyZ1c0TGIvOGhvNnFzbFVBU0dSem8zRVRkMEdIUTZXZ1dIT2t1UVBabUF1NXZuVFdBeGZrSEQ5SkdrT1BoV1pMMmIyZm9yNWNOMzZvWUhOY2dkT0lKdkhNMEg5TG1oRDM1RXA4T3R2WWptVmNXS25FZmtLZ0RrK09KRDNLb2pobG",
  "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.

Security

BasicAuth

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.

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.

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

Chargeback (fraud) information provided to the FraudSight service. This could be from any Worldpay or 3rd party payment provider

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "default"
  },
  "riskProfile": "https://access.worldpay.com/riskprofile/ewogICJ2ZXJzaW9uIiA6IDEsCiAgImtleSIgOiAxLAogICJkYXRhIiA6ICJ5d1NnSzMwYnNGZXVYalR0QUJ0QWdnT3UvK3VhcktrL3c1dCtmSFd4dUFXRmVMZUpuM0MyaEtnYnZlZEdnbGtRY1h4LzltN1pSZGVXZWRBQ1ZvTmxZdFNiZUxaSmFrZXZxenVndFQ2bG44NkpNTW5CeGJSRFVWWWY3dTd5SXVuVFJLK0NYZS9tODRkaHdTUWVnZlYyYTRCb1RaQVNKK0RpcGpmYUxkK1lETlJFclVyZ1c0TGIvOGhvNnFzbFVBU0dSem8zRVRkMEdIUTZXZ1dIT2t1UVBabUF1NXZuVFdBeGZrSEQ5SkdrT1BoV1pMMmIyZm9yNWNOMzZvWUhOY2dkT0lKdkhNMEg5TG1oRDM1RXA4T3R2WWptVmNXS25FZmtLZ0RrK09KRDNLb2pobG",
  "sourceDate": "2020-12-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

{}

FraudSight (v1)

Fraud assessment

Request

Responses

Do you like our page?

Update

Provide details of the payment outcome

Request

Responses

Do you like our page?

Provide details of a payment that resulted in fraud

Request

Responses

Do you like our page?

Provide details of a payment that resulted in a chargeback

Request

Responses

Do you like our page?

FraudSight (v1)

Fraud assessment

RequestExpand all

Responses

Do you like our page?

Update

Provide details of the payment outcome

RequestExpand all

Responses

Do you like our page?

Provide details of a payment that resulted in fraud

RequestExpand all

Responses

Do you like our page?

Provide details of a payment that resulted in a chargeback

RequestExpand all

Responses

Do you like our page?

Request

Request

Request

Request