Integrate with Risk SDK

Last updated: December 18, 2024

To maximize the efficiency of the Fraud Detection solution, integrate with a Checkout.com Risk SDK for every customer-initiated payment flow.

Information

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

Checkout.com offers three Risk SDKs:

The SDKs capture advanced fraud signals that are leveraged in our machine-learning model, including:

Device identification
Precise geolocation
Spoofing attempts
Fingerprinting data

Every payment enriched with the customer’s device data is scored against our machine-learning model for devices. You can implement this model in your risk strategy through:

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

Information

The device-enriched model performs two times better than the model without device data.

The Risk SDK does not support the following frameworks:

Cordova
Flutter
.NET MAUI / Xamarin
React Native

You can use the following device signal properties captured by the SDKs in your own risk-strategy rules.

Property	Sample values	Description
`:device_fingerprint:`	`rekyngyfnrte3ckzvgjlhw4jfm`	The Checkout.com device fingerprint, which is unique to each device. For web flows, this value is unique to each browser.
`:device_ip:`	`10.256.35.48`	The device's IP address. If `:payment_ip:` is omitted in the payment request, the rule property falls back to `:device_ip:`.
`:device_ip_country:`	`GB`	The ISO-2 country code associated with the device's IP address.
`:device_ip_city:`	`London`	The city associated with the geolocation IP address.
`:device_model:`	`Generic Smartphone` `iPad` `iPhone` `Laptop` `Other` `Pixel 5` `Samsung`	The device model.
`:device_os:`	`Android` `Chrome OS` `iOS` `Linux` `Mac OS X` `Windows`	The device’s operating system (OS).
`:device_os_version:`	`13.3`	The version of the device’s operating system.
`:device_browser:`	`Chrome` `Chrome Mobile iOS` `Firefox` `Opera` `Safari`	For web flows, the browser used on the device.
`:device_timezone:`	`America/Chicago` `Asia/Singapore` `Europe/London`	The timezone of device's IP address.
`:device_browser_is_incognito:`	`false` `true`	For web flows, indicates whether the device browser is in incognito mode.

You can view the device signals in the Dashboard:

Sign in to the Dashboard.
Go to Payments > Processing > All payments.
Select the relevant payment to open the Payment details page.

To view the signals offline, download the transaction report.

To integrate the Risk.js SDK, you need your public API key.

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 using your public API key.


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

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


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

Note

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

Forward the deviceSessionId to your back-end server.
When you call the Request a payment or payout endpoint, include the deviceSessionId in the risk object.


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 the Frames solution:

Frames Android from v4.2.2
Frames iOS from v4.3.2

Checkout.com can 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 your customers can make payments using stored payment details, you must integrate a Risk SDK on your checkout page. The SDK correlates the customer's device session, because the Frames form is not involved in the checkout flow. This applies to payments requested using one of the following:

A payment instrument with source.type set to id
A customer object with source.type set to customer

Information

If you do not store reusable card identifiers, you do not need to integrate a Risk SDK.

Integrate with Risk SDK

Information

How it works

Information

Unsupported frameworks

Properties for custom rules

View device signals

Risk.js integration

Note

Request example

Content Security Policies

Compatibility with Frames

Information