Interfaces
Integration Guide
Fraud Intelligence Integration
Fraud Intelligence 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 authentication.
This chapter will cover the technical aspects on how to integrate Fraud Intelligence 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 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
- Bonus Card
- MyOne
- PayPal
Currently, the following flows are supported:
Activation
After the activation of the Fraud Intelligence module on your account, you will have access to the options under Risk & Fraud > Fraud Intelligence 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.
Training
The Fraud Intelligence 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.
Data points
In order for the training and the 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:
Fraugster 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, rather than the merchant. 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 customer's E-Mail address.
ip
Payer.IpAddress
The customer's IP-address.
cust_dob
Payer.BillingAddress.DateOfBirth
The customer's date of birth.
cust_signup_ts
RiskFactors.AccountCreationDate
The customer's 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_preorder
Order.Items[].IsPreOrder
Boolean, whether the item is a pre-ordered item.
delivery_method
RiskFactors[].DeliveryType
The used delivery method. Has to be one of the following:
- 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.
Fraugster 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
Fraugster Datapoint
JSON API
Description
cust_exist ing_merchant
RiskFactors.PayerProfile.HasAccount
as the payer got an account with the merchant (as opposed to ordering "as a guest")?
cust_has_password
RiskFactors.PayerProfile.HasPassword
Has the payer got a password in the system?
cust_forgot_password
RiskFactors.PayerProfile.PasswordForgotten
Has the payer forgot and reset his password within the same session of this purchase?
cust_first_name
RiskFactors.PayerProfile.FirstName
Payer's first name
cust_last_name
RiskFactors.PayerProfile.LastName
Payer's last name
cust_company
RiskFactors.PayerProfile.Company
Payer's company name
cust_dob
RiskFactors.PayerProfile.DateOfBirth
Payer's date of birth
cust_last_login_ts
RiskFactors.PayerProfile.LastLoginDate
The date and time of the last login of the payer (if the payer has an account).
cust_gender
RiskFactors.PayerProfile.Gener
Payer's gender.
cust_signu p_ts
RiskFactors.PayerProfile.CreationDate
The creation date and time of the payer's account in the merchant's system.
password_update_ts
RiskFactors.PayerProfile.PasswordLastChange Date
Timestamp when the payer changed his password for the last time
cust_email
RiskFactors.PayerProfile.Email
Payer's e-mail address.
cust_scndry_email
RiskFactors.PayerProfile.SecondaryEmail
Payer's secondary e-mail address.
phone
RiskFactors.PayerProfile.Phone.Main
Payer's phone number
phone_mobile
RiskFactors.PayerProfile.Phone.Mobile
Payer's mobile phone number
phone_work
RiskFactors.PayerProfile.Phone.Work
Payer's work phone number
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:
1
{
2
"RequestHeader": {
3
"SpecVersion": "<insert current spec-version here>",
4
"CustomerId": "<insert your customer id here>",
5
"RequestId": "798b38f3176f4eb1bc6ce36e946d10ba",
6
"RetryIndicator": 0
7
},
8
"TerminalId": "<insert your terminal id here>",
9
"Payment": {
10
"Amount": {
11
"Value": "55000",
12
"CurrencyCode": "EUR"
13
},
14
"OrderId": "AB-12345.xyz",
15
"Description": "Your order #AB-12345.xyz"
16
},
17
"Payer": {
18
"IpAddress": "127.0.0.1",
19
"DeliveryAddress": {
20
"FirstName": "John",
21
"LastName": "Doe",
22
"Company": "Test Ltd.",
23
"Gender": "MALE",
24
"Street": "Notreal road 42",
25
"Zip": "12346",
26
"City": "Sometown",
27
"CountryCode": "US",
28
"DateOfBirth": "2001-01-01",
29
"Phone": "555707422666701"
30
}
31
},
32
"ReturnUrls": {
33
"Success": "https://yourshop/payment-success",
34
"Fail": "https://yourshop/payment-failed",
35
"Abort": "https://yourshop/payment-aborted"
36
},
37
"Notification": {
38
"NotifyUrl": "https://yourshop/payment-notify"
39
},
40
"Order": {
41
"Items": [
42
{
43
"Type": "PHYSICAL",
44
"Id": "BAAA-BPTENT",
45
"VariantId": "BAAA-BPTENT-RED",
46
"Name": "Awesome Tent",
47
"Description": "Backpacking Tent with room for 3 people, in red.",
48
"Quantity": 1,
49
"UnitPrice": "25000",
50
"IsPreOrder": false
51
},
52
{
53
"Type": "GIFTCARD",
54
"Id": "EVCHR-HIKE",
55
"VariantId": "EVCHR-HIKE-300",
56
"Name": "Hiking vacation voucher",
57
"Description": "Enjoy the vacation with your friends!",
58
"Quantity": 2,
59
"UnitPrice": "30000",
60
"IsPreOrder": false
61
}
62
]
63
},
64
"RiskFactors": {
65
"DeliveryType": "SHOP",
66
"AccountCreationDate": "2019-02-21T12:04:43Z",
67
"PasswordLastChangeDate": "2019-12-23T16:36:43Z"
68
}
69
}
Copied!
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 Fraugster Dashboard with your own credentials you received after signing the contract for Saferpay Fraud Intelligence).
Transaction Risk Analysis
Additionally to applying normal anti-fraud rules, the Fraud Intelligence service is also capable of automatically applying the TRANSACTION_RISK_ANALYSIS SCA exemption in compliance with the PSD2 law. If a transaction is deemed a low fraud risk, this exemption can be applied automatically, in order to avoid the need of Strong Consumer Authentication.
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, inside the Fraugster Dashboard.
It is then up to you, the merchant, to either accept or decline this transaction.
1
"ResponseHeader": {
2
"SpecVersion": "[current Spec-Version]",
3
"RequestId": "[your request id]"
4
},
5
"Transaction": {
6
"Type": "PAYMENT",
7
"Status": "AUTHORIZED",
8
"Id": "MUOGAWA9pKr6rAv5dUKIbAjrCGYA",
9
"Date": "2015-09-18T09:19:27.078Z",
10
"Amount": {
11
"Value": "100",
12
"CurrencyCode": "CHF"
13
},
14
"AcquirerName": "AcquirerName",
15
"AcquirerReference": "Reference",
16
"SixTransactionReference": "0:0:3:MUOGAWA9pKr6rAv5dUKIbAjrCGYA",
17
"ApprovalCode": "012345"
18
},
19
"PaymentMeans": {
20
"Brand": {
21
"PaymentMethod": "VISA",
22
"Name": "VISA Saferpay Test"
23
}
24
},
25
"DisplayText": "9123 45xx xxxx 1234",
26
"Card": {
27
"MaskedNumber": "912345xxxxxx1234",
28
"ExpYear": 2015,
29
"ExpMonth": 9,
30
"HolderName": "Max Mustermann",
31
"CountryCode": "CH"
32
},
33
"Payer": {
34
"IpAddress": "1.2.3.4",
35
"IpLocation": "DE"
36
},
37
"Liability": {
38
"LiabilityShift": true,
39
"LiableEntity": "ThreeDs",
40
"ThreeDs": {
41
"Authenticated": true,
42
"LiabilityShift": true,
43
"Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs=",
44
"VerificationValue": "AAABBIIFmAAAAAAAAAAAAAAAAAA="
45
}
46
},
47
"FraudPrevention": {
48
"Result": "MANUAL_REVIEW"
49
}
50
}
Copied!
Failure
In case of a decline, Saferpay will throw a appropriate error, also caontaining the reason.
1
{
2
"ResponseHeader": {
3
"SpecVersion": "<current spec-version>",
4
"RequestId": "1"
5
},
6
"Risk": {
7
"BlockReason": "BLACKLIST_IP",
8
"IpLocation": "CH"
9
},
10
"Behavior": "ABORT",
11
"ErrorName": "BLOCKED_BY_RISK_MANAGEMENT",
12
"ErrorMessage": "Blocked by fraud detection"
13
}
Copied!
Copy link