Access Worldpay
/
FraudSight

FraudSight (v1)

Download OpenAPI specification:Download

License: Worldpay

Request a risk assessment

Servers

testing (try)

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

live

https://access.worldpay.com/

Fraud assessment

Request a risk assessment

SecurityHTTP: BasicAuth
Request
header Parameters
Content-Type
string
Example: application/vnd.worldpay.fraudsight-v1.hal+json
Accept
string
Example: application/vnd.worldpay.fraudsight-v1.hal+json
Request Body schema: application/vnd.worldpay.fraudsight-v1.hal+json
transactionReference
required
string [ 1 .. 64 ] characters ^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$

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

required
object

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

required
object

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

requestExemption
boolean

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

doNotApplyExemption
boolean

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.

object

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

object

Object containing device data information.

post
/fraudsight/assessment
Request samples
application/vnd.worldpay.fraudsight-v1.hal+json

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

{
"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

200

The authentication has been created

Response Schema: application/vnd.worldpay.fraudsight-v1.hal+json
outcome
required
string

The outcome of the fraudsight assessment request.

Enum: "lowRisk" "highRisk" "review"
transactionReference
required
string [ 1 .. 64 ] characters

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

required
object

An object that holds the risk profile link.

score
number [ 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.

reason
Array of strings <= 10 items

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

object

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

400

Assessment request contains invalid values

401

Assessment request is unauthorized

503

The requested service is unavailable

Response samples
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

Provide details of the payment outcome

Provide payment outcome information

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

SecurityHTTP: BasicAuth
Request
Request Body schema: application/vnd.worldpay.fraudsight-v1.hal+json
transactionReference
required
string [ 1 .. 64 ] characters ^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$

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

required
object

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

riskProfile
required
string <uri> [ 39 .. 2048 ] characters

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

paymentOutcome
required
string

Outcome of the payment authorization.

Enum: "authorized" "refused"
cvcResult
string

Outcome of the CVC check.

Enum: "matched" "not_matched" "not_checked" "not_supplied"
object

Object containing outcome of the address verification service check.

object

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

post
/fraudsight/update/payment
Request samples
application/vnd.worldpay.fraudsight-v1.hal+json

Payment outcome details are provided to the fraudsight service

{
"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

204

Successful update with payment information

400

Update payment request contains invalid values

401

Update payment request is unauthorized

Response samples
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

Provide payment fraud information

SecurityHTTP: BasicAuth
Request
Request Body schema: application/vnd.worldpay.fraudsight-v1.hal+json
transactionReference
required
string [ 1 .. 64 ] characters ^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$

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

required
object

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

riskProfile
required
string <uri> [ 39 .. 2048 ] characters

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

source
required
string

Source format of confirmed fraud cases.

Enum: "SAFE" "TC40"
sourceDate
required
string <date-time> <= 20 characters

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

acquirerReference
required
string [ 1 .. 128 ] characters

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

fraudReasonCode
required
string [ 1 .. 16 ] characters

Visa and Mastercard reason codes.

required
object

Object containing information about value of the transaction.

post
/fraudsight/update/fraud
Request samples
application/vnd.worldpay.fraudsight-v1.hal+json

Provide details of a payment that resulted in fraud

{
"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

204

Successful update with fraud information

400

Update fraud request contains invalid values

401

Update fraud request is unauthorized

Response samples
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

Provide payment chargeback information

SecurityHTTP: BasicAuth
Request
Request Body schema: application/vnd.worldpay.fraudsight-v1.hal+json
transactionReference
required
string [ 1 .. 64 ] characters ^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$

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

required
object

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

riskProfile
required
string <uri> [ 39 .. 2048 ] characters

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

sourceDate
required
string <date-time> <= 20 characters

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

acquirerReference
required
string [ 1 .. 128 ] characters

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

chargebackReasonCode
required
string [ 2 .. 4 ] characters

Visa and Mastercard reason codes.

chargebackCaseReference
required
string [ 1 .. 64 ] characters

Case reference for a specific chargeback.

required
object

Object containing value of the chargeback transaction.

post
/fraudsight/update/chargeback
Request samples
application/vnd.worldpay.fraudsight-v1.hal+json

Provide details of a payment that resulted in a chargeback

{
"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

204

Successful update with chargeback information

400

Update payment request contains invalid values

401

Update chargeback request is unauthorized

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

Provide details of a payment that resulted in a chargeback

{ }