The Fraudsight API from Worldpay — 1 operation(s) for fraudsight.
openapi: 3.0.1
info:
title: 3DS 3DS actions Fraudsight API
description: "Protect your business and meet regulatory requirements by verifying your customer's identity.\n\n__Authentication header__\n ```\n Authorization: {your_credentials}\n ```\nReplace `{your_credentials}` with your base64-encoded Basic Auth username and password given to your by your Worldpay Implementation Manager.\n<br /> <br />\n\nYou **must** use the `Authorization` header for any request you send to our 3DS API.\n\n__Accept/Content-Type header__\n ```\n Content-Type: application/vnd.worldpay.verifications.customers-v3.hal+json\n Accept: application/vnd.worldpay.verifications.customers-v3.hal+json\n ```\nWe 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 3DS API.\n\nWe 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`.\n<br /><br />\n\n\n__DNS whitelisting__ \nWhitelist the following URLs:\n* `https://try.access.worldpay.com/`\n* `https://access.worldpay.com/`\n\nPlease ensure you use DNS whitelisting, not explicit IP whitelisting."
version: '3'
x-metadata:
category:
- 3DS
- SCA Exemptions
business:
- Enterprise
catalog-list: true
generated: false
servers:
- url: https://try.access.worldpay.com
description: Test (Try)
- url: https://access.worldpay.com
description: Live
security:
- BasicAuth: []
tags:
- name: Fraudsight
paths:
/fraudsight/assessment:
post:
summary: Fraud assessment
description: Request a risk assessment
operationId: assessment
parameters:
- in: header
name: Content-Type
required: true
schema:
type: string
example: application/vnd.worldpay.fraudsight-v1.hal+json
- in: header
name: Accept
required: true
schema:
type: string
example: application/vnd.worldpay.fraudsight-v1.hal+json
requestBody:
content:
application/vnd.worldpay.fraudsight-v1.hal+json:
schema:
$ref: '#/components/schemas/fraudsight_assess'
examples:
card/front:
$ref: '#/components/examples/assessment-request-card'
card/tokenized:
$ref: '#/components/examples/assessment-request-token'
card/networkToken:
$ref: '#/components/examples/assessment-request-network-token'
card/plain+masked:
$ref: '#/components/examples/assessment-request-card-plain-masked'
card/front (request exemption):
$ref: '#/components/examples/assessment-request-card-exemption'
responses:
'200':
description: The authentication has been created
content:
application/vnd.worldpay.fraudsight-v1.hal+json:
schema:
$ref: '#/components/schemas/fraudsight_assess_200_response'
examples:
lowRisk:
$ref: '#/components/examples/assessment-response-low-risk'
review:
$ref: '#/components/examples/assessment-response-review'
highRisk:
$ref: '#/components/examples/assessment-response-high-risk'
lowRisk (exemption):
$ref: '#/components/examples/assessment-response-low-risk-with-exemption'
review (exemption):
$ref: '#/components/examples/assessment-response-review-with-exemption'
highRisk (exemption):
$ref: '#/components/examples/assessment-response-high-risk-with-exemption'
'400':
description: Assessment request contains invalid values
content:
application/vnd.worldpay.fraudsight-v1.hal+json:
schema:
$ref: '#/components/schemas/fraudsight_assessment_400_response'
examples:
An assessment request with invalid value in request body:
description: An assessment request using an email which is 2 characters long
value:
errorName: bodyDoesNotMatchSchema
validationErrors:
- errorName: stringFailedRegexCheck
message: Email must be a valid email address
jsonPath: $.riskData.account.email
- errorName: stringIsTooShort
message: Email must be between 3 and 254 characters inclusive
jsonPath: $.riskData.account.email
message: The json body provided does not match the expected schema
An assessment request using invalid header:
description: An assessment request using invalid 'Content-Type' header
value:
errorName: headerHasInvalidValue
message: A valid 'Content-Type' header must be provided
An assessment request using invalid http method:
description: An assessment request using GET method instead of POST
value:
errorName: methodNotAllowed
message: method GET not allowed for this request
'401':
description: Assessment request is unauthorized
content:
application/vnd.worldpay.fraudsight-v1.hal+json:
schema:
$ref: '#/components/schemas/fraudsight_assessment_401_response'
examples:
An assessment request with invalid Authorization header:
description: An assessment request using invalid Authorization header
value:
errorName: unAuthorized
message: Invalid access token
'503':
description: The requested service is unavailable
content:
application/vnd.worldpay.fraudsight-v1.hal+json:
schema:
$ref: '#/components/schemas/fraudsight_assessment_503_response'
examples:
The requested service is unavailable:
description: The requested service is unavailable
value:
errorName: serviceUnavailable
message: Service unavailable
tags:
- Fraudsight
components:
schemas:
deviceData:
type: object
description: Object containing device data information.
properties:
collectionReference:
maxLength: 128
minLength: 30
pattern: ^[A-Za-z0-9_-]*$
type: string
description: Use the sessionId specified in the ThreatMetrix Device Data Collection to link this data to the assessment.
ipAddress:
minLength: 1
type: string
description: A unique identifier for your customer's physical location that can be used in a fraud assessment. Must be in IPv4 or IPv6 format.
email:
maxLength: 254
minLength: 3
pattern: ^.+@.+$
type: string
description: The customer's email address.
fraudsight_assessment_503_response:
required:
- message
- errorName
type: object
properties:
message:
type: string
maxLength: 2048
minLength: 1
description: The error description message.
errorName:
type: string
maxLength: 2048
minLength: 1
description: The unique error name.
firstName:
maxLength: 22
minLength: 1
pattern: ^[a-zA-Z]*$
type: string
description: Customer's first name.
fraudsight_assessment_400_response:
required:
- message
- errorName
type: object
properties:
message:
type: string
maxLength: 2048
minLength: 1
description: The error description message.
errorName:
type: string
maxLength: 2048
minLength: 1
description: The unique error name.
validationErrors:
description: Object containing details of validation errors occurred
type: array
items:
$ref: '#/components/schemas/validation_errors'
cardExpiryDate:
required:
- month
- year
type: object
description: Object containing card expiry information.
properties:
month:
maximum: 12
minimum: 1
type: integer
description: Card expiry month
year:
maximum: 9999
minimum: 1
type: integer
description: Card expiry year
card_plainmasked:
required:
- type
- cardBin
- lastFour
- reference
type: object
properties:
type:
type: string
format: card/plain+masked
description: An identifier for the `paymentInstrument` being used.
cardBin:
maxLength: 8
minLength: 4
pattern: ^[0-9]*$
type: string
description: BIN range of payment card
lastFour:
maxLength: 4
minLength: 4
pattern: ^[0-9]*$
type: string
description: Last four digits of payment card
reference:
maxLength: 36
minLength: 10
type: string
description: A unique reference for this payment card
billingAddress:
$ref: '#/components/schemas/billingAddress'
cardHolderName:
$ref: '#/components/schemas/cardHolderName'
phoneNumber:
maxLength: 20
minLength: 4
pattern: ^[0-9]*$
type: string
description: Customer's phone number.
fraudsight_assessment_401_response:
required:
- message
- errorName
type: object
properties:
message:
type: string
maxLength: 2048
minLength: 1
description: The error description message.
errorName:
type: string
maxLength: 2048
minLength: 1
description: The unique error name.
card_networktoken:
required:
- type
- tokenNumber
- cardExpiryDate
type: object
properties:
type:
type: string
format: card/networkToken
description: An identifier for the `paymentInstrument` being used.
cardExpiryDate:
$ref: '#/components/schemas/cardExpiryDate'
tokenNumber:
maxLength: 19
minLength: 10
pattern: ^[0-9]*$
type: string
description: The network token number
cardHolderName:
$ref: '#/components/schemas/cardHolderName'
billingAddress:
$ref: '#/components/schemas/billingAddress'
custom:
type: object
description: Additional values specific to your order that can be used to create manual fraud rules.
properties:
number1:
maximum: 2147483647
minimum: -2147483648
type: integer
description: Custom number field 1.
number2:
maximum: 2147483647
minimum: -2147483648
type: integer
description: Custom number field 2.
number3:
maximum: 2147483647
minimum: -2147483648
type: integer
description: Custom number field 3.
number4:
maximum: 2147483647
minimum: -2147483648
type: integer
description: Custom number field 4.
number5:
maximum: 2147483647
minimum: -2147483648
type: integer
description: Custom number field 5.
number6:
maximum: 2147483647
minimum: -2147483648
type: integer
description: Custom number field 6.
number7:
maximum: 2147483647
minimum: -2147483648
type: integer
description: Custom number field 7.
number8:
maximum: 2147483647
minimum: -2147483648
type: integer
description: Custom number field 8.
number9:
maximum: 2147483647
minimum: -2147483648
type: integer
description: Custom number field 9.
number10:
maximum: 2147483647
minimum: -2147483648
type: integer
description: Custom number field 10.
string1:
maxLength: 100
minLength: 1
type: string
description: Custom string field 1.
string2:
maxLength: 100
minLength: 1
type: string
description: Custom string field 2.
string3:
maxLength: 100
minLength: 1
type: string
description: Custom string field 3.
string4:
maxLength: 100
minLength: 1
type: string
description: Custom string field 4.
string5:
maxLength: 100
minLength: 1
type: string
description: Custom string field 5
string6:
maxLength: 100
minLength: 1
type: string
description: Custom string field 6.
string7:
maxLength: 100
minLength: 1
type: string
description: Custom string field 7.
string8:
maxLength: 100
minLength: 1
type: string
description: Custom string field 8.
string9:
maxLength: 100
minLength: 1
type: string
description: Custom string field 9.
string10:
maxLength: 100
minLength: 1
type: string
description: Custom string field 10.
card_front:
required:
- type
- cardNumber
- cardExpiryDate
type: object
properties:
type:
type: string
format: card/front
description: An identifier for the `paymentInstrument` being used.
cardExpiryDate:
$ref: '#/components/schemas/cardExpiryDate'
cardNumber:
maxLength: 19
minLength: 10
pattern: ^[0-9]*$
type: string
description: Clear card number (PAN).
billingAddress:
$ref: '#/components/schemas/billingAddress'
cardHolderName:
$ref: '#/components/schemas/cardHolderName'
fraudsight_assess:
required:
- transactionReference
- merchant
- instruction
type: object
properties:
transactionReference:
$ref: '#/components/schemas/transactionReference'
merchant:
required:
- entity
type: object
description: An object that contains information about the merchant and API level configuration.
properties:
entity:
$ref: '#/components/schemas/entity'
exemption:
required:
- capability
type: object
description: An object that contains information about the `type` and `placement` of the requested exemption.
properties:
capability:
type: string
enum:
- authorizationOnly
- authenticationOnly
- authorizationAndAuthentication
x-enumDescriptions:
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`.
description: Indicates whether the exemption requested from us can return a placement of authorization (payment) and/or authentication (3DS).
request:
type: object
description: An object used to control the `placement` and `type` of the requested exemption. If not provided, we decide the best placement and type (optimized).
properties:
placement:
type: string
default: optimized
enum:
- optimized
- authorization
- authentication
x-enumDescriptions:
optimized: We select the best performing placement based on its data.
authorization: A request for an exemption placed within the authorization.
authentication: A request for an exemption placed within the authentication (3DS).
description: Defines where the exemption is being requested.
type:
type: string
default: optimized
enum:
- optimized
- lowValue
- lowRisk
x-enumDescriptions:
optimized: We select the best performing type based on its data.
lowValue: An exemption for an authorization that is under €30.
lowRisk: An exemption for an authorization that has been through Transaction Risk Analysis (TRA).
description: Defines which type of exemption is being requested.
instruction:
required:
- value
- paymentInstrument
type: object
description: The object that contains all the payment information related to the authentication request.
properties:
value:
$ref: '#/components/schemas/value'
paymentInstrument:
oneOf:
- $ref: '#/components/schemas/card_front'
- $ref: '#/components/schemas/card_tokenized'
- $ref: '#/components/schemas/card_networktoken'
- $ref: '#/components/schemas/card_plainmasked'
description: An object that contains the card details or token location.
discriminator:
mapping:
card/front: '#/components/schemas/card_front'
card/tokenized: '#/components/schemas/card_tokenized'
card/networkToken: '#/components/schemas/card_networktoken'
card/plain+masked: '#/components/schemas/card_plainmasked'
propertyName: type
requestExemption:
type: boolean
deprecated: true
description: '__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`'
doNotApplyExemption:
type: boolean
description: 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.
riskData:
type: object
description: An object that holds risk related information that might help in improving the accuracy of fraud assessment.
properties:
account:
type: object
description: Object containing all customer account related risk data.
properties:
shopperId:
$ref: '#/components/schemas/shopperId'
email:
$ref: '#/components/schemas/email'
dateOfBirth:
$ref: '#/components/schemas/dateOfBirth'
transaction:
type: object
description: Object containing all customer transaction related risk data.
properties:
firstName:
$ref: '#/components/schemas/firstName'
lastName:
$ref: '#/components/schemas/lastName'
phoneNumber:
$ref: '#/components/schemas/phoneNumber'
shipping:
type: object
description: Object containing all data related to how the order is shipped.
properties:
firstName:
maxLength: 22
minLength: 1
pattern: ^[a-zA-Z]*$
type: string
description: First name of the shipping recipient.
lastName:
maxLength: 22
minLength: 1
pattern: ^[a-zA-Z]*$
type: string
description: Last name of the shipping recipient.
address:
$ref: '#/components/schemas/shippingAddress'
custom:
$ref: '#/components/schemas/custom'
deviceData:
$ref: '#/components/schemas/deviceData'
dateOfBirth:
maxLength: 20
minLength: 1
type: string
format: date
description: The customer's date of birth.
entity:
maxLength: 64
minLength: 1
pattern: ^[A-Za-z0-9 ]*$
type: string
description: Used to route the request in Access Worldpay, created as part of on-boarding.
validation_errors:
type: object
required:
- errorName
- jsonPath
- message
properties:
errorName:
maxLength: 2048
minLength: 1
type: string
description: Unique name of the validation error.
jsonPath:
maxLength: 2048
minLength: 1
type: string
description: Location of the field in request body for which the error occurred.
message:
maxLength: 2048
minLength: 1
type: string
description: Error description message.
transactionReference:
maxLength: 64
minLength: 1
pattern: ^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$
type: string
description: A unique reference for authentication. For example, e-commerce order code.
shopperId:
maxLength: 128
minLength: 1
type: string
description: A unique identifier for the customer. Use it to create manual fraud rules and identify your customers.
card_tokenized:
required:
- type
- href
type: object
properties:
type:
type: string
format: card/tokenized
description: An identifier for the `paymentInstrument` being used.
href:
minLength: 1
type: string
description: An `http` address that contains your link to an Access Token
fraudsight_assess_200_response:
required:
- outcome
- transactionReference
- riskProfile
type: object
properties:
outcome:
enum:
- lowRisk
- highRisk
- review
type: string
description: The outcome of the fraudsight assessment request. To understand more about the outcomes and how to reproduce them, see [FraudSight testing](/products/fraudsight/testing).
transactionReference:
maxLength: 64
minLength: 1
type: string
description: A unique reference for assessment that was passed in the request.
riskProfile:
required:
- href
type: object
description: An object that holds the risk profile link.
properties:
href:
maxLength: 1024
minLength: 30
type: string
format: uri
description: "A resource to apply in either a [card payment request](/products/card-payments/authorize-a-payment#fraudsight) __OR__ [additional fraudsight requests](/products/fraudsight/update). This represents the outcome of the fraud assessment and exemption. Used to:\n- apply the SCA exemption (if provided)\n- update the data model so future risk assessments are more accurate\n\n__Warning:__ Not providing this will significantly harm the accuracy of future assessments. \n"
score:
maximum: 100
minimum: 0
type: number
description: 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:
type: array
items:
type: string
maxItems: 10
description: '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
'
exemption:
required:
- placement
- type
type: object
description: An object that holds information about the exemption, if it is granted.
properties:
placement:
enum:
- authorization
- authentication
x-enumDescriptions:
authorization: Apply the exemption in the payment authorization.
authentication: Apply the exemption in the 3DS authentication.
type: string
description: "Indicates whether the exemption is provided to be placed in a payment authorization request or 3DS authentication request. \n"
type:
enum:
- lowValue
- lowRisk
x-enumDescriptions:
lowValue: Apply a lowValue exemption. _(only applicable to a placement in authorization)_
lowRisk: Apply a lowRisk exemption.
type: string
description: The type of exemption to apply.
billingAddress:
required:
- address1
- city
- postalCode
- countryCode
type: object
description: An object containing the billing address information.
properties:
city:
maxLength: 50
minLength: 1
type: string
description: Billing address city.
address1:
maxLength: 80
minLength: 1
type: string
description: Billing address line 1.
postalCode:
maxLength: 15
minLength: 1
type: string
description: Billing address postal code.
countryCode:
maxLength: 2
minLength: 2
pattern: ^[A-Z]{2}$
type: string
description: Billing address country code.
state:
maxLength: 30
minLength: 1
type: string
description: Billing address state. Should only be provided following the `ISO-3611-2` two-character sub division (e.g.“CA” for California).
address2:
maxLength: 80
minLength: 1
type: string
description: Billing address line 2.
address3:
maxLength: 80
minLength: 1
type: string
description: Billing address line 3.
cardHolderName:
maxLength: 255
minLength: 1
type: string
description: The name on the customer's card.
value:
required:
- amount
- currency
type: object
description: An object that contains information about the value of the assessment.
properties:
amount:
maximum: 99999999999
minimum: 0
type: integer
description: 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](/products/reference/supported-countries-currencies#iso-currency-codes). 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.
currency:
maxLength: 3
minLength: 3
pattern: ^[A-Z]{3}$
type: string
description: The three digit currency code. See list of [supported currencies](/products/reference/supported-countries-currencies#iso-currency-codes).
lastName:
maxLength: 22
minLength: 1
pattern: ^[a-zA-Z]*$
type: string
description: Customer's last name.
shippingAddress:
required:
- address1
- city
- postalCode
- countryCode
type: object
description: An object containing the shipping address information.
properties:
city:
maxLength: 50
minLength: 1
type: string
description: Shipping address city.
address1:
maxLength: 80
minLength: 1
type: string
description: Shipping address line 1.
postalCode:
maxLength: 15
minLength: 1
type: string
description: Postcode of shipping address.
countryCode:
maxLength: 2
minLength: 2
pattern: ^[A-Z]{2}$
type: string
description: Shipping address country code.
state:
maxLength: 30
minLength: 1
type: string
description: Shipping address state. Should only be provided following the `ISO-3611-2` two-character sub division (e.g.“CA” for California).
address2:
maxLength: 80
minLength: 1
type: string
description: Shipping address line 2.
address3:
maxLength: 80
minLength: 1
type: string
description: Shipping address line 3.
phoneNumber:
maxLength: 20
minLength: 4
pattern: ^[0-9]*$
type: string
description: Shipping recipient's phone number.
examples:
assessment-response-high-risk:
description: High risk outcome, do not proceed with the payment
value:
outcome: highRisk
transactionReference: '123456'
reason:
- Recent unexpected card activity
score: 97.4
riskProfile:
href: https://access.worldpay.com/riskprofile/eyJrIjoxLCJkIjoialRBL0FFelBzcnZ
assessment-response-low-risk:
description: Low risk outcome, proceed with the payment
value:
outcome: lowRisk
transactionReference: '123456'
score: 44.2
riskProfile:
href: https://access.worldpay.com/riskprofile/eyJrIjoxLCJkIjoialRBL0FFelBzcnZ
assessment-request-card-exemption:
description: Assessment using the card instrument & requesting an SCA Exemption
value:
transactionReference: Memory265-13/08/1876
merchant:
entity: default
exemption:
capability: authorizationAndAuthentication
request:
placement: authorization
type: lowValue
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: '1990-09-09'
shopperId: id123
transaction:
firstName: Sherlock
lastName: Holmes
phoneNumber: '00000000000000'
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
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/worldpay/refs/heads/main/openapi/worldpay-fraudsight-api-openapi.yml