Fraud Prevention

Fraud Prevention is a Saferpay module that protects merchants from fraudulent online transactions. It relies on Fraugster's industry-leading AI technology and allows merchants to dynamically react on suspicious behavior and even prevent transactions with malicious intent, during runtime. This chapter will cover the technical aspects on how to integrate Fraud Prevention in your application.

Requirements

  • The corresponding Saferpay eCommerce licence and thus the existence of 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 Prevention 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
  • Bonus Card
  • MyOne
  • PayPal

Currently, the following flows are supported:

Activation

After the activation of the Fraud Prevention module on your account, you will have access to the options under Risk & Fraud > Fraud Prevention settings . There you can find a list of all supported payment methods, for which you can either fully activate the fraud prevention, or select the payment methods alt text

Training

The Fraud Prevention module uses artificial intelligence algorithms and a pre-defined set of rules in order to provide protection against fraud. This means, that the detection quality will improve itself over time, as it adapts itself to the merchant's needs.

Datapoints

In order for the training and also the detection to work properly, the system needs to be provided with a set of datapoints with each transaction. Some are provided automatically by Saferpay, while others need to be submitted by the merchant-system, with the initial request, when starting the transaction, like the Transaction Initialize or Payment Page Initialize.

Note: All of these datapoints are generally optional. However the detection will work better, the more data it has, to do its risk evaluation!

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

Fire Datapoint JSON API Description
trans_amt Payment.Amount.Value The transaction amount.
trans_currency Payment.Amount.CurrencyCode The transaction currency.
cc_num (see description) The used PAN. Note that this value usually comes directly from the card holder and not the merchant directly. Also note that, if you should use Secure Card Data, the PAN behind the provided alias will, of course, be used.
cust_email Payer.DeliveryAddress.Email The customers E-Mail address.
ip Payer.IpAddress The customers IP-address.
cust_dob Payer.BillingAddress.DateOfBirth The customers date of birth.
cust_signup_ts RiskFactors.AccountCreationDate The customers date of signup to the merchant shop.
password_update_ts RiskFactors.PasswordLastChangeDate The date, when the customer last changed his/her password.
items Order.Items[] Array of all the shopping cart items.
item_id Order.Items[].Id Identifier of the product. This ID is created and provided by the merchant!
unique_item_id Order.Items[].VariantId Identifier of the product-variant. This ID is created and provided by the merchant!/td>
item_desc Order.Items[].Name Name of the product, given by the merchant.
additional_description Order.Items[].Description Description of the product, given by the merchant.
item_amt Order.Items[].UnitPrice Price of the product.
quantity Order.Items[].Quantity Quantity ordered of this specific item.
item_category Order.Items[].CategoryName Product category, given by the merchant.
item_type Order.Items[].Type Product type. Has to be one of the following: DIGITAL|PHYSICAL|SERVICE|GIFTCARD
includes_giftcard Order.Items[].IsPreOrder Boolean, whether the item is a giftcard.
includes_preorder Order.Items[].IsPreOrder Boolean, whether the item is a pre-ordered item.
delivery_method RiskFactors[].DeliveryType The used delivery method, for the carts items. Has to be one of the following:
  • EMAIL: The basket 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.
Fire Datapoint JSON API Description
bill_ad_city Payer.BillingAddress.City Billing address city
bill_ad_ctry Payer.BillingAddress.Country Billing address country
bill_ad_first_name Payer.BillingAddress.FirstName Billing address first name
bill_ad_last_name Payer.BillingAddress.LastName Billing address last name
bill_ad_line1 Payer.BillingAddress.Street Billing address street
bill_ad_line2 Payer.BillingAddress.Street2 Additional billing address street information (e.g. PO Box)
bill_ad_zip Payer.BillingAddress.Zip Billing address zip code
phone Payer.BillingAddress.Phone Billing address phone number
ship_ad_city Payer.DeliveryAddress.City Shipping address city
ship_ad_ctry Payer.DeliveryAddress.Country Shipping address country
ship_ad_first_name Payer.DeliveryAddress.FirstName Shipping address first name
ship_ad_last_name Payer.DeliveryAddress.LastName Shipping address last name
ship_ad_line1 Payer.DeliveryAddress.Street Shipping address street
ship_ad_line2 Payer.DeliveryAddress.Street2 Additional shipping address street information (e.g. PO Box)
ship_ad_zip Payer.DeliveryAddress.Zip Delivery address zip code
phone Payer.DeliveryAddress.Phone Delivery address phone number
ship_ad_email Payer.DeliveryAddress.Email Delivery address email address

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",
      "Company": "Test Ltd.",
      "Gender": "MALE",
      "Street": "Notreal road 42",
      "Zip": "12346",
      "City": "Sometown",
      "CountryCode": "US",
      "DateOfBirth": "2001-01-01",
      "Phone": "555707422666701"
    }
  },
  "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",
        "VariantId": "BAAA-BPTENT-RED",
        "Name": "Awesome Tent",
        "Description": "Backpacking Tent with room for 3 people, in red.",
        "Quantity": 1,
        "UnitPrice": "25000",
        "IsPreOrder": false
      },
      {
        "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"
  }
}

Rules

Aside its AI algorithms, Fraugster also offers the option for merchants, to write their own set of rules, which are then incorporated into the evaluation process. For this purpose Fraugster offers its own portal (the Fraugster Dashboard) where merchants can adapt the rules to fit their needs.

Documentation on how to create and manage custom rules can be found in the Fraugster User Guide (you need to log in to the Frauster Dashboard with your own credentials that you received after signing the contract for Saferpay Fraud Prevention).

Responses

Success

In case of a success, the transaction response will aslo 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, inside the Fraugster Dashboard. 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.

{
    "ResponseHeader": {
        "SpecVersion": "<current spec-version>",
        "RequestId": "1"
    },
    "Behavior": "ABORT",
    "ErrorName": "BLOCKED_BY_RISK_MANAGEMENT",
    "ErrorMessage": "Blocked by fraud detection"
}
Back to Top