> For the complete documentation index, see [llms.txt](https://docs.saferpay.com/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/fraud-intelligence/fraud-intelligence.md). # 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 ](/home/master/licensing.md)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](/home/integration-guide/payment-methods/visa-and-vpay.md) * [Mastercard](/home/integration-guide/payment-methods/mastercard.md)/[Maestro](/home/integration-guide/payment-methods/maestro.md) * [American Express](/home/integration-guide/payment-methods/american-express.md) * [Bancontact](/home/integration-guide/payment-methods/bancontact.md) * [Diners Club](/home/integration-guide/payment-methods/diners-and-discover.md) * [JCB](/home/integration-guide/payment-methods/jcb.md) * [PayPal](/home/integration-guide/payment-methods/paypal.md) * [Unionpay](/home/integration-guide/payment-methods/china-unionpay.md) * [Wero](/home/integration-guide/payment-methods/wero.md) Currently, the following flows are supported: * [Payment Page](/home/integration-guide/licences-and-interfaces/payment-page.md) * [Transaction Interface](/home/integration-guide/licences-and-interfaces/transaction-interface.md), including [Saferpay Fields](/home/integration-guide/licences-and-interfaces/saferpay-fields.md) * [Direct Mode for Bancontact](/home/integration-guide/payment-methods/bancontact.md#bancontact-direct-mode) * [Recurring Transactions](/home/integration-guide/licences-and-interfaces/transaction-interface/recurring-payments.md) ## 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](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_Initialize) or [Payment Page Initialize](https://saferpay.github.io/jsonapi/#Payment_v1_PaymentPage_Initialize). {% hint style="info" %} All of these datapoints are generally optional. However the detection will work better the more data are provided. {% endhint %} The following data points can be set via the JSON API: {% hint style="info" %} An Asterisk ( \* ) means, that it is recommended to submit the whole container, if there are multiple parameters inside it, unless there is specific information below, about one of the parameters being optional. Please also see the given request [specification](broken://pages/-MKKE4mUq1quqn3q1rpp) for details. {% endhint %} | JSON API | | ------------------------------------------------------------------------------------------------------------- | | Payment.Amount.\* | | Payer.DeliveryAddress.\* | | Payer.BillingAddress.\* | | Payer.IpAddress | | Payer.Ipv6Address | | RiskFactors.\* | | RiskFactors.DeviceFingerprintTransactionId (If [Device Fingerprinting](#device-fingerprinting) is to be used) | | Order.Items\[].\* | ### Example Here you can see an example [Payment Page Initialize](https://saferpay.github.io/sndbx/fraugster.html) request. Note that the containers and parameters are, of course, consistent throughout the whole API: ```json { "RequestHeader": { "SpecVersion": "", "CustomerId": "", "RequestId": "798b38f3176f4eb1bc6ce36e946d10ba", "RetryIndicator": 0 }, "TerminalId": "", "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 thus 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 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 the client side via script. {% hint style="warning" %} It is imperative that this script is called before the Saferpay payment is initialized. {% endhint %} #### Code Sample ```html ``` **Parameter explanation** * **ORG\_ID**: This ID must have one of the following values, given the environment: * Sandbox/Preprod: **1snn5n9w** * Live: **k8vif92e** * **CYB\_MERCHANTID:** Your Fraud Intelligence customer ID. You will get this information [upon contacting us](#preparation). * **GUID:** Unique identifier for this session, generated by the merchant system. **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/GUID`** (**not including the CYB\_MERCHANTID!**) you previously created with Saferpay. You do so by submitting it inside the **`RiskFactors.DeviceFingerprintTransactionId`** parameter via either the [**PaymentPage Initialize**](https://saferpay.github.io/jsonapi/#Payment_v1_PaymentPage_Initialize) or [**Transaction Initialize**](https://saferpay.github.io/jsonapi/#Payment_v1_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 of how risky the transaction is: A transaction with a high Risk Score generally has a higher probability 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. ```json "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 an appropriate error, also containing the reason. ```json { "ResponseHeader": { "SpecVersion": "", "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. {% hint style="warning" %} Note, that this currently only happens for normal debit transactions. Other transactions, like refunds, are currently not included. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/fraud-intelligence/fraud-intelligence.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.