FraudSight (Direct)

Unparalleled data insights, industry leading technology, and fraud expertise combine to predict and prevent fraud.

Here you will find everything you need to get started with FraudSight - Direct integration.

On this page

Before you start

  • Talk to your Worldpay Relationship Manager or our Customer Support Team to confirm your requirements
  • Confirm that your account has been enabled for FraudSight by Worldpay

Integration overview

There is no mandatory integration required for FraudSight - direct integration. However, to make the most of the FraudSight features, we recommend that you integrate optional functionality:

  • Worldpay Device JavaScript Collector (JSC)
  • Additional shopper data

If you already use our Risk Management Module (RMM) you receive the <riskScore> element in your response. The content of this element changes specifically to FraudSight. There is also an optional <FraudSight> response element that returns the model reason codes. For more details, seePayment responses.

FraudSight Risk Checks

FraudSight Risk Checks can be completed before authorisation.

FraudSight Risk Checks before authorisation

  • FraudSight, without any other Worldpay Protect products:

FraudSight without DDC

  • FraudSight with other Worldpay Protect products:

FraudSight with other products - before Authorisation

  1. TheWorldpay Device JavaScript Collector (JSC)collects shopper device data. If you're using Worldpay's 3DS Flex, Device Data Collection (DDC) for 3DS authentication is also performed
  2. You submit the payment request to WPG
  3. If you're using Worldpay's Exemption Engine an exemption decision is made
  4. Where exemption does not apply, 3DS authentication is performed
  5. FraudSight Risk Check
  6. If the risk is low, payment is sent for authorisation. See theFraudSight response tablefor a list of responses and what they mean
  7. Payment response

Worldpay Device JavaScript Collector (JSC)

You must add Worldpay's JavaScript Collector (JSC) to the head of your payment page.

The JSC collects shopper device data for device fingerprinting and IP geo-location insights.

You can use the data you collect to create a more accurate internal review process and logic that contributes to the decision of authorizing or refusing a payment in real time.

Note: Worldpay have partnered with ThreatMetrix to provide this service. You will see reference to ThreatMetrix throughout the code examples in this guide.

The JavaScript toolkit

  • Obtain the JavaScript toolkit from Worldpay. Your Relationship or Corporate Support Manager will provide you with the credentials.
  • Rename the file provided to something unique. e.g. asdfghjkl.js
  • Place the renamed file in a publicly accessible location on your web server
  • Ensure that the function 'threatmetrix.profile' is renamed within the JavaScript. E.g. Djsc.prfl. This will help avoid ad-blockers from stopping the JavaScript from running.
  • Be prepared to update this file with new versions, released periodically

JavaScript tag placement

The JavaScript must run when the payment page is loaded to collect device data. Add the JavaScript tag to the head of your page.

<script type="text/javascript" src="path/to/asdfghjkl.js"></script>

// asdfghjkl.js is the renamed toolkit file.

Profiling tags have no visual representation and minimal impact on page load times. The ThreatMetrix Profiling Tag creates an iframe when loaded which asynchronously performs profiling. This means that page load times are fast, and there is no interference with existing page load routines.

Session ID and JSC initiation

We recommend that you create a utility library with functions to generate a sessionId and to invoke the JSC JavaScript.

Add the reference to the utility library to the head of your payment page just above the JSC JavaScript tag.

An example content of the utility library:

Copied!
window.onload = function() {
  //...
performJsc();
//...
};
function performJsc() {
 var ndownc = create_uuid(); //that’s the sessionId
var div = document.getElementById('payment-form'); //suggestion how you can store sessionId for when you need it in payment request
 var input = document.createElement('input');
  input.setAttribute('type', 'hidden');
  input.setAttribute('id', 'sessionId');
  input.setAttribute('name', 'sessionId');
  input.setAttribute('value', ndownc);
  div.appendChild(input);
Jsc.prfl ("PROFILING_DOMAIN", "ORGANISATION_ID", ndownc, page_id); // Jsc.prfl is the renamed function
}
function create_uuid() {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
   var r = Math.random() * 16 | 0,
     v = c == 'x' ? r : (r & 0x3 | 0x8);
    return v.toString(16);
 });
}

