Fraud Intelligence Integration

Fraud Intelligence is a Saferpay module that protects merchants from fraudulent online transactions. It relies on industry-leading AI technology and allows merchants to dynamically react on suspicious behavior and even prevent transactions with malicious intent, during authentication.

This chapter will cover the technical aspects on how to integrate Fraud Intelligence in your application.

Requirements

• A corresponding license and thus a valid identification with a username and password for the Saferpay system.

• Availability of at least one active Saferpay terminal via which payments can be carried out, and availability of the associated Saferpay TerminalId.

• A contract to use the Fraud Intelligence module in Saferpay. Please contact your contractual sales contact on that matter.

• Saferpay JSON API SpecVersion 1.20+

Supported Payment Methods and Flows

Currently, the following payment methods are supported:

• Visa/VPay

• Mastercard/Maestro

• American Express

• Bancontact

• Diners Club

• JCB

• PayPal

• Unionpay

Currently, the following flows are supported:

• Payment Page

• Transaction Interface, including Saferpay Fields

• Direct Mode for Bancontact

• Recurring Transactions

Data points

In order for the fraud detection to work properly, the system needs to be provided with a set of data points with each transaction. Some are provided automatically by Saferpay, while others need to be submitted by the merchant's system with the initial request, when starting the transaction with either Transaction Initialize or Payment Page Initialize.

All of these datapoints are generally optional. However the detection will work better the more data are provided.

The following data points can be set via the JSON API:

JSON API	Name in MS DFP	Description
Payment.Amount.Value	Total amount	The transaction amount.
Payment.Amount.CurrencyCode	Currency	The transaction currency.
(see description)	Merchant payment instrument ID	A hash of the used PAN. Note that this value usually comes directly from the card holder, rather than the merchant.
(see description)	BIN country/region ISO	The ISO code of the card issuer country. Only available for Visa, Mastercard, Maestro International, Bancontact and UnionPay transactions.
Payer.DeliveryAddress.Email	Shipping email	The customer's E-Mail address.
Payer.IpAddress	IP address (via Merchant)	The customer's IP-address.
RiskFactors.AccountCreationDate	n/a (used only for scoring)	The customer's date of signup to the merchant shop.
RiskFactors.PasswordLastChangeDate	n/a (used only for scoring)	The date when the customer last changed his/her password.
Order.Items[]	Products	Array of all the shopping cart items.
Order.Items[].Id	Product ID	Identifier of the product. This ID is created and provided by the merchant.
Order.Items[].Description	Product name	Description of the product, given by the merchant.
Order.Items[].UnitPrice	n/a (used only for scoring)	Price of the product.
Order.Items[].Quantity	n/a (used only for scoring)	Quantity ordered of this specific item.
Order.Items[].CategoryName	Category	Product category, given by the merchant.
Order.Items[].Type	Product type	Product type. Has to be one of the following: DIGITAL|PHYSICAL|SERVICE|GIFTCARD
RiskFactors[].DeliveryType	Product shipping method	The used delivery method. Recommended values: EMAIL: The items are delivered electronically to the customer. HOMEDELIVERY: The items are delivered to the customer's shipping address. PICKUP: The customer collects the items from a pickup location. SHOP: The customer collects the items from a branch shop. HQ: The customer collects the items from the flagship store.

JSON API	Name in MS DFP	Description
Payer.BillingAddress.City	City (Billing address)	Billing address city
Payer.BillingAddress.Country	Country/Region (Billing address)	Billing address country
Payer.BillingAddress.FirstName	First name (Billing address)	Billing address first name
Payer.BillingAddress.LastName	Last name (Billing address)	Billing address last name
Payer.BillingAddress.Street	Street 1 (Billing address)	Billing address street
Payer.BillingAddress.Street2	Street 2 (Billing address)	Additional billing address street information (e.g. PO Box)
Payer.BillingAddress.Zip	ZIP code (Billing address)	Billing address zip code
Payer.DeliveryAddress.City	City (Shipping address)	Shipping address city
Payer.DeliveryAddress.Country	Country/Region (Shipping address)	Shipping address country
Payer.DeliveryAddress.FirstName	First name (Shipping address)	Shipping address first name
Payer.DeliveryAddress.LastName	Last name (Shipping address)	Shipping address last name
Payer.DeliveryAddress.Street	Street 1 (Shipping address)	Shipping address street
Payer.DeliveryAddress.Street2	Street 2 (Shipping address)	Additional shipping address street information (e.g. PO Box)
Payer.DeliveryAddress.Zip	ZIP code (Shipping address)	Delivery address zip code
Payer.DeliveryAddress.Email	Shipping email	Delivery address email address

JSON API	Name in MS DFP	Description
RiskFactors.PayerProfile.FirstName	First name (User)	Payer's first name
RiskFactors.PayerProfile.LastName	Last name (User)	Payer's last name
RiskFactors.PayerProfile.CreationDate	n/a (used only for scoring)	The creation date and time of the payer's account in the merchant's system.
RiskFactors.PayerProfile.Email	Email	Payer's e-mail address.
RiskFactors.PayerProfile.Phone.Main	Phone number (User)	Payer's phone number
RiskFactors.DeviceFingerprintTransactionId	Device ID (via Merchant)	Unique ID given by the merchant. This field is only used in conjunction with the Device Fingerprinting functionality.

