> ## 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. ### Checkout.com Requires `@payrails/fraud-sdk` 1.11.0 or later. To initialize the Checkout.com provider, `publicKey` and `environment` need to be passed. The SDK loads Checkout.com Risk.js on the page where the shopper pays and creates a device session. With the Payrails Web SDK, the session is sent automatically when the shopper pays, and Payrails passes it to Checkout.com as the risk device session ID. ```typescript theme={null} import { FraudSDK, FraudProvider } from "@payrails/fraud-sdk"; FraudSDK.load([ { provider: FraudProvider.CHECKOUT, publicKey: "pk_sbox_xxx", environment: "sandbox", // or 'production' providerConfigId: "11111111-1111-4111-8111-111111111111", // optional timeoutMs: 1500, // optional }, ]); ``` | Option | Status | Description | | :- | :- | :- | | `publicKey` | Required | The public key of your Checkout.com account. | | `environment` | Required | `sandbox` or `production`. Must match the public key. | | `providerConfigId` | Optional | The ID of the matching Checkout.com provider config in Payrails. | | `timeoutMs` | Optional | How long Risk.js waits to collect device data, in milliseconds. Defaults to 1000. | Load one Checkout.com entry per page, for a single Checkout.com account. If a second entry with a different `publicKey` or `providerConfigId` loads on the same page, the SDK rejects it and keeps the first account's session. The SDK reuses a Risk.js device session on the same page for 15 minutes. After that, the next load creates a new session. #### API-only integrations If you build your own frontend, load Checkout.com Risk.js yourself and send the device session ID in `meta.risk.sessions` on the [authorize request](https://docs.payrails.com/reference/authorizeaction.md): ```json theme={null} { "meta": { "risk": { "sessions": [{ "provider": "checkout", "sessionId": "dsid_xxx" }] } } } ``` ### HyperPay Requires `@payrails/fraud-sdk` 1.12.0 or later. HyperPay uses a ThreatMetrix device session for server-to-server card payments. To initialize the HyperPay provider, `orgId` and `merchantId` need to be passed. Get both from HyperPay: the ThreatMetrix Org ID and the HyperPay MID for the account. The SDK loads ThreatMetrix and creates a session ID in the format `{MID}_{uuid}`. With the Payrails Web SDK or Drop-in, the session is sent automatically with the authorize request, and Payrails passes it to HyperPay as `customer.browserFingerprint.id`. The session is optional: without it, the payment goes through as before. ```typescript theme={null} import { FraudSDK, FraudProvider } from "@payrails/fraud-sdk"; FraudSDK.load([ { provider: FraudProvider.HYPERPAY, orgId: "threatmetrix-org-id", merchantId: "hyperpay-mid", providerConfigId: "11111111-1111-4111-8111-111111111111", // optional }, ]); ``` | Option | Status | Description | | :- | :- | :- | | `orgId` | Required | The ThreatMetrix Org ID from HyperPay. | | `merchantId` | Required | The HyperPay MID for the account. Used as the prefix of the session ID. | | `providerConfigId` | Optional | The ID of the matching HyperPay provider config in Payrails. Needed only when you have more than one HyperPay config. | Load the HyperPay provider when the payment page opens, not right before the shopper pays. ThreatMetrix needs a few seconds to profile the device. The SDK creates one session per page. Later loads on the same page reuse it, and a new page load creates a new one. ThreatMetrix profiles only once per page, so don't configure HyperPay together with Cybersource, which also uses ThreatMetrix. If ThreatMetrix is already running on the page, for example from Cybersource or a Signifyd script, the SDK skips HyperPay and logs a console warning. If you have more than one HyperPay MID, load the entry for the MID the payment will be routed to. #### Server-to-server integrations If you run ThreatMetrix yourself, load it on the checkout page with a session ID in the format `{MID}_{uuid}`, 30 to 128 characters long: ```text theme={null} https://h.online-metrix.net/fp/tags.js?org_id=&session_id=_ ``` Then send the same session ID in `meta.risk.sessions` on the [authorize request](https://docs.payrails.com/reference/authorizeaction.md): ```json theme={null} { "meta": { "risk": { "sessions": [{ "provider": "hyperpay", "sessionId": "_" }] } } } ``` * Add `providerConfigId` to the entry only if you send sessions for more than one HyperPay config. Payrails uses the session tagged with the config the payment is routed to, and otherwise the untagged HyperPay session. * Payrails doesn't use `meta.risk.sessionId` for HyperPay. * Payrails doesn't send a session ID outside 30 to 128 characters to HyperPay, so it can't cause a decline. * The session applies only when the shopper is present, not to recurring payments. ## Related topics - [Fraud prevention providers](https://docs.payrails.com/docs/integrations/fraud-prevention-providers.md) - [Ravelin](https://docs.payrails.com/docs/integrations/fraud-prevention-providers/ravelin.md) - [Forter](https://docs.payrails.com/docs/integrations/fraud-prevention-providers/forter.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.