Note: You must submit the session ID in the UUID v4 format and ensure it's compliant with RFC 4122.
When the payment page is refreshed and the JSC JavaScript runs again, ensure that a new sessionID is generated. The "PROFILING_DOMAIN" and "ORGANISATION_ID" are provided by Worldpay.

Payment requests

The following examples cover both a standard payment request and payment requests with additional data.

Standard payment request

When you submit astandard xml direct payment requestit includes the generic data required by FraudSight.

Payment request with additional data

Within the element <FraudSightData> you can provide additional data. Use this data to create a more accurate internal review process and logic. This will contribute to the decision of authorizing or refusing a payment in real time.

Copied!
<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
  <submit>
    <order orderCode="YOUR_ORDER_CODE">
      <description>your description</description>
      <amount value="100" currencyCode="EUR" exponent="2"/>
      <orderContent>
        <![CDATA[]]>
      </orderContent>
      <paymentDetails>
        <CARD-SSL>
          <cardNumber>4444333322221111</cardNumber>
          <expiryDate>
            <date month="06" year="2023"/>
          </expiryDate>
          <cardHolderName>AUTHORISED</cardHolderName>
          <cvc>111</cvc>
          <cardAddress>
            <address>
              <firstName>A</firstName>
              <address1>Worldpay</address1>
              <address2>270-289 The Science Park</address2>
              <address3>Milton Road</address3>
              <postalCode>CB4 0WE</postalCode>
              <city>Cambridge</city>
              <countryCode>GB</countryCode>
            </address>
          </cardAddress>
        </CARD-SSL>
        <session shopperIPAddress="127.0.0.1" id="ssn590393660"/>
      </paymentDetails>
      <shopper>
        <shopperEmailAddress>sp@worldpay.com</shopperEmailAddress>
        <browser>
          <acceptHeader>text/html</acceptHeader>
          <userAgentHeader>Mozilla/5.0 ...</userAgentHeader>
        </browser>
      </shopper>
      <FraudSightData>
        <customStringFields>
          <customStringField1>nextDayShipping1</customStringField1>
          <customStringField2>nextDayShipping2</customStringField2>
          <customStringField3>nextDayShipping3</customStringField3>
          <customStringField4>nextDayShipping4</customStringField4>
          <customStringField5>nextDayShipping5</customStringField5>
          <customStringField6>nextDayShipping6</customStringField6>
          <customStringField7>nextDayShipping7</customStringField7>
          <customStringField8>nextDayShipping8</customStringField8>
          <customStringField9>nextDayShipping9</customStringField9>
          <customStringField10>nextDayShipping10</customStringField10>
        </customStringFields>
        <customNumericFields>
          <customNumericField1>111</customNumericField1>
          <customNumericField2>111</customNumericField2>
          <customNumericField3>111</customNumericField3>
          <customNumericField4>111</customNumericField4>
          <customNumericField5>111</customNumericField5>
          <customNumericField6>111</customNumericField6>
          <customNumericField7>111</customNumericField7>
          <customNumericField8>111</customNumericField8>
          <customNumericField9>111</customNumericField9>
          <customNumericField10>111</customNumericField10>
        </customNumericFields>
        <shopperFields>
          <shopperName>shopperName</shopperName>
          <shopperId>shopperId</shopperId>
          <birthDate>
            <date dayOfMonth="01" month="06" year="2000"/>
          </birthDate>
          <shopperAddress>
            <address>
              <firstName>A</firstName>
              <lastName>Shopper</lastName>
              <address1>Worldpay</address1>
              <address2>270-289 The Science Park</address2>
              <address3>Milton Road</address3>
              <postalCode>CB4 0WE</postalCode>
              <city>Cambridge</city>
              <countryCode>GB</countryCode>
              <telephoneNumber>1564645646465465</telephoneNumber>
            </address>
          </shopperAddress>
        </shopperFields>
      </FraudSightData>
      <deviceSession>
        <sessionId>07576199-0243-46dc-bad2-0eeb21414ab7</sessionId>
      </deviceSession>
    </order>
  </submit>