Deprecated Fields

This fields are not in use anymore:

JSON API
Payer.BillingAddress.DateOfBirthPayer.BillingAddress.DateOfBirth
Order.Items[].VariantIdOrder.Items[].VariantId
Order.Items[].IsPreOrderOrder.Items[].IsPreOrder
Payer.BillingAddress.PhonePayer.BillingAddress.Phone
Payer.DeliveryAddress.PhonePayer.DeliveryAddress.Phone
RiskFactors.PayerProfile.HasAccountRiskFactors.PayerProfile.HasAccount
RiskFactors.PayerProfile.HasPasswordRiskFactors.PayerProfile.HasPassword
RiskFactors.PayerProfile.PasswordForgottenRiskFactors.PayerProfile.PasswordForgotten
RiskFactors.PayerProfile.DateOfBirthRiskFactors.PayerProfile.DateOfBirth
RiskFactors.PayerProfile.LastLoginDateRiskFactors.PayerProfile.LastLoginDate
RiskFactors.PayerProfile.GenderRiskFactors.PayerProfile.Gender
RiskFactors.PayerProfile.SecondaryEmailRiskFactors.PayerProfile.SecondaryEmail
RiskFactors.PayerProfile.Phone.MobileRiskFactors.PayerProfile.Phone.Mobile
RiskFactors.PayerProfile.Phone.WorkRiskFactors.PayerProfile.Phone.Work

Device Fingerprinting

If Devide Fingerprinting is enabled, the following additional data points are available:

Name in MS DFP	Description
Device ID (via Merchant)	The Device ID given by the Merchant
True IP	The identified IP address of the device
Device state	State of the approximate device location
Device city	City of the approximate device location
Device postal code	ZIP code of the approximate device location
Proxy	Example "yes" or "no"
Screen resolution	Example "2560x1440"

Example

Here you can see an example Payment Page Initialize request. Note that the containers and parameters are, of course, consistent throughout the whole API:

{
  "RequestHeader": {
    "SpecVersion": "<insert current spec-version here>",
    "CustomerId": "<insert your customer id here>",
    "RequestId": "798b38f3176f4eb1bc6ce36e946d10ba",
    "RetryIndicator": 0
  },
  "TerminalId": "<insert your terminal id here>",
  "Payment": {
    "Amount": {
    "Value": "55000",
    "CurrencyCode": "EUR"
  },
  "OrderId": "AB-12345.xyz",
  "Description": "Your order #AB-12345.xyz"
  },
  "Payer": {
    "IpAddress": "127.0.0.1",
    "DeliveryAddress": {
      "FirstName": "John",
      "LastName": "Doe",
      "Gender": "MALE",
      "Street": "Notreal road 42",
      "Zip": "12346",
      "City": "Sometown",
      "CountryCode": "US",
      "DateOfBirth": "2001-01-01"
    }
  },
  "ReturnUrls": {
    "Success": "https://yourshop/payment-success",
    "Fail": "https://yourshop/payment-failed",
    "Abort": "https://yourshop/payment-aborted"
  },
  "Notification": {
    "NotifyUrl": "https://yourshop/payment-notify"
  },
  "Order": {
    "Items": [
      {
        "Type": "PHYSICAL",
        "Id": "BAAA-BPTENT",
        "Name": "Awesome Tent",
        "Description": "Backpacking Tent with room for 3 people, in red.",
        "Quantity": 1,
        "UnitPrice": "25000"
      },
      {
        "Type": "GIFTCARD",
        "Id": "EVCHR-HIKE",
        "VariantId": "EVCHR-HIKE-300",
        "Name": "Hiking vacation voucher",
        "Description": "Enjoy the vacation with your friends!",
        "Quantity": 2,
        "UnitPrice": "30000",
        "IsPreOrder": false
      }
    ]
  },
  "RiskFactors": {
    "DeliveryType": "SHOP",
    "AccountCreationDate": "2019-02-21T12:04:43Z",
    "PasswordLastChangeDate": "2019-12-23T16:36:43Z"
  }
}

Device Fingerprinting

Device Fingerprinting is a process to identify and track devices across websites through a central service. The data collected is used to identify malicious devices and thusly to prevent fraud.

The Saferpay Fraud Intelligence solution does offer possibilities to benefit from such a process, however it needs additional integration steps, in order to function.

Preparation

Before you can start integrating, please contact [e-mail] in order to get your so called instanceId, which is important for this service to function.

Integration

The integration of the Device Fingerprinting service is done on client-side via JavaScript.

It is imperative, that this script is called before the Saferpay payment is initialized.

Code Sample

