- Home
- All APIs
- Access Worldpay
- FraudSight API
- Fraud assessment
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:
{
"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"
}
}
}
Parameter | Required | Description |
---|---|---|
transactionReference | A reference for the assessment. For example, e-commerce order code. | |
merchant.entity | Used to route the assessment request in Access Worldpay, created as part of on-boarding. | |
requestExemption | To request an
| |
instruction | The object that contains all the payment information related to the assessment request. | |
instruction.paymentInstrument | An object that contains the card details or token location. | |
paymentInstrument.type | An identifier for the paymentInstrument being used.type : card/front
type : card/tokenized
| |
paymentInstrument.billingAddress | An 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:
Descriptions of your additional account riskData
parameters:
Parameter | Mandatory | Description |
---|---|---|
account | Object containing all customer account related risk data. | |
account.email | The customer's email address. | |
account.dateOfBirth | The customer's date of birth. |
Descriptions of your additional transaction riskData
parameters:
Parameter | Required | Description |
---|---|---|
transaction | Object containing all customer transaction related risk data. | |
transaction.firstName | Customer's first name. | |
transaction.lastName | Customer's last name. | |
transaction.phoneNumber | Customer's phone number. |
Descriptions of your additional shipping riskData
parameters:
Parameter | Required | Description |
---|---|---|
shipping | Object containing all data related to how the order is shipped. | |
shipping.firstName | First name used on the shipping address | |
shipping.lastName | Last name used on the shipping address | |
shipping.address | An object containing the shipping address information. If included you must send at least:
|
Additional values specific to your order that can be used to create manual fraud rules.
Parameter | Required | Description |
---|---|---|
customRule | Object containing all data that can be used to configure manual fraud rules | |
customRule.string1-10 | 10 available slots for custom string values to be used to configure manual fraud rules | |
customRule.number1-10 | 10 available slots for custom number values to be used to configure manual fraud rules |
Assessment responses
The response contains the outcome of your assessment
request.
{
"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.
Parameter | Description |
---|---|
outcome | The recommendation from FraudSight:
outcomes and how to reproduce them, see |
reason | Short description of the reason for the outcome:
|
score | 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. |
exemption.placement |
Note: Only placement 'authorization' will be configured to be returned for now until Access 3DS supports exemption placement |
exemption.type | The type of exemption to apply
|
riskProfile.href | A resource you can use in the payment authorization request that represents the outcome of the fraud assessment and exemption. Used to:
|
Next steps