</paymentService>

Additional data table

Additional data elements and attributes you can add to your request within <FraudSightData>.

Be consistent when you assign values to your custom fields to avoid a mismatch of data for your payments.

ElementChild elementAttributeDescription
<customStringFields>
<customStringField1>Add one to ten lines of customStringFields and provide additional data to support your request.

Format: alpha numeric and special characters
<customNumericField>
<customNumericField1>Add one to ten lines of customNumericFields and provide additional data to support your request

Format: numeric characters only
<shopperFields>
<shopperName>The shopper's name
<shopperId>Your ID for your shopper
<birthDate>The shopper's birthdate
<date dayOfMonth="xx" month="xx" year="xxxx"/>The shopper's date of birth
<shopperAddress>The address of the shopper on your system.

When you use this element the following child elements must be used:
  • <address1>
  • <city>
<firstName>The first name of the shopper on your system.

Format: alpha numeric and special characters
<lastName>The last name of the shopper on your system.

Format: alpha numeric and special characters
<houseNumber>The shopper's house number for their given address

Format: numeric characters
<houseNumberExtension>For example: Flat A.

Format: alpha numeric and special characters
<address1>The first line of the shopper's address.

Format: alpha numeric and special characters
<address2>The second line of the shopper's address.

Format: alpha numeric and special characters
<address3>The third line of the shopper's address.

Format: alpha numeric and special characters
<postalCode>The shopper's post code.

Format: alpha numeric and special characters
<city>The shopper's city.

Format: alpha numeric and special characters
<countryCode>The shopper's country.

Format: ISO-3166 country code
<telephoneNumber>The shopper's telephone number.

Format: alpha numeric and special characters

Payment responses

Payment responses with FraudSight

The response includes both a <riskScore> and <FraudSight> element. These are optional but you need <riskScore> enabled to receive the <FraudSight> data.

Where a FraudSight response is not available, we still return the <riskScore> from our Risk Management Module (RMM).

Ask your Worldpay Relationship Manager or Support Team member to enable them on your account.

Response table for FraudSight

ElementChild elementAttributeDescription
<FraudSight>scoreThe score returned by the FraudSight model
idThe unique identifier generated for the payment event
messageFraudSight risk decision. Values:
  • low-risk
  • review
  • high-risk
<reasonCodes>Risk reasons triggered by the FraudSight model. Values:
  • 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 behaviour for card
  • FRAUD SUSPICION (returned by Risk Management Module only if used as a secondary risk management tool)
<riskScore>providerDescribes the fraud product that assessed the payment. Values:
  • FraudSight
  • Risk Management Module
finalScoreThe score returned by the Risk Management Module
idThe unique identifier generated for the payment event
messageFraudSight risk decision. Values:
  • low-risk
  • review
  • high-risk

FraudSight response examples

Payment responses with RMM

When FraudSight is unavailable we fallback to our Risk Management Module (RMM).

RMM is included with FraudSight. RMM returns a <riskScore>.

Note: Returning the <riskScore> is optional.
Ask your Worldpay Relationship Manager or Support Team member to enable this on your account.

Response table for RMM

ElementAttributeMandatory/OptionalDescription
<riskScore>OptionalEnabled by default for RMM. <riskScore> is optional for both your RMM and FraudSight response
providerThe risk management tool providing the response
finalScoreThe final score assigned to this transaction by RMM

RMM response examples

Testing

To test your setup, use ourtest environmentas a reference. FraudSight has its ownmagic values(coming soon). If you are using additional data, use the reference table below.

Payment request reference table

If you make an error in formatting your request you'll receive one of the following responses.