<html>
  <head>
    <title>Device Fingerprint Example</title>
    <script src="https://code.jquery.com/jquery-3.6.4.min.js"></script>
    <script>
      $(function(){
        // Construct dfpScriptUrl:
        var dfpBaseUrl = "https://devicefingerprint.pay.checkout.worldline-solutions.com/mdt.js?";
        var dfpScriptUrl = dfpBaseUrl + decodeURIComponent($.param({
        session_id: "[UNIQUE SESSION ID]", // This sessionId must be unique for this transaction and is later forwarded to Saferpay
        instanceId: "[INSTANCE_ID]", // The ID you got in the previous step
        pageId: "P" // Don't change this value!
      }));
 
     // Load the DFP script:
     console.log("DFP: Loading script from " + dfpScriptUrl);
     $.getScript(dfpScriptUrl)
       .done(function(){
         // Execute the DFP script:
         window.dfp.doFpt(document);
         console.log("DFP: Script successfully executed - see the browser console Network tab for details");
       })
       .fail(function(){
         // Something went wrong:
         console.log("DFP: Something went wrong");
       });
   });
   </script>
   </head>
   <body>
     <h1>Device Fingerprint Test</h1>
     Press Shift + CTR + J to open the browser console
   </body>
</html>

Explanation

The above script creates the fingerprint itself and directly submits the data towards the Fraud Intelligence service.

• dfpBaseUrl: This URL static and provided by us. It will change shortly and we'll then inform what the new URL is.

• session_id: A unique id generated by you which is diferent for each transaction. It is also used by Saferpay, see the next step.

• instanceId: The instanceId which was given to you by the DFP support

• pageId: This value always needs to be "P" which stands for "Prevention" and helps to route the data to the right location.

Saferpay Integration

Once the above script has been successfully initialized and the necessary device-fingerprint has been created, you can initialize the Saferpay Payment.

It is however important, that you share the unique session_id you previously created with Saferpay. You do so, by submitting it inside the RiskFactors.DeviceFingerprintTransactionId parameter, via either the PaymentPage Initialize, or Transaction Initialize request, depending on your integration.

Risk Score

The Fraud Intelligence module uses artificial intelligence to calculate a Risk Score from all available data. This Risk Score is an indicator how risky the transaction is: A transaction with a high Risk Score generally has a higher propability to be fraudulent than a transaction with a low risk score.

Rules

Rules are used to configure the individual risk appetite of a merchant and to make a decision based on the calculated Risk Score and other criteria. For example, a simple rule could block all transactions with a Risk Score higher than x. A rule can also combine multiple conditions such as velocity thresholds and check other data points, which allows to model complex business requirements and manually block specific fraud scenarios.

Responses

Success

In case of a success, the transaction response will also carry additional information inside the FraudPrevention.Result parameter. This can have one of two values: APPROVED and MANUAL_REVIEW.

In both cases, the transaction was indeed successful. However, the latter indicates that there may be issues with this transaction, which need to be reviewed manually.

It is then up to you, the merchant, to either accept or decline this transaction.

 "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Transaction": {
    "Type": "PAYMENT",
    "Status": "AUTHORIZED",
    "Id": "MUOGAWA9pKr6rAv5dUKIbAjrCGYA",
    "Date": "2015-09-18T09:19:27.078Z",
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    },
    "AcquirerName": "AcquirerName",
    "AcquirerReference": "Reference",
    "SixTransactionReference": "0:0:3:MUOGAWA9pKr6rAv5dUKIbAjrCGYA",
    "ApprovalCode": "012345"
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "VISA",
      "Name": "VISA Saferpay Test"
    }
  },
  "DisplayText": "9123 45xx xxxx 1234",
  "Card": {
    "MaskedNumber": "912345xxxxxx1234",
    "ExpYear": 2015,
    "ExpMonth": 9,
    "HolderName": "Max Mustermann",
    "CountryCode": "CH"
  },
  "Payer": {
    "IpAddress": "1.2.3.4",
    "IpLocation": "DE"
  },
  "Liability": {
    "LiabilityShift": true,
    "LiableEntity": "ThreeDs",
    "ThreeDs": {
      "Authenticated": true,
      "LiabilityShift": true,
      "Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs=",
      "VerificationValue": "AAABBIIFmAAAAAAAAAAAAAAAAAA="
    }
  },
  "FraudPrevention": {
    "Result": "MANUAL_REVIEW"
  }
}

Failure

In case of a decline, Saferpay will throw a appropriate error, also containing the reason.

{
    "ResponseHeader": {
        "SpecVersion": "<current spec-version>",
        "RequestId": "1"
    },
    "Risk": {
        "BlockReason": "BLACKLIST_IP",
        "IpLocation": "CH"
    },
    "Behavior": "ABORT",
    "ErrorName": "BLOCKED_BY_RISK_MANAGEMENT",
    "ErrorMessage": "Blocked by fraud detection"
}

Feedback to Fraud Intelligence Hub

These responses will in return be transferred to the Fraud Intelligence Hub for further Risk analysis and overview purposes.

Note, that this currently only happens for normal debit transactions. Other transactions, like refunds, are currently not included.