# Risk.js SDK

`Version 4.1.0`

The Risk.js SDK supports the [Fraud Detection](https://www.checkout.com/docs/business-operations/prevent-fraud.md) solution by capturing advanced fraud signals that are leveraged in Checkout.com's machine learning model for risk scores.

> **Information**
>
> To enable access to the SDK, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes).
>
> For more information, see [Integrate with Risk SDK](https://www.checkout.com/docs/business-operations/prevent-fraud/integrate-with-risk-sdk.md).

---

## Before you start

Generate a [public API key](https://www.checkout.com/docs/developer-resources/api/manage-api-keys/api-keys.md#Public_API_keys) from your [Dashboard](https://dashboard.checkout.com).

---

## How it works

1. Import the SDK.
2. Initialize the SDK.
3. Publish the device data.
4. Allow Content Security Policies.

---

## Import the SDK

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

**Sandbox**

```html
<script
  id="risk-js" defer
  src="https://risk.sandbox.checkout.com/cdn/risk/4.1.0/risk.js"
  integrity="sha384-KaurwuezIoMGaRHWXtBqmQG4TLP3gj+iV13/0I6r4YW1/zse+PWLxCamr5QwpUnn"
  crossorigin="anonymous"
></script>
```

**Production**

```html
<script
  id="risk-js" defer
  src="https://risk.checkout.com/cdn/risk/4.1.0/risk.js"
  integrity="sha384-xa8HwcYvFZ++H7IkHlsKyI926/Kc+RheJn6vghIyYTi/kHLWi6t+FACkI0xwu59p"
  crossorigin="anonymous"
></script>
```

2. Wait for the script to load and then use Risk.js:

```javascript
const script = document.getElementById('risk-js');

script.addEventListener('load', () => {
  // Use Risk.js here
});
```

---

## Initialize the SDK

Before the customer selects _Pay_, initialize Risk.js using your public API key and MSSD, which you can find in [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md):

```javascript
const risk = await window.Risk.create("pk_XXXX", "XXXXXXXX");
```

Optionally, you can pass a configuration object as the third argument:

```javascript
const risk = await window.Risk.create("pk_XXXX", "XXXXXXXX", { timeoutMs: 1500 });
```

The optional `timeoutMs` property controls how long to wait for the SDK to be ready, and how long the device data submission to our API can take. The default value for `timeoutMs` is `1000` (1 second). If either operation exceeds this limit, `Risk.create()` or `risk.publishRiskData()` throw an error.

---

## Publish the device data

1. Publish the device data and retrieve the `deviceSessionId`:

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

> **Note**
>
> The data collection session expires if you do not perform a payment request within 20 minutes after the `deviceSessionId` is issued.

2. Forward the `deviceSessionId` to your back-end server.

3. When you call the [Request a payment or payout](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint, include the `deviceSessionId` in the `risk` object:

### Request example

```json
{
  "source": {
    "type": "card",
    "number": "4242424242424242",
    "expiry_month": "6",
    "expiry_year": "2024",
    "name": "John Smith"
  },
  "amount": "100",
  "currency": "USD",
  "risk": {
    "device_session_id": "dsid_ipsmclhxwq72phhr32iwfvrflm"
  },
  "customer": {
    "email": "john.smith@example.com"
  },
  "reference": "order_1234",
  "shipping": {
    "address": {
      "address_line1": "123 Anywhere St.",
      "city": "Anytown",
      "zip": "123456",
      "country": "US"
    }
  },
  "payment_ip": "10.3.1.1",
  "metadata": {
    "coupon_code": 1234
  }
}
```

---

## Allow Content Security Policies

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

**Sandbox environment**

```javascript
script-src [...] https://risk.sandbox.checkout.com;
connect-src [...] https://fpjs.sandbox.checkout.com https://fpjscache.sandbox.checkout.com;
frame-src [...] https://risk.sandbox.checkout.com;
```

**Production environment**

```javascript
script-src [...] https://risk.checkout.com;
connect-src [...] https://fpjs.checkout.com https://fpjscache.checkout.com;
frame-src [...] https://risk.checkout.com;
```