Custom field/Shopper fieldFieldCharacters supportedCould be empty?XML response error codes
Custom field<customStringField1>alpha-numeric and special charactersNo<error code="5"><![CDATA[The tag 'customStringField1' cannot be empty]]></error>
Custom field<customNumericField2>Numeric charactersNo<error code="5"><![CDATA[The tag 'customNumericField2' isn't a valid number]]></error>

<error code="5"><![CDATA[The tag 'customNumericField2' cannot be empty]]></error>
Shopper field<shopperName>alpha-numeric and special charactersNo<error code="5"><![CDATA[The tag 'shopperName' cannot be empty]]></error>
Shopper field<shopperId>alpha-numeric and special charactersNo<error code="5"><![CDATA[The tag 'shopperId' cannot be empty]]></error>
Shopper field<birthDate>should follow the format:
<date dayOfMonth="02" month="06" year="2000">
No<error code="2"><![CDATA[Invalid day : 32]]></error>

<error code="2"><![CDATA[Invalid month : 13]]></error>

<error code="2"><![CDATA[Numeric value expected for year. Actually received: abc2]]></error>
Shopper field - <shopperAddress><firstName>alpha-numeric and special charactersYes
Shopper field - <shopperAddress><lastName>alpha-numeric and special charactersYes
Shopper field – <shopperAddress> (address 1 format)<address1>alpha-numeric and special charactersNo<error code="5"><![CDATA[Invalid address: Address 1/Street is required.]]></error>

<error code="5"><![CDATA[Invalid address: Address 1/Street is required.]]></error>
Shopper field – <shopperAddress> (address 1 format)<address2>alpha-numeric and special charactersYes
Shopper field – <shopperAddress> (address 1 format)<address3>alpha-numeric and special charactersYes
Shopper field – <shopperAddress><postalCode>alpha-numeric and special charactersYes
Shopper field – <shopperAddress><city>alpha-numeric and special charactersNo<error code="5"><![CDATA[Invalid address: City is required]]></error>
Shopper field – <shopperAddress><state>alpha-numeric and special charactersYes
Shopper field – <shopperAddress><telephoneNumber>alpha-numeric and special charactersYes
Shopper field – <shopperAddress><countryCode>Should be a valid ISO-3166 country codeNo<error code="5"><![CDATA[Invalid address: Country code "GBA" is not a valid ISO-3166 country code. ]]></error>

<error code="5"><![CDATA[Invalid address: Country code is null or blank. ]]></error>
Shopper field – <shopperAddress> (address 2 format)<street>alpha-numeric and special charactersNo<error code="5"><![CDATA[Invalid address: Address 1/Street is required.]]></error>
Shopper field – <shopperAddress> (address 2 format)<houseName>alpha-numeric and special charactersYes
Shopper field – <shopperAddress> (address 2 format)<houseNumber>numeric charactersNo<error code="5"><![CDATA[Expecting a numeric value for: houseNumber]]></error>

<error code="5"><![CDATA[Expecting a numeric value for: houseNumber]]></error>
Shopper field – <shopperAddress> (address 2 format)<houseNumberExtension>alpha-numeric and special charactersYes

Payment response magic values - coming soon

Use the magic values listed below and ourtest card numbersto test your payment request XML.

Magic values

Insert the below values in <address1> of <cardAddress> to simulate the FraudSight risk decision described in the message field:

Magic ValueMessageFraudSight scorePayment status
LOW-RISKlow-risk0.0AUTHORISED
REVIEWreview0.0AUTHORISED
HIGH-RISKhigh-risk1.0REFUSED
Any other valuelow-risk0.0AUTHORISED

Add the below values in <address3> of <cardAddress> to simulate the reason codes. Enter magic values separated by a comma to simulate a list of reason codes returned by FraudSight:

Magic valueReason
RC1Unusual behaviour for card
RC2Unusual transaction for merchant
RC3Recent unexpected card activity
RC4Card unfamiliarity
RC5Card type often linked to fraud
RC6Irregularities in cardholder-entered information
RC7High risk email
Any other valueFRAUD SUSPICION

Going Live

Before you go live with FraudSight, check the following:

  • You’re aware when the FraudSight Risk Check will trigger and what happens if FraudSight is unavailable
  • You’re sending through the recommended data points
  • You’ve requested the response format from Worldpay that you require
  • You’ve configured your fallback to RMM (if required)