Integrate with Risk.js

Last updated: May 10, 2023

To maximize the efficiency of our Fraud Detection solution, you should integrate our Risk.js package for every customer-initiated payment flow.

Risk.js captures multiple fraud signals to leverage in the fraud score, including:

device identification
precise geolocation
spoofing attempts

You can then set up automated actions based on the final score using custom rules.

To integrate 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/risk.js" /></script>


1<script id="risk-js" async src="https://risk.checkout.com/cdn/risk/1/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 customer 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 backend 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": "john.smith@example.com"
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 you have any questions or issues, contact fraud-detection@checkout.com.

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

For the sandbox environment:


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

For the production environment:


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

Risk.js is natively integrated and fully compatible with our Frames solution. This means that Checkout.com is able to collect device data and correlate it for single-use token-based payments generated by Frames.js. 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.js on your checkout page. This is to correlate the customer's device session, as the Frames.js 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 Risk.js.

The Risk.js package can be integrated in iOS and Android applications with a hidden web view.

We've made some changes to our API

Integrate with Risk.js

Integrate the package

Note

Content Security Policies

Compatibility with Frames.js

Compatibility with mobile SDKs