Skip to content

Improve your Fraud Detection integration

Last updated: December 14, 2022

The effectiveness of our Fraud Detection solution is tied to the quality of data available for use by the rules and machine learning (ML) models.

The more data your integration provides, the higher the level of confidence in the data quality, and the more effective your fraud prevention solution will be.

IntegrationConfidence level

Frames

High

Hosted Payment Pages

High

Payment Links

High

Full card details API with customer data and risk.js

High

Full card details API with customer data

Medium

Full card details API without customer data

Low

You can check your integration score on the risk analytics page of the Fraud Detection solution. We recommend you share the following data points via our payment gateway, and by integrating risk.js on your Checkout.com page.

Data pointImportance for fraud ML model performanceWays to provide data

Billing country

Required

Gateway

Customer email

Required

Gateway

Customer IP address

Required

Gateway, risk.js

Device and browser data

Required

risk.js

Billing postcode

Important

Gateway

Customer name

Important

Gateway

Customer phone

Important

Gateway

Shipping country, postcode

Important

Gateway

Billing street address

Optional

Gateway

Shipping street address

Optional

Gateway


Integrate with risk.js

If you're using our full card details API, we recommend you integrate with our risk.js package. This will enable you to start providing our Fraud Detection solution with device and browser data.

You can integrate risk.js into iOS and Android applications that support web views.

For testing, use the following risk.js script tag:

1
<script id="risk-js" async src="https://prism-qa.ckotech.co/cdn/risk/1/risk.js" />

Information

You do not need to integrate if you already use a Checkout.com form to process payments. For example, using Frames, Hosted Payment Pages, or Payment Links.

To start passing device and browser data to Checkout.com:

  1. Attach the risk.js script tag to your Checkout.com page:
1
<script id="risk-js" async src="https://risk.checkout.com/cdn/risk/1/risk.js" />
  1. Wait for the script to load before using risk.js:
1
const script = document.getElementById('risk-js');
2
3
script.addEventListener('load', () => {
4
// use Risk here
5
})
  1. Initialize the Risk SDK with your public key as follows. You can generate public keys in the Dashboard or Portal.
1
const risk = window.Risk.init("pk_XXXX");
  1. When the customer selects Pay, publish the device data and retrieve the deviceSessionId:
1
const deviceSessionId = await risk.publishRiskData(); // dsid_XXXX

Note

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

  1. Forward the deviceSessionId to your backend server.
  2. Include the deviceSessionId inside the risk object of the POST/payments request.
1
{
2
3
"source": {
4
5
"type": "card",
6
7
"number": "4242424242424242",
8
9
"expiry_month": "6",
10
11
"expiry_year": "2024",
12
13
"name": "John Smith"
14
15
},
16
17
"amount": "100",
18
19
"currency": "USD",
20
21
"customer": {
22
23
"email": "john.smith@example.com"
24
25
},
26
27
"reference": "order_1234",
28
29
"shipping": {
30
31
"address": {
32
33
"address_line1": "123 Anywhere St.",
34
35
"city": "Anytown",
36
37
"zip": "123456",
38
39
"country": "US"
40
41
}
42
43
},
44
45
"payment_ip": "10.3.1.1",
46
47
"risk": {
48
49
"enabled": true,
50
51
"device_session_id": "dsid_ipsmclhxwq72phhr32iwfvrflm"
52
53
},
54
55
"metadata": {
56
57
"coupon_code": 1234
58
59
}
60
61
}

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

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

If you have any questions, please contact fraud-detection@checkout.com.