> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Payrails Web Fraud SDK

> Initialize the Payrails fraud SDK to collect device signals from several fraud providers behind one interface, for the web SDK.

## Payrails Fraud SDK provides abstraction on different fraud client SDKs

The SDK should be initialized as soon as possible to enable data collection as soon as possible. The SDK will then pass all the information needed to the Payrails Web SDK without additional work on the merchant client.

## Including the SDK

```typescript theme={null}
import { FraudSDK } from "@payrails/fraud-sdk";
```

## Loading specific fraud providers

The load function accepts an array of providers with merchant specific configurations.

```typescript theme={null}
import { FraudSDK } from "@payrails/fraud-sdk";

// Pass an array of providers
FraudSDK.load([
  {
    provider: "provider name",
    // specific provider options
  },
]);
```

## Supported providers

### Cybersource

To initialize the Cybersource provider, `merchantId` and `orgId` needs to be passed.

```typescript theme={null}
import { FraudSDK, FraudProvider } from "@payrails/fraud-sdk";

// Pass an array of providers
FraudSDK.load([
  {
    provider: FraudProvider.CYBERSOURCE,
    merchantId: "merchantId",
    orgId: "orgId",
  },
]);
```

### Forter

To initialize the Forter provider, `siteId` needs to be passed.

```typescript theme={null}
import { FraudSDK } from "@payrails/fraud-sdk";

// Pass an array of providers
FraudSDK.load([
  {
    provider: FraudProvider.FORTER,
    siteId: "siteId",
  },
]);
```

### Ravelin

To initialize the Ravelin provider, `key` needs to be passed.

```typescript theme={null}
import { FraudSDK } from "@payrails/fraud-sdk";

// Pass an array of providers
FraudSDK.load([
  {
    provider: FraudProvider.RAVELIN,
    key: "ravelinPublicKey",
  },
]);
```

### Airwallex

Requires `environment` parameter. `orderSessionId` is optional and auto-generated if omitted:

```typescript theme={null}
import { FraudSDK, FraudProvider } from "@payrails/fraud-sdk";

FraudSDK.load([
  {
    provider: FraudProvider.AIRWALLEX,
    environment: "LIVE", // use 'TEST' for sandbox
    orderSessionId: "orderSessionId", // optional
  },
]);
```

### Stripe Radar

To initialize the Stripe Radar provider, `publishableKey` needs to be passed:

```typescript theme={null}
import { FraudSDK, FraudProvider } from "@payrails/fraud-sdk";

FraudSDK.load([
  {
    provider: FraudProvider.STRIPE_RADAR,
    publishableKey: "pk_test_xxx",
  },
]);
```

#### Multiple Stripe accounts

Requires `@payrails/fraud-sdk` 1.9.0 and `@payrails/web-sdk` 6.1.2 or later.

A Radar session is only valid for the Stripe account whose publishable key created it, and Payrails selects the account when the payment is routed, which happens after the session is created. If you process through more than one Stripe account, configure one entry per account, each with that account's own `publishableKey` and the `providerConfigId` of the matching Payrails provider config:

```typescript theme={null}
FraudSDK.load([
  {
    provider: FraudProvider.STRIPE_RADAR,
    publishableKey: "pk_live_accountA_xxx",
    providerConfigId: "11111111-1111-4111-8111-111111111111",
  },
  {
    provider: FraudProvider.STRIPE_RADAR,
    publishableKey: "pk_live_accountB_xxx",
    providerConfigId: "22222222-2222-4222-8222-222222222222",
  },
]);
```

`stripe.js` loads once regardless of how many entries you configure, and one Radar session is created per entry. The Web SDK sends them all when the payment is authorized, and Payrails uses the one matching the account it routed to.

Each entry's publishable key must belong to the account its `providerConfigId` points at. A mismatched pair is not rejected up front and instead surfaces as Stripe declining the payment with `No such radar session`.

With a single Stripe account, omit `providerConfigId` and nothing changes.

### Signifyd

To initialize the Signifyd provider, no required fields are needed. Optionally, pass `orderSessionId` — a merchant-generated session id (fewer than 128 characters, \[a-zA-Z0-9\_-]). If omitted, a UUID is auto-generated. This value is sent to the backend as `device.sessionID`.

```typescript theme={null}
FraudSDK.load([
  {
    provider: FraudProvider.SIGNIFYD,
    orderSessionId: "optional-merchant-session-id", // optional, auto-generated if omitted
  },
]);
```

### Riskified

To initialize the Riskified provider, `storeDomain` needs to be passed (your Riskified shop domain, matching the `X-RISKIFIED-SHOP-DOMAIN` header on backend API calls). Riskified's Beacon auto-generates the session id, which is sent to the backend as the order's cart\_token.

```typescript theme={null}
FraudSDK.load([
  {
    provider: FraudProvider.RISKIFIED,
    storeDomain: "my-store.myshopify.com",
  },
]);
```

### HiPay

To initialize the HiPay provider, username, password, and environment need to be passed. username/password are the same public HiPay SDK credentials configured for the HiPay provider in the Payrails portal. lang is optional and defaults to 'en'. HiPay's JS SDK collects a device fingerprint synchronously once loaded; this value is sent to the backend as `device_fingerprint` on the HiPay Order/Authorize API request.

```typescript theme={null}
FraudSDK.load([
  {
    provider: FraudProvider.HIPAY,
    username: "public-username",
    password: "public-password",
    environment: "stage", // or 'production'
  },
]);
```

Requires `@payrails/fraud-sdk` 1.10.0 or later.


## Related topics

- [Elements](/docs/orchestration/checkout-sdks/web-v5-legacy/elements.md)
- [SDK API Reference](/docs/orchestration/checkout-sdks/android/api-reference.md)
- [Fraud Score](/docs/fraud-management/fraud-score.md)