Integrate with Risk SDK

Last updated: October 16, 2024

To maximize the efficiency of our Fraud Detection solution, you should integrate with one of our Risk SDKs for every shopper-initiated payment flow.

The Risk SDK captures advanced fraud signals that are leveraged in our fraud scoring machine learning model. These signals include:

Device identification
Precise geolocation
Spoofing attempts
Fingerprinting data

Every payment enriched with shopper’s device data is scored against our dedicated device machine learning model. You can use our machine learning model in your risk strategy through:

A machine-learning risk profile
The :score: threshold rule property

Information

Our device-enriched model offers 2x performance in comparison with our general model.

The device signals captured by Risk SDK integration can be used in custom rules to build risk strategies.

Property	Sample values	Description
`:device_fingerprint:`	rekyngyfnrte3ckzvgjlhw4jfm	Checkout.com’s device fingerprint. Unique to each device. If the flow is web based, then the value is unique for each browser.
`:device_ip:`	10.256.35.48	The IP address collected on the device. If `:payment_ip:` is omitted in the payment request, the rule property will fallback to `:device_ip:`.
`:device_ip_country:`	GB	The ISO-2 country code associated with the collected device IP.
`:device_ip_city:`	London	The city associated with the geolocation IP.
`:device_model:`	iPhone, iPad, Generic Smartphone, Laptop, Other, Samsung, Pixel 5	The device model.
`:device_os_version:`	13.3	The device’s operating system (OS) version.
`:device_browser:`	Chrome, Chrome Mobile iOS, Safari, Firefox, Opera	The device's browser used. Applicable for web flows only.
`:device_timezone:`	Europe/London	The timezone of IP associated with the device.
`:device_browser_is_incognito:`	true, false	Indicates whether the device browser is in incognito mode. Applicable for web flows only.

Information

The device signals are displayed on the Payments > Processing > All Payments > Payment details section on the Dashboard, and in the downloadable transaction reports for offline analysis.

You can choose to integrate with one of the following:

Information

To enable access to the Risk SDKs, contact your Account Manager or [email protected].

Integrate with Risk.js

Attach the risk.js script tag to your Checkout.com page.


1<script id="risk-js" async src="https://risk.sandbox.checkout.com/cdn/risk/1.2/risk.js"></script>


1<script id="risk-js" async src="https://risk.checkout.com/cdn/risk/1.2/risk.js"></script>

Wait for the script to load before you use the package:


1const script = document.getElementById('risk-js');
2
3script.addEventListener('load', () => {
4  // use Risk.js here
5});

Initialize Risk.js with your public key. You can generate public keys in the Dashboard.


1const risk = window.Risk.init("pk_XXXX");

When the shopper selects Pay, publish the device data and retrieve the deviceSessionId.


1const deviceSessionId = await risk.publishRiskData(); // dsid_XXXX

Note

The data collection session will expire if you do not perform a payment request within 20 minutes of the deviceSessionId being issued.

Forward the deviceSessionId to your back-end server.
Include the deviceSessionId inside the risk object of the POST/payments request.


1{
2  "source": {
3    "type": "card",
4    "number": "4242424242424242",
5    "expiry_month": "6",
6    "expiry_year": "2024",
7    "name": "John Smith"
8  },
9  "amount": "100",
10  "currency": "USD",
11  "risk": {
12    "device_session_id": "dsid_ipsmclhxwq72phhr32iwfvrflm"
13  },
14  "customer": {
15    "email": "[email protected]"
16  },
17  "reference": "order_1234",
18  "shipping": {
19    "address": {
20      "address_line1": "123 Anywhere St.",
21      "city": "Anytown",
22      "zip": "123456",
23      "country": "US"
24    }
25  },
26  "payment_ip": "10.3.1.1",
27  "metadata": {
28    "coupon_code": 1234
29  }
30}

If your website has Content Security Policy (CSP) headers set up, allow the following directives:


1script-src [...] https://risk.sandbox.checkout.com
2connect-src [...] https://fpjs.sandbox.checkout.com https://fpjscache.sandbox.checkout.com;


1script-src [...] https://risk.checkout.com
2connect-src [...] https://fpjs.checkout.com https://fpjscache.checkout.com;

The Risk SDK is natively integrated and fully compatible with our Frames solution (Frames iOS as of v4.3.2 and Frames Android as of v4.2.2). This means that Checkout.com is able to collect device data and correlate it for single-use, token-based payments generated by Frames. For example, payments where source.type is set to token.

If you plan to allow your customers to make payments with stored payment details, you will need to integrate Risk SDK on your checkout page. This is to correlate the customer's device session, as the Frames form would not be involved in the checkout flow. This applies to payments requested using a payment instrument (source.type set to id), or a customer object (source.type set to customer).

If you do not plan on storing reusable card identifiers, you do not need to integrate the Risk SDK.

Integrate with Risk SDK

Information

Properties for custom rules

Information

Integration options

Information

Integrate Risk.js package

Note

Content Security Policies

Compatibility with Frames